Doc to Markdown

Convert documents to high-quality markdown with intelligent multi-tool orchestration and automatic DOCX post-processing.

Architecture: Format-specific converters with automatic post-processing.

Quick Start

# DOCX → Markdown
uv run --with pymupdf --with pymupdf4llm --with "markitdown[pdf]" scripts/convert.py document.docx -o output.md --assets-dir ./media

# PDF → Markdown
uv run --with pymupdf --with pymupdf4llm --with "markitdown[pdf]" scripts/convert.py document.pdf -o output.md

# Saved HTML → Markdown (Pandoc required; no remote fetching)
uv run scripts/convert.py page.html -o page.md

# Run tests
uv run --with pytest pytest scripts/test_convert.py -v

Conversion Modes

Tool Selection

Read select_tools for format preferences and availability filtering. HTML/HTM follows the saved HTML procedure. For Heavy Mode selection and failure handling, read its procedure.

PDF Manuals And Question Banks

Before delivering a PDF conversion or changing its structure, follow the PDF acceptance procedure. It owns source comparison, structural review, actual-reader checks and original-file handoff.

Saved HTML And Website Manuals

For HTML/HTM, read references/html-conversion.md before converting. Use scripts/convert.py; the default converts the whole body and does not trim navigation. An explicit --html-selector selects exactly one tag, #id or .class. --html-heading-offset shifts parsed headings for assembly and rejects overflow beyond H6. Relative assets are not downloaded or copied.

Verify source href occurrences against the emitted Markdown AST, then rerun scripts/html_to_markdown.py after cleanup or merging. For manuals, map the book, chapters, lessons and internal headings before assembly; preserve code fences and reconcile rewritten anchors. Conversion success does not certify that figures are readable inside the recipient's actual Markdown reader.

DOCX Post-Processing (automatic)

When converting DOCX via pandoc, these cleanups are applied automatically:

PDF Post-Processing (automatic)

When converting PDF via pymupdf4llm, these cleanups are applied automatically (skip with --no-postprocess):

For engine availability and failure handling, read Heavy Mode selection.

Known limits:

• pymupdf4llm may emit duplicated paragraphs (source text layer has only one copy) — not auto-fixed; spot-check.
• Dotted TOC pages get detected as tables — rewrite the TOC manually if it matters.
• Cross-page tables are NOT merged (each page's fragment keeps its own header row) — merge manually.
• Table cells overlapped by diagonal watermarks can contain watermark character shards (dn, uFE, ...); the repeating-line stripper removes full lines only, not intra-cell shards. Watermark-heavy PDFs need cell-level rebuild (collect non-watermark spans per cell bbox).
• Complex infographics (dense in-image text) come out as images only; transcribing in-image text needs a VLM pass, not this tool.

CJK Bold Spacing — why and how

DOCX uses run-level styling (no spaces between bold/normal runs in CJK text). Markdown renderers need whitespace around ** to recognize bold boundaries.

Rule: if a **content** span contains any CJK character, ensure both sides have a space — unless already spaced or at line boundary. This handles CJK punctuation, emoji adjacency, and mixed content.

Before: 打开**飞书**，就可以    → some renderers fail to bold
After:  打开 **飞书** ，就可以  → inspect bold rendering in the target reader

Heavy Mode Workflow

Before choosing Heavy Mode, read its selection and degradation behavior. For explicit segment-level merging, use Merge Outputs Manually.

Image Extraction

# Extract images with metadata
uv run --with pymupdf scripts/extract_pdf_images.py document.pdf -o ./extracted-images

# Generate markdown references file
uv run --with pymupdf scripts/extract_pdf_images.py document.pdf --markdown refs.md

Output:

• Images: extracted-images/img_page1_1.png, extracted-images/img_page2_1.jpg
• Metadata: extracted-images/images_metadata.json (page, position, dimensions)

Quality Validation

For the validator's command, prerequisites, result fields and exit handling, read Mechanical comparison. The CLI accepts PDF or DOCX source files; the remainder of that procedure covers PDF structural and recipient acceptance.

From this Skill's source checkout, run the validator's bidirectional controls with python3 -m unittest discover -s tests -v (Pandoc required). Default packages exclude this development test directory; a zero-test run is not validation.

Merge Outputs Manually

# Merge multiple markdown files
python scripts/merge_outputs.py output1.md output2.md -o merged.md

# Show segment attribution
python scripts/merge_outputs.py output1.md output2.md -o merged.md --verbose

Path Conversion (Windows/WSL)

# Windows to WSL conversion
python scripts/convert_path.py "C:\Users\<windows-user>\Documents\file.pdf"
# Output: /mnt/c/Users/<windows-user>/Documents/file.pdf

Common Issues

"No conversion tools available" Follow converter installation, then rerun the selected conversion command. Check imports in the same Python runtime as the converter; a distribution name alone does not prove an engine is available.

FontBBox warnings during PDF conversion

• A font warning alone does not establish output quality; follow PDF acceptance.

Images missing from output

• Follow PDF acceptance to reconcile missing images and references.
• Or extract separately with scripts/extract_pdf_images.py

Tables broken in output

• Compare the table with the original and reconstruct missing cells if needed.
• Read Heavy Mode selection before trying another candidate; the validator diagnoses coverage and does not repair tables.

Bundled Scripts

References

• references/benchmark-2026-03-22.md - Historical converter benchmark
• references/heavy-mode-guide.md - Detailed Heavy Mode documentation
• references/tool-comparison.md - Tool capabilities comparison
• references/conversion-examples.md - Batch operation examples
• references/html-conversion.md - Saved HTML scope, link retention, assets and manual heading assembly
• references/pdf-acceptance.md - PDF text/structure checks, synthetic boundary controls, reader and original-file handoff
• references/obsidian-link-examples.md - Native heading/citation and same-name book-index navigation controls

Next Step: Clean Up Converted Content

After converting documents to markdown, suggest cleanup:

Conversion complete: [N] files converted to markdown.

Options:
A) Clean up docs — run /daymade-docs:docs-cleaner to consolidate redundant content (Recommended if multiple files)
B) Check facts — run /fact-checker to verify claims in the converted content
C) No thanks — the markdown conversion is sufficient