README.md
1# mdBook
2
3[](https://github.com/rust-lang/mdBook/actions?workflow=CI)
4[](https://crates.io/crates/mdbook)
5[](LICENSE)
6
7mdBook is a utility to create modern online books from Markdown files.
8
9
10## What does it look like?
11
12The [User Guide] for mdBook has been written in Markdown and is using mdBook to
13generate the online book-like website you can read. The documentation uses the
14latest version on GitHub and showcases the available features.
15
16## Installation
17
18There are multiple ways to install mdBook.
19
201. **Binaries**
21
22 Binaries are available for download [here][releases]. Make sure to put the
23 path to the binary into your `PATH`.
24
252. **From Crates.io**
26
27 This requires at least [Rust] 1.39 and Cargo to be installed. Once you have installed
28 Rust, type the following in the terminal:
29
30 ```
31 cargo install mdbook
32 ```
33
34 This will download and compile mdBook for you, the only thing left to do is
35 to add the Cargo bin directory to your `PATH`.
36
37 **Note for automatic deployment**
38
39 If you are using a script to do automatic deployments using Travis or
40 another CI server, we recommend that you specify a semver version range for
41 mdBook when you install it through your script!
42
43 This will constrain the server to install the latest **non-breaking**
44 version of mdBook and will prevent your books from failing to build because
45 we released a new version.
46
47 You can also disable default features to speed up compile time.
48
49 Example:
50
51 ```
52 cargo install mdbook --no-default-features --features output --vers "^0.1.0"
53 ```
54
553. **From Git**
56
57 The version published to crates.io will ever so slightly be behind the
58 version hosted here on GitHub. If you need the latest version you can build
59 the git version of mdBook yourself. Cargo makes this ***super easy***!
60
61 ```
62 cargo install --git https://github.com/rust-lang/mdBook.git mdbook
63 ```
64
65 Again, make sure to add the Cargo bin directory to your `PATH`.
66
674. **For Contributions**
68
69 If you want to contribute to mdBook you will have to clone the repository on
70 your local machine:
71
72 ```
73 git clone https://github.com/rust-lang/mdBook.git
74 ```
75
76 `cd` into `mdBook/` and run
77
78 ```
79 cargo build
80 ```
81
82 The resulting binary can be found in `mdBook/target/debug/` under the name
83 `mdBook` or `mdBook.exe`.
84
85
86## Usage
87
88mdBook is primarily used as a command line tool, even though it exposes
89all its functionality as a Rust crate for integration in other projects.
90
91Here are the main commands you will want to run. For a more exhaustive
92explanation, check out the [User Guide].
93
94- `mdbook init <directory>`
95
96 The init command will create a directory with the minimal boilerplate to
97 start with. If the `<directory>` parameter is omitted, the current
98 directory will be used.
99
100 ```
101 book-test/
102 ├── book
103 └── src
104 ├── chapter_1.md
105 └── SUMMARY.md
106 ```
107
108 `book` and `src` are both directories. `src` contains the markdown files
109 that will be used to render the output to the `book` directory.
110
111 Please, take a look at the [CLI docs] for more information and some neat tricks.
112
113- `mdbook build`
114
115 This is the command you will run to render your book, it reads the
116 `SUMMARY.md` file to understand the structure of your book, takes the
117 markdown files in the source directory as input and outputs static html
118 pages that you can upload to a server.
119
120- `mdbook watch`
121
122 When you run this command, mdbook will watch your markdown files to rebuild
123 the book on every change. This avoids having to come back to the terminal
124 to type `mdbook build` over and over again.
125
126- `mdbook serve`
127
128 Does the same thing as `mdbook watch` but additionally serves the book at
129 `http://localhost:3000` (port is changeable) and reloads the browser when a
130 change occurs.
131
132- `mdbook clean`
133
134 Delete directory in which generated book is located.
135
136### 3rd Party Plugins
137
138The way a book is loaded and rendered can be configured by the user via third
139party plugins. These plugins are just programs which will be invoked during the
140build process and are split into roughly two categories, *preprocessors* and
141*renderers*.
142
143Preprocessors are used to transform a book before it is sent to a renderer.
144One example would be to replace all occurrences of
145`{{#include some_file.ext}}` with the contents of that file. Some existing
146preprocessors are:
147
148- `index` - a built-in preprocessor (enabled by default) which will transform
149 all `README.md` chapters to `index.md` so `foo/README.md` can be accessed via
150 the url `foo/` when published to a browser
151- `links` - a built-in preprocessor (enabled by default) for expanding the
152 `{{# playground}}` and `{{# include}}` helpers in a chapter.
153- [`katex`](https://github.com/lzanini/mdbook-katex) - a preprocessor rendering LaTex equations to HTML.
154
155Renderers are given the final book so they can do something with it. This is
156typically used for, as the name suggests, rendering the document in a particular
157format, however there's nothing stopping a renderer from doing static analysis
158of a book in order to validate links or run tests. Some existing renderers are:
159
160- `html` - the built-in renderer which will generate a HTML version of the book
161- `markdown` - the built-in renderer (disabled by default) which will run
162 preprocessors then output the resulting Markdown. Useful for debugging
163 preprocessors.
164- [`linkcheck`] - a backend which will check that all links are valid
165- [`epub`] - an experimental EPUB generator
166
167> **Note for Developers:** Feel free to send us a PR if you've developed your
168> own plugin and want it mentioned here.
169
170A preprocessor or renderer is enabled by installing the appropriate program and
171then mentioning it in the book's `book.toml` file.
172
173```console
174$ cargo install mdbook-linkcheck
175$ edit book.toml && cat book.toml
176[book]
177title = "My Awesome Book"
178authors = ["Michael-F-Bryan"]
179
180[output.html]
181
182[output.linkcheck] # enable the "mdbook-linkcheck" renderer
183
184$ mdbook build
1852018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
1862018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
1872018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend
188```
189
190For more information on the plugin system, consult the [User Guide].
191
192### As a library
193
194Aside from the command line interface, this crate can also be used as a
195library. This means that you could integrate it in an existing project, like a
196web-app for example. Since the command line interface is just a wrapper around
197the library functionality, when you use this crate as a library you have full
198access to all the functionality of the command line interface with an easy to
199use API and more!
200
201See the [User Guide] and the [API docs] for more information.
202
203## Contributions
204
205Contributions are highly appreciated and encouraged! Don't hesitate to
206participate to discussions in the issues, propose new features and ask for
207help.
208
209If you are just starting out with Rust, there are a series of issues that are
210tagged [E-Easy] and **we will gladly mentor you** so that you can successfully
211go through the process of fixing a bug or adding a new feature! Let us know if
212you need any help.
213
214For more info about contributing, check out our [contribution guide] which helps
215you go through the build and contribution process!
216
217There is also a [rendered version][master-docs] of the latest API docs
218available, for those hacking on `master`.
219
220
221## License
222
223All the code in this repository is released under the ***Mozilla Public License v2.0***, for more information take a look at the [LICENSE] file.
224
225
226[User Guide]: https://rust-lang.github.io/mdBook/
227[API docs]: https://docs.rs/mdbook/*/mdbook/
228[E-Easy]: https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy
229[contribution guide]: https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md
230[LICENSE]: https://github.com/rust-lang/mdBook/blob/master/LICENSE
231[releases]: https://github.com/rust-lang/mdBook/releases
232[Rust]: https://www.rust-lang.org/
233[CLI docs]: http://rust-lang.github.io/mdBook/cli/init.html
234[master-docs]: http://rust-lang.github.io/mdBook/
235[`linkcheck`]: https://crates.io/crates/mdbook-linkcheck
236[`epub`]: https://crates.io/crates/mdbook-epub
237
){kind=link}
){kind=link}
){kind=link}