CLI Reference

Overview

leafpress [OPTIONS] COMMAND [ARGS]...

Command	Description
`convert`	Convert an MkDocs site to PDF, DOCX, HTML, ODT, and/or EPUB
`doctor`	Check your environment and optional dependency status
`import`	Import Word, PowerPoint, Excel, or LaTeX documents to Markdown
`init`	Generate a starter `leafpress.yml` branding config
`info`	Display detected MkDocs site info
`fetch-diagrams`	Fetch diagrams from external sources (URLs, Lucidchart)
`ui`	Launch the desktop menu bar / system tray app

Global Options

Option	Description
`--version`, `-v`	Show the leafpress version and exit

`convert`

Convert an MkDocs site to PDF, DOCX, HTML, ODT, and/or EPUB.

leafpress convert [SOURCE] [OPTIONS]

Arguments

Argument	Description
`SOURCE`	Path to a local MkDocs project directory, or a git URL. Optional — auto-detected if omitted (see Project Auto-Detection)

Options

Option	Default	Description
`--output`, `-o`	`output/`	Output directory for generated files
`--format`, `-f`	`pdf`	Output format: `pdf`, `docx`, `html`, `odt`, `epub`, `markdown`, `both` (pdf+docx), or `all`
`--config`, `-c`	(auto-detect)	Path to `leafpress.yml` branding config
`--mkdocs-config`	(auto-detect)	Override path to `mkdocs.yml`, or `zensical.toml` (experimental)
`--branch`, `-b`	(default branch)	Git branch to clone (remote sources only)
`--cover-page` / `--no-cover-page`	`--cover-page`	Include a cover page
`--toc` / `--no-toc`	`--toc`	Include a table of contents
`--open`	`false`	Open the generated file(s) after conversion
`--local-time`	`false`	Use the local timezone instead of UTC for the cover date, footer generation date, and Markdown front matter. Also `LEAFPRESS_LOCAL_TIME=true`
`--watermark`, `-w`	(none)	Watermark text overlay (e.g. `"DRAFT"`, `"CONFIDENTIAL"`) in PDF, DOCX, HTML, ODT, and EPUB. Markdown export has no watermark
`--footer-date` / `--no-footer-date`	(config)	Include document generation date in footer
`--sanitize-html` / `--no-sanitize-html`	(auto)	Strip scripts, event handlers, and other active content from page HTML. The default is on for git URL sources and otherwise follows `sanitize_html` in `leafpress.yml`
`--mermaid` / `--no-mermaid`	(config)	Render mermaid diagrams via the configured server. `--no-mermaid` keeps them as code blocks and sends nothing
`--fetch-diagrams`	`false`	Fetch diagrams from external sources before converting. Uses `-c`, or `leafpress.yml`/`.yaml` in the source directory. Ignored, with a warning, for git URL sources
`--verbose`	`false`	Show warnings, debug details, and full traceback on error

Examples

# Auto-detect project and convert to PDF
leafpress convert

# Convert local project to PDF
leafpress convert /path/to/project

# Convert to both PDF and DOCX
leafpress convert /path/to/project -f both

# Convert to HTML, ODT, or EPUB
leafpress convert /path/to/project -f html
leafpress convert /path/to/project -f odt
leafpress convert /path/to/project -f epub

# Convert to all formats (PDF, DOCX, HTML, ODT, EPUB)
leafpress convert /path/to/project -f all

# Convert with branding config, output to custom dir
leafpress convert /path/to/project -c leafpress.yml -o dist/

# Convert from a git URL (specific branch)
leafpress convert https://github.com/org/repo -b main -f pdf

# Use local timezone for the cover page date
leafpress convert . --local-time

# Add a watermark overlay
leafpress convert . -f pdf -w "DRAFT"
leafpress convert . -f all --watermark "CONFIDENTIAL"

# Fetch diagrams before converting
leafpress convert . -c leafpress.yml --fetch-diagrams

# No cover page, open after conversion
leafpress convert . --no-cover-page --open

# Monorepo — combine multiple MkDocs projects into one document
# (requires "projects" in leafpress.yml, see Configuration > Monorepo support)
leafpress convert /path/to/monorepo -c leafpress.yml -f pdf

# Use a specific mkdocs.yml
leafpress convert /path/to/project --mkdocs-config /path/to/docs/mkdocs.yml

Config auto-detection

leafpress looks for leafpress.yml or leafpress.yaml in the project root automatically. You only need --config if the file is elsewhere.

leafpress also loads a .env file from the project root and applies any LEAFPRESS_* environment variables on top of the YAML config. See Configuration.

Verbose output

By default, LeafPress surfaces all warnings during conversion — for example, SVG logo skips, failed Markdown extensions (with install suggestions), and missing image/asset references (listed by page and path). Mermaid diagram pages also report how many diagrams were rendered.

Pass --verbose to additionally show debug-level detail and full tracebacks on error:

leafpress convert . --verbose

`doctor`

