prettypdf

README

go-pretty-pdf

Transform a directory of MDX files into a beautiful, print-ready PDF via headless Chrome.

Library + CLI. Use it as a composable Go library or as a standalone command-line tool.

Install

CLI (binary)

go install github.com/sazardev/go-pretty-pdf/cmd/pretty-pdf@latest

Library

go get github.com/sazardev/go-pretty-pdf

Requirements

• Go 1.26+
• Chrome or Chromium installed on the system (for PDF rendering)

Quick start

CLI

# Scaffold a new book project (interactive wizard)
pretty-pdf init my-book

# Build a PDF
pretty-pdf build --source my-book --out my-book.pdf

# Watch for changes and rebuild
pretty-pdf watch --source my-book --out my-book.pdf

# Validate MDX files
pretty-pdf check --source my-book

Library

package main

import (
	"context"
	"log"

	prettypdf "github.com/sazardev/go-pretty-pdf"
)

func main() {
	pdf, err := prettypdf.New(
		prettypdf.WithSourceDir("./docs"),
		prettypdf.WithOutputFile("output.pdf"),
		prettypdf.WithTitle("My Documentation"),
		prettypdf.WithAuthor("Jane Doe"),
	)
	if err != nil {
		log.Fatal(err)
	}

	if err := pdf.Build(context.Background()); err != nil {
		log.Fatal(err)
	}
}

How it works

MDX files → Parse frontmatter & markdown → Transpile components → Compose HTML → Render PDF

1. Parse — goldmark parses MDX files with YAML frontmatter
2. Transpile — custom components (<DeepDive>, <Warning>, <Axiom>) become styled HTML
3. Compose — HTML assembled with embedded template + CSS + auto-generated Table of Contents
4. Render — headless Chrome prints to PDF with headers, footers, and PDF bookmarks

Documents are sorted by their [X.Y.Z] frontmatter ID, not filename.

Trust model

MDX is parsed with raw HTML passthrough enabled, and custom components don't escape their inner content — this lets authors embed arbitrary HTML/CSS for rich documents, but it also means a .mdx file can contain a <script> tag that will execute during rendering. By default, headless Chrome's network access is blocked while rendering (see WithNetworkAccess), so scripts can't exfiltrate data or fetch remote content — but they still run. Only build PDFs from MDX you trust. See SECURITY.md for details.

MDX format

---
id: "[1.0.0]"
title: "Getting Started"
subtitle: "A simple introduction"
tags: [example, intro]
difficulty: "beginner"
status: complete
completeness: 100
depends_on: []
---

# Welcome to Your Book

This is the first chapter.

## Variables

You can use {{key}} syntax for variable substitution: running {{product}} v{{version}}.

Required frontmatter fields: id (format [X.Y.Z]), title.

Built-in components

Component	Usage	Appearance
<DeepDive>	<DeepDive title="Details">...</DeepDive>	Blue info panel
<Warning>	<Warning title="Note">...</Warning>	Orange warning panel
<Axiom>	<Axiom>...</Axiom>	Green italic quote

Register custom components via WithComponent():

prettypdf.WithComponent("Callout", func(attrs map[string]string, inner string) string {
	level := attrs["level"]
	return fmt.Sprintf(`<div class="callout callout-%s">%s</div>`, level, inner)
})

Configuration

Create a go-pretty-pdf.yml in your project:

title: "My Book"
subtitle: "A Complete Guide"
author: "Jane Doe"
source: book
output: out.pdf
theme: default

css: custom.css
template: custom-template.html

vars:
  product: "go-pretty-pdf"
  version: "1.0"

lint:
  require_frontmatter: [id, title]
  require_id_format: "[X.Y.Z]"
  no_duplicate_ids: true
  max_heading_depth: 3

render:
  timeout: 60s
  paper: a4
  margin_top: 20mm
  margin_bottom: 20mm
  margin_left: 15mm
  margin_right: 15mm
  header_title: "{{title}}"

Library API

// Constructor with functional options
pdf, err := prettypdf.New(opts...)

// All-in-one build pipeline
pdf.Build(ctx)

// Step-by-step pipeline
docs, _ := pdf.ParseDir()
errs := pdf.ValidateDoc(doc)
html, _ := pdf.ComposeHTML(docs)
pdf.Render(html)

// Validation-only
errs, _ := pdf.Validate(ctx)

Available options

