Theme Features & Markdown Showcase — Complete Reference

This post is the complete, one-file documentation for this theme. Every section below both renders a feature live and shows you the exact syntax to write it yourself.

Shortcodes are disabled. This theme no longer ships a shortcodes feature — content is written in plain standard Markdown only (the CommonMark spec, with the GFM extensions Hugo ships: tables, task lists, strikethrough). Any Hugo curly-brace shortcode syntax in a content file now fails the build loudly, so there is nothing to learn besides Markdown itself.

The canonical reference lives in docs/ (CONTENT.md, CONFIGURATION.md, THEMING.md, DEVELOPMENT.md); this page is the condensed, clickable version — keep it open while authoring new posts.

Front matter — the content model

Every post is a Markdown file under content/blog/ with YAML front matter. Hugo reads this and the theme turns it into the card, the page, the search index entry, the Open Graph image, and the RSS feed item.

Fields

A complete example

---
title: "Your Post Title"
description: "One sentence for cards, search, and social previews."
date: 2026-08-10T09:00:00+00:00
draft: true
slug: "your-post"
image: "/images/posts/cover.jpg"
tags: ["hugo", "css"]
categories: ["Documentation"]
featured: true
toc: true
---

Your post body in Markdown…

Standard Markdown (CommonMark)

Everything a post is made of. The syntax examples below are ready to paste into any post.

Headings & the table of contents

An ## heading — a major section

An ### heading — a subsection

An #### heading — leaf-level detail

Headings from level 2 to 4 appear in the auto-generated table of contents in the sidebar, so structure your posts with these to give readers quick navigation (collapsible on mobile). Use exactly one # heading as the post’s title — it’s redundant, since the theme renders the front matter title as the page heading.

Emphasis & strong

Bold, italic, and bold with nested emphasis.

**Bold**, *italic*, and **bold with *nested* emphasis**.

Links

Inline links, link with a title, and reference-style links are all standard CommonMark. Absolute http(s) URLs render with a dotted underline that turns solid on hover:

An inline link

Link with a title

Reference-style link — the reference is defined at the bottom of the post and can be reused anywhere in it.

