md-document
/md-document
Convert authored markdown into a polished self-contained HTML document with a table of contents, numbered figures and tables, cross-references, footnotes, and print-ready CSS. Use when publishing a report, whitepaper, or memo.
- Author
- borghei ↗
- Repository
- Claude-Skills ↗
- Licence
- MIT
- Last repository change
- 23.10.2026
Assessment and security
- Files in this package
- 11
- Scripts
- 4
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 23.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 4 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/crossref_auditor.py, scripts/md_render.py, scripts/md_to_html.py, scripts/print_profile.py
What it does and when to use it
Convert authored markdown into a polished self-contained HTML document with a table of contents, numbered figures and tables, cross-references, footnotes, and print-ready CSS. Use when publishing a report, whitepaper, or memo.
Original author description
Convert authored markdown into a polished self-contained HTML document with a table of contents, numbered figures and tables, cross-references, footnotes, and print-ready CSS. Use when publishing a report, whitepaper, or memo.
How it works
- When to use this skill
- Inputs the skill expects
- Clarify First
- Workflows
- Decision frameworks
- Anti-Patterns
- Files
- Scope & Limitations
SKILL.md preview
--- name: md-document description: > Convert authored markdown into a polished self-contained HTML document with a table of contents, numbered figures and tables, cross-references, footnotes, and print-ready CSS. Use when publishing a report, whitepaper, or memo. license: MIT + Commons Clause metadata: version: 1.0.0 author: borghei category: markdown-html domain: document-publishing updated: 2026-07-21 tags: [markdown, html, publishing, pdf, cross-references, typography] --- # Markdown Document Publishing Turn an authored markdown file into a single HTML document you can email, host, or print — semantic structure, an automatic table of contents, figures and tables numbered and referenceable by number, footnotes, and a print stylesheet that survives contact with a PDF exporter. One file out, no runtime dependencies, no external assets. ## When to use this skill - **Publishing a report or whitepaper** that must arrive as one file, not a folder - **Producing a PDF** from markdown without a LaTeX or Pandoc toolchain - **Numbering figures and tables** so prose can reference them instead of saying "below" - **Converting untrusted or contributed markdown** where injection safety matters - **Standardizing a document series** so every issue looks like the same publication - **Catching broken cross-references** before a document reaches readers ## Inputs the skill expects - A markdown source file, optionally with YAML frontmatter - Figure images as relative paths, or as base64 data URIs (PNG, JPEG, GIF, WebP or AVIF) for true single-file output - The intended output: screen, print, or both - Document length and whether a table of contents is warranted - Page geometry, if printing: size, margins, single- or double-sided - A stylesheet, if not using the bundled theme ## Clarify First Before converting, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used. - **Screen, print, or both:** why it changes the output: print needs a page profile, forced light colors, and break control; skipping it produces a document that looks right on screen and breaks on paper. - **Whether images must be embedded:** why it changes the output: relative image paths mean the HTML file is not actually self-contained, which defeats the point if it will be emailed. - **Document length and TOC expectation:** why it changes the output: a TOC on a two-page memo is noise; depth 3 on a long report produces a TOC longer than some sections. - **Whether the markdown is trusted:** why it changes the output: it does not change escaping (always on), but it determines whether a review gate should run first. Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top. ## Workflows ### Workflow 1 — Convert a document to self-contained HTML 1. Audit labels and references first — the converter's gate reports broken references, but the auditor explains what to do about each one. 2. Convert. The bundled theme is inlined automatically; pass `--css` to override. 3. Check the gate. A non-zero exit means the rendered document contains visible `[?fig:name]` markers where numbers should be. ```bash python3 markdown-html/md-document/scripts/crossref_auditor.py \ --input markdown-html/md-document/assets/sample_document.md --format text python3 markdown-html/md-document/scripts/md_to_html.py \ --input markdown-html/md-document/assets/sample_document.md \ --out build/report.html --toc-depth 2 --format text ``` ### Workflow 2 — Produce a print-ready PDF 1. Generate the print block from a page profile and append it to the theme, so the exported file carries its own print rules. 2. Convert with the extended stylesheet. 3. Open in a browser, print to PDF with margins set to **Default** — a browser margin setting overrides `@page` and will clip content. ```bash python3 markdown-html/md-document/scripts/print_profile.py \ --input markdown-html/md-document/assets/sample_print_profile.json \ --out build/print.css --format text cat markdown-html/md-document/assets/document_theme.css build/print.css > build/full.css python3 markdown-html/md-document/scripts/md_to_html.py \ --input markdown-html/md-document/assets/sample_document.md \ --css build/full.css --out build/report.html ``` ### Workflow 3 — Gate a document series in CI 1. Run the auditor at `warning` severity so unlabelled figures block, not just broken references. 2. Run the conversion gate; it fails on unresolved references and undefined footnotes — both render as visible defects. 3. Emit JSON for both so a CI job can annotate the diff. ```bash python3 markdown-html/md-document/scripts/crossref_auditor.py \ --input markdown-html/md-document/assets/sample_document.md --max-severity warning --format json python3 markdown-html/md-document/scripts/md_to_html.py \ --input markdown-html/md-document/assets/sample_document.md --out build/report.html --format json ``` ## Decision frameworks ### Table-of-contents depth | Document length | TOC | `--toc-depth` | |-----------------|-----|---------------| | Under 3 pages | none — omit `[TOC]` | n/a | | 3-10 pages | yes | 1 (`##` only) | | 10-30 pages | yes | 2 (default) [PROVEN] | | Over 30 pages | yes | 2, plus per-section navigation | If the TOC exceeds one screen, reduce the depth. A contents list longer than the first section is a navigation failure, not thoroughness. ### Reference style | Situation | Write | Not | |-----------|-------|-----| | Pointing at a figure | `[@fig:access]` | "the chart below" | | Pointing at a table | `[@tbl:policies]` | "see the table above" | | Pointing at a section | `[@sec:context]` | "as discussed earlier" | | A caveat that breaks the sentence | a footnote | a parenthetical | | Evidence the argument depends on | body text | a footnote | **[PROVEN] Never use positional language in a document that may be paginated.** "Below" breaks when the table lands on the next page, breaks silently when a section is reordered, and means nothing to a reader navigating by heading. ### Alt text versus caption | | Alt text | Caption | |---|---------|---------| | Audience | Non-sighted readers | Everyone | | Length | 15-125 characters | One or two sentences | | Says | What the image depicts | What to conclude, plus the number | | Fails as | "chart", "figure 3", "" | "See above" | The auditor flags placeholder alt text (`chart`, `image`, `screenshot`, empty) at **error** severity and alt text under 15 or over 125 characters at **warning**. ### Print geometry | Decision | Default | Change when | |----------|---------|-------------| | Page size | A4 [RECOMMENDED] | Audience is exclusively North American → Letter | | Side margins | 25-30mm | Never below 20mm — the measure exceeds 90 characters | | Body size | 11pt | 12pt for older audiences or dense reference material | | Mirrored margins | off | The document will be bound double-sided | | `break-inside: avoid` | figures, tables, code | Never on an element taller than one page | At A4 with 20mm margins the text column is ~92 characters — well outside the 55-85 comfort band. Widening the margins is the fix; `max-width: none` on `main` is what causes the problem. ## Anti-Patterns ### The "see the table below" reference **Mistake:** Writing positional prose — "the chart below", "as shown above" — instead of a numbered cross-reference. **Why it happens:** It reads naturally while drafting, when the author can see the whole document at once and the table genuinely is below. **Instead:** Write `[@tbl:policies]`. Pagination moves content, reordering breaks positional claims silently, and a reader navigating by heading has no "below". The auditor cannot detect a broken "below"; it fails the build on a broken `[@tbl:policies]`. ### Allowing raw HTML through the converter **Mistake:** Adding an escape hatch so authors can drop `<div class="...">` or an embed into the markdown. **Why it happens:** A real formatting need appears that the subset does not cover, and passing HTML through is a one-line change. **Instead:** Extend the subset or the stylesheet. The escape-then-render ordering is the entire security model — the moment raw HTML passes through, every document becomes an injection vector, and the converter can no longer be pointed at contributed content. There is deliberately no `--allow-html` flag. ### Reusing the caption as alt text **Mistake:** Writing one string and letting it serve as both the figure caption and the alt attribute. **Why it happens:** The converter falls back to exactly this when no caption is given, which makes it look sanctioned. **Instead:** Write both. The caption tells a sighted reader what to conclude; the alt text describes what the figure shows to someone who cannot see it. "Figure 3. Costs fall 40% under Policy B" is a fine caption and useless alt text — it states the conclusion without describing the chart. ### Print rules added after the fact **Mistake:** Building the document for screen, then bolting on a print stylesheet when someone asks for a PDF. **Why it happens:** Print feels like a rendering detail rather than a design constraint, and the screen version already looks finished. **Instead:** Decide print-or-not before converting. Retrofitted print CSS produces the classic failures — stranded headings, tables split mid-row, dark theme reaching paper as invisible gray text, a 92-character measure. `print_profile.py` exists so the geometry is a reviewed input, not an afterthought. ### Trusting the gate as a proof of quality **Mistake:** Treating a passing conversion as evidence the document is ready to publish. **Why it happens:** The gate is automated and green, which reads as authoritative. **Instead:** The gate checks that references resolve and footnotes are defined. It cannot see a stranded heading, a figure separated from its caption, a table split across pages, or a PDF whose margins clipped the content. Proof every page of the actual output at 100% zoom before publishing. ## Files | File | Purpose | |------|---------| | `scripts/md_to_html.py` | CLI: convert markdown to a self-contained HTML document; gates on broken references | | `scripts/md_render.py` | Markdown subset parser, escaping-first inline renderer, label numbering — imported by `md_to_html.py`, not a CLI | | `scripts/crossref_auditor.py` | Audit labels, references, alt text, and heading hierarchy; CI gate | | `scripts/print_profile.py` | Generate a print/PDF stylesheet from a JSON page profile | | `references/markdown-conventions.md` | Supported syntax, labelling contract, escaping and URL-allowlist model | | `references/print-and-pdf-production.md` | Paged media, break control, export mechanics, proofing checklist | | `assets/sample_document.md` | Working document exercising every construct; converts clean | | `assets/sample_print_profile.json` | A4 double-sided print profile with running heads | | `assets/document_theme.css` | Bundled theme inlined by default — this skill's own copy | | `assets/document_outline_template.md` | Starting structure for a new report or memo | All scripts share one exit-code contract: **0** clean, **2** gate failed (findings at or above the threshold), **1** the tool itself errored. A CI job can therefore tell a real defect from a broken invocation. **Three CLI tools, one module.** `md_render.py` is a library, not a fourth command — it holds the parser that `md_to_html.py` imports. A single-file converter came to 429 lines, well over the 300-line ceiling. Splitting CLI from parser is the remedy the tool-design standard prescribes for an oversized script, and same-directory imports keep the package self-contained: `md-slides` carries its own separate `slide_render.py` rather than importing this one. ## Scope & Limitations **In Scope:** - Converts one markdown file into a self-contained HTML document with the theme inlined, a table of contents, numbered figures and tables, `[@fig:]`, `[@tbl:]` and `[@sec:]` cross-references, and footnotes (`md_to_html.py`). - Audits labels, references, alt text and heading hierarchy before conversion (`crossref_auditor.py`). - Generates a print/PDF stylesheet from a JSON page profile covering page size, margins, mirrored margins and running heads (`print_profile.py`). - Escapes all source text, including raw HTML, and passes link and image URLs through a scheme allowlist. **Out of Scope:** - Producing the PDF file itself. The skill writes print CSS; the PDF comes from a browser's print dialog. - Slide decks; see `markdown-html/md-slides/`. - Pre-publication review of links, readability, terminology and frontmatter; see `markdown-html/md-review/`. - Building or validating theme tokens and contrast; see `markdown-html/design-system/`. - Reading or auditing existing Word or PDF files; see `documents/docx-toolkit/` and `documents/pdf-toolkit/`. **Important Caveats:** - The converter supports a subset of markdown. Nested lists, reference-style links and raw HTML are not rendered; anything outside the subset appears as escaped text. A URL with a literal parenthesis truncates unless it is percent-encoded. - The converter does not embed image files itself. A document with relative image paths needs those files beside it. For a single file, write the image as a base64 data URI (`data:image/png;base64,...`); the allowlist accepts PNG, JPEG, GIF, WebP and AVIF data URIs in an image source only. SVG data URIs, other `data:` types and `data:` link targets are replaced with `#blocked-url`. - Fenced code gets a `language-*` class but no syntax highlighting. - The gate checks only that references resolve and footnotes are defined. Stranded headings, split tables and clipped margins show up only when the printed output is proofed, and browsers differ in how much of `@page` they honour.
Files in this package (11)
- SKILL.md 14 KB
- assets/document_outline_template.md 2 KB
- assets/document_theme.css 7 KB
- assets/sample_document.md 3 KB
- assets/sample_print_profile.json 1 KB
- references/markdown-conventions.md 11 KB
- references/print-and-pdf-production.md 10 KB
- scripts/crossref_auditor.py 10 KB
- scripts/md_render.py 13 KB
- scripts/md_to_html.py 6 KB
- scripts/print_profile.py 10 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · borghei/Claude-Skills | 100 | MIT |
| alirezarezvani/claude-skills | 100 | MIT |
| bestagentkits/agency-skills | 100 | MIT |
| tmj-90/gaffer | 90 | Apache-2.0 |
Database snapshot: 13.11.2026 · package version a148f6ace690 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95lov-any2pdf
Convert Markdown to polished PDF with CJK typography, code, tables, images, covers, TOC, bookmarks, and reading themes. Trigger on md2pdf, Chinese report typesetting, or print-ready PDF requests. - 90arkad-documents
ALWAYS use this skill when the user asks for a branded Arkad document — "write a memo", "internal memo about", "make this an Arkad document", "put this on our letterhead", "print-ready version of". Fills the templates shipped in this plugin and returns one self-contained,… - 100docx
Create and edit Microsoft Word (.docx) documents to a professional standard — reports, proposals, contracts, letters, memos — with custom styles, multi-level lists, styled/merged tables, headers/footers, table of contents, hyperlinks, footnotes, tracked changes and comments. Use… - 100document-conversion
This skill should be used when users need to convert PDFs (especially with tables or figures), mentions 'convert', 'PDF', 'document processing', has complex academic papers to import, or asks about document conversion options. - 100document-conversion
This skill should be used when users need to convert PDFs (especially with tables or figures), mentions 'convert', 'PDF', 'document processing', has complex academic papers to import, or asks about document conversion options. - 100md-to-doc
Convert Markdown files into clean Word (.docx) or PDF documents with tables, code blocks, headings and a table of contents intact, using pandoc plus a fallback chain for PDF engines. Use this whenever someone wants to turn a .md / README / notes / report into a Word doc or PDF,…