blog » self-hosted » markdown

Writing Pages in Markdown

If you are still here, you might be interested in How to Add Color to the fenced-code-blocks.

This section documents how Markdown works on this website, how code blocks are rendered, how admonitions behave, and a few extra features supported by my setup.
If you’re used to GitHub-style Markdown, most of this will feel familiar — except the parts that absolutely aren’t.

Code Blocks and Syntax Highlighting

The fenced-code-blocks extra lets you write code with syntax highlighting using triple quotes (```) (in the following example, I replaced ``` by ''' so that it renders).

Here is a simple Python example:

'''python
import numpy as np

print(np.sum(range(100)))
'''

... which renders to:

import numpy as np

print(np.sum(range(100)))

If you forget an import or misspell a function, the syntax highlighter won’t judge you. I might — but the highlighter won’t.

Inline code is supported as usual, try mv /some/path /some/other/path to fix a wrongly placed file, or use it to demonstrate your outstanding typing accuracy.

Strikethrough is also available: very useful for crossing out bad ideas.

Admonitions (Important!)

This website uses the admonitions extra from markdown2, which is not the same syntax as GitHub Markdown.
It’s both more flexible and more obscure — a perfect combination for a self-hosted blog. They use the following synxtax:

Admonitions come in seven flavors:

• Note
• Tip
• Important
• Warning
• Caution / Danger
• Error

Each one has its own style in the final HTML.
Use them to highlight information, warn future-you about bad decisions, or add visibility to critical details.

Example of a Tip

Syntax Explained

Anatomy of an Admonition

Common Pitfalls

Blockquotes

Quotes use the classic Markdown syntax:

Hello

Written like this:

> Hello

Useful for callouts, citations, and passive-aggressive comments.

LaTeX Support

Mathematical expressions are rendered using the latex extra.

For example:

$$\sum_{i=1}^n i = \frac{n(n+1)}{2}$$

renders to:

Block math, inline math, and equations involving actual numbers (as opposed to purely symbolic flexing) all work.

Tables

Tables are fully supported and behave as you’d expect:

Good for structured information, comparisons, or listing all the services you forgot to configure properly the first time.