Check your environment and show the status of optional dependencies. Useful for diagnosing missing system libraries (e.g. WeasyPrint's cairo/pango) or confirming your install is complete.

leafpress doctor [OPTIONS]

Options

Option	Default	Description
`--verbose`	`false`	Also check core dependencies (normally guaranteed to be installed)
`--debug`	`false`	Show captured error output from failed checks for troubleshooting

Checks performed

Check	What it verifies
Python version	Python >= 3.13
WeasyPrint	Python package installed (optional — needed for PDF output)
WeasyPrint system libs	cairo, pango, gdk-pixbuf C libraries work correctly
PyQt6	Python package installed (optional — needed for desktop UI)
pyobjc (macOS only)	Cocoa bindings installed (optional — needed for macOS UI)

With --verbose, all 18 core dependencies are also checked.

Exit codes

0 — all checks passed
1 — one or more checks failed

Examples

# Quick check of optional dependencies
leafpress doctor

# Include core dependency checks
leafpress doctor --verbose

# Show captured stderr from failed checks
leafpress doctor --debug

`import`

Import one or more Word, PowerPoint, Excel, or LaTeX documents and convert them to Markdown.

leafpress import SOURCES... [OPTIONS]

Arguments

Argument	Description
`SOURCES...`	One or more `.docx`, `.pptx`, `.xlsx`, or `.tex` files or URLs to import. You can mix local files and URLs in a single command.

Options

Option	Default	Description
`--output`, `-o`	`<stem>.md`	Output `.md` file path or directory. Must be a directory when importing multiple files. Without it, local files are written next to the source and URLs to the current directory.
`--extract-images` / `--no-extract-images`	`--extract-images`	Extract embedded images to an `assets/` folder
`--code-styles`	(none)	Comma-separated Word style names to treat as code blocks (DOCX only)
`--notes` / `--no-notes`	`--notes`	Include speaker notes as blockquotes (PPTX only)

Examples

# Import a single Word document (creates report.md alongside report.docx)
leafpress import report.docx

# Import a PowerPoint presentation
leafpress import deck.pptx

# Import a LaTeX document
leafpress import paper.tex

# Import from a URL
leafpress import https://example.com/paper.tex
leafpress import https://example.com/report.docx -o docs/

# Mix local files and URLs
leafpress import report.docx https://example.com/paper.tex -o docs/

# Import all supported files in a directory
leafpress import *.docx *.pptx *.xlsx *.tex

# Output all results to a directory
leafpress import *.docx *.pptx -o docs/

# Import PPTX without speaker notes
leafpress import deck.pptx --no-notes

# Specify output path for a single file
leafpress import report.docx -o docs/report.md

# Skip image extraction
leafpress import deck.pptx --no-extract-images

# Treat custom Word styles as code blocks
leafpress import report.docx --code-styles "Code Block,Source Code"

Batch behavior

Failures don't stop the batch. Each error names its source file, and the command exits with code 1 if any file failed.
Summary. After importing more than one file, a table summarizes each source: status, output or error, and image and warning counts.
Name collisions are refused. Two inputs that would write the same output file (e.g. a/report.docx and b/report.docx with -o docs/) would otherwise overwrite each other, so the second is refused.
Downloads. URLs must be http(s) and are capped at 200 MB. See Document Import for format-specific details.

`init`

Generate a starter leafpress.yml branding config file.

leafpress init [PATH]

Arguments

Argument	Default	Description
`PATH`	`.`	Directory to create the config file in

Example

leafpress init
# Creates ./leafpress.yml

leafpress init /path/to/project
# Creates /path/to/project/leafpress.yml

`info`

Display detected site info (from mkdocs.yml, or zensical.toml for Zensical projects): navigation structure, markdown extensions, and git information.

leafpress info [SOURCE] [OPTIONS]

Arguments

Argument	Description
`SOURCE`	Path to a local MkDocs directory or git URL. Optional — auto-detected if omitted (see Project Auto-Detection)

Options

Option	Description
`--branch`, `-b`	Git branch (for remote git URLs)

Example

# Auto-detect project
leafpress info

# Explicit path
leafpress info /path/to/project
leafpress info https://github.com/org/repo -b main

`fetch-diagrams`

Fetch diagrams from external sources (URLs, Lucidchart API) defined in your leafpress.yml config.

leafpress fetch-diagrams [OPTIONS]

Options

Option	Default	Description
`--config`, `-c`	(auto-detect)	Path to `leafpress.yml` config file
`--refresh`	`false`	Force re-download even if cached files exist
`--verbose`	`false`	Show full traceback on error

Examples

# Fetch using auto-detected leafpress.yml
leafpress fetch-diagrams

# Specify a config file
leafpress fetch-diagrams -c path/to/leafpress.yml

# Force re-download, ignoring cache
leafpress fetch-diagrams --refresh

How it works:

Checks first. Before any request is made, every dest is validated: it must stay inside the directory containing leafpress.yml, and no two sources may share one. The Lucidchart token is also checked, if any source needs it.
Downloads in parallel, up to 4 at a time. Each download is capped at 50 MB.
Reports all failures together. If some downloads fail, the rest still finish, then the command lists every failure and exits with code 1.

See Diagrams for full configuration and usage details.

`ui`

Launch the leafpress menu bar / system tray desktop application.

leafpress ui [OPTIONS]

Options

Option	Default	Description
`--show`	`false`	Open the conversion window immediately on launch

Example

leafpress ui
leafpress ui --show

Requires the [ui] extra. See Desktop UI for installation and usage details.

Project Auto-Detection

When SOURCE is omitted from convert or info, leafpress automatically searches for an MkDocs project:

Search order:

Git repo root — if you're inside a git repository, leafpress checks the repo root for a site config
Git root / docs/ — checks a docs/ subdirectory of the repo root
Current directory — the directory you ran leafpress in (if not already checked)
CWD / docs/ — checks a docs/ subdirectory of CWD

The first directory containing mkdocs.yml, mkdocs.yaml, or zensical.toml is used. If a directory has both mkdocs.yml and zensical.toml, mkdocs.yml wins; pass --mkdocs-config zensical.toml to use the Zensical config (see Zensical Projects).

Examples

# Inside a git repo with mkdocs.yml at root
cd ~/projects/my-docs
leafpress convert -f pdf

# Inside a git repo with mkdocs.yml in docs/
cd ~/projects/my-app
leafpress convert -f all -o dist/

# Not in a git repo — uses CWD
cd /tmp/some-docs
leafpress info

If no site config is found, leafpress exits with an error and suggests specifying the path explicitly.