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
, dimensions400x200
or even horizontal alignment)1
![image title|size](URI "alt title")
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 ↩