Syntaxes for Writing Markdown Documents

There are some useful Markdown extensions that brings more convenience for you while working with writing, especially in editing technical documents. Let's take a look at all extensions and new syntaxes which are being used in this site.

#markdown

Last update: 2022-05-07

Table of Content

For basic markdown syntax, refer to Markdown Guide

Meta-data#

The Meta-Data extension adds a syntax for defining meta-data of a document. It is inspired by and follows the syntax of MultiMarkdown. Meta-data is the additional information that can be used to briefly describe the content of a post, such as the title, the short description, tags, and sometimes the banner image. I prefer YAML format:

---
title: The page title
description: The summary of the page content
---

The meta-data can be used in the template and the page content¹. In Jinja syntax, each page is represented as a page object, then the meta-data field {{page.meta.title}} will be replaced by the string The page title.

Code highlighting#

Below extensions are extremely useful for showing code blocks by adding colors, and decoration.

Inline code#

The InlineHilite is an inline code highlighter inspired by CodeHilite.

Borrowing from CodeHilite’s existing syntax, InlineHilite utilizes the following syntax to insert inline highlighted code: `:::language my code` or `#!language my code`.

This will render this line `#!python [x for x in range(1, 10) if x % 2]` to a fully colored inline Python code: [x for x in range(1, 10) if x % 2].

Code blocks#

The Code blocks plugin provides a number of features including allowing the nesting of fences, and ability to specify custom fences to provide features like flowcharts, sequence diagrams, or other custom blocks. Highlighting can be further controlled via the Highlight extension.

The standard format which supports to add id, class, or custom attribute key=value is as below:

```{ .language #id .class key="value"}
content
```

Some special attributes key=value are as below:

title="abc" creates a title for the block, used to show the filename or the purpose.
linenums="n" creates line numbers starting from n.
hl_lines="x y-z" highlights the x-th line and lines in the range from y-th to z-th. Line numbers are always referenced starting at 1 ignoring what the line number is started labeling at the number set by the option linenums="n".

Example:

``` cpp title="main.c" linenums="2" hl_lines="1 4-5"
#include <stdio.h>

int main(void) {
    printf("Hello world!\n");
    return 0;
}
```

Result:

main.c

#include <stdio.h>

int main(void) {
    printf("Hello world!\n");
    return 0;
}

Code annotations#

Code annotation is a unique feature of Material theme which offers a comfortable and friendly way to attach arbitrary content to specific sections of code blocks by adding numeric markers in block and inline comments in the language of the code block.

Code annotations can be placed anywhere in a code block where a comment for the language of the block can be placed, e.g. for JavaScript in // ... and /* ... */, for YAML in # ..., etc.

Example:

``` cpp
int main(void) {
    printf("Hello world!\n");
    return 0;
}
```

1. Need including\
   `#!cpp #include <stdio.h>`

Result:

Click on to show the annotation.

int main(void) {
    printf("Hello world!\n"); // (1)
    return 0;
}

Need including
#include <stdio.h>

Admonitions#

Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow.

Marked blocks#

These types of blocks show an icon to help readers notice the kind of content, such as additional information, caution, or error.

Example:

!!! info "The title of the block"

    The content can contain formatted text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam sagittis ante blandit diam accumsan scelerisque.

    - Lorem ipsum dolor sit amet
    - Lorem ipsum dolor sit amet

    ``` cpp
    int main(void) {
        return 0;
    }
    ```

Result:

The title of the block

The content can contain formatted text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam sagittis ante blandit diam accumsan scelerisque.

Lorem ipsum dolor sit amet
Lorem ipsum dolor sit amet

int main(void) {
    return 0;
}

To remove the title but keep the icon, use a space:

!!! hint " "

    Need some CSS styles to adjust content block of admonitions.

Result:

Need some CSS styles to adjust content block of admonitions.

Supported types#

abstract, summary, tldr

info, todo

tip, hint, important

success, check, done

question, help, faq

tag

warning, caution, attention

failure, fail, missing

danger, error

bug

example

quote, cite

Collapsible blocks#

