Hugo/themes/hextra/docs/superpowers/specs/2026-04-18-examples-design.md

Examples Directory Design

Date: 2026-04-18
Status: Approved

Goal

Add three minimal, self-contained starter examples to examples/ demonstrating Hextra for different use cases: developer documentation, a writer's blog, and a personal portfolio. Each example is independently runnable without touching any parent repository files.

Directory Layout

examples/
├── README.md          # index: what each example shows, link to each
├── docs/
│   ├── go.mod         # requires github.com/imfing/hextra (published module)
│   ├── hugo.yaml      # commented config showcasing relevant features
│   ├── README.md      # what it demonstrates, how to run, what to tweak
│   ├── assets/css/custom.css
│   └── content/
├── blog/              # same shape
└── portfolio/         # same shape

Each example is self-contained: a user copies one folder, runs hugo mod get && hugo server, and gets a working site. No parent files, no path setup required.

For development inside the hextra repo, a replace directive is added manually to the example's go.mod and not committed.

Example 1 — examples/docs/

Theme: Clean developer docs — neutral blue accent, compact sans-serif, tight line-height.

Config features showcased (commented in hugo.yaml):

• params.search.enable + FlexSearch
• params.editURL (GitHub edit links)
• Auto-generated sidebar from content sections
• params.toc (table of contents)
• params.breadcrumb

custom.css tweaks:

• Override --hextra-primary-hue for blue accent
• Slight sidebar font-size reduction for compact feel

Content (~5 files):

• _index.md — landing page with short intro
• getting-started/_index.md — section intro
• getting-started/installation.md — sample content
• guides/_index.md — section intro
• guides/configuration.md — sample content

Example 2 — examples/blog/

Theme: Writer's blog — warm sepia/paper palette, serif headings, wider reading column.

Config features showcased (commented in hugo.yaml):

• taxonomies (tags)
• RSS output (outputs)
• params.page.width for wider reading column
• Author metadata in frontmatter convention
• params.dateFormat

custom.css tweaks:

• Serif font stack for headings
• Warm --hextra-primary-hue for paper/sepia tone

Content (~5 files):

• _index.md — post list homepage
• posts/hello-world.md — first post with tags
• posts/on-writing.md — second post
• posts/using-hextra.md — third post (demonstrates config)
• about.md — about page linked from navbar

Example 3 — examples/portfolio/

Theme: Personal portfolio — bold dark-mode-first palette, strong accent color, hero homepage.

Config features showcased (commented in hugo.yaml):

• menu.main entries (nav links)
• hextra-home layout with hero + cards shortcode
• Social links in params.footer
• params.theme.default set to dark

custom.css tweaks:

• Override accent hue for bold brand color
• Optional hero background tint

Content (~4 files):

• _index.md — layout: hextra-home, hero block + project cards via shortcodes
• projects/_index.md — projects listing
• projects/project-one.md — sample project page
• projects/project-two.md — sample project page

hugo.yaml Convention

Each hugo.yaml is generously commented. Every non-obvious setting gets an inline comment explaining what it does and why the example sets it that way. This makes reading the config a learning experience, not just boilerplate.

README.md Convention

Each example's README.md has three short sections:

1. What this shows — one paragraph on the use-case and featured configs
2. How to run — hugo mod get && hugo server
3. What to change first — 3–5 bullet points pointing to the most relevant config keys or CSS vars

Top-level examples/README.md

Links to all three examples, one-line description each, and a note on how to run any of them.

Out of Scope

• Shared assets or base configs across examples (keep them independent)
• CI testing of examples (can be added later)
• More than three examples in this iteration