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.
Links¶
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
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
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 iconsfontawesome-regular
for all regular iconsfontawesome-solid
for all Solid iconsmaterial
for the Material Design iconsocticons
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 }
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.).