Definitions
mdbook is a command-line tool to create books with Markdown. It is commonly used for Rust user guides, such as the Rust book and the Rust How-to book.
Markdown links and reference definitions
Markdown is a lightweight, readable markup language for writing structured documents.
A Markdown link can be an autolink, e.g. <https://example.com>, an inline link like [The user will see this](https://example.com), or a reference-style link: [The user will see this][thisisthelabel].
A reference-style link requires a reference definition with a matching label thisisthelabel: https://example.com/ on a separate line.
Images and badges
Images can be inserted using  or, reference-style, ![Image][1] followed by a reference definition [1]: <http://url/b.jpg>.
More details may be found in the CommonMark documentation.
A status badge is a small image that provides at-a-glance information, for example the build status of a code repository. Badges are commonly displayed on GitHub READMEs and inserted in mdbook documentation as links to a crate’s docs.rs documentation, GitHub repo, or crates.io page. More information about badges may be found in the awesome-badges repo and in the shields.io documentation.
There is no “badge” concept in the Markdown specification. Badges are simply clickable images e.g. [  ](link-to-webpage).
mdbook-utils refdefs generate --badges creates a flat-style GitHub badge by
default. Add --badge-style flat-square, plastic, for-the-badge, or
social to choose another Shields.io style. Repository name
hyphens and underscores are escaped in the badge path so Shields.io renders
them as literal characters. The default flat style omits the style query
parameter, matching Shields.io’s default and preserving existing output for
repository names without separators.
For example, a GitHub repository named my_repo-with-dash uses this badge
image URL with the flat-square style:
https://img.shields.io/badge/my__repo--with--dash-steelblue?logo=github&style=flat-square
Code blocks and includes
Markdown fenced code blocks (we will call them code examples as well) are inserted between two code fences (e.g. sets of triple backticks), with an optional info string (a.k.a. attributes ) after the first backtick group:
```rust
fn main() {}
```
mdbook allows including files into your book via include statements. mdbook interprets included files as Markdown. Since the include syntax is usually used for inserting code snippets and examples, it is often wrapped between two sets of backticks.
```rust
{{# include file.rs}}
```
An include path is relative to the Markdown file containing the directive.
mdBook also supports selecting a line or line range, or the content between
matching ANCHOR and ANCHOR_END markers. A :2:5 selector includes lines
2 through 5, while :setup selects the content inside the setup anchor.
See the mdBook include reference for the complete syntax.
The mdbook-utils markdown extract-code-examples command writes each fenced
Rust block to a deterministic file beneath the requested output directory.
The chapter’s source-relative path is retained in the output path, and blocks
are numbered in source order (block-000.rs, block-001.rs, and so on). This
prevents same-named chapters from overwriting each other’s examples. The
companion replace-code-examples-by-includes command uses the same mapping to
refer back to those files.