When Details is enabled and an admonition block is started with ??? instead of !!!, the admonition is rendered as a collapsible block with a small toggle on the right side. Use plus (+) sign to make it expanded by default.

Example:

???+ quote "Expandable"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

Result:

Expandable

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

MathJax#

MathJax is a beautiful and accessible way to display mathematical content in the browser, adds support for mathematical typesetting in different notations (e.g. LaTeX, MathML, AsciiMath).

Block syntax#

Blocks must be enclosed in $$...$$ or \[...\] on separate lines:

Example:

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$

Result:

\[ \operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}} \]

Inline syntax#

Inline blocks must be enclosed in $...$ or $...$ :

Example:

The homomorphism $f$ is injective if and only if its kernel is only the singleton set $e_G$, because otherwise $\exists a,b \in G$ with $a \neq b$ such that $f(a)=f(b)$.

Result:

The homomorphism $f$ is injective if and only if its kernel is only the singleton set $e_G$, because otherwise $\exists a,b \in G$ with $a \neq b$ such that $f(a)=f(b)$.

Formatting#

Beside Italic, Bold, Italic and Bold, here are some more syntax to format texts.

Caret#

Caret optionally adds two different features which are syntactically built around the ^ character.

The double carets ^^ inserts <ins></ins> tags, and
the single caret ^ inserts  tags.

Example:

The ^^mass-energy^^ equivalence: E=m*c^2^.

Result:

The mass-energy equivalence: E=m*c².

Mark#

Mark adds the ability to insert  tags.

The syntax requires the text to be surrounded by double equal signs == .

Example:

==mark me== and ==mark==me==all==.

Result:

mark me and mark==me==all.

Tildes#

Tildes optionally adds two different features which are syntactically built around the ~ character.

Add Deletion by using double tildes ~~ which inserts <del></del> tags and
Add Subscript by using single tilde ~ which inserts  tags.

Example:

~~Remove~~ the existence of CH~3~CH~2~OH.

Result:

~~Remove~~ the existence of CH₃CH₂OH.

Critic#

Critic is an extension that adds handling and support of Critic Markup which uses a special syntax to represent edits to a Markdown document. This extension runs before all other extensions to parse the critic edits.

Critic Markup uses special markup to insert, delete, substitute, highlight, and comment.

Example:

To insert or remove text, use {++insert me++} and {--remove me--}.\
Denote a substitution with {~~that ~> this one~~}.

Highlight specific text with {==highlight me==}.\
Or even add {>>a comment<<}.

Result:

To insert or remove text, use insert me and ~~remove me~~.
Denote a substitution with ~~that~~ this one.

Highlight specific text with highlight me.
Or even add a comment.

Lists#

This element allows to group a set of related items in lists. Children items can be numbered in ordered list, or even can have inline checkbox.

Ordered list#

1. Ordered item 1
    1. Child 1
    2. Child 2
2. Ordered item 2

Ordered item 1
1. Child 1
2. Child 2
Ordered item 2

Unordered list#

-   Unordered item 1
    -   Child 1
    -   Child 2
-   Unordered item 2

Unordered item 1
- Child 1
- Child 2
Unordered item 2

Task list#

-   [x] item 1
    -   [x] item a
    -   [ ] item b
-   [ ] item 2

item 1
- item a
- item b
item 2

Definition#

Roses
:   are red

Violets
:   are blue

Roses: are red
Violets: are blue

Images#

There are some extensions to add a caption to an image. After testing, markdown-captions is a good one that uses the alternate text to make caption, accepts markdown in the alternate text.

