Introduction

Welcome to the mdBook Getting Started Guide.

mdBook is a command-line tool for creating books from Markdown files. It is written in Rust and produces clean, navigable HTML output that is ideal for project documentation, tutorials, and technical books.

In this guide you will learn how to:

1. Install mdBook using mise for reproducible tooling
2. Create a new book project
3. Configure your book
4. Write content in Markdown
5. Build and deploy to GitHub Pages with a GitHub Actions workflow

Prerequisites

Before getting started, you need Git and mise installed on your system.

Git

Install Git if you do not already have it:

mise

mise is a polyglot tool-version manager. It lets you pin exact tool versions per project so that every contributor uses the same setup.

Install mise:

curl https://mise.run | sh

Then activate it in your shell. Add one of the following to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

# Bash
eval "$(~/.local/bin/mise activate bash)"

# Zsh
eval "$(~/.local/bin/mise activate zsh)"

# Fish
~/.local/bin/mise activate fish | source

Restart your shell (or source the config file) and verify:

mise --version

What mise will manage

In this guide mise installs and manages mdBook so you do not need Rust or Cargo on your machine. The exact version is pinned in mise.toml at the project root.

Create a Project

Scaffold the book

Create a directory for your book, enter it, and set up mise:

mkdir mybook && cd mybook
git init

Create a mise.toml file to pin the mdBook version:

[tools]
"aqua:rust-lang/mdBook" = "0.5.2"

Let mise install the tool:

mise install

Verify the installation:

mdbook --version

Now initialise the book:

mdbook init

When prompted, accept the defaults. This creates the following structure:

mybook/
├── book.toml
└── src/
    ├── SUMMARY.md
    └── chapter_1.md

Preview locally

Start the built-in development server:

mdbook serve --open

This builds the book, opens it in your browser, and live-reloads whenever you save a file. The default address is http://localhost:3000.

Configuration

All configuration lives in book.toml at the project root. Here is a typical setup:

[book]
authors = ["Your Name"]
language = "en"
src = "src"
title = "My Awesome Book"

[build]
build-dir = "book"

[output.html]
git-repository-url = "https://github.com/youruser/yourrepo"

Key sections

[book]

[build]

[output.html]

Built-in search

mdBook ships with a client-side search engine that is enabled by default. It builds a search index at compile time and bundles it into the output. Readers can press S or click the magnifying-glass icon to search across the entire book — no server required.

You can configure search in book.toml:

[output.html.search]
enable = true            # enabled by default
limit-results = 30       # max results shown
use-hierarchical-headings = true  # show parent headings in results

The search index adds some weight to the final output. If your book is very large and you want to reduce the download size, you can set enable = false, but for most books the convenience far outweighs the extra kilobytes.

Further reading

See the mdBook documentation for the full list of options.

Mermaid Diagrams

mdbook-mermaid integrates Mermaid.js so you can write diagrams directly in fenced code blocks.

Installation

Add the plugin to mise.toml alongside mdBook:

[tools]
"aqua:rust-lang/mdBook" = "0.5.2"
"ubi:badboy/mdbook-mermaid" = "0.17.0"

Install:

mise install

Then run the one-time setup to copy the JavaScript files and update book.toml:

mdbook-mermaid install path/to/your/book

This adds mermaid.min.js and mermaid-init.js to your project root and configures the preprocessor in book.toml:

[output.html]
additional-js = ["mermaid.min.js", "mermaid-init.js"]

[preprocessor.mermaid]
command = "mdbook-mermaid"

Usage

Wrap your diagram code in a fenced block tagged mermaid:

```mermaid
graph LR
    A[Write Markdown] --> B[mdBook Build]
    B --> C[Static HTML]
    C --> D[GitHub Pages]
```

Renders as:

graph LR
    A[Write Markdown] --> B[mdBook Build]
    B --> C[Static HTML]
    C --> D[GitHub Pages]

More examples

Sequence diagram

sequenceDiagram
    participant B as Browser
    participant S as Server
    B->>S: GET /index.html
    S-->>B: HTML + JS
    B->>B: Render book

Flowchart

