md-render

Render a local Markdown file or GitHub URL as a styled PDF or standalone HTML document.

The tool sends Markdown to GitHub's /markdown API, applies the selected GitHub or Zed-inspired document template, syntax highlighting, and Twemoji, then optionally prints the result with Playwright Chromium.

Demo

This image shows the README rendered as a PDF with the default settings.

Install

uv tool install git+https://github.com/MilkClouds/md-render

The first PDF export downloads Playwright Chromium, which is about 170 MB. HTML export does not require Chromium.

PDF output

md-render README.md
md-render README.md -o build/readme.pdf
md-render README.md --template zed
md-render README.md --markdown-mode markdown
md-render README.md --theme dark
md-render README.md --scale 0.85
md-render README.md --page-size Letter --landscape

The default output path is <basename>.pdf. Use --keep-html to retain the intermediate HTML next to the PDF.

The default API mode is gfm, which renders each source newline as a hard line break. Use --markdown-mode markdown to keep single newlines as soft breaks while retaining paragraph breaks and tables.

HTML output

md-render README.md --html
md-render README.md --html --template zed
md-render README.md --html -o build/readme.html

The default HTML output path is <basename>.html. The generated file uses CDN-hosted styles and scripts, so opening it requires network access unless the browser has already cached those assets.

Remote sources

md-render https://github.com/owner/repo/blob/main/FILE.md
md-render https://raw.githubusercontent.com/owner/repo/main/FILE.md

GitHub blob URLs are converted to raw content URLs. Their owner/repo context is passed to the Markdown API for issue and user references.

Relative local images are embedded as data URLs. Relative images in remote documents are resolved against the source URL.

Authentication

If the gh CLI is installed and authenticated, the tool reads its token automatically. You can also set GITHUB_TOKEN or pass --token. Authentication is required for private repositories and raises the GitHub API rate limit from 60 to 5000 requests per hour.

Rendering pipeline

1. Read Markdown from a local path or URL.
2. Render Markdown through GitHub's /markdown API using the selected mode.
3. Resolve relative image paths.
4. Wrap the result with the selected document template, highlight.js, and Twemoji.
5. Write HTML directly, or print it to PDF with Playwright Chromium.

The GitHub API handles GFM features such as alerts, task lists, tables, footnotes, and emoji shortcodes. --template github uses github-markdown-css; --template zed uses an independent CSS implementation inspired by Zed Markdown Preview and the MIT-licensed Zed One palette. The default is github.

PDF layout

The default scale is 1.0, which keeps the 16 px body text used by github-markdown-css. This is comfortable on screen but relatively large for a dense A4 report. Use --scale 0.85 when page count matters.

Tables, images, and code blocks are kept together when possible. A large table that does not fit in the remaining page space may therefore leave blank space before moving to the next page.

Limits

• Rendering requires access to the GitHub API and jsDelivr CDN.
• Mermaid blocks are not rendered because Mermaid support is provided by the full GitHub page, not the /markdown API.
• HTML files reference CDN assets and are not fully self-contained.
• The unauthenticated GitHub API limit is 60 requests per hour.

Development

The package version is derived from Git tags through hatch-vcs. Release tags should use a PEP 440 compatible version such as v0.2.0.

uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build

See also

• jmaupetit/md2pdf
• simonhaenisch/md-to-pdf

License

MIT