Publish Markdown as a polished docs site, printable PDF, portable HTML, and ePub.
$ mdpress build --format site,pdf,html,epub
✓ Loaded book.yaml (12 chapters)
✓ Parsed Markdown (technical theme)
✓ Generated PDF → _output/my-book.pdf
✓ Generated HTML → _output/my-book.html
✓ Generated site → _output/my-book_site/
✓ Generated ePub → _output/my-book.epub
Use book.yaml for full control, SUMMARY.md for GitBook-style projects, or zero-config discovery for a focused docs folder. For large repositories, point mdPress at the specific docs/book directory instead of the repo root.
- One source, multiple outputs: build a docs site, a shareable HTML file, a PDF, and an ePub from the same Markdown project.
- Fast writing loop:
mdpress servegives you live preview, search, sidebar navigation, and dark mode while you edit. - Works with existing Markdown: use
book.yaml,SUMMARY.md, or a clean folder of Markdown files. - Fits publishing workflows: migrate from GitBook/HonKit, export for review, or deploy the generated static site anywhere.
- Technical documentation that needs a deployable static site and a printable PDF
- Internal handbooks and playbooks maintained in Git
- Guides and books that should also ship as HTML or ePub
- Theme:
technical - Best output:
site+pdf - Good for product docs, API guides, operations runbooks
- Theme:
minimal - Best output:
site+html - Good for onboarding, internal standards, process docs
- Theme:
elegant - Best output:
pdf+epub - Good for long-form writing, essays, and narrative documentation
mdpress serve generates a documentation site with sidebar navigation, chapter structure, and built-in themes:
mdpress build --format site produces a polished multi-page site, ready for hosting:
Generated sites include:
- full-text search with
Cmd/Ctrl+K - sidebar navigation and per-page table of contents
- dark mode
brew tap yeasy/tap
brew install mdpressgo install github.com/yeasy/mdpress@latest# Minimal image (~15 MB, no PDF support)
docker run --rm -v "$(pwd):/book" ghcr.io/yeasy/mdpress build
# Full image (~300 MB, with Chromium for PDF)
docker run --rm -v "$(pwd):/book" ghcr.io/yeasy/mdpress:full build --format pdfDownload a pre-built binary for your platform from GitHub Releases.
Supported platforms: macOS (amd64 / arm64), Linux (amd64 / arm64), Windows (amd64 / arm64).
# 1. Install mdpress (see Installation above)
# 2. Create a sample book and preview it
mdpress quickstart my-book
cd my-book
mdpress serveOpen http://127.0.0.1:9000 in your browser to see the live-preview site. Edit any .md file and the browser refreshes automatically. If you want mdPress to launch the browser for you, run mdpress serve --open:
flowchart LR
A["Edit .md file"] --> B["mdPress detects change"]
B --> C["Rebuilds HTML"]
C --> D["Browser auto-refreshes"]
When you are ready to publish:
mdpress build --format pdf,htmlThat's it. You now have a printable PDF and a self-contained HTML file.
Already have a Markdown book project? Just point mdPress at it:
# Serve an existing project with live preview
mdpress serve ~/my-book/
# Build HTML output
mdpress build --format html ~/my-book/
# Build from a GitHub repository
mdpress build https://github.com/user/repo
# Migrate from GitBook/HonKit
mdpress migrate ~/my-gitbook-project/mdPress automatically detects book.yaml, book.json, or SUMMARY.md. Zero-config discovery works best when a directory clearly maps to a single docs set or book.
| Format | Command | Result |
|---|---|---|
mdpress build --format pdf |
A printable book with cover, TOC, page numbers, margins, and optional watermarks | |
| HTML | mdpress build --format html |
A single self-contained .html file you can email or upload |
| Site | mdpress build --format site |
A multi-page website ready for GitHub Pages or Netlify |
| ePub | mdpress build --format epub |
An ebook for Kindle, Apple Books, etc. |
| Typst | mdpress build --format typst |
PDF backend via the Typst CLI as a Chromium-free alternative |
| Preview | mdpress serve |
A local website with live reload |
-
htmlproduces a single self-contained.htmlfile with all chapters on one page. It includes a sidebar for navigation, embedded images, and everything needed to read offline. Great for sharing via email or uploading to a file host. -
siteproduces a multi-page static website with one HTML file per chapter, an index page, and sidebar navigation. Designed for deployment to GitHub Pages, Netlify, or any static hosting platform.
Use html when you need a single portable file. Use site when you want a proper documentation website.
mdPress figures out your project structure automatically:
flowchart TD
A["Your project folder"] --> B{"What's inside?"}
B -->|"Has book.yaml"| C["Use the explicit config\n(full control)"]
B -->|"Has SUMMARY.md"| D["Use GitBook-style TOC\n(great for migration)"]
B -->|"Just .md files"| E["Auto-discover chapters\n(best for a focused docs folder)"]
C --> F["Build any format"]
D --> F
E --> F
mdpress build ./docs --format html
mdpress serve ./docsIf your project has a SUMMARY.md, mdPress picks it up automatically:
mdpress build # reads SUMMARY.md, just works
mdpress serve # live previewSee the full GitBook migration guide.
Create a book.yaml:
book:
title: "My Book"
author: "Author Name"
chapters:
- title: "Preface"
file: "README.md"
- title: "Getting Started"
file: "chapter01/README.md"
style:
theme: "technical" # or "elegant", "minimal"
output:
toc: true
cover: trueThen mdpress build --format pdf generates a professional PDF with cover page, table of contents, and syntax highlighting.
mdpress build https://github.com/yeasy/agentic_ai_guide --format html
mdpress serve https://github.com/yeasy/agentic_ai_guidemdPress ships with three themes. List them with mdpress themes list:
$ mdpress themes list
technical — Clean and structured, ideal for technical documentation
elegant — Refined serif typography for books and essays
minimal — Light and distraction-free
Set style.theme in book.yaml to switch themes.
| Command | What it does |
|---|---|
mdpress build [source] |
Build PDF, HTML, site, or ePub |
mdpress serve [source] |
Start live preview with auto-reload |
mdpress quickstart [directory] |
Create a complete sample project |
mdpress migrate [directory] |
Migrate from GitBook/HonKit to mdPress |
mdpress init [directory] |
Generate book.yaml from existing Markdown files |
mdpress validate [directory] |
Check your config and files for errors |
mdpress doctor [directory] |
Verify your environment is set up correctly |
mdpress upgrade |
Check for and install a newer version of mdpress |
mdpress completion <shell> |
Generate shell completion scripts |
mdpress themes list|show|preview |
Explore built-in themes |
mdpress version |
Print the current version |
- Go 1.26+ for installation
- Chrome or Chromium — only needed for PDF output with the default backend. HTML, site, and ePub work without it.
- Typst CLI (optional) — enables the
--format typstbackend as a Chromium-free alternative when Typst is installed.
| System | Chrome install |
|---|---|
| macOS | brew install chromium or install Chrome |
| Ubuntu/Debian | sudo apt install chromium-browser |
| Windows | Install Google Chrome |
For the Typst backend alternative, install Typst from typst.app.
Run mdpress doctor to check if everything is ready.
| Document | Description |
|---|---|
| User Manual | Complete guide to using mdPress |
| Command manuals | Every flag and option explained |
| GitBook migration | Step-by-step migration guide |
| Architecture | How mdPress works internally |
| Roadmap | What's coming next |
| Changelog | Release history |
git clone https://github.com/yeasy/mdpress.git
cd mdpress
make build # binary at bin/mdpress
make test # run all testsSee CONTRIBUTING.md.