Writing Content

Everything on this site is a Markdown file under content/. The directory structure is the navigation — there is no separate nav config to keep in sync.

Layout

content/
├── _index.md              → the home page
├── blog/
│   ├── _index.md          → the /blog listing page
│   └── hello-world.md     → /blog/hello-world/
└── docs/
    ├── _index.md          → /docs/
    └── writing-content.md → /docs/writing-content/  (this page)

An _index.md makes a directory into a section with its own landing page. A plain .md file is a single page.

Front matter

The YAML block at the top of each file:

---
title: Writing Content   # shown in nav, sidebar, and <title>
weight: 1                # sidebar order, lower first
date: 2026-08-16         # used for article sorting
draft: true              # excluded from builds unless you pass -D
prev: /docs              # optional explicit pager links
next: /docs/building-and-deploying
---

Only title is really required. Without weight, sidebar entries fall back to alphabetical order, which is rarely what you want for docs.

Adding a new section

Make a directory with an _index.md, then add it to the navbar in hugo.yaml under menu.main:

menu:
  main:
    - name: Guides
      pageRef: /guides
      weight: 4

The sidebar inside the section builds itself; only the top navbar is explicit.

Images and files

Anything in static/ is copied to the site root verbatim. static/images/logo.png is served at /images/logo.png.

For images that belong to one specific page, you can instead make that page a bundle — a directory with index.md plus the images beside it — and reference them relatively:

content/blog/my-post/
├── index.md
└── diagram.png        → ![](diagram.png)

Search

Search is built at compile time by Hextra’s FlexSearch integration and shipped as static JSON. No server, no third-party service, no API key. To keep a page out of the index:

excludeSearch: true