How to Use This Site

Andi Lamprecht ·2026-05-11· 6 min read· Stable

Hugo static site using the Hextra theme. Content is markdown under content/docs/. Trunk-based; all changes land via PR.

Prerequisites

You need Hugo (extended) installed locally to preview and build the site. The Hextra theme is vendored in _vendor/, so there’s nothing else to install.

brew install hugo
# or: make install-hugo

Verify the install:

hugo version

The output must include extended (e.g. hugo v0.156.0+extended …). The standard edition will fail to build — Hextra depends on the extended SCSS pipeline.

CI pins Hugo to 0.156.0 in .github/workflows/dev.yml and branch.yml. Keep your local version close to that to avoid drift.

Build Commands

Always run make build before pushing. Hugo logs icon and shortcode errors that are otherwise invisible during make serve.

File Structure

Pages live under content/docs/ and are organized by product:

Page Types

• Section page (_index.md) — landing page for a folder, lists children
• Leaf bundle (my-page/index.md) — page with co-located images/assets
• Simple page (my-page.md) — standalone page, no assets

Frontmatter

Every page begins with YAML frontmatter. Only title is required:

---
title: "Human-readable title"
weight: 10            # sort order; lower = higher; use multiples of 10
status: Draft         # colored pill in the page header; defaults to Draft if omitted
sidebar:
  open: false         # section indexes: start expanded (true) or collapsed (false, default)
comments: true        # enable/disable giscus comments (default: true)
date: 2026-04-20      # optional; otherwise git Lastmod is used
description: "…"      # optional; used in page metadata/SEO
---

Status Values (auto-colored)

Unknown values fall back to gray.

Creating New PRDs and ADRs

Use Hugo archetypes — they scaffold consistent frontmatter + sections:

hugo new --kind adr content/docs/atomx/ADR/0008-my-decision.md
hugo new --kind prd content/docs/Uncrew/PRD/0004-my-feature.md

The numeric prefix is the next free number in the target folder. After creation, tune title, weight, and fill in sections.

Page Header Metadata

Every doc page automatically renders a page-info block under the title:

[avatar] Author Name · 2026-04-20 · 3 min read · Draft

• Author + avatar — git’s last commit author. Links to the GitHub profile when the commit email is a GitHub noreply address.
• Date — .Lastmod, from git.
• Reading time — Hugo’s .ReadingTime.
• Status pill — from status: frontmatter (defaults to Draft).

A stale-doc warning banner renders on trunk (production) builds when a page’s Lastmod is older than 180 days. It never shows locally or on branch preview deploys.

Where to Put New Documents

Key Rules

• Body starts at ## (H2); title renders as H1
• Leaf bundles: co-locate images, reference with relative paths: ![Alt](image.png)
• weight in multiples of 10 so new pages can be inserted without renumbering
• Sidebar defaults to collapsed; set sidebar.open: true only for sections that should start expanded
• Internal links: [text]({{< relref "path/to/page" >}}) — Hugo validates these at build time
• Don’t edit files under _vendor/ directly

Markdown Basics

Standard markdown works as expected: bold, italic, inline code, links, and lists.

Tables

| Column A | Column B |
| :--- | :--- |
| value 1 | value 2 |

Task Lists

• Completed item
• Pending item

Shortcodes

Callouts

{{< callout type="info" >}}Message{{< /callout >}}

Types: info, warning, error, important, default.

Tabs

fmt.Println("Hello from Go")

print("Hello from Python")

{{< tabs >}}
  {{< tab name="Tab Name" >}}Content{{< /tab >}}
{{< /tabs >}}

Steps

gh repo clone droneup/droneup-product-docs

git checkout -b feat/your-change

{{% steps %}}

### Step title
Content.

{{% /steps %}}

Details (Collapsible)

{{< details title="Click to expand" >}}Hidden content.{{< /details >}}

Cards

{{< cards cols="2" >}}
  {{< card link="/docs/path" title="Title" subtitle="Description" icon="icon-name" >}}
{{< /cards >}}

Status Badges (Inline)

The page header renders the document’s overall status automatically. For inline status pills inside content, use the status shortcode — a <span>, so it works in headings, table cells, and body text.

Draft Accepted Deprecated Custom

{{< status "Draft" >}}
{{< status "Custom Label" "blue" >}}

Second param overrides the color. See Status Values above for the auto-color table.

Recent Changes

Sortable table of recently-modified pages:

{{< recent-changes limit="10" >}}

Columns: Page, Section, Status, Updated. Used on the landing page.

Doc Dashboard

Table of every PRD and ADR across the site:

{{< doc-dashboard >}}
{{< doc-dashboard kinds="ADR" >}}

Filter via kinds (comma-separated). Defaults to ADR,PRD.

File Trees

{{< filetree/container >}}
  {{< filetree/folder name="src" >}}
    {{< filetree/file name="main.go" >}}
  {{< /filetree/folder >}}
{{< /filetree/container >}}

Diagrams with Mermaid

    graph LR
    A[Flight Request] --> B{Authorization}
    B -->|Approved| C[Known / Verified]
    B -->|Denied| D[Rejected]
  

```mermaid
graph LR
    A[Start] --> B[End]
```

Supports flowcharts, sequence, class, state, and Gantt diagrams. Full syntax: https://mermaid.js.org/intro/

GitHub-Style Alerts

> [!NOTE]
> Your note here.

Code Blocks

package main

import "fmt"

func main() {
    fmt.Println("Hello, DroneUp!")
}

```go filename="main.go"
// your code
```

Copy button appears on hover.

Images

Two approaches:

1. Site-wide: drop into static/media/<section>/<page>/image.png, reference with absolute path: ![Alt](/media/section/page/image.png)
2. Leaf bundle: co-locate next to index.md, reference with relative path: ![Alt](image.png)

Click-to-zoom is enabled site-wide.

Icons

Icons are defined in _vendor/github.com/imfing/hextra/data/icons.yaml. Always verify an icon name exists before using it — Hugo logs a build error for missing icons.

Common valid names: check-circle, exclamation, exclamation-circle, eye, clock, shield-check, map, document-text, light-bulb, chip, paper-airplane, wifi, device-mobile, desktop-computer, x-circle.

Comments

Every page has a comment thread at the bottom, powered by giscus (GitHub Discussions backend).

• GitHub account required to comment
• Comments mapped by page URL — each page has its own thread
• Theme follows site light/dark mode
• Disable per page with comments: false in frontmatter

Context Menu

A Copy Page button in the top-right of every page lets you:

• Copy the page as Markdown
• View the raw Markdown source

Tips for Contributors