|Linux / OS X|
Documentation for mdBook has been written in Markdown and is using mdBook to generate the online book-like website you can read. The documentation uses the latest version on GitHub and showcases the available features.
Binaries are available for download here. Make sure to put the path to the binary into your
This requires Rust and Cargo to be installed. Once you have installed Rust, type the following in the terminal:
This will download and compile mdBook for you, the only thing left to do is to add the Cargo bin directory to your
cargo install mdbook
Note for automatic deployment
If you are using a script to do automatic deployments using Travis or another CI server, we recommend that you specify a semver version range for mdBook when you install it through your script! This will constrain the server to install the latests non-breaking version of mdBook and will prevent your books from failing to build because we released a new version. For example:
cargo install mdbook --vers "^0.1.0"
The version published to crates.io will ever so slightly be behind the version hosted here on GitHub. If you need the latest version you can build the git version of mdBook yourself. Cargo makes this super easy!
Again, make sure to add the Cargo bin directory to your
cargo install --git https://github.com/azerupi/mdBook.git
If you want to contribute to mdBook you will have to clone the repository on your local machine:
git clone https://github.com/azerupi/mdBook.git
The resulting binary can be found in
mdBook/target/debug/under the name
Here are the main commands you will want to run. For a more exhaustive explanation, check out the documentation.
The init command will create a directory with the minimal boilerplate to start with.
book-test/ ├── book └── src ├── chapter_1.md └── SUMMARY.md
srcare both directories.
srccontains the markdown files that will be used to render the output to the
Please, take a look at the Documentation for more information and some neat tricks.
This is the command you will run to render your book, it reads the
SUMMARY.mdfile to understand the structure of your book, takes the markdown files in the source directory as input and outputs static html pages that you can upload to a server.
When you run this command, mdbook will watch your markdown files to rebuild the book on every change. This avoids having to come back to the terminal to type
mdbook buildover and over again.
Does the same thing as
mdbook watchbut additionally serves the book at
http://localhost:3000(port is changeable) and reloads the browser when a change occurs.
See the Documentation and the API docs for more information.
The second edition is a rewrite that will be printed by NoStarch Press, available around October 2017.
You can read it online; the last few chapters aren't completed yet, but the first half of the book is much improved from the first edition. We recommend starting with the second edition.
The first edition is still available to read online.
Building the book requires mdBook >= v0.0.13. To get it:
$ cargo install mdbook
cdinto either the
second-editiondirectory depending on which edition of the book you would like to build. Then type:
$ mdbook build
booksubdirectory. To check it out, open it in your web browser.
$ firefox book/index.html # Linux $ open -a "Firefox" book/index.html # OS X $ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell) $ start firefox.exe .\book\index.html # Windows (Cmd)
$ google-chrome book/index.html # Linux $ open -a "Google Chrome" book/index.html # OS X $ Start-Process "chrome.exe" .\book\index.html # Windows (PowerShell) $ start chrome.exe .\book\index.html # Windows (Cmd)
$ mdbook test
Translations label to join in efforts that are currently in progress. Open a new issue to start working on a new language! We're waiting on mdbook support for multiple languages before we merge any in, but feel free to start! The chapters in the frozen column of the project won't see major changes, so if you start with those, you won't have to redo work :)
As such, there’s a directory, nostarch, which corresponds to the text in No Starch’s system.
When we've started working with No Starch in a word doc, we will also check those into the repo in the nostarch/odt directory. To extract the text from the word doc as markdown in order to backport changes to the online book:
- Open the doc file in LibreOffice
- Accept all tracked changes
- Save as Microsoft Word 2007-2013 XML (.docx) in the tmp directory
- Inspect changes made to the markdown file in the nostarch directory and copy the changes to the src directory as appropriate.
We're using Graphviz for some of the diagrams in the book. The source for those files live in the
dotdirectory. To turn a
dotfile, for example,
$ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg
svgelement and set the
0.00 0.00 1000.00 1000.00or other values that don't cut off the image.
spellcheck.shscript. It needs a dictionary of valid words, which is provided in
dictionary.txt. If the script produces a false positive (say, you used word
BTreeMapwhich the script considers invalid), you need to add this word to
dictionary.txt(keep the sorted order for consistency).