mdBook is a command-line tool written in Rust for creating books using Markdown. It’s ideal for crafting product or API documentation, tutorials, course materials, or any content requiring a clean, navigable, and customizable presentation. Functionally similar to GitBook, its greatest advantage lies in speed.
Lightweight, Markdown-based syntax
Built-in search functionality
Syntax highlighting
Multiple themes for customizing output appearance
Preprocessors support — extend markdown rendering by modifying content before processing
Backend support for multiple output formats
Speed — built with Rust, performance is excellent
Even supports automated testing of Rust code
Installing mdBook
Since mdBook is developed in Rust, you need to install Rust first.
# curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh......
Rust is installed now. Great!
To get started you may need to restart your current shell.
This would reload your PATH environment variable to include
Cargo's bin directory ($HOME/.cargo/bin).
To configure your current shell, run:
source"$HOME/.cargo/env"# cargo versioncargo 1.65.0 (4bc8f24d3 2022-10-20)
After installing Rust, build and install mdBook via the command line. Once completed:
# mdbook init devops-manualDo you want a .gitignore to be created? (y/n)y
What title would you like to give the book?
devops-manual
2022-10-06 13:59:33 [INFO](mdbook::book::init): Creating a new book with stub content
All done, no errors...
# tree devops-manualdevops-manual
├── book
├── book.toml
└── src
├── SUMMARY.md
└── chapter_1.md
2 directories, 3 files
# mdbook serve --open2022-10-06 14:04:05 [INFO](mdbook::book): Book building has started
2022-10-06 14:04:05 [INFO](mdbook::book): Running the html backend
2022-10-06 14:04:05 [INFO](mdbook::cmd::serve): Serving on: http://localhost:3000
2022-10-06 14:04:05 [INFO](mdbook): Opening web browser
2022-10-06 14:04:05 [INFO](warp::server): Server::run; addr=127.0.0.1:3000
2022-10-06 14:04:05 [INFO](warp::server): listening on http://127.0.0.1:3000
2022-10-06 14:04:05 [INFO](mdbook::cmd::watch): Listening for changes...
The --open flag automatically opens your default web browser to view the book.
Directory Structure of a New mdBook Project
book.toml: Configuration file describing how to build the eBook, written in TOML format
SUMMARY.md: Located at src/SUMMARY.md, this file lists all chapters in the book. You must add each chapter here before it can be viewed.
src: Contains the source files for the book. Each chapter has its own Markdown file.
book: Stores the generated HTML files. After running mdbook build, static files for the eBook are generated here, ready to be hosted on services like GitHub Pages.
Now, to write a DevOps eBook, simply define your structure, then write each chapter one by one.
After completing these steps, just run mdbook build, map the book directory to your Nginx root path, and configure the virtual host — isn’t that simple?