Markdown Benchmark
h1🔗
See markdownguide.org for basic and extended Markdown syntax.
Markdown is fairly relaxed regarding its syntax, e.g. indentation. However, different Markdown processors are more or less forgiving. Python-Markdown (MkDocs) for example, requires 4 spaces of indentation or things won’t render properly.
h2🔗
h3🔗
h4🔗
h5🔗
1 2 3 4 5 6 7 8 9 | |
Text Formatting🔗
| Formatting | Syntax | Rendered | Standard |
|---|---|---|---|
| italic | *using asterisks* or _using underscores_ |
using asterisks or using underscores | ✅ |
| bold | **using asterisks** or __using underscores__ |
using asterisks or using underscores | ✅ |
| strike-though | ~~strike-through~~ |
 |
|
| highlight | ==highlighted text== |
highlighted text | |
| subscript | H~2~O |
H2O | |
| superscript | ^13^C |
Carbon-13 (13C) | |
Lists🔗
- unordered
- list
- ordered
- list
non-standard
- item
- definition
- check lists
1 2 3 4 5 6 7 8 9 10 11 12 | |
Links and Images🔗
- Standard Markdown:
[link text](path/URI "alt text")(link description is optional) - Wiki-links (non-standard):
[[path/to/file|link text]] -
To embed images add an exclamation mark
!to a markdown link (or Wiki-link if supported).Some Markdown processors support specifying attributes in the alt text, such as the size (width in pixels
200, dimensions400x200or even horizontal alignment)1
Free Books Leather photo and picture by Joa70 via Pixabay
Block Quotes🔗
Pre-pended with >␣
Don’t walk behind me; I may not lead. Don’t walk in front of me; I may not follow. Just walk beside me and be my friend.
– Albert Camus
Code🔗
inline code: `code`
fenced code block with language syntax highlighting
| Example fenced code block: YAML front matter | |
|---|---|
1 2 3 | |
Syntax:
```yaml title="Example fenced code block: YAML front matter"
---
title: Example Code Block
---
```
Some Markdown processors allow for additional specifications beside a syntax language. Whether this results in unrendered crap if unsupported depends on your Markdown reader. Obsidian just ignores it. Some processors, such as Pandoc, use curly braces {} to specify options for fenced code blocks. Generally be aware of incompatibilities or stick to one Markdown implementation/reader, ideally one with high compatibility such as CommonMark.
An alternative syntax for code blocks is simply by indentation. However this syntax is highly ambiguous,1 does not have a way of specifying a code language for syntax highlighting and is therefore not recommended.
1 2 3 | |
Tables🔗
See https://www.markdownguide.org/extended-syntax/#tables
| col1 | col2 | col3 |
|---|---|---|
| left-aligned | centered | right-aligned |
1 2 3 | |
Footnotes🔗
Footnote referenced simply by number,2 and a longer one.3
1 2 3 4 5 6 7 | |
Some Markdown processors have additional syntax for direct definition of the footnote text, using the text in square brackets as the footnote text if not otherwise specified.^[e.g. Obsidian]
1 | |
HTML🔗
⚠ Don’t mix HTML with Markdown, it usually doesn’t render well.
Columns
Stick to HTML inside this construct. This will make it more difficult to use lists, tables and especially code blocks.
However, things might render at least partially.
1 2 3 4 5 6 7 | |
This happens to render fine in MkDocs (using Python-Markdown), but not in Obsidian.
Tags🔗
Tags are a helpful tool to categorise information and as bookmarks. They can be
specified for an entire page/note in the YAML front matter,
1 2 3 4 5 6 | |
or inline #markdown/tags
MkDocs (Python-Markdown) don’t handle tags at a line start well and interpret
them as headings. Obsidian considers them as tags as it is assumed that headings
will have a space after the # symbol.
Maths🔗
inline: \(\int_0^\infty \frac{1}{x} \text{d}x\)
equation:
Mermaid Graphs🔗
Most Markdown processors have built-in support for Mermaid graphs. For some additional plugins are required.
See mermaid.js.org for syntax and graph types.
Example
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
```mermaid
graph LR
A[Start] --> B{Error?};
B -->|Yes| C[Hmm...];
C --> D[Debug];
D --> B;
B ---->|No| E[Yay!];
```
Emojis🔗
Some Markdown processors support rendering emoji short codes (possibly requiring
a plugin). :partying_face: 
Refer for example to this (not necessarily complete) list of emoji shortcodes.
Admonitions or Call-outs🔗
These are highlighted boxes and are another common Markdown extension. They feature a title line and usually distinct symbols and colours to stand out. As such they are great to emphasise important information. They are similar to the HTML tag <details> and can be collapsible as well.
MkDocs admonitions
In MkDocs the extension admonition is required in mkdocs.yml. MkDocs uses the syntax
1 2 3 4 5 6 | |
This is problematic for various reasons and renders poorly in systems not supporting this extension.
Obsidian uses the term call-out and the syntax
> [!type] title
> content
> [!type]- collapsed call-out
> content
> [!type]+ expanded call-out
> content
rendering more reasonable in processors without this Markdown extension.
With MkDocs plugins this syntax can be kept and will be automatically translated
to MkDocs admonition syntax, see mkdocs-callouts and mkdocs-obsidian-support-plugin.
-
Python-Markdown for example expects 4 spaces of indentation. Other Markdown processors use 2 spaces and 4 spaces designate an indented code block. Beside rendering, this syntax is also unclear when reading the plain text Markdown. Many linters even complain about these code blocks. Just don’t use them. ↩
-
easy to use, but you have to keep track of anchors to avoid duplicate definitions ↩
-
Longer footnotes with paragraphs
just indent the contents ↩