-
Notifications
You must be signed in to change notification settings - Fork 7
Markdown in Mkdocs
The source of the pages for this tutorial must be written in Markdown, as supported by Mkdocs and its extensions. This is a memo on the possible syntaxes.
You can check the full Markdown tutorial from MkDocs here.
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.
This is a paragraph of text.
This is another paragraph of text.
This line and the next one,
belong to the same paragraph.
Because there's no empty
line in between
Markdown supports 6 levels of titles. To create them, you put 1-6 hash marks (#) at the beginning of the line — the number of hashes equals the resulting HTML header level.
# This is a level 1 header
#### This is a level 4 header
Block-quotes behave almost like a normal paragraph, but the line starts with a >
symbol, like in emails.
> This is a paragraph in a block quote
>
> This is another paragraphe in the same block quote
>
> # This is a level 1 title in a block quote
Asterisks *
can be use to create spans of emphasis. They cannot overlap, but they can be nested.
This is a **bold** emphasis.
This is a *light* emphasis.
This is a ***both** a partially **bold** and fully light* emphasis.
Result:
This is a bold emphasis.
This is a light emphasis.
This is a both a partially bold and fully light emphasis.
It is possible to create bullet lists or ordered (numbered) list. Note that the "sane-lists
" extension is activated for this repository.
For bullet lists, three markers are supported (+
, *
or -
), but in order to keep a harmonized syntax, we recommend using -
.
- first list item
- second list item
- etc
Ordered lists use number followed by a period:
1. first list item
2. second list item
3. etc
Thanks to the sane-lists
extension, it should be possible to nest lists of different types, as long as the indentation is consistent :
- first bullet item
1. first ordered item in first bullet item
2. second ordered item in first bullet item
- second bullet item
It is fairly easy to insert links in the text:
This is an inline [link](https://some.links.com].
output: This is an inline [link](https://some.links.com].
The syntax is very similar for inserting images:
![image: alternative text describing the image](local/path/to/the/img.ext "Optional title")
The alternative text is required for this documentation: it's a elementary way to ensure that anyone can read the full content of the page.
For a better readability of the documentation in case of a broken link to the image, we suggest adding "image:" at the beginning of the alternative text.
The optional title is... optional, but it can be used as a legend for the image.
The "footnotes
" extension is activated in this repository. The syntax is similar to links but requires two components: the anchor (in the text) and the content of the footnote (preferably placed after the paragraph or at the end of the section).
This is a paragraph of text[^id]
[^id]: This is the content of the footnote
The id
can be a keyword (ex: [anchor]
) or a number (ex: [1]
).
The "admonition
" extension is activated in this repository. It allows the creation of colored blocks to insert tips, warnings, notes, etc in the documentation.
The syntax is fairly simple:
!!! type "optional explicit title, within double quotes"
Any number of indented markdown elements.
This is a, for example, a second paragraph.
The supported types that we recommend using in this documentation are:
-
note
: to highlight an important element of additional information -
warning
: to highlight a warning on a feature (ex: a known bug) or on the documentation (ex: an section currently under revision) -
tips
: to provide any additional information which is not essential to using a feature described in the documentation.
Using other types (abstract, info, success, question, failure, danger, bug, example, quote) should be discussed in an issue.
Thanks to the activation of "pymdownx.details
", it is possible to use fancier syntax listed here, such as:
??? type
Collapsed block.
???+ Type
Collapsible block, initially expanded
!!! type inline end
inline block aligned on the right side of the text.
!!! type inline
inline block aligned on the left side of the text.
The "pymdownx.keys
" extension is activated, which enables the rendering of keyboard key combinations. The syntax is fairly simple but requires to take a look at the official key names.
The combination is surrounded by two ++
signs and each key is separated by a single +
sign.
Press ++shift+right-button++
The list of the key names can be found here: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#extendingmodifying-key-map-index
Here are some of the most common ones:
control
shift
backspace
delete
alt
alt-graph
command
In general, the syntax does not support capital letters so ++control+c++
would show Ctrl+C
but ++Control+C++
wouldn't work.
To modify the rendering of the keys, see the "KEYS" section in src/css/extrq.css
and "key_map" in mkdocs.yml
.