Publishing

This chapter covers building your mdBook and deploying it for readers. The publishing process transforms your Markdown source files into a polished, navigable website.

Building Locally

Build your book with:

mdbook build

This generates static HTML in the book/ directory (or the path specified in book.toml).

Preview the build:

mdbook serve --open

This starts a local server and opens your browser. Use this during development for live preview with automatic rebuilding on file changes.

Build Output Structure

The generated book/ directory contains:

book/
├── index.html              # Book landing page
├── print.html              # Single-page print version
├── searchindex.json        # Search index
├── searchindex.js          # Search functionality
├── 404.html                # Not found page
├── fonts/                  # Embedded fonts
├── css/                    # Stylesheets
├── FontAwesome/            # Icons
├── clipboard.min.js        # Copy functionality
├── highlight.js            # Syntax highlighting
├── highlight.css           # Highlighting styles
├── book.js                 # Book functionality
├── introduction.html       # Chapter pages
├── getting-started.html
└── ...

All assets are included. The output is fully static and requires no server-side processing.

Deployment Options

GitHub Pages

The most common deployment target. Two approaches:

Approach 1: Deploy from /docs

Configure mdBook to output to docs/:

[build]
build-dir = "docs"

Build and commit:

mdbook build
git add docs/
git commit -m "Build book for GitHub Pages"
git push

In GitHub repository settings:

Go to Settings > Pages
Source: "Deploy from a branch"
Branch: main (or your default branch)
Folder: /docs

Approach 2: GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy mdBook

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install mdBook
        run: |
          mkdir -p $HOME/.local/bin
          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C $HOME/.local/bin
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Build book
        run: mdbook build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'book'

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Enable GitHub Pages:

Go to Settings > Pages
Source: "GitHub Actions"

This deploys automatically on every push to main.

Netlify

Create netlify.toml in repository root:

[build]
  command = "curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz && ./mdbook build"
  publish = "book"

[build.environment]
  RUST_BACKTRACE = "1"

[[redirects]]
  from = "/*"
  to = "/404.html"
  status = 404

Connect your repository to Netlify. Builds trigger automatically on push.

Vercel

Create vercel.json:

{
  "buildCommand": "curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz && ./mdbook build",
  "outputDirectory": "book"
}

Import the repository in Vercel's dashboard.

CloudFlare Pages

In CloudFlare Pages settings:

Build command: curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz && ./mdbook build
Build output directory: book

Self-Hosted

For self-hosted deployment, copy the book/ directory to any static file server:

mdbook build
rsync -avz book/ user@server:/var/www/mybook/

Configure your web server (nginx, Apache, Caddy) to serve static files.

Example nginx configuration:

server {
    listen 80;
    server_name book.example.com;
    root /var/www/mybook;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
}

Custom Domain Setup

For GitHub Pages with a custom domain:

Add CNAME file to your source:

echo "book.yourdomain.com" > CNAME

Configure DNS:
- For apex domain: A record pointing to GitHub's IPs
- For subdomain: CNAME record pointing to yourusername.github.io
Enable HTTPS in repository settings after DNS propagates.

For other platforms, follow their custom domain documentation.

Build Optimization

Reducing Build Size

Minimize the output size for faster loading:

[output.html]
# Disable features you don't need
google-analytics = ""  # Remove analytics
mathjax-support = false  # If not using math

[output.html.playground]
editable = false  # Disable in-browser code editing

Caching for CI

Cache mdBook binary in CI for faster builds:

- name: Cache mdBook
  uses: actions/cache@v4
  with:
    path: ~/.local/bin/mdbook
    key: mdbook-${{ runner.os }}-v0.4.36

- name: Install mdBook
  run: |
    if [ ! -f ~/.local/bin/mdbook ]; then
      mkdir -p ~/.local/bin
      curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C ~/.local/bin
    fi
    echo "$HOME/.local/bin" >> $GITHUB_PATH

Pre-Publication Checklist

Before deploying a new version:

Content Checks

All chapters complete
mdbook build produces no warnings
Links verified (internal and external)
Code examples tested
Spelling and grammar checked

Configuration Checks

book.toml metadata accurate (title, author, description)
Repository URL correct (for edit links)
Theme configured appropriately
Search enabled

Deployment Checks

Build succeeds in CI environment
Custom domain configured (if applicable)
HTTPS enabled
404 page works

Versioning Releases

For books with multiple versions:

Branch-Based Versions

Maintain separate branches for major versions:

main       → latest version
v1.x       → version 1 maintenance
v2.x       → version 2 maintenance

Deploy each branch to a different subdirectory or subdomain.

Add a version dropdown using custom JavaScript or a preprocessor. The specific approach depends on your hosting platform and requirements.

Release Tags

Tag releases for reference:

git tag -a v1.0.0 -m "Version 1.0.0 release"
git push origin v1.0.0

Monitoring

After deployment, verify:

Accessibility — All pages load correctly
Search — Search functionality works
Navigation — Sidebar links function
Mobile — Responsive layout works on small screens
Performance — Pages load in reasonable time

Use browser developer tools to check for console errors or failed resource loads.

Continuous Deployment

With GitHub Actions (or similar CI), every push to main triggers a fresh build and deploy. This enables:

Frequent small updates
Confidence that the deployed version matches source
Rollback by reverting commits

Monitor your CI pipeline for build failures. Fix broken builds immediately — a failing pipeline blocks all updates.

Next Steps

With your book deployed, the next chapter covers best practices — patterns that have proven effective across many documentation projects.

Writing Books with Claude Code