flowchart TD
    Start --> Install[mise install]
    Install --> Init[mdbook init]
    Init --> Write[Write content]
    Write --> Serve[mdbook serve]
    Serve --> Happy{Looks good?}
    Happy -- Yes --> Build[mdbook build]
    Happy -- No --> Write
    Build --> Deploy[Push to GitHub]

Mermaid supports many diagram types: flowcharts, sequence diagrams, Gantt charts, class diagrams, state diagrams, ER diagrams, pie charts, and more. See the Mermaid documentation for the full list.

Custom Styling

You do not need to replace the entire mdBook theme to tweak the look. A small custom CSS file loaded via additional-css is often all you need.

Setup

Create a theme/ directory next to your src/ folder and add a CSS file:

mkdir theme
touch theme/custom.css

Then reference it in book.toml:

[output.html]
additional-css = ["./theme/custom.css"]

Example customisations

Here is a small theme/custom.css that makes a few tasteful tweaks without fighting the default theme:

/* Slightly wider content area */
:root {
    --content-max-width: 850px;
}

/* Softer sidebar font size */
.sidebar {
    font-size: 0.9em;
}

/* Accent underline on h1 headings */
.content main h1 {
    border-bottom: 2px solid var(--sidebar-active);
    padding-bottom: 0.3em;
}

/* Rounded code blocks */
.content main pre {
    border-radius: 6px;
}

/* Make inline code stand out */
.content main code {
    padding: 0.1em 0.35em;
    border-radius: 3px;
}

Useful CSS variables

mdBook exposes CSS custom properties you can override. A few handy ones:

These variables change per theme (Light, Rust, Coal, Navy, Ayu), so your overrides automatically adapt to the reader’s chosen theme.

Going further

If CSS overrides are not enough, you can replace individual template files. Copy them from the mdBook source into your theme/ directory:

mdbook init --theme   # dumps all default theme files into theme/

You can then edit theme/index.hbs (the page template), theme/header.hbs, or any of the CSS files. mdBook will use your local copies instead of the built-in ones.

Tip: Only copy the files you actually want to change. Keeping the rest at their defaults means you automatically benefit from upstream improvements when you upgrade mdBook.

Add Content

The SUMMARY.md file

src/SUMMARY.md is the table of contents. mdBook uses it to determine the book structure, chapter ordering, and navigation. Every chapter must be listed here.

Example:

# Summary

[Introduction](./introduction.md)

# Part One

- [Getting Started](./part1/getting-started.md)
- [Core Concepts](./part1/core-concepts.md)

# Part Two

- [Advanced Topics](./part2/advanced.md)

• Lines starting with # create part headings (rendered as section dividers).
• Lines starting with - are chapters (linked Markdown files).
• Indented items become sub-chapters.

Writing Markdown

mdBook supports standard Markdown plus a few extensions:

• Code blocks with syntax highlighting (specify the language after the opening triple backticks)
• {{#include}} — include external files or parts of files
• {{#playground}} — embed Rust playgrounds (useful for Rust documentation)

Including files

You can include the contents of another file:

{{#include ../path/to/file.rs}}

Or include only specific lines:

{{#include ../path/to/file.rs:3:10}}

This is handy for keeping code examples in separate, testable files.

Creating a new chapter

1. Add an entry to SUMMARY.md
2. Create the corresponding .md file
3. Write your content

If the development server is running (mdbook serve), the browser will automatically reload with your changes.

Build and Deploy

Production build

Generate the static site:

mdbook build

The rendered HTML is written to the book/ directory (or whatever build-dir is set to in book.toml). You can serve this directory with any static file host.

Deploy to GitHub Pages

Repository setup

1. Push your project to a GitHub repository.
2. Go to Settings > Pages.
3. Under Build and deployment, set the source to GitHub Actions.

GitHub Actions workflow

Create .github/workflows/mdbook.yaml with the following content:

name: Deploy mdBook to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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 tools via mise
        uses: jdx/mise-action@v3

      - name: Build book
        run: mdbook build

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

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

How it works

1. On every push to main, the workflow triggers.
2. mise installs the exact mdBook version and all plugins from mise.toml.
3. mdbook build renders the book to book/ (preprocessors like mermaid, admonish, and katex run automatically).
4. The artifact is uploaded and deployed to GitHub Pages.

After the first successful run, your book is live at https://<username>.github.io/<repository>/.