You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: CONTRIBUTING.md
+1-1
Original file line number
Diff line number
Diff line change
@@ -127,4 +127,4 @@ The following are instructions for updating [highlight.js](https://highlightjs.o
127
127
1. Compare the language list that it spits out to the one in [`syntax-highlighting.md`](https://github.com/camelid/mdBook/blob/master/guide/src/format/theme/syntax-highlighting.md). If any are missing, add them to the list and rebuild (and update these docs). If any are added to the common set, add them to `syntax-highlighting.md`.
128
128
1. Copy `build/highlight.min.js` to mdbook's directory [`highlight.js`](https://github.com/rust-lang/mdBook/blob/master/src/theme/highlight.js).
129
129
1. Be sure to check the highlight.js [CHANGES](https://github.com/highlightjs/highlight.js/blob/main/CHANGES.md) for any breaking changes. Breaking changes that would affect users will need to wait until the next major release.
130
-
1. Build mdbook with the new file and build some books with the new version and compare the output with a variety of languages to see if anything changes. (TODO: It would be nice to have a demo file in the repo to help with this.)
130
+
1. Build mdbook with the new file and build some books with the new version and compare the output with a variety of languages to see if anything changes. The [test_book](https://github.com/rust-lang/mdBook/tree/master/test_book) contains a chapter with many languages to examine.
The completions command is used to generate auto-completions for some common shells.
4
+
This means when you type `mdbook` in your shell, you can then press your shell's auto-complete key (usually the Tab key) and it may display what the valid options are, or finish partial input.
5
+
6
+
The completions first need to be installed for your shell:
Whilst still in your repository's settings page, navigate to Options and change the
43
-
Source on GitHub pages to `gh-pages`.
39
+
### Building from source
44
40
45
-
Then, append this snippet to your `.travis.yml` and update the path to the
46
-
`book` directory:
41
+
Building from source will require having Rust installed.
42
+
Some services have Rust pre-installed, but if your service does not, you will need to add a step to install it.
47
43
48
-
```yaml
49
-
deploy:
50
-
provider: pages
51
-
skip-cleanup: true
52
-
github-token: $GITHUB_TOKEN
53
-
local-dir: book # In case of custom book path: path/to/mybook/book
54
-
keep-history: false
55
-
on:
56
-
branch: main
57
-
```
44
+
After Rust is installed, `cargo install` can be used to build and install mdBook.
45
+
We recommend using a SemVer version specifier so that you get the latest **non-breaking** version of mdBook.
46
+
For example:
58
47
59
-
That's it!
60
-
61
-
Note: Travis has a new [dplv2](https://blog.travis-ci.com/2019-08-27-deployment-tooling-dpl-v2-preview-release) configuration that is currently in beta. To use this new format, update your `.travis.yml` file to:
If your CI doesn't support GitHub pages, or you're deploying somewhere else
98
-
with integrations such as Github Pages:
99
-
*note: you may want to use different tmp dirs*:
100
-
101
-
```console
102
-
$> git worktree add /tmp/book gh-pages
103
-
$> mdbook build
104
-
$> rm -rf /tmp/book/* # this won't delete the .git directory
105
-
$> cp -rp book/* /tmp/book/
106
-
$> cd /tmp/book
107
-
$> git add -A
108
-
$> git commit 'new book message'
109
-
$> git push origin gh-pages
110
-
$> cd -
111
-
```
52
+
This includes several recommended options:
112
53
113
-
Or put this into a Makefile rule:
114
-
115
-
```makefile
116
-
.PHONY: deploy
117
-
deploy: book
118
-
@echo "====> deploying to github"
119
-
git worktree add /tmp/book gh-pages
120
-
rm -rf /tmp/book/*
121
-
cp -rp book/* /tmp/book/
122
-
cd /tmp/book && \
123
-
git add -A && \
124
-
git commit -m "deployed on $(shell date) by ${USER}" && \
125
-
git push origin gh-pages
126
-
```
54
+
*`--no-default-features` — Disables features like the HTTP server used by `mdbook serve` that is likely not needed on CI.
55
+
This will speed up the build time significantly.
56
+
*`--features search` — Disabling default features means you should then manually enable features that you want, such as the built-in [search] capability.
57
+
*`--vers "^0.4"` — This will install the most recent version of the `0.4` series.
58
+
However, versions after like `0.5.0` won't be installed, as they may break your build.
59
+
Cargo will automatically upgrade mdBook if you have an older version already installed.
60
+
*`--locked` — This will use the dependencies that were used when mdBook was released.
61
+
Without `--locked`, it will use the latest version of all dependencies, which may include some fixes since the last release, but may also (rarely) cause build problems.
62
+
63
+
You will likely want to investigate caching options, as building mdBook can be somewhat slow.
64
+
65
+
[search]: guide/reading.md#search
66
+
67
+
## Running tests
68
+
69
+
You may want to run tests using [`mdbook test`] every time you push a change or create a pull request.
70
+
This can be used to validate Rust code examples in the book.
71
+
72
+
This will require having Rust installed.
73
+
Some services have Rust pre-installed, but if your service does not, you will need to add a step to install it.
74
+
75
+
Other than making sure the appropriate version of Rust is installed, there's not much more than just running `mdbook test` from the book directory.
76
+
77
+
You may also want to consider running other kinds of tests, like [mdbook-linkcheck] which will check for broken links.
78
+
Or if you have your own style checks, spell checker, or any other tests it might be good to run them in CI.
Inside your repository's project root, create a file named `.gitlab-ci.yml` with the following contents:
130
-
```yml
131
-
stages:
132
-
- deploy
133
-
134
-
pages:
135
-
stage: deploy
136
-
image: rust
137
-
variables:
138
-
CARGO_HOME: $CI_PROJECT_DIR/cargo
139
-
before_script:
140
-
- export PATH="$PATH:$CARGO_HOME/bin"
141
-
- mdbook --version || cargo install mdbook
142
-
script:
143
-
- mdbook build -d public
144
-
rules:
145
-
- if: '$CI_COMMIT_REF_NAME == "master"'
146
-
artifacts:
147
-
paths:
148
-
- public
149
-
cache:
150
-
paths:
151
-
- $CARGO_HOME/bin
83
+
## Deploying
84
+
85
+
You may want to automatically deploy your book.
86
+
Some may want to do this with every time a change is pushed, and others may want to only deploy when a specific release is tagged.
87
+
88
+
You'll also need to understand the specifics on how to push a change to your web service.
89
+
For example, [GitHub Pages] just requires committing the output onto a specific git branch.
90
+
Other services may require using something like SSH to connect to a remote server.
91
+
92
+
The basic outline is that you need to run `mdbook build` to generate the output, and then transfer the files (which are in the `book` directory) to the correct location.
93
+
94
+
You may then want to consider if you need to invalidate any caches on your web service.
95
+
96
+
See the [Automated Deployment] wiki page for examples of various different services.
97
+
98
+
[GitHub Pages]: https://docs.github.com/en/pages
99
+
100
+
### 404 handling
101
+
102
+
mdBook automatically generates a 404 page to be used for broken links.
103
+
The default output is a file named `404.html` at the root of the book.
104
+
Some services like [GitHub Pages] will automatically use this page for broken links.
105
+
For other services, you may want to consider configuring the web server to use this page as it will provide the reader navigation to get back to the book.
106
+
107
+
If your book is not deployed at the root of the domain, then you should set the [`output.html.site-url`] setting so that the 404 page works correctly.
108
+
It needs to know where the book is deployed in order to load the static files (like CSS) correctly.
109
+
For example, this guide is deployed at <https://rust-lang.github.io/mdBook/>, and the `site-url` setting is configured like this:
110
+
111
+
```toml
112
+
# book.toml
113
+
[output.html]
114
+
site-url = "/mdBook/"
152
115
```
153
116
154
-
After you commit and push this new file, GitLab CI will run and your book will be available!
117
+
You can customize the look of the 404 page by creating a file named `src/404.md` in your book.
118
+
If you want to use a different filename, you can set [`output.html.input-404`] to a different filename.
[Third Party Plugins]: https://github.com/rust-lang/mdBook/wiki/Third-party-plugins
24
+
[Preprocessors for Developers]: ../../for_developers/preprocessors.md
22
25
23
-
###Custom Preprocessor Configuration
26
+
## Custom Preprocessor Configuration
24
27
25
-
Like renderers, preprocessor will need to be given its own table (e.g.
26
-
`[preprocessor.mathjax]`). In the section, you may then pass extra
27
-
configuration to the preprocessor by adding key-value pairs to the table.
28
+
Preprocessors can be added by including a `preprocessor` table in `book.toml` with the name of the preprocessor.
29
+
For example, if you have a preprocessor called `mdbook-example`, then you can include it with:
28
30
29
-
For example
31
+
```toml
32
+
[preprocessor.example]
33
+
```
34
+
35
+
With this table, mdBook will execute the `mdbook-example` preprocessor.
36
+
37
+
This table can include additional key-value pairs that are specific to the preprocessor.
38
+
For example, if our example prepocessor needed some extra configuration options:
30
39
31
40
```toml
32
-
[preprocessor.links]
33
-
# set the renderers this preprocessor will run for
34
-
renderers = ["html"]
35
-
some_extra_feature = true
41
+
[preprocessor.example]
42
+
some-extra-feature = true
36
43
```
37
44
38
-
####Locking a Preprocessor dependency to a renderer
45
+
## Locking a Preprocessor dependency to a renderer
39
46
40
47
You can explicitly specify that a preprocessor should run for a renderer by
41
48
binding the two together.
42
49
43
50
```toml
44
-
[preprocessor.mathjax]
45
-
renderers = ["html"] #mathjax only makes sense with the HTML renderer
51
+
[preprocessor.example]
52
+
renderers = ["html"] #example preprocessor only runs with the HTML renderer
46
53
```
47
54
48
-
###Provide Your Own Command
55
+
## Provide Your Own Command
49
56
50
57
By default when you add a `[preprocessor.foo]` table to your `book.toml` file,
51
58
`mdbook` will try to invoke the `mdbook-foo` executable. If you want to use a
@@ -57,7 +64,7 @@ be overridden by adding a `command` field.
57
64
command = "python random.py"
58
65
```
59
66
60
-
###Require A Certain Order
67
+
## Require A Certain Order
61
68
62
69
The order in which preprocessors are run can be controlled with the `before` and `after` fields.
63
70
For example, suppose you want your `linenos` preprocessor to process lines that may have been `{{#include}}`d; then you want it to run after the built-in `links` preprocessor, which you can require using either the `before` or `after` field:
Available configuration options for the `[output.html.print]` table:
168
+
### `[output.html.print]`
169
+
170
+
The `[output.html.print]` table provides options for controlling the printable output.
171
+
By default, mdBook will include an icon on the top right of the book (which looks like <iclass="fa fa-print"></i>) that will print the book as a single page.
172
+
173
+
```toml
174
+
[output.html.print]
175
+
enable = true# include support for printable output
176
+
```
75
177
76
178
-**enable:** Enable print support. When `false`, all print support will not be
77
179
rendered. Defaults to `true`.
78
180
79
-
Available configuration options for the `[output.html.fold]` table:
181
+
### `[output.html.fold]`
182
+
183
+
The `[output.html.fold]` table provides options for controlling folding of the chapter listing in the navigation sidebar.
184
+
185
+
```toml
186
+
[output.html.fold]
187
+
enable = false# whether or not to enable section folding
188
+
level = 0# the depth to start folding
189
+
```
80
190
81
191
-**enable:** Enable section-folding. When off, all folds are open.
82
192
Defaults to `false`.
83
193
-**level:** The higher the more folded regions are open. When level is 0, all
84
194
folds are closed. Defaults to `0`.
85
195
86
-
Available configuration options for the `[output.html.playground]` table:
196
+
### `[output.html.playground]`
197
+
198
+
The `[output.html.playground]` table provides options for controlling Rust sample code blocks, and their integration with the [Rust Playground].
199
+
200
+
[Rust Playground]: https://play.rust-lang.org/
201
+
202
+
```toml
203
+
[output.html.playground]
204
+
editable = false# allows editing the source code
205
+
copyable = true# include the copy button for copying code snippets
206
+
copy-js = true# includes the JavaScript for the code editor
207
+
line-numbers = false# displays line numbers for editable code
208
+
```
87
209
88
210
-**editable:** Allow editing the source code. Defaults to `false`.
89
211
-**copyable:** Display the copy button on code snippets. Defaults to `true`.
@@ -93,7 +215,26 @@ Available configuration options for the `[output.html.playground]` table:
93
215
94
216
[Ace]: https://ace.c9.io/
95
217
96
-
Available configuration options for the `[output.html.search]` table:
218
+
### `[output.html.search]`
219
+
220
+
The `[output.html.search]` table provides options for controlling the built-in text [search].
221
+
mdBook must be compiled with the `search` feature enabled (on by default).
222
+
223
+
[search]: ../../guide/reading.md#search
224
+
225
+
```toml
226
+
[output.html.search]
227
+
enable = true# enables the search feature
228
+
limit-results = 30# maximum number of search results
229
+
teaser-word-count = 30# number of words used for a search result teaser
230
+
use-boolean-and = true# multiple search terms must all match
231
+
boost-title = 2# ranking boost factor for matches in headers
232
+
boost-hierarchy = 1# ranking boost factor for matches in page names
233
+
boost-paragraph = 1# ranking boost factor for matches in text
234
+
expand = true# partial words will match longer terms
235
+
heading-split-level = 3# link results to heading levels
236
+
copy-js = true# include Javascript code for search
237
+
```
97
238
98
239
-**enable:** Enables the search feature. Defaults to `true`.
99
240
-**limit-results:** The maximum number of search results. Defaults to `30`.
@@ -116,61 +257,24 @@ Available configuration options for the `[output.html.search]` table:
116
257
-**copy-js:** Copy JavaScript files for the search implementation to the output
117
258
directory. Defaults to `true`.
118
259
119
-
This shows all available HTML output options in the **book.toml**:
The table contains key-value pairs where the key is where the redirect file needs to be created, as an absolute path from the build directory, (e.g. `/appendices/bibliography.html`).
272
+
The value can be any valid URI the browser should navigate to (e.g. `https://rust-lang.org/`, `/overview.html`, or `../bibliography.html`).
273
+
274
+
This will generate an HTML page which will automatically redirect to the given location.
275
+
Note that the source location does not support `#` anchor redirects.
276
+
277
+
## Markdown Renderer
174
278
175
279
The Markdown renderer will run preprocessors and then output the resulting
176
280
Markdown. This is mostly useful for debugging preprocessors, especially in
@@ -189,20 +293,3 @@ only whether it is enabled or disabled.
189
293
190
294
See [the preprocessors documentation](preprocessors.md) for how to
191
295
specify which preprocessors should run before the Markdown renderer.
192
-
193
-
### Custom Renderers
194
-
195
-
A custom renderer can be enabled by adding a `[output.foo]` table to your
196
-
`book.toml`. Similar to [preprocessors](preprocessors.md) this will
197
-
instruct `mdbook` to pass a representation of the book to `mdbook-foo` for
198
-
rendering. See the [alternative backends] chapter for more detail.
199
-
200
-
The custom renderer has access to all the fields within its table (i.e.
201
-
anything under `[output.foo]`). mdBook checks for two common fields:
202
-
203
-
-**command:** The command to execute for this custom renderer. Defaults to
204
-
the name of the renderer with the `mdbook-` prefix (such as `mdbook-foo`).
205
-
-**optional:** If `true`, then the command will be ignored if it is not
206
-
installed, otherwise mdBook will fail with an error. Defaults to `false`.
Copy file name to clipboardexpand all lines: guide/src/format/markdown.md
+118-3
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
# Markdown
2
2
3
-
mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/)
4
-
specification. You can take a quick [tutorial](https://commonmark.org/help/tutorial/),
3
+
mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/) specification with some extensions described below.
4
+
You can take a quick [tutorial](https://commonmark.org/help/tutorial/),
5
5
or [try out](https://spec.commonmark.org/dingus/) CommonMark in real time. A complete Markdown overview is out of scope for
6
6
this documentation, but below is a high level overview of some of the basics. For a more in-depth experience, check out the
7
7
[Markdown Guide](https://www.markdownguide.org).
@@ -84,6 +84,20 @@ Read about [mdBook](mdBook.md).
84
84
85
85
A bare url: <https://www.rust-lang.org>.
86
86
87
+
----
88
+
89
+
Relative links that end with `.md` will be converted to the `.html` extension.
90
+
It is recommended to use `.md` links when possible.
91
+
This is useful when viewing the Markdown file outside of mdBook, for example on GitHub or GitLab which render Markdown automatically.
92
+
93
+
Links to `README.md` will be converted to `index.html`.
94
+
This is done since some services like GitHub render README files automatically, but web servers typically expect the root file to be called `index.html`.
95
+
96
+
You can link to individual headings with `#` fragments.
97
+
For example, `mdbook.md#text-and-paragraphs` would link to the [Text and Paragraphs](#text-and-paragraphs) section above.
98
+
The ID is created by transforming the heading such as converting to lowercase and replacing spaces with dashes.
99
+
You can click on any heading and look at the URL in your browser to see what the fragment looks like.
100
+
87
101
## Images
88
102
89
103
Including images is simply a matter of including a link to them, much like in the _Links_ section above. The following markdown
@@ -103,5 +117,106 @@ Which, of course displays the image like so:
103
117
104
118
105
119
120
+
## Extensions
121
+
122
+
mdBook has several extensions beyond the standard CommonMark specification.
123
+
124
+
### Strikethrough
125
+
126
+
Text may be rendered with a horizontal line through the center by wrapping the
127
+
text with two tilde characters on each side:
128
+
129
+
```text
130
+
An example of ~~strikethrough text~~.
131
+
```
132
+
133
+
This example will render as:
134
+
135
+
> An example of ~~strikethrough text~~.
136
+
137
+
This follows the [GitHub Strikethrough extension][strikethrough].
138
+
139
+
### Footnotes
140
+
141
+
A footnote generates a small numbered link in the text which when clicked
142
+
takes the reader to the footnote text at the bottom of the item. The footnote
143
+
label is written similarly to a link reference with a caret at the front. The
144
+
footnote text is written like a link reference definition, with the text
145
+
following the label. Example:
146
+
147
+
```text
148
+
This is an example of a footnote[^note].
149
+
150
+
[^note]: This text is the contents of the footnote, which will be rendered
151
+
towards the bottom.
152
+
```
153
+
154
+
This example will render as:
155
+
156
+
> This is an example of a footnote[^note].
157
+
>
158
+
> [^note]: This text is the contents of the footnote, which will be rendered
159
+
> towards the bottom.
160
+
161
+
The footnotes are automatically numbered based on the order the footnotes are
162
+
written.
163
+
164
+
### Tables
165
+
166
+
Tables can be written using pipes and dashes to draw the rows and columns of
167
+
the table. These will be translated to HTML table matching the shape. Example:
168
+
169
+
```text
170
+
| Header1 | Header2 |
171
+
|---------|---------|
172
+
| abc | def |
173
+
```
174
+
175
+
This example will render similarly to this:
176
+
177
+
| Header1 | Header2 |
178
+
|---------|---------|
179
+
| abc | def |
180
+
181
+
See the specification for the [GitHub Tables extension][tables] for more
182
+
details on the exact syntax supported.
183
+
184
+
### Task lists
185
+
186
+
Task lists can be used as a checklist of items that have been completed.
187
+
Example:
188
+
189
+
```md
190
+
- [x] Complete task
191
+
- [ ] Incomplete task
192
+
```
193
+
194
+
This will render as:
195
+
196
+
> -[x] Complete task
197
+
> -[ ] Incomplete task
198
+
199
+
See the specification for the [task list extension] for more details.
200
+
201
+
### Smart punctuation
202
+
203
+
Some ASCII punctuation sequences will be automatically turned into fancy Unicode
204
+
characters:
205
+
206
+
| ASCII sequence | Unicode |
207
+
|----------------|---------|
208
+
|`--`| – |
209
+
|`---`| — |
210
+
|`...`| … |
211
+
|`"`| “ or ”, depending on context |
212
+
|`'`| ‘ or ’, depending on context |
213
+
214
+
So, no need to manually enter those Unicode characters!
215
+
216
+
This feature is disabled by default.
217
+
To enable it, see the [`output.html.curly-quotes`] config option.
106
218
107
-
See the [Markdown Guide Basic Syntax](https://www.markdownguide.org/basic-syntax/) document for more.
The code block has an eyeball icon (<iclass="fa fa-eye"></i>) which will toggle the visibility of the hidden lines.
32
+
33
+
## Rust Playground
34
+
35
+
Rust language code blocks will automatically get a play button (<iclass="fa fa-play"></i>) which will execute the code and display the output just below the code block.
36
+
This works by sending the code to the [Rust Playground].
37
+
38
+
```rust
39
+
println!("Hello, World!");
40
+
```
41
+
42
+
If there is no `main` function, then the code is automatically wrapped inside one.
43
+
44
+
If you wish to disable the play button, you can include the `noplayground` option on the code block like this:
45
+
46
+
~~~markdown
47
+
```rust,noplayground
48
+
let mut name = String::new();
49
+
std::io::stdin().read_line(&mut name).expect("failed to read line");
50
+
println!("Hello {}!", name);
51
+
```
52
+
~~~
53
+
54
+
## Rust code block attributes
55
+
56
+
Additional attributes can be included in Rust code blocks with comma, space, or tab-separated terms just after the language term. For example:
57
+
58
+
~~~markdown
59
+
```rust,ignore
60
+
# This example won't be tested.
61
+
panic!("oops!");
62
+
```
63
+
~~~
64
+
65
+
These are particularly important when using [`mdbook test`] to test Rust examples.
66
+
These use the same attributes as [rustdoc attributes], with a few additions:
67
+
68
+
*`editable` — Enables the [editor].
69
+
*`noplayground` — Removes the play button, but will still be tested.
70
+
*`mdbook-runnable` — Forces the play button to be displayed.
71
+
This is intended to be combined with the `ignore` attribute for examples that should not be tested, but you want to allow the reader to run.
72
+
*`ignore` — Will not be tested and no play button is shown, but it is still highlighted as Rust syntax.
73
+
*`should_panic` — When executed, it should produce a panic.
74
+
*`no_run` — The code is compiled when tested, but it is not run.
75
+
The play button is also not shown.
76
+
*`compile_fail` — The code should fail to compile.
77
+
*`edition2015`, `edition2018`, `edition2021` — Forces the use of a specific Rust edition.
Once you have the `mdbook` CLI tool installed, you can use it to create and render a book.
4
+
5
+
## Initializing a book
6
+
7
+
The `mdbook init` command will create a new directory containing an empty book for you to get started.
8
+
Give it the name of the directory that you want to create:
9
+
10
+
```sh
11
+
mdbook init my-first-book
12
+
```
13
+
14
+
It will ask a few questions before generating the book.
15
+
After answering the questions, you can change the current directory into the new book:
16
+
17
+
```sh
18
+
cd my-first-book
19
+
```
20
+
21
+
There are several ways to render a book, but one of the easiest methods is to use the `serve` command, which will build your book and start a local webserver:
22
+
23
+
```sh
24
+
mdbook serve --open
25
+
```
26
+
27
+
The `--open` option will open your default web browser to view your new book.
28
+
You can leave the server running even while you edit the content of the book, and `mdbook` will automatically rebuild the output *and* automatically refresh your web browser.
29
+
30
+
Check out the [CLI Guide](../cli/index.html) for more information about other `mdbook` commands and CLI options.
31
+
32
+
## Anatomy of a book
33
+
34
+
A book is built from several files which define the settings and layout of the book.
35
+
36
+
### `book.toml`
37
+
38
+
In the root of your book, there is a `book.toml` file which contains settings for describing how to build your book.
39
+
This is written in the [TOML markup language](https://toml.io/).
40
+
The default settings are usually good enough to get you started.
41
+
When you are interested in exploring more features and options that mdBook provides, check out the [Configuration chapter](../format/configuration/index.html) for more details.
42
+
43
+
A very basic `book.toml` can be as simple as this:
44
+
45
+
```toml
46
+
[book]
47
+
title = "My First Book"
48
+
```
49
+
50
+
### `SUMMARY.md`
51
+
52
+
The next major part of a book is the summary file located at `src/SUMMARY.md`.
53
+
This file contains a list of all the chapters in the book.
54
+
Before a chapter can be viewed, it must be added to this list.
55
+
56
+
Here's a basic summary file with a few chapters:
57
+
58
+
```md
59
+
# Summary
60
+
61
+
[Introduction](README.md)
62
+
63
+
- [My First Chapter](my-first-chapter.md)
64
+
- [Nested example](nested/README.md)
65
+
- [Sub-chapter](nested/sub-chapter.md)
66
+
```
67
+
68
+
Try opening up `src/SUMMARY.md` in your editor and adding a few chapters.
69
+
If any of the chapter files do not exist, `mdbook` will automatically create them for you.
70
+
71
+
For more details on other formatting options for the summary file, check out the [Summary chapter](../format/summary.md).
72
+
73
+
### Source files
74
+
75
+
The content of your book is all contained in the `src` directory.
76
+
Each chapter is a separate Markdown file.
77
+
Typically, each chapter starts with a level 1 heading with the title of the chapter.
78
+
79
+
```md
80
+
# My First Chapter
81
+
82
+
Fill out your content here.
83
+
```
84
+
85
+
The precise layout of the files is up to you.
86
+
The organization of the files will correspond to the HTML files generated, so keep in mind that the file layout is part of the URL of each chapter.
87
+
88
+
While the `mdbook serve` command is running, you can open any of the chapter files and start editing them.
89
+
Each time you save the file, `mdbook` will rebuild the book and refresh your web browser.
90
+
91
+
Check out the [Markdown chapter](../format/markdown.md) for more information on formatting the content of your chapters.
92
+
93
+
All other files in the `src` directory will be included in the output.
94
+
So if you have images or other static files, just include them somewhere in the `src` directory.
95
+
96
+
## Publishing a book
97
+
98
+
Once you've written your book, you may want to host it somewhere for others to view.
99
+
The first step is to build the output of the book.
100
+
This can be done with the `mbdook build` command in the same directory where the `book.toml` file is located:
101
+
102
+
```sh
103
+
mdbook build
104
+
```
105
+
106
+
This will generate a directory named `book` which contains the HTML content of your book.
107
+
You can then place this directory on any web server to host it.
108
+
109
+
For more information about publishing and deploying, check out the [Continuous Integration chapter](../continuous-integration.md) for more.
This chapter gives an introduction on how to interact with a book produced by mdBook.
4
+
This assumes you are reading an HTML book.
5
+
The options and formatting will be different for other output formats such as PDF.
6
+
7
+
A book is organized into *chapters*.
8
+
Each chapter is a separate page.
9
+
Chapters can be nested into a hierarchy of sub-chapters.
10
+
Typically, each chapter will be organized into a series of *headings* to subdivide a chapter.
11
+
12
+
## Navigation
13
+
14
+
There are several methods for navigating through the chapters of a book.
15
+
16
+
The **sidebar** on the left provides a list of all chapters.
17
+
Clicking on any of the chapter titles will load that page.
18
+
19
+
The sidebar may not automatically appear if the window is too narrow, particularly on mobile displays.
20
+
In that situation, the menu icon (three horizontal bars) at the top-left of the page can be pressed to open and close the sidebar.
21
+
22
+
The **arrow buttons** at the bottom of the page can be used to navigate to the previous or the next chapter.
23
+
24
+
The **left and right arrow keys** on the keyboard can be used to navigate to the previous or the next chapter.
25
+
26
+
## Top menu bar
27
+
28
+
The menu bar at the top of the page provides some icons for interacting with the book.
29
+
The icons displayed will depend on the settings of how the book was generated.
30
+
31
+
| Icon | Description |
32
+
|------|-------------|
33
+
| <iclass="fa fa-bars"></i> | Opens and closes the chapter listing sidebar. |
34
+
| <iclass="fa fa-paint-brush"></i> | Opens a picker to choose a different color theme. |
35
+
| <iclass="fa fa-search"></i> | Opens a search bar for searching within the book. |
36
+
| <iclass="fa fa-print"></i> | Instructs the web browser to print the entire book. |
37
+
| <iclass="fa fa-github"></i> | Opens a link to the website that hosts the source code of the book. |
38
+
| <iclass="fa fa-edit"></i> | Opens a page to directly edit the source of the page you are currently reading. |
39
+
40
+
Tapping the menu bar will scroll the page to the top.
41
+
42
+
## Search
43
+
44
+
Each book has a built-in search system.
45
+
Pressing the search icon (<iclass="fa fa-search"></i>) in the menu bar, or pressing the `S` key on the keyboard will open an input box for entering search terms.
46
+
Typing some terms will show matching chapters and sections in real time.
47
+
48
+
Clicking any of the results will jump to that section.
49
+
The up and down arrow keys can be used to navigate the results, and enter will open the highlighted section.
50
+
51
+
After loading a search result, the matching search terms will be highlighted in the text.
52
+
Clicking a highlighted word or pressing the `Esc` key will remove the highlighting.
53
+
54
+
## Code blocks
55
+
56
+
mdBook books are often used for programming projects, and thus support highlighting code blocks and samples.
57
+
Code blocks may contain several different icons for interacting with them:
58
+
59
+
| Icon | Description |
60
+
|------|-------------|
61
+
| <iclass="fa fa-copy"></i> | Copies the code block into your local clipboard, to allow pasting into another application. |
62
+
| <iclass="fa fa-play"></i> | For Rust code examples, this will execute the sample code and display the compiler output just below the example (see [playground]). |
63
+
| <iclass="fa fa-eye"></i> | For Rust code examples, this will toggle visibility of "hidden" lines. Sometimes, larger examples will hide lines which are not particularly relevant to what is being illustrated (see [hiding code lines]). |
64
+
| <iclass="fa fa-history"></i> | For [editable code examples][editor], this will undo any changes you have made. |
0 commit comments