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