Option	Description
WithSourceDir(dir)	MDX source directory (default: book)
WithOutputFile(path)	Output PDF path (default: out.pdf)
WithTitle(title)	Document title
WithSubtitle(sub)	Document subtitle
WithAuthor(author)	Document author
WithCSS(css)	Custom CSS content string
WithTemplate(html)	Custom HTML template string
WithTheme(t)	Pre-built theme (theme.Default, theme.Minimal)
WithComponent(name, handler)	Register custom MDX component
WithValidator(v)	Custom validation logic
WithTimeout(d)	Chrome render timeout (default: 60s)
WithHeaderTitle(t)	PDF header title
WithVerbose(bool)	Enable verbose logging
WithVars(map)	Variable substitution map
WithRenderMargins(t,b,l,r)	PDF margins in inches
WithPaperSize(w,h)	Paper size in inches
WithConfig(cfg)	Apply source/output/title/subtitle/author from config
WithConfigCSSAndTemplate(cfg)	Load CSS/template from config file paths
WithFullConfig(cfg)	Apply the entire config struct (source, CSS/template, theme, vars, render settings) in one call
WithNetworkAccess(bool)	Allow headless Chrome to make network requests while rendering (default: false, blocked)

Themes

Two themes are built in:

• Default — embedded print.css + template.html (professional, feature-rich)
• Minimal — stripped-down CSS, system font stack

prettypdf.WithTheme(theme.Minimal)

CLI reference

pretty-pdf build     Build a PDF from MDX source files
pretty-pdf check     Validate MDX files without building
pretty-pdf init      Scaffold a new book project (interactive wizard)
pretty-pdf watch     Watch for changes and rebuild automatically
pretty-pdf version   Print the version number

Global flags: --config, --source, --verbose, --no-color, --quiet

License

MIT — see LICENSE.

Documentation

Overview

Package prettypdf transforms MDX source files into print-ready PDFs via headless Chrome.

It is both a composable Go library and a CLI tool. The library exposes a pipeline with step-by-step methods (ParseDir, ValidateDoc, ComposeHTML, Render) and 18 functional options for full customization.

Quick start (library)

pdf, err := prettypdf.New(
	prettypdf.WithSourceDir("./docs"),
	prettypdf.WithOutputFile("output.pdf"),
	prettypdf.WithTitle("My Book"),
)
if err != nil {
	log.Fatal(err)
}
if err := pdf.Build(context.Background()); err != nil {
	log.Fatal(err)
}

Quick start (CLI)

go install github.com/sazardev/go-pretty-pdf/cmd/pretty-pdf@latest
pretty-pdf build --source ./docs --out out.pdf

MDX files require frontmatter with an `id` field in [X.Y.Z] format (e.g. `[1.0.0]`). Documents are sorted by ID, not filename. Variables in {{key}} syntax are substituted before parsing.

Built-in custom components: <DeepDive>, <Warning>, <Axiom>. Additional components can be registered via WithComponent().

Trust model

MDX is parsed with raw HTML passthrough enabled, and component transpilation does not escape inner content. Only build PDFs from MDX you trust — see SECURITY.md for details. Network access during rendering is blocked by default (see WithNetworkAccess).

Index

• func ComposeHTML(docs []*mdx.Document, opts ComposeOptions) (string, error)
• type ComposeOptions
  • func DefaultComposeOptions() ComposeOptions
• type Option
  • func WithAuthor(author string) Option
  • func WithCSS(css string) Option
  • func WithComponent(name string, handler mdx.ComponentHandler) Option
  • func WithConfig(cfg *config.Config) Option
  • func WithConfigCSSAndTemplate(cfg *config.Config) Option
  • func WithFullConfig(cfg *config.Config) Option
  • func WithHeaderTitle(title string) Option
  • func WithNetworkAccess(enabled bool) Option
  • func WithOutputFile(path string) Option
  • func WithPaperSize(width, height float64) Option
  • func WithRenderMargins(top, bottom, left, right float64) Option
  • func WithSourceDir(dir string) Option
  • func WithSubtitle(subtitle string) Option
  • func WithTemplate(html string) Option
  • func WithTheme(t theme.Theme) Option
  • func WithTimeout(d time.Duration) Option
  • func WithTitle(title string) Option
  • func WithValidator(v mdx.Validator) Option
  • func WithVars(vars map[string]string) Option
  • func WithVerbose(v bool) Option
