113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# 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
|