Skip to content

Formatting Help

This page lists all the different Markdown formatting syntaxes, which are used across the documentation.
Please not that not all Styles are available for the default Markdown shipped with MkDocs and require extensions to be installed.
Any extension required will be mentioned.

Lists

Unordered and ordered lists have a slightly different formatting than the one you're probably used to.
In order for the list to work will they require an empty line between the list, and any displayed text above them.

List example

This list below will work.

- Entry 1
- Entry 2
- Entry 3

----  
This list, however, won't work.
- Entry 1
- Entry 2
- Entry 3

This list below will work.

  • Entry 1
  • Entry 2
  • Entry 3

This list, however, won't work. - Entry 1 - Entry 2 - Entry 3

In addition to the above requirement will you also need to use 4 spaces compared to the usual 2, when you want to indent the list.

Indent example

Working indents:

- Entry 1
    - Entry 1.1
- Entry 2

----  
Not working indents:

- Entry 1
  - Entry 1.1
- Entry 2

Working indents:

  • Entry 1
    • Entry 1.1
  • Entry 2

Not working indents:

  • Entry 1
  • Entry 1.1
  • Entry 2

Info boxes

You sure have noticed those neat looking boxes that contain various information of stuff.
Those are provided through MkDocs and use a specific syntax, that you need to follow.

Box examples

!!! info "Title"
    Rules about Markdown still apply.

    - F.e. Lists
    - Still need an empty line

----

!!! info
    The title can be omited.  
    The box will then use the name of its type.

Title

Rules about Markdown still apply.

  • F.e. Lists
  • Still need an empty line

Info

The title can be omited.
The box will then use the name of its type.

Special rules

  • You don't need to add two spaces after the !!! <type> "<title>". MkDocs can handle this just fine.
  • You need to add at least one empty line before and after the info box to not have unwanted formatting issues.

Types

The info boxes have various types available which you can choose from:

Note

Summary

Info

Tip

Success

Question

Warning

Failure

Danger

Bug

Example

Quote

Collapsable info boxes (Details)

This feature requires the Details extension from PyMdown.

Those boxes are similar to the normal info boxes, but can be collapsed (closed) or expanded (opened).
They follow the same syntax as the info boxes, but use question marks (?) instead of exclamation marks (!).
You can use the exact same types as with the info boxes.

Collapsable Box example

??? info "Title"
    This box is closed by default

----

???+ info "Title"
    Adding a + after the question mark makes this box open by default.
Title

This box is closed by default

Title

Adding a + after the question mark makes this box open by default.

Tabs

This feature requires the Tabbed extension from PyMdown.

Adds tabbed Markdown to list content after each other. This was used here for the various Markdown examples and their results.
The syntax is the same as with the info box, with the difference that it uses equal signs (=) instead of exclamation marks (!).
Additionally does it also not have a type parameter, meaning you can only set the tile itself.

Tabs example

=== "Tab 1"
    You can add more tabs...

=== "Tab 2"
    ...by adding extra `===`.

===! "Tab A"
    Using a ! after the equal signs...

=== "Tab B"
    ...indicates a new set of tabs.

You can add more tabs...

...by adding extra ===.

Using a ! after the equal signs...

...indicates a new set of tabs.

We use the PyMdown extension MagicLink which allows us to automatically transform links into clickable links. This doesn't happen by default.

Link example

https://purrbot.site

https://purrbot.site

Additionally can we link to a repository or GitHub user by just using the format @user/repo and @user respectively.
This also works with Twitter-users by prefixing the name with twitter: (@twitter:username)

Mention examples

@purrbot-site  
@purrbot-site/Docs  
@twitter:TruePurrBot

@purrbot-site
purrbot-site/Docs
@TruePurrBot

Emojis

We use the Emojis extension from PyMdown to allow the usage of emojis through the common :emoji: pattern.
We also use the MkDocs-Material Extension which adds support for using SVG icons of FontAwesome, Material Design and Octicons in the same format.

Note that unlike emojis, the custom ones added by the MkDocs-Material Extension require to be prefixed with the site they should come from.

  • fontawesome-brands for brand icons
  • fontawesome-regular for all regular icons
  • fontawesome-solid for all Solid icons
  • material for the Material Design icons
  • octicons for the Octicons icons

Note about FontAwesome and Octicons

The MkDocs-Material Extension will only be able to use free FontAwesome icons! Paid ones aren't supported.

Due to Octicons being offered in 16px and 24px format, are you required to suffix the icon name with either -16 or -24 depending on which you want to use.
As an example: Instead of :octicon-repo: would you use :octicon-repo-16: or :octicon-repo-24:

Emoji/Icons Examples

Normal Emojis  

- :smile:
- :heart:

FontAwesome Icons (Brands):  

- :fontawesome-brands-github:
- :fontawesome-brands-discord:

FontAwesome Icons (Regular)  

- :fontawesome-regular-bell:
- :fontawesome-regular-bell-slash:

FontAwesome Icons (Solid)  

- :fontawesome-solid-bell:
- :fontawesome-solid-bell-slash:

Material Design:

- :material-sync:
- :material-alert:

Octicons:

- :octicons-repo-24:
- :octicons-git-pull-request-24:

Normal Emojis

  • 😄
  • ❤

FontAwesome Icons (Brands):

FontAwesome Icons (Regular)

FontAwesome Icons (Solid)

Material Design:

Octicons:

Buttons

Using the List Attribute extension can we turn embedded Links ([text](link)) into buttons by appending {: .md-button } to it.

Button Example

[To the Website](https://purrbot.site){: .md-button }

To the Website

Final Words

Those are all the important parts you need to know about the markdown syntax for the documentation.
Anything Markdown-related that wasn't mentioned here is assumed to be the normal formatting (e.g. *italic*, **bold**, etc.).