Creating a Book or Documentation with mdBook

create-book-mdbook.md

This page describes how to create a modern online book (or) tech documentation from the Markdown files with mdBook, developed and maintained by the Rust Programming Language community, and how to serve it locally.

mdBook is a great tool for creating product or API documentation, tutorials, guides, course materials or anything that requires a clean, easily navigable and customizable.

Download and install the mdbook CLI tool using the binary file,

$ curl -LO https://github.com/rust-lang/mdBook/releases/download/v0.4.48/mdbook-v0.4.48-x86_64-unknown-linux-gnu.tar.gz

Please, note that's for the Linux x86_64 platform. For any other platform, please see https://github.com/rust-lang/mdBook/releases.

$ tar -xzvf mdbook-v0.4.48-x86_64-unknown-linux-gnu.tar.gz
$ sudo install mdbook /usr/local/bin/mdbook

Create a book,

$ mdbook init first-sample-book

Build a book locally,

$ cd first-sample-book
$ mdbook build

2025-04-21 17:11:53 [INFO] (mdbook::book): Book building has started
2025-04-21 17:11:53 [INFO] (mdbook::book): Running the html backend

Serve a book locally,

$ cd first-sample-book
$ mdbook serve --port 4000 --open

Default port number is 3000. I've set it to 4000. The --open option opens the compiled book in a web browser automatically.

For mdBook structure and format, please see https://rust-lang.github.io/mdBook/format/summary.html.

For set up automated testing and deployment of books using mdBook and hosting on GitHub Pages, please see https://github.com/rust-lang/mdBook/wiki/Automated-Deployment.