Index Page

mdBook is a command line tool and Rust crate to create books using Markdown (as by the CommonMark specification) files. It's very similar to Gitbook but written in Rust.

What you are reading serves as an example of the output of mdBook and at the same time as a high-level documentation.

mdBook is free and open source, you can find the source code on GitHub. Issues and feature requests can be posted on the GitHub issue tracker.

API docs

Alongside this book you can also read the API docs generated by Rustdoc if you would like to use mdBook as a crate or write a new renderer and need a more low-level overview.

License

mdBook, all the source code, is released under the Mozilla Public License v2.0.

Chapter 1

Demo

There is some minimal boilerplate that is the same for every new book. It's for this purpose that mdBook includes an init command.

The init command is used like this:

mdbook init

When using the init command for the first time, a couple of files will be set up for you:

book-test/
├── book
└── src
    ├── chapter_1.md
    └── SUMMARY.md

• The src directory is where you write your book in markdown. It contains all the source files, configuration files, etc.

• The book directory is where your book is rendered. All the output is ready to be uploaded to a server to be seen by your audience.

• The SUMMARY.md file is the most important file, it's the skeleton of your book and is discussed in more detail in another chapter

Tip: Generate chapters from SUMMARY.md

When a SUMMARY.md file already exists, the init command will first parse it and generate the missing files according to the paths used in the SUMMARY.md. This allows you to think and create the whole structure of your book and then let mdBook generate it for you.

Specify a directory

The init command can take a directory as an argument to use as the book's root instead of the current working directory.

mdbook init path/to/book

--theme

When you use the --theme flag, the default theme will be copied into a directory called theme in your source directory so that you can modify it.

The theme is selectively overwritten, this means that if you don't want to overwrite a specific file, just delete it and the default file will be used.

Chapter 1

There is some minimal boilerplate that is the same for every new book. It's for this purpose that mdBook includes an init command.

The init command is used like this:

mdbook init

When using the init command for the first time, a couple of files will be set up for you:

book-test/
├── book
└── src
    ├── chapter_1.md
    └── SUMMARY.md

• The src directory is where you write your book in markdown. It contains all the source files, configuration files, etc.

• The book directory is where your book is rendered. All the output is ready to be uploaded to a server to be seen by your audience.

• The SUMMARY.md file is the most important file, it's the skeleton of your book and is discussed in more detail in another chapter

Tip: Generate chapters from SUMMARY.md

When a SUMMARY.md file already exists, the init command will first parse it and generate the missing files according to the paths used in the SUMMARY.md. This allows you to think and create the whole structure of your book and then let mdBook generate it for you.

Specify a directory

The init command can take a directory as an argument to use as the book's root instead of the current working directory.

mdbook init path/to/book

--theme

When you use the --theme flag, the default theme will be copied into a directory called theme in your source directory so that you can modify it.

The theme is selectively overwritten, this means that if you don't want to overwrite a specific file, just delete it and the default file will be used.