Reference post that exercises every render path the theme ships with. Each example shows the exact markdown source first, then the rendered output. Delete this post once your own content takes over.

Code blocks

Inline code#

A short identifier like printer.cfg, a long path like /usr/share/klipper/config/F008/printer.cfg, and a verbose attribute like box_action.motor_send_data all wrap correctly on narrow viewports.

Plain block, no language#

Just plain pre-formatted text.
No syntax highlighting.
No file caption.

With language#

#!/usr/bin/env bash
set -euo pipefail
for h in "${HOSTS[@]}"; do
  ssh "$h" "uptime; df -h /" | awk '{print $1, $2}'
done

With filename caption#

The file= attribute on the fence renders a captioned code block with the language pill on the left and the filename on the right.

You write:

```bash {file="scripts/deploy.sh"}
#!/usr/bin/env bash
set -euo pipefail
rsync -av --delete public/ deploy@host:/var/www/site/
ssh deploy@host 'sudo systemctl reload nginx'
```

You get:

bash scripts/deploy.sh

#!/usr/bin/env bash
set -euo pipefail
rsync -av --delete public/ deploy@host:/var/www/site/
ssh deploy@host 'sudo systemctl reload nginx'

With line highlighting#

Use hl="2 4" (space-separated line numbers) or hl="1-3 5" (with ranges). The attribute name is hl, not hl_lines, because Hugo's Goldmark IAL parser drops attribute keys containing underscores.

You write:

```bash {file="scripts/deploy.sh" hl="2 4"}
#!/usr/bin/env bash
set -euo pipefail
rsync -av public/ deploy@host:/var/www/site/
rsync -av --delete public/ deploy@host:/var/www/site/
ssh deploy@host 'sudo systemctl reload nginx'
```

You get:

bash scripts/deploy.sh

#!/usr/bin/env bash
set -euo pipefail
rsync -av public/ deploy@host:/var/www/site/
rsync -av --delete public/ deploy@host:/var/www/site/
ssh deploy@host 'sudo systemctl reload nginx'

Another language, with filename#

python probe.py

import asyncio
from typing import Any

async def probe(host: str, port: int = 443, timeout: float = 5.0) -> dict[str, Any]:
    try:
        reader, writer = await asyncio.wait_for(
            asyncio.open_connection(host, port), timeout=timeout
        )
        writer.close()
        await writer.wait_closed()
        return {"host": host, "ok": True}
    except (TimeoutError, OSError) as e:
        return {"host": host, "ok": False, "err": str(e)}

Config files#

ini /etc/wireguard/wg0.conf

[Interface]
Address = 10.200.200.1/24
ListenPort = 41820
PrivateKey = REDACTED

[Peer]
PublicKey = C0229a2mWRNTds9kZb6WK8f20FeJdQjc/wETzGTSAyc=
AllowedIPs = 10.200.200.0/24
Endpoint = relay.example.com:40000
PersistentKeepalive = 25

json config.json

{
  "name": "archworks-relay",
  "wireguard": {
    "interface": "wg0",
    "port": 41820,
    "peers": [
      { "name": "opnsense", "ip": "10.200.200.250" }
    ]
  }
}

Diff (added/removed lines)#

diff services.yaml.patch

 services:
   - name: Element
     host: element.archworks.co
-  - name: Jellyseerr
+  - name: Seer
     host: req.archworks.co
-  - name: PeerTube
-    host: tube.archworks.co
   - name: Git
     host: git.archworks.co

Footnotes#

Hugo's Goldmark supports markdown footnotes natively¹. The theme styles the references as superscript pills² and shows the note in a tooltip when you hover.

Media

Image, plain markdown#

Click the rendered image to open it in the lightbox overlay. Press Esc or click the backdrop to close. Images wrapped inside a link ([![alt](img)](url)) navigate to the link instead of opening the lightbox.

You write:

![ArchWorks logo](/img/logo.png)

You get:

Image, responsive shortcode (page resource)#

The img shortcode works when the image is a page resource (i.e. lives next to the markdown file inside a leaf bundle, like this post). It produces multiple sizes via Hugo's image processing and serves the right one for the viewport via srcset.

You write:

{{< img src="screenshot.png" alt="Sample page resource" caption="Optional caption shown below." >}}

You get:

Sample page resource — Page-resource image, served as WebP with `srcset` for the viewport.

Video (HTML5, self-hosted)#

You write:

{{< video src="/clips/sample.mp4" caption="Two-second test clip." >}}

You get:

Two-second test clip.

Video with autoplay + loop + muted#

Most browsers only allow autoplay when the video is muted. Setting all three together is the safe combination.

{{< video src="/clips/sample.mp4" autoplay="true" loop="true" muted="true" caption="Autoplay + loop + muted." >}}

Autoplay + loop + muted.

PDF (inline viewport)#

