|
6 | 6 |
|
7 | 7 | mdBook is a utility to create modern online books from Markdown files. |
8 | 8 |
|
| 9 | +Check out the **[User Guide]** for a list of features and installation and usage information. |
| 10 | +The User Guide also serves as a demonstration to showcase what a book looks like. |
9 | 11 |
|
10 | | -## What does it look like? |
11 | | - |
12 | | -The [User Guide] for mdBook has been written in Markdown and is using mdBook to |
13 | | -generate the online book-like website you can read. The documentation uses the |
14 | | -latest version on GitHub and showcases the available features. |
15 | | - |
16 | | -## Installation |
17 | | - |
18 | | -There are multiple ways to install mdBook. |
19 | | - |
20 | | -1. **Binaries** |
21 | | - |
22 | | - Binaries are available for download [here][releases]. Make sure to put the |
23 | | - path to the binary into your `PATH`. |
24 | | - |
25 | | -2. **From Crates.io** |
26 | | - |
27 | | - This requires at least [Rust] 1.46 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, we recommend that |
40 | | - you specify a semver version range for mdBook when you install it through |
41 | | - 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 --vers "^0.4.0" |
53 | | - ``` |
54 | | - |
55 | | -3. **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 | | - |
67 | | -4. **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 | | - |
88 | | -mdBook is primarily used as a command line tool, even though it exposes |
89 | | -all its functionality as a Rust crate for integration in other projects. |
90 | | - |
91 | | -Here are the main commands you will want to run. For a more exhaustive |
92 | | -explanation, 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 | | -
|
138 | | -The way a book is loaded and rendered can be configured by the user via third |
139 | | -party plugins. These plugins are just programs which will be invoked during the |
140 | | -build process and are split into roughly two categories, *preprocessors* and |
141 | | -*renderers*. |
142 | | -
|
143 | | -Preprocessors are used to transform a book before it is sent to a renderer. |
144 | | -One example would be to replace all occurrences of |
145 | | -`{{#include some_file.ext}}` with the contents of that file. Some existing |
146 | | -preprocessors 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 | | -
|
155 | | -Renderers are given the final book so they can do something with it. This is |
156 | | -typically used for, as the name suggests, rendering the document in a particular |
157 | | -format, however there's nothing stopping a renderer from doing static analysis |
158 | | -of 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 | | -- [`man`] - a backend that generates manual pages from the book |
167 | | -
|
168 | | -> **Note for Developers:** Feel free to send us a PR if you've developed your |
169 | | -> own plugin and want it mentioned here. |
170 | | -
|
171 | | -A preprocessor or renderer is enabled by installing the appropriate program and |
172 | | -then mentioning it in the book's `book.toml` file. |
173 | | -
|
174 | | -```console |
175 | | -$ cargo install mdbook-linkcheck |
176 | | -$ edit book.toml && cat book.toml |
177 | | -[book] |
178 | | -title = "My Awesome Book" |
179 | | -authors = ["Michael-F-Bryan"] |
180 | | -
|
181 | | -[output.html] |
182 | | -
|
183 | | -[output.linkcheck] # enable the "mdbook-linkcheck" renderer |
184 | | -
|
185 | | -$ mdbook build |
186 | | -2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started |
187 | | -2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend |
188 | | -2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend |
189 | | -``` |
190 | | - |
191 | | -For more information on the plugin system, consult the [User Guide]. |
192 | | - |
193 | | -### As a library |
194 | | - |
195 | | -Aside from the command line interface, this crate can also be used as a |
196 | | -library. This means that you could integrate it in an existing project, like a |
197 | | -web-app for example. Since the command line interface is just a wrapper around |
198 | | -the library functionality, when you use this crate as a library you have full |
199 | | -access to all the functionality of the command line interface with an easy to |
200 | | -use API and more! |
201 | | - |
202 | | -See the [User Guide] and the [API docs] for more information. |
203 | | - |
204 | | -## Contributions |
205 | | - |
206 | | -Contributions are highly appreciated and encouraged! Don't hesitate to |
207 | | -participate to discussions in the issues, propose new features and ask for |
208 | | -help. |
209 | | - |
210 | | -If you are just starting out with Rust, there are a series of issues that are |
211 | | -tagged [E-Easy] and **we will gladly mentor you** so that you can successfully |
212 | | -go through the process of fixing a bug or adding a new feature! Let us know if |
213 | | -you need any help. |
214 | | - |
215 | | -For more info about contributing, check out our [contribution guide] which helps |
216 | | -you go through the build and contribution process! |
217 | | - |
218 | | -There is also a [rendered version][master-docs] of the latest API docs |
219 | | -available, for those hacking on `master`. |
220 | | - |
| 12 | +If you are interested in contributing to the development of mdBook, check out the [Contribution Guide]. |
221 | 13 |
|
222 | 14 | ## License |
223 | 15 |
|
224 | 16 | All the code in this repository is released under the ***Mozilla Public License v2.0***, for more information take a look at the [LICENSE] file. |
225 | 17 |
|
226 | | - |
227 | 18 | [User Guide]: https://rust-lang.github.io/mdBook/ |
228 | | -[API docs]: https://docs.rs/mdbook/*/mdbook/ |
229 | | -[E-Easy]: https://github.com/rust-lang/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy |
230 | 19 | [contribution guide]: https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md |
231 | 20 | [LICENSE]: https://github.com/rust-lang/mdBook/blob/master/LICENSE |
232 | | -[releases]: https://github.com/rust-lang/mdBook/releases |
233 | | -[Rust]: https://www.rust-lang.org/ |
234 | | -[CLI docs]: http://rust-lang.github.io/mdBook/cli/init.html |
235 | | -[master-docs]: http://rust-lang.github.io/mdBook/ |
236 | | -[`linkcheck`]: https://crates.io/crates/mdbook-linkcheck |
237 | | -[`epub`]: https://crates.io/crates/mdbook-epub |
238 | | -[`man`]: https://crates.io/crates/mdbook-man |
0 commit comments