md2pdf

The md2pdf tool supports a wide range of standard Markdown elements for PDF generation, including:

• Text Styling: Emphasis using *text*, **text**, or ___text___.
• Headings: Hierarchical headings from # Heading One down to ###### Heading Six.
• Lists:
  • Unordered lists using -.
  • Ordered/numbered lists using 1..
  • Support for nested sub-items in both list types.
• Tables: Standard Markdown pipe tables.
• Code Blocks: Fenced code blocks with syntax highlighting support.
• Blockquotes: Support for blockquotes, including nested code blocks within them.
• Images: Inline images using ![alt text](url) and images with optional titles ![alt text](url "title").
• Paragraphs: Standard text blocks. Note that the tool handles newlines within paragraphs by replacing them with spaces to maintain proper paragraph flow.

Use the md2pdf CLI utility to generate PDF documents from Markdown files, directories of Markdown files, or HTTP(S) URLs.

Basic Usage: To convert a single file:

md2pdf -i doc.md -o doc.pdf

To convert an entire directory of .md or .markdown files into a single PDF:

md2pdf -i /path/to/md/directory -o doc.pdf

To support non-Latin charsets (e.g., Cyrillic), you must specify the unicode encoding, a font file, and the font name ID.

Required flags:

• --unicode-encoding <string>: e.g., cp1251.
• --font-file <string>: Path to the font file.
• --font-name <string>: The Font name ID (e.g., Helvetica-1251).

Example:

md2pdf -i russian.md -o russian.pdf \
    --unicode-encoding cp1251 --font-file helvetica_1251.json --font-name Helvetica_1251

You can automatically generate a clickable Table of Contents (TOC) where each item corresponds to a header in your Markdown document. The TOC is included on the first page.

Use the --generate-toc flag to enable this feature.

Themes

md2pdf supports built-in light and dark themes. You can also provide a custom JSON theme file.

• Use --theme light or --theme dark.
• Use --theme /path/to/custom/theme.json for custom styling.

Syntax Highlighting

To enable colorized output for code blocks, you must provide the path to the syntax files used by the gohighlight module using the -s flag.

md2pdf -i syn_doc.md -s /usr/share/mdtopdf/syntax_files -o doc.pdf

To support non-Latin charsets (e.g., Russian), you must configure the PDF generator with a Unicode translator and ensure the Styler uses a matching font.

Programmatic usage (Go API)

Use mdtopdf.WithUnicodeTranslator when creating the renderer:

// Example for Windows-1251
pf := mdtopdf.NewPdfRenderer("", "", *output, "trace.log", mdtopdf.WithUnicodeTranslator("cp1251"))

CLI usage

Pass the encoding, font file, and font name via flags:

$ go run md2pdf.go -i russian.md -o russian.pdf \
    --unicode-encoding cp1251 --font-file helvetica_1251.json --font-name Helvetica_1251

// https://en.wikipedia.org/wiki/Windows-1251
pf := mdtopdf.NewPdfRenderer("", "", *output, "trace.log", mdtopdf.WithUnicodeTranslator("cp1251"))

Page Layout

• Orientation: Set to portrait (default) or landscape using --orientation.
• Page Size: Choose from A3, A4 (default), or A5 using --page-size.
• Pagination for Presentations: Use --new-page-on-hr to interpret horizontal rules (---) as page breaks. This is useful for creating slide-like presentations.

Footers

To include a footer containing the author, title, and page number, use the --with-footer flag. You must also provide the title and author names:

• --title <string>: The presentation or document title.
• --author <string>: The author's name.

Example for a presentation-style PDF:

go run md2pdf.go -i /path/to/md \
    -o /path/to/pdf --title "My Grand Title" --author "Random Bloke" \
    --theme dark --new-page-on-hr --with-footer

By default, md2pdf supports light and dark themes via the --theme flag.

To use a custom theme, create a JSON file defining font faces, sizes, and colors, then pass the path to that file using the --theme flag.

$ md2pdf --theme /path/to/custom/theme.json -i input.md -o output.pdf

You can install the md2pdf binary using one of the following methods:

Via Go install

Install directly to your $GOBIN directory:

$ go install github.com/solworktech/md2pdf/v2/cmd/md2pdf@latest

Via Homebrew

$ brew install md2pdf

Pre-built Binaries

Download pre-built binaries for your OS and architecture from the GitHub Releases page.

To convert a single Markdown file to PDF, use the -i (input) and -o (output) flags.

To convert multiple Markdown files in a directory into a single PDF, pass the directory path to the -i flag.

# Single file
$ go run md2pdf.go -i test.md -o test.pdf

# Multiple files in a directory
$ go run md2pdf.go -i /path/to/md/directory -o test.pdf

To automatically generate a Table of Contents (TOC) where each item corresponds to a header in the document and includes clickable navigation anchors, use the --generate-toc flag.

$ md2pdf --generate-toc -i input.md -o output.pdf