![A photo from <https://picsum.photos>](https://picsum.photos/320/240)

Some images have big size that does not show the detail, therefore, it’s better to zoom in by clicking on them, and pan the image on the screen. The view-bigimg library can do that requirement well.

Tabs#

Tabbed extension provides a syntax to easily add tabbed Markdown content.

Tabs start with === to signify a tab followed by a quoted title. Consecutive tabs are grouped into a tab set.

Example:

=== "Tab 1"
    Some texts

    === "Tab A"
        Text A

    === "Tab B"
        Text B

=== "Tab 2"
    Some other texts

Result:

Tab 1Tab 2

Some texts

Tab ATab B

Text A

Text B

Some other texts

Tables#

Markdown Tables are written in pipe-line format: row is on one line, cell is inline text only. The 1^st line contains the column headers. The 2^nd line is to control text alignment in a column: :---, :---: and ---: are left, center, and right alignment. Styles for table need to change a little to show cell border.

Example:

| Syntax     | Description  |   Test Text |
| :--------- | :----------: | ----------: |
| Left align | Center align | Right align |
| A text     | Another text |  More texts |

Result:

Syntax	Description	Test Text
Left align	Center align	Right align
A text	Another text	More texts

Icons & Emojis#

The Emoji extension adds support for inserting emoji via simple short names enclosed within colons :short_name:. This is accomplished by using a short name index to map easy-to-remember names to the corresponding emoji characters.

Emojis#

Emojis can be written by putting the short-code of the emoji between two colons. Look up the short-codes at Emojipedia.

:smile: , and :heart:

Icons#

Icons can be used similarly to emojis, by referencing a valid path to any icon bundled with the theme, which are located in the .icons directory, and replacing / with -.

E.g. The short-code :material-account-circle: will be converted to an SVG image element with the path .icons/material/account-circle.svg which eventually shows the icon on the webpage.

Using include function of Jinja to add an icon wrapped in a twemoji class, e.g. to show :

<span class="twemoji">
    {% include ".icons/fontawesome/brands/twitter.svg" %}
</span>

Escape All#

The Escape All extension makes the backslash \ character escape everything after it, except things in code blocks of any kind.

There are two special escapes among all of these escapes though: escaping space characters and escaping newline characters:

Enable nbsp to convert an escaped space into a non-breaking space:  .
Enable hardbreak to convert an escaped newline to a hard break  . The advantage of hard break is that the backslash is visually seen in the document, opposed to the Markdown’s default method of two spaces at the end of a line.

Special characters#

The Smarty Pants extension converts ASCII dashes, quotes and ellipses to their HTML entity equivalents.

Syntax	Render
`'single quote'`	‘single quote’
`"double quote"`	“double quote”
`<<angle quote>>`	«angle quote»
`ellipses ...`	ellipses …
`N-dash --`	N-dash –
`M-dash ---`	M-dash –

The Smart Symbols adds syntax for creating special characters such as trademarks, arrows, fractions, etc.

Syntax	Render
`trademark (tm)`	trademark ™
`copyright (c)`	copyright ©
`registered (r)`	registered ®
`in care of c/o`	in care of ℅
`plus or minus +/-`	plus or minus ±
`arrows --> <-- <-->`	arrows → ← ↔
`not equal =/=`	not equal ≠
`fractions 1/4 2/3`	fractions ¼ ⅔
`ordinal numbers 1st 2nd 3rd 4th 5th`	ordinal numbers 1^st 2^nd 3^rd 4^th 5^th

Not all fractions can be displayed. To render fractions in a better format, use MathJax with inline format. Such as $1 \over 4$ → $1 \over 4$, or $2 \over 3$ → $2 \over 3$.

Footnotes#

The Footnotes extension adds syntax for defining footnotes in Markdown documents.

Example:

Footnotes[^fn] have a label[^lb] and the footnote's content.

[^fn]: This is a footnote content.
[^lb]: A footnote on the label `lb`.

Result:

Footnotes² have a label³ and the footnote’s content.

Use mkdocs-macros plugin to use Jinja template directly in the Markdown content. ↩
This is a footnote content. ↩
A footnote on the label lb. ↩

Syntaxes for Writing Markdown Documents

Table of Content

Meta-data#

Code highlighting#

Inline code#

Code blocks#

Code annotations#

Admonitions#

Marked blocks#

Supported types#

Collapsible blocks#

MathJax#

Block syntax#

Inline syntax#

Formatting#

Caret#

Mark#

Tildes#

Critic#

Lists#

Ordered list#

Unordered list#

Task list#

Definition#

Images#

Tabs#

Tables#

Icons & Emojis#

Emojis#

Icons#

Escape All#

Special characters#

Footnotes#

Comments