Markdown Syntax¶

Pages on this site are written in Markdown and built with Zensical. Zensical uses Python-Markdown with the PyMdown Extensions, so a few things work differently from other Markdown flavors (like GitHub’s).

Zensical syntax guides¶

See the following links from the Zensical docs for specific Markdown syntax, and for an idea of how things will render:

Things to watch out for¶

Indent nested content by 4 spaces¶

Anything nested inside a list item (sub-lists, code blocks, admonitions) must be indented by 4 spaces. Some editors (including VS Code) indent by 3 spaces after 1., which makes nested lists flatten into the parent list.

example.md

1. Install Caddy:
    ```bash
    sudo apt install caddy
    ```
2. Configure Caddy:
    1. Open the Caddyfile.
    2. Edit it.

Admonitions¶

Admonitions (callout boxes) start with !!!, the type, and an optional title. The content is indented by 4 spaces:

example.md

!!! warning "Optional title"
    Content goes here.

The types we use are note, info, tip, warning, danger and todo. The todo type is custom to this handbook, for marking unfinished work.

Key/value blocks¶

For blocks like the URL / Login / Account Info blocks at the top of app and provider pages, use a definition list. Leave a blank line between entries:

example.md

URL
:   [git.f13.io](https://git.f13.io)

Login
:   - Billing: [example.com](https://example.com)
    - Control Panel: [panel.example.com](https://panel.example.com)

Keyboard keys¶

Write keyboard keys like ++ctrl+x++, which renders as Ctrl+X.

Badges¶

Write badges as a bit of inline HTML. The available colors are badge--primary, badge--success and badge--danger:

example.md

<span class="badge badge--success">recommended</span>

recommended

Links between pages¶

Link to other pages with a path relative to the current page, pointing at the .md file, like [Fail2Ban](fail2ban.md) or [Docker](../docker/index.md). Paths starting with / don’t work, and the build warns you about links to pages that don’t exist.

Icons¶

Zensical has several icon sets built in. See the Icons page for syntax and to browse available icons.