Docco

Plugin-based Markdown to PDF converter.

Installation

uv add docco
uv run playwright install chromium --only-shell

Usage

docco input.md                        # output: input.pdf (next to input file)
docco input.md -o output/             # output: output/input.pdf
docco chapter1.md chapter2.md -o output/
docco page.html -o output/            # HTML input (skips Markdown stages)
docco -o output/                      # uses 'file' key from docco.toml
docco input.md --config path/to/docco.toml

Configuration

Create docco.toml in your project root (see docco.example.toml for all options). This configuration will apply to all documents parsed by Docco.

Each document can have its own document-specific configuration as well. Create a .toml file with the same name as the document, e.g.:

my_doc.md
my_doc.toml

These config files usually contain variable definitions, like document title and version.

The document-specific configuration overrules the project configuration (per-key override; lists are appended).

Plugins

All plugins run automatically. Config sections in docco.toml provide per-plugin settings.

Plugin	Description
vars	$$varname$$ substitution
translation	Language filtering and PO-based translation
inline	<!-- inline src="file" --> embedding
pdf2svg	<!-- pdf2svg --> PDF page to SVG extraction
html	Markdown to HTML conversion
toc	Table of contents (<!-- toc -->)
page_bg	<!-- page-bg --> background image injection
page	Page breaks and orientation changes
urls	URL absolutization and validation
htmlhint	HTML linting (opt-in)
pdf	PDF rendering via Playwright/Chromium
diffpdf	Skip writing identical PDFs
dpi	Image DPI downscaling and validation
upload	SFTP upload of the generated PDF

For information on writing your own plugins, see the plugin development guide.

Error Handling

When the pipeline fails, Docco saves the intermediate output (the content at the point of failure, e.g. .intermediate.html) to the output directory and logs the filename. This makes it easier to inspect what the document looked like before the error.

To disable this behavior, add to docco.toml:

[error]
save_intermediate = false

Acknowledgements

Docco builds on the following projects:

• markdown-it-py -- Markdown parsing and HTML conversion
• mdit-py-plugins -- markdown-it extensions (attributes, tables, anchors)
• Playwright -- headless Chromium for PDF rendering
• paged.js -- CSS paged media polyfill (table of contents, page breaks)
• diffpdf -- visual PDF comparison
• PyMuPDF -- PDF/SVG manipulation and DPI validation
• polib -- PO file parsing for translations
• Translate Toolkit -- translation utilities
• HTMLHint -- HTML linting