mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/) specification with some extensions described below.
You can take a quick [tutorial](https://commonmark.org/help/tutorial/),
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](#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.
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.
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](https://github.com/raphlinus/pulldown-cmark/blob/master/pulldown-cmark/specs/heading_attrs.txt).
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:
```md
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:
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.
Terms are clickable just like headers, which will set the browser's URL to point directly to that term.
See the [definition lists spec](https://github.com/pulldown-cmark/pulldown-cmark/blob/HEAD/pulldown-cmark/specs/definition_lists.txt) for more information on the specifics of the syntax. See the [Wikipedia guidelines for glossaries](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Glossaries#General_guidelines_for_writing_glossaries) for some guidelines on how to write a glossary.
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.
```md
> [!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.
