doc-to-markdown

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

AGENTS.md

'<img src="../../escape.png">', '<a href="next.html">Next</a>', '<img src="missing.png">',

svg = base64.b64decode(encoded.group(1)).decode()

Audit 0.4.1 · source sha 5ed779aacda4 · 31 Oct 2026Report an issue or request a re-scan

• Publisherdaymade GitHub userOwner of the repository this skill is read from
• Source folderdaymade/claude-code-skills/daymade-docs/doc-to-markdownThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict5ed779aacda4A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Converts DOCX/PDF/PPTX and saved HTML/HTM to high-quality Markdown with automatic post-processing. Fixes pandoc grid tables, simple tables, image paths, CJK bold spacing, attribute noise, and code blocks; for PDFs also…

---
name: doc-to-markdown
disable-model-invocation: true
description: >-
  Converts DOCX/PDF/PPTX and saved HTML/HTM to high-quality Markdown with automatic post-processing. Fixes pandoc grid tables, simple tables, image paths, CJK bold spacing, attribute noise, and code blocks; for PDFs also strips OCR garbage blocks, repeated headers/footers/watermarks, and absolute image paths from pymupdf4llm output. Trigger on "convert document", "docx to markdown", "parse word", "doc to markdown", "解析word", "转换文档", "HTML to Markdown".
---

# 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

```bash
# 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

| Mode | Speed | Selection | Use Case |
|------|-------|---------|----------|
| **Quick** (default) | Fast | Single converter | Drafts, simple documents |
| **Heavy** | Slower | Compares converter candidates | Complex layouts needing source review |

## Tool Selection

Read [`select_tools`](scripts/convert.py) for format preferences and availability
filtering. HTML/HTM follows the [saved HTML procedure](references/html-conversion.md).
For Heavy Mode selection and failure handling, read
[its procedure](references/heavy-mode-guide.md#selection-behavior).

## PDF Manuals And Question Banks

Before delivering a PDF conversion or changing its structure, follow the
[PDF acceptance procedure](references/pdf-acceptance.md). 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](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:

| Problem | Fix | Test coverage |
|---------|-----|---------------|
| Grid tables (`+:---+`) | Single-column → blockquote, multi-column → pipe table | `TestPostprocessPipeline` |
| Simple tables (`  ---- ----`) | Multi-column images → pipe table with captions | `TestSimpleTable` |
| Image path nesting (`media/media/`) | Flatten to `media/`, absolute → relative | `test_stats_tracking` |
| Pandoc attributes (`{width="..."}`) | Removed | `test_pandoc_attributes_removed` |
| CJK bold spacing (`**粗体**中文`) | Add space around `**` for CJK bold spans | `TestCjkBoldSpacing` |
| Indented dashed code blocks | → fenced ``` with language detection | `test_code_block_with_language` |
| Escaped brackets (`\[...\]`) | → `[...]` | `test_escaped_brackets_fixed` |
| Double-bracket links (`[[text]](url)`) | → `[text](url)` | `test_double_bracket_links_fixed` |

## PDF Post-Processing (automatic)

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

| Problem | Fix | Test coverage |
|---------|-----|---------------|
| Tesseract OCR garbage on image regions (`<!-- Start of picture text -->...`) | Block removed; images themselves kept | `TestStripOcrPictureText` |
| Repeated header/footer/watermark lines (including diagonal watermarks) | Detected via pymupdf cross-page scan, removed from markdown; bold-wrapped and merged-with-page-number variants also caught | `TestRepeatingLines` |
| Absolute image paths (`![](/abs/tmp/assets/...)`) | Rewritten relative to the output markdown file (portable output) | `TestImagePathsRelative` |

For engine availability and failure handling, read [Heavy Mode selection](references/heavy-mode-guide.md#selection-behavior).

**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 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source 5ed779aacda4

Questions about doc-to-markdown

• github.com/daymade/claude-code-skills/tree/main/daymade-docs/doc — the audited source at commit 5ed779aacda4 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology