Markdown Reference

Statik ships with GitHub Flavored Markdown plus a few conveniences to make your docs and posts richer. Use this page as a quick refresher when authoring content.

Frontmatter (metadata)

Every Markdown file can start with YAML frontmatter. Statik reads it into the metadata object for templates, RSS, and datasources.

---
title: "My Post"
published: "2024-10-07T10:00:00"
description: "Optional meta description"
draft: false
nav_order: 2       # Controls sidebar ordering for pages
layout: "main"     # Overrides template layout if needed
category: Guides   # Custom fields are allowed
---

• title is recommended for both pages and posts.
• published controls post dates; falls back to file mtime when omitted.
• draft: true hides the post in production builds.
• Add any custom keys; access them in templates with {{post.metadata.category}} or {{page.metadata.category}}.

Headings and anchors

Heading anchors are added automatically. Any # Heading becomes linkable via #heading.

Tables

| Feature      | Support |
|--------------|---------|
| Tables       | ✅      |
| Anchor links | ✅      |

Footnotes

Write footnotes with reference-style markers. Statik renders them as a list or inline hover tooltips.

Content that needs a citation.[^why]

[^why]: Footnote text shown at the bottom, or inline when hover tooltips are enabled.

Here's how it renders: Content that needs a citation.¹

Important: The footnote definition ([^id]: text) must be separated from other content by a blank line, and must start at the beginning of a line (no indentation).

To switch to hover tooltips instead of a list, set in config.json:

"html": {
  "footnotes": { "display": "HOVER" }
}

Strikethrough

Use double tildes: ~~deprecated~~.

Automatic links

Bare URLs and emails are linked automatically, e.g. https://example.com or hello@example.com.

Images with captions

Add a title to an image to turn it into a <figure> with <figcaption>:

![Server diagram](./images/server.png "High-level architecture")

Blockquotes with attribution

Finish the last line with -- or an em dash to capture the author and emit semantic HTML:

> Good documentation survives redesigns.
> -- Statik Team

Code fences and syntax highlighting

Triple backticks with a language flag enable highlighted blocks:

fun main() {
    println("Hello, Statik!")
}

Inline elaborations

For inline explanations that don't warrant a footnote, use the HTML <abbr> element. Statik styles these with a dotted underline and shows a click-to-toggle popup:

The server uses <abbr title="A protocol for real-time bidirectional communication over a single TCP connection">WebSocket</abbr> for live updates.

Here's how it renders: The server uses WebSocket for live updates.

Click the term to see the explanation popup. Click again or anywhere else to dismiss.

Inline HTML

Inline HTML is left intact, so you can sprinkle custom markup or data attributes wherever Markdown falls short.