This post is a living reference for everything you can drop into a normal article: front matter, math, the fig shortcode, plain images, highlighted code with line numbers, links, lists, and quotes. Copy the fenced blocks into your own .md files.

1. Front matter (YAML)

Every post starts with metadata between --- lines:

1
2
3
4
5
6
7
8

---
title: "Your title"
date: 2026-03-26
author: "Your Name"
tags: ["TagOne", "TagTwo"]
params:
  math: true   # load KaTeX on this page only (site default can be false)
---

• tags: show under the post and on /tags/… pages.
• params.math: true: required for LaTeX below unless you set math = true globally in config.toml.

2. Math (KaTeX)

Inline (same line as text), use \( … \):

1

The loss is \( \mathcal{L} = -\sum_i y_i \log \hat{y}_i \).

Live: The loss is \( \mathcal{L} = -\sum_i y_i \log \hat{y}_i \).

Display block with \[ … \] or $$ … $$:

1
2
3

\[
\mathrm{softmax}(z_i) = \frac{e^{z_i}}{\sum_j e^{z_j}}
\]

Live:

3. Captions: fig shortcode

Hugo runs shortcodes before Markdown, so putting fig shortcode markup inside ordinary fenced code blocks still executes the shortcode. The copy-paste examples below use raw HTML with < so the line shows up literally (what you copy is normal angle brackets).

Named arguments (easiest to read):

{{< fig src="/images/rag-pipeline.svg" alt="Short description for accessibility" caption="Caption text; **markdown** works here." >}}

Live:

Positional (src, alt, caption in order):

{{< fig "/images/rag-pipeline.svg" "Alt text" "Optional caption." >}}

Clickable image (opens URL in a new context—use full URLs for external assets):

{{< fig src="/images/rag-pipeline.svg" alt="Diagram" caption="Thumbnail linking out" href="https://gohugo.io" >}}

4. Plain markdown image

File lives under static/; URL starts at site root:

1

![Alt text only](/images/rag-pipeline.svg)

Live:

5. Code fences (syntax + line numbers)

Use a language right after the opening backticks. Hugo/Chroma adds colors and a gutter.

1
2
3
4
5
6

def softmax(z):
    import math
    m = max(z)
    exps = [math.exp(x - m) for x in z]
    s = sum(exps)
    return [e / s for e in exps]

Highlight specific lines (optional fence options — array syntax as in Hugo docs):

1
2
3
4
5
6
7

def line_one():
    def line_two_highlighted():
        return 2
    def line_three():
        return 3
    def line_four_highlighted():
        return 4

Shell:

1

hugo server -D --bind 127.0.0.1 --port 1313

Inline code: wrap with single backticks: params.math, relURL, config.toml.

6. Writing & structure

Links: Hugo docs

Emphasis: italic, bold, both.

List:

• bullets
• second item

Numbered:

1. first
2. second

Blockquote:

Use for callouts or citations.

Rule:

7. Quick checklist

Tip: open content/posts/blog-authoring-showcase.md in your editor to compare raw markdown with this rendered page.