| name | md2all |
| description | Convert Markdown and Quarto Markdown into DOCX, PDF, and HTML publishing outputs with a DOCX-first workflow. Use when Codex needs to render or validate .md or .qmd files, select or patch a reference.docx template, choose a CSL style, repair non-destructive citation or cross-reference issues, run Quarto or Pandoc publishing commands, or install and verify Quarto, Pandoc, and TinyTeX on Windows or macOS. Prefer the built-in scripts and template assets for deterministic conversion; only use LLM-assisted cleanup when the user explicitly asks for editing or when scripted conversion fails and a fallback is needed. |
MD2All
Overview
Use the bundled scripts to turn single-file md or qmd inputs into publishing outputs with a deterministic, script-first workflow. Default to DOCX, keep fixes conservative, and only escalate to LLM help when the user requests revision work or when scripted conversion cannot recover.
Quick Start
Run the main command from scripts/md2all.py.
python scripts/md2all.py input.md
python scripts/md2all.py input.md --to pdf
python scripts/md2all.py input.md --template degree-thesis --validate
python scripts/md2all.py --doctor
python scripts/md2all.py --install
Interpret the workflow this way:
- Verify the environment first.
- Normalize
md into temporary qmd when needed.
- Infer a template and locale unless the user overrides them.
- Build a minimal
.bib only when the user did not provide bibliography data.
- Render with Quarto.
- For DOCX output, post-process the rendered file to enforce built-in house styles for title, paragraph indentation, captions, and equation numbering.
- Run structural validation.
- Suggest LLM fallback only after a scripted failure or when the user asks for cleanup.
On Windows Codex sessions, if quarto render fails inside the sandbox with handle or process-spawn errors, rerun the render step outside the sandbox. Treat that as an execution-environment requirement rather than a document-content failure.
For Markdown files with relative image paths, keep the render input in the source file's directory. Do not place the temporary qmd inside a nested temp directory unless resource paths are rewritten accordingly.
After each md2all bug fix or workflow repair, record the bad case and the best practice in the skill references before finishing the task.
Workflow
1. Diagnose before mutating content
Run python scripts/md2all.py --doctor or read references/workflow.md when:
- Quarto or Pandoc might be missing
- PDF output needs TinyTeX
- the user asks to "install", "fix", or "set up" the environment
On Windows, install with winget. On macOS, install with brew. Follow references/install-windows-macos.md for exact expectations.
2. Keep rendering deterministic
Default to the script pipeline instead of freeform editing:
- Use
scripts/normalize_markdown.py to convert plain Markdown into temporary Quarto Markdown.
- Use
scripts/infer_template.py to pick the closest built-in template.
- Use
scripts/build_bibliography.py to infer a .bib when bibliography metadata is missing.
- Use
scripts/patch_reference_docx.py to generate or patch reference.docx.
- Use
scripts/validate_outputs.py after rendering.
- For DOCX output with figures, verify both
word/media/* entries and figure-caption/cross-reference resolution after rendering.
Read references/template-selection.md before overriding template heuristics. Read references/bibliography-rules.md before changing citation or bibliography behavior.
3. Default output policy
Apply these defaults unless the user overrides them:
- Output target:
docx
- Output location: next to the source file
- Input scope: one
md or qmd file
- Temporary files: use a temp directory instead of writing intermediates beside the source file
- Validation: run basic structural validation
- Reports: only save a Markdown report if the user explicitly asks for one
4. Built-in assets
Use the built-in asset catalogs in assets/:
assets/reference-docx/template-catalog.jsonassets/reference-docx/profiles/*.jsonassets/csl/catalog.json
The template families are:
- Academic:
degree-thesis, proposal-midterm, academic-report
- Business:
business-report, business-brief, business-handout
- Daily:
general-document, notice-explanation, resume
Each built-in template fully defines heading styles, body typography, block quotes, lists, margins, and formal headers and footers. User-supplied reference.docx or .csl files override the built-ins.
5. Conservative repair only
Do not rewrite substance by default. Limit scripted fixes to:
- normalizing line endings and front matter boundaries
- converting
md to temporary qmd
- repairing obvious citation-key mismatches when a deterministic match exists
- replacing irreparable citation keys with
ref-missing-N
- normalizing obvious cross-reference markers
Do not auto-generate document titles or add substantive headings. If the user explicitly asks for polishing, read references/markdown-repair-rules.md and then use LLM assistance intentionally.
6. LLM escalation boundary
Stay in pure script mode unless one of these is true:
- the user asks to edit, polish, rewrite, or fix the prose
- the user passes an explicit flag such as
--allow-llm-fix
- scripted conversion fails and the user wants fallback help
When scripted conversion fails, summarize the deterministic failure first. Then propose LLM-assisted repair rather than jumping straight into edits.
References
Read only what is needed:
