mdBook is a command line tool and Rust library to create books using Markdown. -It's very similar to Gitbook but written in Rust.
-This book serves as an example of the output of mdBook and as the docs at the same time.
-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.
-mdBook, all the code and this book, are released under the Mozilla Public License v2.0
- -The build command is used to render your book:
-mdbook build
-It will try to parse your SUMMARY.md file to understand the structure of your book
-and fetch the corresponding files.
The rendered ouput will maintain the same directory structure as the source for -convenience. Large books will therefore remain structured when rendered.
-Like init, the build command can take a directory as argument to use instead of the -current working directory.
-mdbook build path/to/book
-note: make sure to run the build command in the root directory and not in the source directory
- -mdBook can be used either as a command line tool or a Rust library. -Let's focus on the command line tool capabilities first.
- -The init command, used like this:
-mdbook init
-Will create a couple of files and directories in the working directory so that you can -spend more time writing your book and less setting it up.
-The files set up for you are the following:
-book-test/
-├── book
-└── src
- ├── chapter_1.md
- └── SUMMARY.md
-The src directory is were 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 serer to be seen by the internet.
The SUMMARY.md file is the most important file, it's the skeleton of your book.
-It's so important that it has it's own chapter.
When using the init command, you can also specify a directory, instead of using the current directory, -by appending a path to the command:
-mdbook init path/to/book
-In the future I would like mdBook init to be able to:
src directory in a theme directory when using a flag like --theme.
-The user could then tweak the theme to his needs.SUMMARY.md. If the user has already created a SUMMARY.md file and added some entries but did
-not create the corresponding files, init command should create the files for him.You can configure the parameters for your book in the book.json file.
-Here is an example of what a book.json file might look like:
-{
- "title": "Example book",
- "author": "Name",
-}
-In this section you will learn how to:
-SUMMARY.md filebook.jsonThe summary file is used by mdBook to know what chapters to include, -in what order they should appear, what their hierarchy is and where the source files are. -Without this file, there is no book.
-Even though SUMMARY.md is a markdown file, the formatting is very strict to
-allow for easy parsing. Let's see how you should format your SUMMARY.md file.
Title It's common practice to begin with a title, generally
-# Summary.
-But it is not mandatory, the parser just ignores it. So you can too
-if you feel like it.
list link the other elements have to be list elements in form of a link
-- [Title of the Chapter](relative/path/to/markdown.md)
-You can either use - or * to indicate a list. The lists can be nested,
-resulting in a nice hierarchy (chapters, sub-chapters, etc.)
All other elements are unsupported and will be ignored at best or result in an error.
-In the feature I would like to add support for links without the need to be list elements -at the root level to add chapters that don't need numbering, like an index, appendix, -contributor list, introduction, foreword, etc.
- -index.hbs is the handlebars template that is used to render the book.
-The markdown files are processed to html and then injected in that template.
If you want to change the layout or style of your book, chances are that you will -have to modify this template a little bit. Here is what you need to know.
-A lot of data is exposed to the handlebars template with the "context". -In the handlebars template you can access this information by using
-{{name_of_property}}
-Here is a list of the properties that are exposed:
-language Language of the book in the form en. To use in <html lang="{{ language }}"> for example.
-At the moment it is hardcoded.
title Title of the book, as specified in book.json
path Relative path to the original markdown file from the source directory
-content This is the rendered markdown.
-path_to_root This is a path containing exclusively ../'s that points to the root of the book from the current file.
-Since the original directory structure is maintained, it is useful to prepend relative links with this path_to_root.
chapters Is an array of dictionaries of the form
-{"section": "1.2.1", "name": "name of this chapter", "path": "dir/markdown.md"}
-containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).
-In addition to the properties you can access, there are some handlebars helpers at your disposal.
-The toc helper is used like this
-{{#toc}}{{/toc}}
-and outputs something that looks like this, depending on the structure of your book
-<ul class="chapter">
- <li><a href="link/to/file.html">Some chapter</a></li>
- <li>
- <ul class="section">
- <li><a href="link/to/other_file.html">Some other Chapter</a></li>
- </ul>
- </li>
-</ul>
-If you would like to make a toc with another structure, you have access to the chapters property containing all the data. -The only limitation at the moment is that you would have to do it with JavaScript instead of with a handlebars helper.
-<script>
-var chapters = {{chapters}};
-// Processing here
-</script>
-The previous and next helpers expose a link and name property to the previous and next chapters.
They are used like this
-{{#previous}}
- <a href="{{link}}" class="nav-chapters previous">
- <i class="fa fa-angle-left"></i>
- </a>
-{{/previous}}
-The inner html will only be rendered if the previous / next chapter exists. -Of course the inner html can be changed to your liking.
-If you would like me to expose other properties or helpers, please create a new issue -and I will consider it.
- -For syntax highlighting I use Highlight.js with a custom theme.
-Automatic language detection has been turned off, so you will probably want to -specify the programming language you use like this
-```rust
-fn main() {
- // Some code
-}
-```If you think the default theme doesn't look quite right for a specific language, or could be improved. -Feel free to submit a new issue explaining what you have in mind and I will take a look at it.
-You could also create a pull-request with the proposed improvements.
-Overall the theme should be light and sober, without to many flashy colors.
-Like the rest of the theme, the files used for syntax highlighting can be overwritten with your own.
-If you want to use another theme for highlight.js download it from their website, or make it yourself,
-rename it to highlight.css and put it in src/theme (or the equivalent if you changed your source folder)
Now your theme will be used instead of the default theme.
- -The default renderer uses a handlebars template to render your markdown files in and comes with a default theme -included in the mdBook binary.
-But the theme is totally customizable, you can replace every file from the theme by your own by adding a
-theme directory in your source folder. Create a new file with the name of the file you want to overwrite
-and now that file will be used instead of the default file.
Here are the files you can overwrite:
-index.hbs when you want to radically change the layout.Note:
-When you overwrite a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. In the future you will be able to copy the default theme into your source directory automatically by using mdbook init --theme.
mdBook is a command line tool and Rust library to create books using Markdown. -It's very similar to Gitbook but written in Rust.
-This book serves as an example of the output of mdBook and as the docs at the same time.
-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.
-mdBook, all the code and this book, are released under the Mozilla Public License v2.0
- -