Markdown Tech PDF
Overview
Use this skill to turn Markdown into a professional technical PDF. Prefer the bundled script for repeatable output, then inspect the generated PDF when visual fidelity matters.
The script auto-detects the markdown Python library (install via pip install markdown) for full spec-compliant parsing, and falls back to a zero-dependency built-in parser if the library is not available.
Workflow
- Identify the source Markdown file or create one from the user's provided content.
- Decide the title from, in order: the user's requested title, the first
# H1, YAML frontmatter title, or the file name.
- Run the bundled converter:
python <skill-folder>\scripts\md_to_tech_pdf.py input.md output.pdf --title "Document Title"
- If the user needs reviewable intermediate output, add
--html-output output.html.
- Open or render-check the PDF if the task depends on layout quality, tables, page breaks, CJK font rendering, or code block wrapping.
- If conversion fails because no Chromium-family browser is available, install Microsoft Edge, Google Chrome, or Chromium, then rerun the script. The script auto-detects the browser on Windows, macOS, and Linux.
Script Options
| Flag |
Default |
Description |
--title |
(auto) |
Document title override |
--html-output PATH |
— |
Also write the generated HTML to PATH |
--keep-html |
off |
Keep the intermediate HTML next to the PDF |
--browser PATH |
(auto) |
Path to Chrome/Edge/Chromium binary |
--page-number |
on |
Include page numbers in PDF footer |
--no-page-number |
— |
Omit page numbers |
--extra-css PATH |
— |
Inject a custom CSS file |
--timeout SECS |
60 |
Browser render timeout in seconds |
--author TEXT |
— |
Document author (HTML meta) |
--subject TEXT |
— |
Document subject (HTML meta) |
Style Standard
Default to a restrained technical-document style:
- A4 pages with comfortable print margins and page numbers.
- Clear title block, generated table of contents, and section hierarchy.
- System sans-serif body font with CJK fallbacks.
- Monospace code blocks with wrapping, subtle background, and left accent.
- Bordered tables with shaded headers, cross-page header repeat, and print-friendly spacing.
- Callout-like styling for blockquotes.
- Avoid decorative gradients, oversized hero sections, and marketing-page styling.
- Orphan/widow control for clean paragraph breaks across pages.
For exact style guidance, read references/technical-document-style.md before changing CSS or layout behavior.
Markdown Expectations
The script uses two parsing modes:
Mode A — markdown library (recommended, pip install markdown): full CommonMark spec compliance supporting all Markdown below plus images (), definition lists, nested lists, auto-links (<url>), footnotes, and more.
Mode B — Built-in fallback (zero dependencies): supports common AI-generated technical Markdown:
# through ###### headings- paragraphs, bold, italic, inline code, and links
- fenced code blocks with optional language labels
- unordered and ordered lists, including checklist markers
- blockquotes
- pipe tables
- horizontal rules
If using the fallback parser, install markdown (pip install markdown) for full capability.
Output Checks
Before considering a PDF done, check:
- the title and table of contents match the document,
- code blocks are readable and do not clip horizontally,
- tables fit the page (cross-page headers repeat automatically),
- Chinese text renders with a real font,
- page numbers are present and not overlapping content,
- page breaks do not leave major headings stranded at the bottom of a page.
1---2name: markdown-tech-pdf3description: Convert Markdown technical documentation into polished PDF files with a standard engineering-document style. Use when the user asks to export, render, print, or convert Markdown or AI-generated Markdown summaries into PDF technical documents, including docs with headings, tables, code blocks, checklists, images, Chinese or English text, and predictable page layout.4---56# Markdown Tech PDF78## Overview910Use this skill to turn Markdown into a professional technical PDF. Prefer the bundled script for repeatable output, then inspect the generated PDF when visual fidelity matters.1112The script auto-detects the `markdown` Python library (install via `pip install markdown`) for full spec-compliant parsing, and falls back to a zero-dependency built-in parser if the library is not available.1314## Workflow15161. Identify the source Markdown file or create one from the user's provided content.172. Decide the title from, in order: the user's requested title, the first `# H1`, YAML frontmatter `title`, or the file name.183. Run the bundled converter:1920```powershell21python <skill-folder>\scripts\md_to_tech_pdf.py input.md output.pdf --title "Document Title"22```23244. If the user needs reviewable intermediate output, add `--html-output output.html`.255. Open or render-check the PDF if the task depends on layout quality, tables, page breaks, CJK font rendering, or code block wrapping.266. If conversion fails because no Chromium-family browser is available, install Microsoft Edge, Google Chrome, or Chromium, then rerun the script. The script auto-detects the browser on Windows, macOS, and Linux.2728## Script Options2930| Flag | Default | Description |31| --- | --- | --- |32| `--title` | (auto) | Document title override |33| `--html-output PATH` | — | Also write the generated HTML to PATH |34| `--keep-html` | off | Keep the intermediate HTML next to the PDF |35| `--browser PATH` | (auto) | Path to Chrome/Edge/Chromium binary |36| `--page-number` | on | Include page numbers in PDF footer |37| `--no-page-number` | — | Omit page numbers |38| `--extra-css PATH` | — | Inject a custom CSS file |39| `--timeout SECS` | 60 | Browser render timeout in seconds |40| `--author TEXT` | — | Document author (HTML meta) |41| `--subject TEXT` | — | Document subject (HTML meta) |4243## Style Standard4445Default to a restrained technical-document style:4647- A4 pages with comfortable print margins and page numbers.48- Clear title block, generated table of contents, and section hierarchy.49- System sans-serif body font with CJK fallbacks.50- Monospace code blocks with wrapping, subtle background, and left accent.51- Bordered tables with shaded headers, cross-page header repeat, and print-friendly spacing.52- Callout-like styling for blockquotes.53- Avoid decorative gradients, oversized hero sections, and marketing-page styling.54- Orphan/widow control for clean paragraph breaks across pages.5556For exact style guidance, read `references/technical-document-style.md` before changing CSS or layout behavior.5758## Markdown Expectations5960The script uses **two parsing modes**:6162**Mode A — `markdown` library** (recommended, `pip install markdown`): full CommonMark spec compliance supporting all Markdown below plus images (``), definition lists, nested lists, auto-links (`<url>`), footnotes, and more.6364**Mode B — Built-in fallback** (zero dependencies): supports common AI-generated technical Markdown:6566- `#` through `######` headings67- paragraphs, bold, italic, inline code, and links68- fenced code blocks with optional language labels69- unordered and ordered lists, including checklist markers70- blockquotes71- pipe tables72- horizontal rules7374If using the fallback parser, install `markdown` (`pip install markdown`) for full capability.7576## Output Checks7778Before considering a PDF done, check:7980- the title and table of contents match the document,81- code blocks are readable and do not clip horizontally,82- tables fit the page (cross-page headers repeat automatically),83- Chinese text renders with a real font,84- page numbers are present and not overlapping content,85- page breaks do not leave major headings stranded at the bottom of a page.
zarttic