sanmu-doc2md: Academic PDFs and Slides to Markdown in Claude Code or Codex
Turn textbooks, lecture slides, and papers into organized Markdown with LaTeX math, figures, and page provenance. Existing OCR results can be assembled locally for reading in tools such as Obsidian.
中文Install in Claude Code、Codex
Standalone assembly uses Python 3.10 or later. Formula validation and local preview use Node.js 22.20 or later and KaTeX. A network connection and MINERU_API_TOKEN are needed for new cloud OCR jobs.
- Download the archive at the pinned GitHub commit. Keep the complete skills/sanmu-doc2md/ directory, including SKILL.md, scripts/, references/, and requirements.txt.
- Place the directory in ~/.claude/skills/ for Claude Code or ~/.agents/skills/ for Codex. Run python scripts/doctor.py from that skill directory to check the environment.
- For the full conversion and validation workflow, install the Python requirements in a dedicated virtual environment. Use npm --prefix scripts install --ignore-scripts --no-audit --no-fund for KaTeX. Skip cloud credentials when you already have OCR results.
Example task
From the skill directory, save the following synthetic OCR data in demo-raw/lesson-01/content_list.json:
[{"type":"text","text":"Demo lesson: a square has four sides.","page_idx":0,"bbox":[72,72,420,110]},{"type":"equation","text":"A = s^2","page_idx":0,"bbox":[72,134,260,172]}]Run from the skill directory:
python scripts/build_markdown.py --raw ./demo-raw --out ./demo-notes --mode slidesWhat to check
The demo-notes/lesson-01.md file should contain the sample sentence and the formula A = s^2. The demo-notes/00-目录.md contents page should link to the lesson. This tests local Markdown assembly with pre-existing OCR data.
Original SKILL.md on GitHub · Updated
Frequently asked question
Do I need a MinerU token if I already have content_list.json?
Markdown assembly can read an existing OCR result without a MinerU token. Configure cloud credentials when submitting new scans for recognition.