Markdown

Syntax

Basic Syntax

These are the basic commands that Markdown offers and should fundamentally work in every tool.

Headings

To display headings, one or more hashtags are placed before the heading title, depending on the level.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Note: It is best to always insert a blank line before a heading, as interpretations may otherwise be incorrect.

Paragraphs/Lines

There are no real notations for line breaks and paragraphs; the text is displayed as written. To support a line break, two spaces can be added at the end of the line, or alternatively, the HTML tag <br> can be used.


First line with two spaces at the end.  
And now the next line.

First line with the HTML tag at the end.<br>
And now the next line.

Text Formatting

By default, Markdown offers the ability to display text as bold and/or italic.

To display text in bold, the corresponding text part is written between double stars or underscores.


I also have **bold text**.

I also have __bold text__.

And here is **bold text** in the middle.

To display text in italics, the corresponding text part is written between single stars or underscores.


I also have *italic text*.

I also have _italic text_.

And here is *italic text* in the middle.

Of course, these can also be combined:

To display text in bold and italic, the corresponding text part is written between triple stars or underscores.


I also have ***bold and italic text***.

I also have ___bold and italic text___.

And here is ***bold and italic text*** in the middle.

Blockquotes

To quote text as a block, simply place a “greater than” sign before the line.


> This text is in a blockquote.

If the blockquote is to span multiple lines, the “greater than” sign must be placed at the beginning of each line (including empty lines).


> This text represents the first line in the blockquote.
> 
> And here is the next line.

Quotes can also be nested; in this case, an additional “greater than” sign is added for the next level or indentation.


> This text is in a blockquote.
> 
>> This text is nested.

Lists

Lists are just as simple and are written directly in the text. If the list goes to another level, this is enabled by indentation (4 spaces or 1 tab).

Ordered List

Ordered lists are generated by simply placing the corresponding number followed by a period before the line.


1. First item
2. Second item
3. Third item
    1. first indentation
    2. second indentation
4. Fourth item

Unordered List

Unordered lists are generated by simply placing a hyphen before the line.


- First item
- Second item
- Third item
    - first indentation
    - second indentation
- Fourth item

Links and Images

To display a link, the link text is placed in square brackets, followed by the URL within parentheses.

Ordered lists are generated by simply placing the corresponding number followed by a period before the line.


My favorite search engine is [Swisscows](https://swisscows.com/en).

A title can also be added to the link as a tooltip.


My favorite search engine is [Swisscows](https://swisscows.com/en "The Swiss search engine").

As a shorthand, a URL can also simply be written within angle brackets.


My favorite search engine is <https://swisscows.com/en>.

Extended Syntax

Tables

Tables are defined using vertical bars (|) and hyphens (-). The first line contains the column headers, the second line defines the alignment (optional).

| Left aligned | Centered      | Right aligned |
| :----------- | :-----------: | ------------: |
| Cell 1       | Cell 2        | Cell 3        |
| Cell 4       | Cell 5        | Cell 6        |

Note: The number of hyphens in the separator line is arbitrary; only the : for alignment matters.

Code Blocks

For multi-line code, a code block is created with three backticks (```) or with four spaces per line. Optionally, the language can be specified to activate syntax highlighting.

```python
def hello():
    print("Hello, World!")


---

#### Footnotes

Footnotes are inserted in the text with `[^identifier]` and defined at the end of the file with `[^identifier]:`.

```markdown
Here is a text with a footnote.[^1]

[^1]: This is the explanation for the footnote.

Note: Not all Markdown parsers support footnotes – e.g., Hugo requires goldmark with the option enabled.

IDs for Headings

Headings can be provided with an ID to link to them directly (e.g., for tables of contents or anchor links).

## Heading with ID {#my-id}

[Link to heading](#my-id)

Note: In Hugo, enableInlineShortcodes = true must be activated in the configuration.

Task Lists

Task lists (checklists) are created with - [ ] for unchecked and - [x] for checked items.

- [x] Task completed
- [ ] To do
- [ ] Do later

Note: Often used in GitHub, GitLab, or note apps like Obsidian.

Strikethrough

Strikethrough text is enclosed with double tildes (~~).

This text is ~~strikethrough~~.

Emojis

Emojis can be inserted directly (e.g., 😊) or with shortcodes like :smile: (depending on the parser).

I'm in a good mood today 😊

Note: In Hugo, emojis must be explicitly activated (enableEmoji = true).

Highlighting Text

Some parsers (e.g., Hugo with Goldmark) support highlighting with ==:

This text is ==highlighted==.

Note: Not standardized – does not work everywhere.

Sub-/Superscript

Subscript (H₂O) and superscript (x²) are represented with ~ and ^ respectively – but only in some extensions like Pandoc or Hugo with a special parser.

Water is H~2~O.  
x^2^ is x squared.

Note: Not part of the CommonMark standard – Works, for example, in Hugo with goldmark and the option enabled.

Usage

Markdown does not represent a system of its own but stands purely for an open and freely available syntax. One could compare Markdown to an embeddable scripting language. This is certainly also the reason why so many systems support Markdown and the language is thus so versatile.

Wiki Systems

Wiki systems such as Mediawiki (on which Wikipedia is based), dokuWiki, or integrated wiki functions like those in GitHub or GitLab standardly use Markdown for content management.

Wikis are primarily there to present content, in the Git area documentation for the offered software. Thanks to the simple syntax, these can also be created and managed by non-techies.

Notes

The widely available note apps (or sometimes also called desktop wikis) also rely on Markdown for content management. Often an integrated WYSIWYG editor is provided, but it uses Markdown in the background. There is usually also the possibility to switch to the source text and edit directly there. Examples include Zim, Zettlr, QOwnNotes, and Logseq in the open-source area, or popular variants like Evernote, Obsidian, or Joplin.

Websites

In the area of websites, Markdown appears in two ways. On the one hand, well-known Content Management Systems (such as WordPress and Drupal) often offer plugins/modules to publish content in Markdown. But besides CMS, there are also SSGs, so-called Static Site Generators, such as Hugo or Jekyll. In addition, there are similar systems specialized in technical documentation like MKDocs, Sphinx, or Docusaurus. Here too, all content is created in Markdown and then converted into static websites using a preprocessor, which can then be published.

Presentations/Courses

Besides websites, presentations can also be created with Markdown. However, these are not PowerPoint presentations but are dynamically converted into web elements using preprocessors. Examples include Marp, remarkJS, or Cleaver. Specifically for online courses, the Markdown extension LiaScript is suitable.

Documents

Markdown certainly lacks some functionalities that a word processor like MS Word or LibreOffice Writer can offer, but it is perfectly sufficient for simple documents such as letters.

Conclusion

Advantages

Markdown has a simple and clear syntax and is therefore easy to learn. Markdown documents also have the advantage of being easily readable even in source text. They are thus both machine-readable and human-readable. The latter thanks to the simple and straightforward syntax without overhead. The wide distribution of Markdown and its integration into so many tools also speaks for itself.

Disadvantages

Besides the clear advantages, there is unfortunately also negative news about Markdown.

Markdown is very suitable for articles and notes that are not structured too complexly. If one wants to create more, e.g., large and complex documents, such as entire books, useful functions like a table of contents or the possibility to nest files using “Include” are missing.

Although there is a Markdown standard with CommonMark, the strong distribution has nevertheless led to many “dialects,” as many tools extend the standard syntax with their own commands. As a result, Markdown documents from different systems are not necessarily compatible with each other.