mdpress

mdPress

中文说明

Turn your Markdown into a real book — PDF, HTML, ePub, or a live-preview website — with one command.

$ mdpress build --format pdf,html,site,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

No templates to write. No config files required. Just point mdpress at a folder of .md files and mdPress figures out the rest.

What the output looks like

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:

Installation

Homebrew (macOS / Linux)

brew tap yeasy/tap
brew install mdpress

Go Install

go install github.com/yeasy/mdpress@latest

Docker

# 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 pdf

Download Binary

Download a pre-built binary for your platform from GitHub Releases.

Supported platforms: macOS (amd64 / arm64), Linux (amd64 / arm64), Windows (amd64 / arm64).

Get Started In 60 Seconds

# 1. Install mdpress (see Installation above)

# 2. Create a sample book and preview it
mdpress quickstart my-book
cd my-book
mdpress serve

Open 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,html

That's it. You now have a printable PDF and a self-contained HTML file.

Existing Projects

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. No configuration needed for most projects.

What You Get

HTML vs Site: What's the difference?

• html produces a single self-contained .html file 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.

• site produces 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.

Three Ways To Use It

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(zero config)"]
    C --> F["Build any format"]
    D --> F
    E --> F

Already have a docs folder?

mdpress build ./docs --format html
mdpress serve ./docs

Migrating from GitBook?

If your project has a SUMMARY.md, mdPress picks it up automatically:

mdpress build    # reads SUMMARY.md, just works
mdpress serve    # live preview

See the full GitBook migration guide.

Want full control?

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: true

Then mdpress build --format pdf generates a professional PDF with cover page, table of contents, and syntax highlighting.

Build from a GitHub repo

mdpress build https://github.com/yeasy/agentic_ai_guide --format html
mdpress serve https://github.com/yeasy/agentic_ai_guide

Built-In Themes

mdPress ships with three themes. Preview them all with mdpress themes preview:

$ 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.

Why mdPress Over Other Tools?

All Commands

Requirements

• Go 1.25+ 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 typst backend as a zero-dependency alternative to Chromium.

Chrome/Chromium Installation

Typst Installation (Optional)

For the Typst backend alternative, install Typst from typst.app.

Run mdpress doctor to check if everything is ready.

Learn More

Build From Source

git clone https://github.com/yeasy/mdpress.git
cd mdpress
make build        # binary at bin/mdpress
make test         # run all tests

Contributing

See CONTRIBUTING.md.

License

MIT License