Skip to content

Markdown in Mkdocs

Alix Chagué edited this page Feb 2, 2023 · 5 revisions

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.

Basic syntax

Paragraphs, headers and blockquotes

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

Emphasis

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.

Lists

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

Links

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].

Images

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.

Footnotes

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]).

Admonition in Mkdocs

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.

Keys

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.

Clone this wiki locally