Markdown & Zola Feature Reference

This post is a kitchen sink: it exercises every Markdown element and Zola feature the site is configured for, so you can see exactly how each one renders. Everything above the fold here becomes the post summary in the feed and lists.

🔗Text formatting

Regular text with bold, italic, bold italic, strikethrough, and inline code. You can also use highlighted text, Cmd + K, H₂O and E = mc² via raw HTML.

Smart punctuation is on, so “straight quotes” become curly, an en dash (10–20), an em dash (yes—really), and an ellipsis… are all typeset automatically.

🔗Headings and IDs

Every heading below gets an automatic slug ID and a hover anchor link. This is an <h2>; here are the deeper levels:

🔗Third-level heading

🔗Fourth-level heading

🔗Fifth-level heading

🔗Sixth-level heading

🔗Links

• An inline link to the Zola site.
• An inline link with a title.
• A reference-style link resolved at the bottom of the source.
• An autolink: https://www.rust-lang.org.
• An internal link to another post, resolved at build time (Zola checks it exists): the Hello, World post, or jump straight to a heading in that post.
• A footnote reference sits here.¹

🔗Lists

Unordered, with nesting:

• Distributed systems
  • Consensus
    • Raft
    • Paxos
  • Replication
• Reliability

Ordered:

1. Write the post
2. Run zola serve
3. Ship it
   1. Set base_url
   2. zola build

Task list (GitHub-style):

• Enable class-based highlighting
• Add an RSS feed
• Write more posts

🔗Definition list

Idempotency

The property that applying an operation multiple times has the same effect as applying it once.

Backoff

A strategy of increasing the delay between retries.

Often paired with jitter to avoid synchronised retries.

🔗Blockquotes

A single-level blockquote.

And a nested one inside it, for good measure.

🔗GitHub-style alerts

Useful information the reader should notice even when skimming.

An optional, helpful suggestion.

Key information the reader needs to succeed.

Something that needs immediate attention to avoid problems.

Advises about risks or negative outcomes of an action.

🔗Tables

Column alignment is controlled by the separator row:

🔗Images

Images can be co-located with the post in a page bundle and referenced by relative path:

🔗Horizontal rule

🔗Code blocks

Plain, no language — just monospaced and framed:

$ zola build
Done in 88ms.

Highlighted by language:

def with_retries(fn, *, attempts=5):
    for attempt in range(1, attempts + 1):
        try:
            return fn()
        except TransientError:
            if attempt == attempts:
                raise

With line numbers, a starting offset, and highlighted lines (```rust,linenos,linenostart=10,hl_lines=2-3):

10fn main() {
11    let data = load();          // highlighted
12    let result = process(data); // highlighted
13    println!("{result:?}");
14}

With a filename caption (```toml,name=config.toml):

[markdown.highlighting]
style = "class"
light_theme = "github-light"
dark_theme = "github-dark"

Diff highlighting:

 fn retry(f: impl Fn()) {
-    f();
+    for _ in 0..3 {
+        f();
+    }
 }

A very long line, to show horizontal overflow rather than wrapping the page:

This is a deliberately long single line of text with no natural break points sothatyoucanseehowthecodeblockscrollshorizontallyinsteadofforcingthewholepagetogetwiderthanitshould.

🔗Zola shortcodes

The custom code_file shortcode includes a source file (or a line range) straight from disk, so code in a post never drifts from the real file:

use std::fmt;

/// A tiny greeter, used to demonstrate `code_file` includes.
struct Greeter {
    name: String,
}

impl fmt::Display for Greeter {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Hello, {}!", self.name)
    }
}

fn main() {
    let g = Greeter { name: "world".into() };
    println!("{g}");
}

🔗Raw HTML

Raw HTML passes through, which is handy for things Markdown can’t express — for example a collapsible section:

🔗Things this site deliberately leaves off

Emoji shortcodes like :tada: are not auto-converted (that option is off, to keep colons in technical text safe) — but literal Unicode emoji still work: 🎉 ✅ 🚀. Math (KaTeX/MathJax) and Mermaid diagrams aren’t built in; both can be added later with a shortcode plus a small script if you ever want them.