• type PDF
  • func New(opts ...Option) (*PDF, error)
  • func (p *PDF) Build(ctx context.Context) error
  • func (p *PDF) ComposeHTML(docs []*mdx.Document) (string, error)
  • func (p *PDF) ParseDir() ([]*mdx.Document, error)
  • func (p *PDF) Render(html string) error
  • func (p *PDF) Validate(ctx context.Context) ([]mdx.ValidationError, error)
  • func (p *PDF) ValidateAll(docs []*mdx.Document) []mdx.ValidationError
  • func (p *PDF) ValidateDoc(doc *mdx.Document) []mdx.ValidationError

Functions

func ComposeHTML

func ComposeHTML(docs []*mdx.Document, opts ComposeOptions) (string, error)

Types

type ComposeOptions

type ComposeOptions = compose.Options

func DefaultComposeOptions

func DefaultComposeOptions() ComposeOptions

type Option

type Option func(*PDF)

func WithAuthor

func WithAuthor(author string) Option

func WithCSS

func WithCSS(css string) Option

func WithComponent

func WithComponent(name string, handler mdx.ComponentHandler) Option

func WithConfig

func WithConfig(cfg *config.Config) Option

func WithConfigCSSAndTemplate

func WithConfigCSSAndTemplate(cfg *config.Config) Option

WithConfigCSSAndTemplate loads CSS and template content from the file paths in cfg. Read failures are recorded as warnings and flushed to stderr by New() once all options have been applied, so ordering relative to WithVerbose does not matter.

func WithFullConfig

func WithFullConfig(cfg *config.Config) Option

WithFullConfig applies every field of cfg: source/output/title/subtitle /author (via WithConfig), CSS/template/theme (via WithConfigCSSAndTemplate), variable substitution (cfg.Vars), and render settings (cfg.Render: timeout, paper size, margins, header title). Unlike WithConfig and WithConfigCSSAndTemplate, which only cover a subset of Config, this is the single option needed to fully apply a loaded go-pretty-pdf.yml.

func WithHeaderTitle

func WithHeaderTitle(title string) Option

WithHeaderTitle sets the PDF page header text. If never called, New() defaults it to the document title (WithTitle/composeOpts.Title).

func WithNetworkAccess

func WithNetworkAccess(enabled bool) Option

WithNetworkAccess controls whether headless Chrome may make outbound network requests while rendering. It defaults to false: the composed HTML is a self-contained data URI, so network access is blocked to prevent SSRF/exfiltration from untrusted MDX content (e.g. a malicious <img> or <script> tag). Enable it only if your documents intentionally reference remote images, fonts, or other resources by URL.

func WithOutputFile

func WithOutputFile(path string) Option

func WithPaperSize

func WithPaperSize(width, height float64) Option

func WithRenderMargins

func WithRenderMargins(top, bottom, left, right float64) Option

func WithSourceDir

func WithSourceDir(dir string) Option

func WithSubtitle

func WithSubtitle(subtitle string) Option

func WithTemplate

func WithTemplate(html string) Option

func WithTheme

func WithTheme(t theme.Theme) Option

WithTheme applies a pre-built theme's CSS and template. It shares composeOpts.CSS/Template with WithCSS, WithTemplate, and the theme branch of WithConfigCSSAndTemplate — whichever of these options is applied last wins, since New() applies options in the order they're passed.

func WithTimeout

func WithTimeout(d time.Duration) Option

func WithTitle

func WithTitle(title string) Option

func WithValidator

func WithValidator(v mdx.Validator) Option

func WithVars

func WithVars(vars map[string]string) Option

func WithVerbose

func WithVerbose(v bool) Option

type PDF

type PDF struct {
	// contains filtered or unexported fields
}

func New

func New(opts ...Option) (*PDF, error)

func (*PDF) Build

func (p *PDF) Build(ctx context.Context) error

func (*PDF) ComposeHTML

func (p *PDF) ComposeHTML(docs []*mdx.Document) (string, error)

func (*PDF) ParseDir

func (p *PDF) ParseDir() ([]*mdx.Document, error)

func (*PDF) Render

func (p *PDF) Render(html string) error

func (*PDF) Validate

func (p *PDF) Validate(ctx context.Context) ([]mdx.ValidationError, error)

func (*PDF) ValidateAll

func (p *PDF) ValidateAll(docs []*mdx.Document) []mdx.ValidationError

func (*PDF) ValidateDoc

func (p *PDF) ValidateDoc(doc *mdx.Document) []mdx.ValidationError