mdBook 0.5.4 fixed documentation, MPL-2.0. Original chapter · Original Markdown · Editable Libx document · Complete fixed upstream source. · Editable source and build context.
"}, {"kind": "editorial", "html": "Original example assets retained. Rust logo: CC BY 4.0, unchanged, no affiliation or endorsement. Font Awesome SVG: CC BY 4.0; non-icon code: MIT. The original MIT wording and literal SVG example remain unchanged. Original example materials retain their separate terms; Libx provides an unofficial static edition.
"}, {"kind": "editorial", "html": "Static Libx presentation: examples show their complete code, including lines hidden in the original demo. Editing, code execution and MathJax rendering are provided by the original project; formula examples retain their original TeX notation here. The document text and expanded examples are retained. This is an unofficial Libx static edition. Original text and examples are preserved; translated pages are identified separately.
"}, {"kind": "editorial", "html": "Images are displayed once as static figures. The image zoom instructions describe the original mdBook output; use the original project for those controls.
"}] prev: {"text": "mdBook-specific features", "link": "/v0-5-4/en/01-guide/22-format-mdbook"} next: {"text": "Continuous integration", "link": "/v0-5-4/en/01-guide/10-continuous-integration"} ---mdBook’s parser adheres to the CommonMark specification with some extensions described below. You can take a quick tutorial, or try out CommonMark in real time. A complete Markdown overview is out of scope for this documentation, but below is a high level overview of some of the basics. For a more in-depth experience, check out the Markdown Guide.
Text is rendered relatively predictably:
Here is a line of text.
This is a new line.
Will look like you might expect:
Here is a line of text.
This is a new line.
Headings use the # marker and should be on a line by themselves. More # mean smaller headings:
### A heading
Some text.
#### A smaller heading
More text.
Some text.
More text.
Lists can be unordered or ordered. Ordered lists will order automatically:
* milk
* eggs
* butter
1. carrots
1. celery
1. radishes
Linking to a URL or local file is easy:
Use [mdBook](https://github.com/rust-lang/mdBook).
Read about [mdBook](mdbook.md).
And now [an mdBook link] that is not inline, unlike the above.
A bare url: <https://www.rust-lang.org>.
[an mdBook link]: https://github.com/rust-lang/mdBook
Use mdBook.
Read about mdBook.
And now an mdBook link that is not inline, unlike the above.
A bare url: https://www.rust-lang.org.
Relative links that end with .md will be converted to the .html extension.
It is recommended to use .md links when possible.
This is useful when viewing the Markdown file outside of mdBook, for example on GitHub or GitLab which render Markdown automatically.
Links to README.md will be converted to index.html.
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.
You can link to individual headings with # fragments.
For example, mdbook.md#text-and-paragraphs would link to the Text and Paragraphs section above.
The ID is created by transforming the heading such as converting to lowercase and replacing spaces with dashes.
You can click on any heading and look at the URL in your browser to see what the fragment looks like.
Including images is simply a matter of including a link to them, much like in the Links section above. The following markdown
includes the Rust logo SVG image found in the images directory at the same level as this file:
Produces the following HTML when built with mdBook:
<p><img src="images/rust-logo-blk.svg" alt="The Rust Logo" /></p>
Which, of course displays the image like so:
mdBook has several extensions beyond the standard CommonMark specification.
Text may be rendered with a horizontal line through the center by wrapping the text with one or two tilde characters on each side:
An example of ~~strikethrough text~~.
This example will render as:
An example of
strikethrough text.
This follows the GitHub Strikethrough extension.
A footnote generates a small numbered link in the text which when clicked takes the reader to the footnote text at the bottom of the item. The footnote label is written similarly to a link reference with a caret at the front. The footnote text is written like a link reference definition, with the text following the label. Example:
This is an example of a footnote[^note].
[^note]: This text is the contents of the footnote, which will be rendered
towards the bottom.
This example will render as:
This is an example of a footnote1.
The footnotes are automatically numbered based on the order the footnotes are written.
Tables can be written using pipes and dashes to draw the rows and columns of the table. These will be translated to HTML table matching the shape. Example:
| Header1 | Header2 |
|---------|---------|
| abc | def |
This example will render similarly to this:
| Header1 | Header2 |
|---|---|
| abc | def |
See the specification for the GitHub Tables extension for more details on the exact syntax supported.
Task lists can be used as a checklist of items that have been completed. Example:
- [x] Complete task
- [ ] Incomplete task
This will render as:
- Complete task
- Incomplete task
See the specification for the task list extension for more details.
Some ASCII punctuation sequences will be automatically turned into fancy Unicode characters:
| ASCII sequence | Unicode |
|---|---|
-- | – |
--- | — |
... | … |
" | “ or ”, depending on context |
' | ‘ or ’, depending on context |
So, no need to manually enter those Unicode characters!
This feature is enabled by default.
To disable it, see the output.html.smart-punctuation config option.
Headings can have a custom HTML ID and classes. This lets you maintain the same ID even if you change the heading’s text, it also lets you add multiple classes in the heading.
Example:
# Example heading { #first .class1 .class2 }
This makes the level 1 heading with the content Example heading, ID first, and classes class1 and class2. Note that the attributes should be space-separated.
More information can be found in the heading attrs spec page.
Definition lists can be used for things like glossary entries. The term is listed on a line by itself, followed by one or more definitions. Each definition must begin with a : (after 0-2 spaces).
Example:
term A
: This is a definition of term A. Text
can span multiple lines.
term B
: This is a definition of term B.
: This has more than one definition.
This will render as:
Terms are clickable just like headers, which will set the browser’s URL to point directly to that term.
See the definition lists spec for more information on the specifics of the syntax. See the Wikipedia guidelines for glossaries for some guidelines on how to write a glossary.
This feature is enabled by default.
To disable it, see the output.html.definition-lists config option.
An admonition is a special type of callout or notice block used to highlight important information. It is written as a blockquote with a special tag on the first line.
> [!NOTE]
> General information or additional context.
> [!TIP]
> A helpful suggestion or best practice.
> [!IMPORTANT]
> Key information that shouldn't be missed.
> [!WARNING]
> Critical information that highlights a potential risk.
> [!CAUTION]
> Information about potential issues that require caution.
These will render as:
Note
General information or additional context.
Tip
A helpful suggestion or best practice.
Important
Key information that shouldn’t be missed.
Warning
Critical information that highlights a potential risk.
Caution
Information about potential issues that require caution.
This feature is enabled by default.
To disable it, see the output.html.admonitions config option.
All images in the chapters content have a “zoom-in” feature: you can click on it to make it bigger, and click it again to zoom out. You can focus the image with the keyboard as well, and press the spacebar to zoom in and out as well.
This text is the contents of the footnote, which will be rendered towards the bottom. ↩