Skip to content

Lecture 03 - Markdown extended syntax

Here a first overview of the Markdown extended syntax, and some additional feature from Mkocs-et.

Tables

To add a table, use pipes | to separate columns, and hyphens - to delimit the header. You can optionally add pipes on either end of the table, and they don't need to be aligned in the markdown source.

| Method      | Description                          |
| ----------- | ------------------------------------ |
| `GET`       | :material-check:     Fetch resource  |
| `PUT`       | :material-check-all: Update resource |
| `DELETE`    | :material-close:     Delete resource |
Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource

It is also possible to align the columns by putting : next to the hyphens.

| Left        | Centered    | Right         |
|  :--------  | :---------: | ------------: |
| Header      | Title       | Here's this   |
| Paragraph   | Text        | And more      |
Left Centered Right
Header Title Here's this
Paragraph Text And more

The tables are sortable by default (just click on a header).

To prevent a table to be sortable, add a comment <!-- @nosort --> just before the table. This is a Mkdocs-et hack; the result will not be observable in serve mode, only in publish mode.

Method Description
GET Fetch resource
PUT Update resource
DELETE Delete resource

You can also remove the header from a table, by adding a comment <!-- @noheader --> just before a table; again, this is a Mkdocs-et hack, only visible in publish mode.

GET Fetch resource
PUT Update resource
DELETE Delete resource

(there may be a Python plugin that allows you to do this in markdown syntax).

Footnotes

To create a footnote reference, add a caret and an identifier inside brackets, e.g. [^n]. Identifiers can be numbers or words, but they can’t contain spaces or tabs. Identifiers only correlate the footnote reference with the footnote itself; in the output, footnotes are numbered sequentially.

Add the footnote using the same label and a colon, e.g. [n]:, followed by the text.

Here is a simple footnote,[^1] and here is a longer one.[^bignote]

[^1]: This is the first footnote.

[^bignote]: Here is one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    `{ my code }`

    Add as many paragraphs as you like.

Here is a simple footnote,1 and here is a longer one.2

Custom Heading IDs as anchors

Each heading title can get a custom ID as an anchor.

The syntax is

## This is a title { #title-id }

Note:

Remember to put a space between { and # to not confused them with Jinja2 comments {#.

You can then link the title from its ID with [this is a link](#title-id) or in other page with

[this is a link](../path-to-file/#title-id)

There is also the possibility to give a long title and a short title for the table of content with

## This is a long title { #title-id data-toc-label="Short title" }

The short title will appear in the table of content. For instance, this section's title was obtained by

## Custom Heading IDs as anchors { #heading-id data-toc-label="Heading IDs" }

and this link by [this link](#heading-id).

Definition Lists

A definition list allows to create an HTML <dl>...</dl> block with terms and indented definitions.

To create a definition list, type the term on the first line. On the next line, type a colon followed by one or more spaces and the definition.

First Term
:   This is the definition of the first term.

Second Term
:   This is one definition of the second term
    on several lines␣␣
    with a line break.
:   This is another definition of the second term.
First Term
This is the definition of the first term.
Second Term
This is one definition of the second term on several lines
with a line break.
This is another definition of the second term.

Strikethrough and subscript

Thanks to the extension pymdownx.tilde, it is possible to strike out text or put it in superscript.

For superscript, put the text between single tildes ~...~; for strikethrough, put it between double tildes ~~...~~. White spaces must be escaped in superscripts.

For instance,

This text ~is\ superscript~ while this one is ~~striked out~~.

will be rendered as
This text is superscript while this one is striked out.

Task Lists

Task lists allow you to create a list of items with checkboxes, and is provided by the extension pymdownx.tasklist.

- [X] Write this documentation
- [ ] Check the website
- [ ] Contact the media
  • Write this documentation
  • Check the website
  • Contact the media

Emoji and keyboard keys

To put an emoji like 😄, write its name between single columns, e.g. :smile:.

You can find lists of emoji names from the pymdownx.emoji extension page or for instance in this table.

It is also possible to draw keyboard keys, for instance Ctrl+Alt+T is obtained by ++ctrl+alt+t++.


  1. This is the first footnote. 

  2. Here is one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    { my code }

    Add as many paragraphs as you like.