[An inline link](https://gohugo.io/)

[Link with a title](https://gohugo.io/ "Hugo's home page")

[Reference-style link][hugo-docs]

[hugo-docs]: https://gohugo.io/documentation/ "Hugo documentation"

Lists

Unordered, ordered, and nested lists behave exactly as the CommonMark spec defines — tight lists are rendered without paragraph gaps, loose lists with them.

• Unordered item
• Second item
  • Nested item
  • Another nested item
    • Deeper still

1. Ordered item
2. Second item
3. Third item

- Unordered item
- Second item
  - Nested item
    - Deeper still

1. Ordered item
2. Second item
3. Third item

Blockquotes

Blockquotes can contain multiple paragraphs, other blockquotes, lists, and code. Plain quotes render as a terminal-style panel: a hairline frame with a solid accent rail on the left and a macOS-style dot row in the corner (echoing the code-block frames). Nested quotes recede one step — no dots, fainter border and text.

A paragraph of quoted text.

• A quoted list item
• Another quoted list item

A nested quotation.

> A paragraph of quoted text.
>
> - A quoted list item
> - Another quoted list item
>
> > A nested quotation.

Code

Inline code spans and fenced code blocks (see the next section for the frame styles). A code span uses backticks; fence an indented block or an entire file with triple backticks:

Inline: hugo new blog/my-post.md — use code spans for short commands and identifiers.

Inline: `hugo new blog/my-post.md`

Horizontal rules & raw HTML

A line of three or more -, *, or _ becomes a thematic break:

Raw HTML is allowed (Goldmark runs with unsafe: true), so you can drop in a <details> or a styled inline element when you truly need it — but prefer plain Markdown so content stays portable.

---

<details>
<summary>Raw HTML still works when needed</summary>
Goldmark's `unsafe: true` lets hand-written HTML through.
</details>

Hugo’s GFM extensions

These aren’t in the CommonMark core, but Hugo’s Markdown engine ships them out of the box — no configuration needed.

Tables

Markdown tables get Pico-style styling — thin row separators, a heavier rule under the header, no outer border. Wide tables scroll horizontally instead of breaking the layout.

| Feature   | Built-in | Notes                        |
| --------- | -------- | ---------------------------- |
| Dark mode | Yes      | Toggle in the header         |
| Search    | Yes      | Client-side, on `/blog/`     |
| RSS feeds | Yes      | Per section and per tag      |
| Comments  | Opt-in   | Per-site via `params.yaml`   |

For hand-written HTML tables, add .striped (Pico) or table table--striped (theme BEM) for zebra rows, and wrap wide ones in .table__scroll.

Task lists

• Write this post in plain Markdown
• Show every feature live
• Replace this demo post with real content

- [x] Write this post in plain Markdown
- [x] Show every feature live
- [ ] Replace this demo post with real content

Strikethrough

A line of two tildes marks text as deleted, rendered with a line-through.

A line of ~~two tildes~~ marks text as deleted.

Fenced code block frames

Every fenced code block renders in an Expressive Code-style frame (opencode.ai) with a copy button injected by assets/js/modules/copy.js. The frame mode is chosen automatically from the language and attributes.

File frame

Add a title attribute to show a filename tab:

package main

import "fmt"

func main() {
	fmt.Println("Hello from a file frame")
}

```go {title="main.go"}
package main

func main() {
	fmt.Println("Hello from a file frame")
}
```

Terminal frame

Shell languages (bash, sh, zsh, fish, powershell, pwsh, cmd, bat, console) get a macOS traffic-light header:

hugo new blog/my-first-post.md
hugo server -D

```bash
hugo new blog/my-first-post.md
hugo server -D
```

Plain frame

No title and no language — a frameless block:

no header, no syntax highlighting, just the copy button

```
no header, no syntax highlighting, just the copy button
```

Line numbers

Line numbers are off by default; opt in per block with {.d-lineno}:

1
2
3
4

body {
  display: grid;
  gap: 1rem;
}

```css {.d-lineno}
body {
  display: grid;
  gap: 1rem;
}
```

Line highlighting

Emphasize specific lines with hl-lines. The value is space-delimited and accepts ranges (2-4 7), works with or without {.d-lineno}, and in table mode also highlights the matching gutter number:

package main

func main() {
	println("hi")
}

```go {hl-lines="4"}
package main

func main() {
	println("hi")
}
```

Diff blocks

Fence with the diff language for a git-style review: + lines render on a green background, - lines on red, and @@ headers bold — the highlight spans the full line width. Composes with {.d-lineno}:

@@ -1,3 +1,4 @@
 # Changelog
-removed line
+added line
 context line

```diff
@@ -1,3 +1,4 @@
 # Changelog
-removed line
+added line
 context line
```

Content utilities

Shortcodes are disabled, but the theme ships a few helpers for prose that plain Markdown can’t express: callouts via blockquote alerts (pure CommonMark, portable to GitHub and Obsidian), plus a few plain-HTML classes where Markdown has no equivalent — Goldmark runs with unsafe: true so they drop straight into a post.

Callout boxes

The GitHub/Obsidian alert syntax becomes a styled callout — the first line is the type marker, everything after is the body. All five GFM types are supported ([!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]); the label comes from i18n:

> [!NOTE]
> Useful information that users should know.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

An optional custom title overrides the label (Obsidian syntax):

> [!WARNING] Radiation hazard
> Do not approach without protective gear.

Lead & small

A <p class="lead"> opens a section with slightly larger type; a <p class="small"> drops to caption size:

A lead paragraph — a slightly larger opener for section intros.

A small caption for images, disclaimers, or asides.

<p class="lead">A slightly larger opener for section intros.</p>
<p class="small">A small caption for images or disclaimers.</p>

Keyboard keys & highlights

<kbd> renders a terminal-style keycap; <mark> uses the code-highlight accent:

Press Ctrl + Shift + P to open the command palette, then look for the mark highlight.

Press <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> … then <mark>mark</mark>.

Figures with captions

A Markdown image with a title becomes a <figure> with a centered caption:

![The site logo](/images/logo.svg "The site's SVG logo")

Footnotes

Goldmark’s footnote syntax is styled: the list sits under a hairline rule after the post, and the targeted footnote highlights when you jump to it¹.

Goldmark's footnote syntax[^showcase].

[^showcase]: Footnote bodies render under a hairline rule after the post.

Content-driven features

These aren’t shortcodes or extensions — they’re behaviors the theme ships automatically when you structure content correctly.

Home hero (featured posts)

Set featured: true on the newest post you want showcased. The home page promotes the most recent featured post into the hero; if none are flagged it falls back to the newest post.

Table of contents (sidebar)

Opt-in via toc: true in front matter (this post has it set). When active, the post’s ##–#### headings render as a TOC in a sticky sidebar on the right of the article on desktop, with a scrollspy highlighting the heading being read (opencode.ai style). On mobile it becomes a collapsible <details> list, closed by default — tap the summary to expand the full nested list. Without toc: true no TOC is rendered and the article spans the full column. It’s the navigation you’re using right now.

Related posts

Posts sharing tags get a related-posts section after the body. This post shares the css and design-systems tags, so related cards appear below.

Share buttons & author card

Every blog post renders share buttons and an author card after the body — the author comes from params.yaml (posts no longer need their own author field).

Search on /blog/

The search widget lives inline on /blog/ (there is deliberately no search modal). It filters client-side over /search-index.json, which Hugo generates from every post via the custom output format in layouts/index.searchindex.json.

Theme toggle

The header theme toggle flips between light and dark, persisting the choice and respecting the OS default. Components only ever use var(--color-*) semantic aliases, mapped to --c-* primitives per theme.

Tags & categories

List them in front matter and Hugo auto-generates /tags/<tag>/ and /categories/<category>/ pages plus index pages — no extra templates.

Pagination

The blog list paginates 6 posts per page with numbered pagination. Add more posts than that and it appears automatically.

Archive page

/archive/ auto-lists every post grouped by year, newest first — generated entirely from content/blog/*.md, nothing to maintain.

404 page

There’s no content/404.md — /404.html comes from layouts/404.html (Hugo’s “Kind” convention). Its copy lives in the page_not_found_* i18n strings (i18n/en.yaml, i18n/id.yaml).

RSS, sitemap, webmanifest

All generated on every build: /index.xml + per-section/per-tag feeds, sitemap.xml, robots.txt, and /site.webmanifest (rendered from params.yaml via layouts/index.webmanifest.webmanifest).

Comments

Enabled per-site (not per-post) via params.yaml → comments.provider (none, disqus, or giscus). Set up steps are in docs/THEMING.md.

Writing workflow

Drafting

hugo new blog/my-new-post.md
hugo server -D

hugo server -D shows drafts so you can preview them live; hugo --gc --minify builds production output to public/ (drafts excluded). For this site the build is a single hugo command — no npm, no node_modules, no package.json.

Publishing

Flip draft: false (or delete the line) when ready. Update the docs in docs/ whenever behavior changes — README links to them.