TbusOS Doc-to-Markdown Converter
Convert PDF and DOCX files to clean Markdown with extracted images. Supports single file or batch directory conversion.
Output Structure
<output-dir>/
├── <doc1-name>.md
├── <doc2-name>.md
└── images/
├── <doc1-slug>/
│ ├── sec01_01.png
│ ├── sec01_02_boot_flow.png
│ └── sec02_01.png
└── <doc2-slug>/
└── ...
Image naming convention: sec{章节号}_{序号}_{描述}.png — makes images easy to find and associate with document章节。
Workflow
1. Confirm with user
Identify the source (single file or directory) and confirm:
- What to convert
- Where to put output (default: create a
markdown/dir in project root, or user can specify)
2. Ensure dependencies
python3 -c "import fitz" 2>/dev/null || pip3 install pymupdf
python3 -c "from docx import Document" 2>/dev/null || pip3 install python-docx
3. Run the converter
The bundled scripts/convert.py handles the core conversion.
Single file:
python3 <skill-dir>/scripts/convert.py /path/to/file.pdf --output /project/markdown/
Batch directory:
python3 <skill-dir>/scripts/convert.py /path/to/docs/ --output /project/markdown/
What the script handles:
- PDF: Extracts text with heading detection, extracts embedded images per page. For scanned PDFs (no text layer), exports full page as 2x PNG.
- DOCX: Extracts text preserving heading/list/code styles, extracts PNG/JPEG images, attempts EMF/WMF conversion via LibreOffice or PIL.
- Image placement: Images are inserted inline near the paragraphs that reference them, not dumped at the end.
- Tables: Converted to markdown table format.
4. Post-processing (important!)
After the script runs, the output needs human-guided curation to become truly useful. This is where you add value beyond raw conversion:
Read the generated markdown to verify text quality — fix garbled headings, broken lists, or misformatted code blocks.
Review extracted images — read the image files to check which are:
- Substantive (diagrams, flowcharts, architecture drawings, code screenshots) → keep
- Decorative (logos, horizontal rules, tiny icons, blank images) → delete
Rename images to descriptive names based on content:
sec01_01.png→sec01_01_验签流程图.png(if it shows verification flow)sec03_02.png→sec03_02_efuse_layout.png(if it shows eFuse layout)- Update the markdown references to match
For EMF/WMF diagrams that couldn't be extracted: If the user provides a screenshot or describes the diagram, recreate it using Python PIL and save as PNG. This is common for Visio diagrams embedded in Word docs — they're the most valuable images and worth recreating.
Place images contextually — if images ended up in "Other Images" section at the end, move the
![...]()references to where they logically belong in the text.
5. Report results
Show the user:
- File tree of what was generated
- Number of images kept vs removed
- Any EMF/WMF files that couldn't be converted (suggest user provide screenshots from original doc)
- Any issues encountered
Edge Cases
- Scanned PDFs: Page images are exported as fallback; text will be empty. Note this in the markdown.
- Password-protected PDFs: Report to user if PyMuPDF can't open.
- Large PDFs (>50 pages): Still convert, but warn user. Consider extracting only pages with figures.
- Chinese content: PyMuPDF and python-docx handle CJK well, no special handling needed.
- Complex tables with merged cells: Best-effort markdown tables; suggest "see original" for very complex ones.