Introduction

  • Josh Rotenberg
  • New to Write the Docs community
  • Staff Engineer, Developer Experience at American Express
  • Like to write code, end up playing documentation police
  • Using/learning Rust for about a year

What is mdbook

  • Command line documentation site generator
  • Markdown (CommonMark spec) to HTML
  • Written in Rust
  • TOML Configuration
  • Markdown-based content layout (SUMMARY.md)
  • Preprocessor and/or Alternative Backend (i.e. PDF, epub, etc.) support via plugins
  • Also a Rust library
  • Not a full featured static site generator like Hugo or Docusaurus
  • Open source (Mozilla Public License v2.0)

How to mdbook

Initialize a new book

$ mdbook init --title="my new book" --ignore=git my-new-book
2022-02-22 16:32:41 [INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

$ tree my-new-book 
my-new-book
├── book
├── book.toml
└── src
    ├── SUMMARY.md
    └── chapter_1.md

2 directories, 3 files

Add some basic content and structure

The SUMMARY.md explicitly determines the structure of the output. Let's add an introduction, an appendix and another chapter with a sub section. A README.md in a directory will become an index.html in the generated output:

# Summary

[Introduction](./intro.md)
- [Chapter 1](./chapter_1.md)
- [Chapter 2](./chapter_2.md)
    - [Notes](./chapter_2/README.md)
[Appendix](./appendix.md)

Config the config

The first section is created for us by the init command. In this example, we've also added some options for the search functionality. Plugins such as preprocessors and alternative backends can also be configured here.

[book]
authors = ["josh rotenberg"]
language = "en"
multilingual = false
src = "src"
title = "my new book"

[rust]
edition = "2021"

[output.html.search]
limit-results = 20
use-boolean-and = true
boost-title = 2
boost-hierarchy = 2
boost-paragraph = 1
expand = true
heading-split-level = 2

Integrate Continuously

Deploying an mdbook to GitHub Pages is easy:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
           mdbook-version: 'latest'

      - run: mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book

Who uses mdbook

Official Rust Projects

Other Rust Projects

Other Projects