The PDF embed shows in an iframe sized to the height you set. Hover the frame to reveal an expand button in the top-right; click it to open the PDF in a full-viewport overlay. The overlay closes on Esc or click of the backdrop. Mobile browsers that refuse to render PDFs inline show the fallback "Open in new tab / download" link.

You write:

{{< pdf src="/pdfs/sample.pdf" height="540" caption="Generated one-page test PDF." >}}

You get:

Your browser cannot display this PDF inline. Open in new tab or download.

Generated one-page test PDF. Hover and tap the expand icon to open fullscreen.

PDF, smaller height#

{{< pdf src="/pdfs/sample.pdf" height="320" >}}

Your browser cannot display this PDF inline. Open in new tab or download.

Audio#

{{< audio src="/audio/track.mp3" type="audio/mpeg" caption="Optional caption." >}}

(No sample audio shipped with the theme, so not rendered here.)

YouTube (privacy-friendly nocookie embed)#

{{< youtube id="dQw4w9WgXcQ" caption="Optional caption." >}}

(Not rendered to avoid an external network call. Use it freely in your own posts.)

Generic sandboxed iframe#

{{< iframe src="https://example.com/embed" ratio="16/9" caption="Generic iframe." >}}

(Not rendered for the same reason.)

Visualisations

Mermaid: flowchart#

Any code fence labelled mermaid is rendered client-side by the Mermaid library, which the theme only loads on pages that actually contain a Mermaid block.

You write:

```mermaid
flowchart LR
  A[Client] -->|HTTPS| B(Relay)
  B -->|WireGuard| C[OPNsense]
  C --> D[proxy01]
  D --> E[(Service VM)]
```

You get:

flowchart LR
  A[Client] -->|HTTPS| B(Relay)
  B -->|WireGuard| C[OPNsense]
  C --> D[proxy01]
  D --> E[(Service VM)]

Mermaid: sequence#

sequenceDiagram
  participant C as Client
  participant R as Relay
  participant H as Home
  C->>R: TLS ClientHello (SNI=archworks.co)
  R->>H: WG-tunneled stream
  H-->>R: TLS response
  R-->>C: TLS response

Mermaid: state#

stateDiagram-v2
  [*] --> Checking
  Checking --> Online : 2xx-3xx response
  Checking --> Offline : timeout or refused
  Online --> Checking : refresh
  Offline --> Checking : refresh

KaTeX: inline math#

Wrap inline math in $ and $. Set math = true in the post's frontmatter (see the top of this post) to load the KaTeX assets only where they are needed.

You write:

The Reynolds number is \(Re = \frac{\rho v L}{\mu}\) for a fluid with density \(\rho\) and viscosity \(\mu\).

You get:

The Reynolds number is $Re = \frac{\rho v L}{\mu}$ for a fluid with density $\rho$ and viscosity $\mu$.

KaTeX: display math#

Wrap display math in $$ ... $$ on their own lines.

$$
\nabla \times \mathbf{E} = -\frac{\partial \mathbf{B}}{\partial t}
$$

$$ \nabla \times \mathbf{E} = -\frac{\partial \mathbf{B}}{\partial t} $$$$ \sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6} $$

Inline SVG (uses `currentColor`)#

You can paste raw SVG directly into markdown. Use stroke="currentColor" or fill="currentColor" so the SVG inherits the theme's foreground colour and looks right in both dark and light themes.

You write:

<svg viewBox="0 0 200 80" width="200" height="80" xmlns="http://www.w3.org/2000/svg"
     fill="none" stroke="currentColor" stroke-width="2">
  <rect x="6" y="6" width="60" height="68" rx="6"/>
  <path d="M70 40 L130 40"/>
  <polygon points="130,32 144,40 130,48" fill="currentColor"/>
  <circle cx="168" cy="40" r="20"/>
</svg>

You get:

The same SVG renders correctly in both themes because it does not hard-code its own colours.

A simple footnote with a single sentence. ↩︎
A longer footnote that spans a few sentences to demonstrate that the tooltip handles multi-sentence content without overflowing the viewport. It will wrap at the tooltip's max-width and stay readable. ↩︎

Code blocks

Inline code#

Plain block, no language#

With language#

With filename caption#

With line highlighting#

Another language, with filename#

Config files#

Diff (added/removed lines)#

Footnotes#

Media

Image, plain markdown#

Image, responsive shortcode (page resource)#

Video (HTML5, self-hosted)#

Video with autoplay + loop + muted#

PDF (inline viewport)#

PDF, smaller height#

Audio#

YouTube (privacy-friendly nocookie embed)#

Generic sandboxed iframe#

Visualisations

Mermaid: flowchart#

Mermaid: sequence#

Mermaid: state#

KaTeX: inline math#

KaTeX: display math#

Inline SVG (uses currentColor)#

Related

Inline SVG (uses `currentColor`)#