AccelerUpDocs
Running AccelerUp/Operations/Contributing to these docs

Contributing to these docs

How this site is built, how to add a page, and the checks that run before it ships.

This site lives in docs-site/ in the AccelerUp monorepo. It is Next.js with content in plain Markdown, exported to static HTML.

Why it is in the same repository

So that a change to behaviour and the change to its documentation are in the same pull request. Documentation rots when updating it is a separate project; the person who just learned that a setting behaves differently than written will fix a .md file next to the code and will not stand up a second repository to do it.

Adding a page

  1. Create content/<section>/<page>.md.
  2. Add frontmatter.
  3. Add it to src/lib/nav.ts.
  4. npm run check.

That is the whole process. The content tree is the URL tree — there is no route to register.

Frontmatter

markdown
---
title: Notification delivery
description: One sentence, shown under the heading and in search results.
keywords: [notifications, retry, dlq]
source: [backend/internal/notification/dispatcher.go]
status: draft
---
KeyRequiredPurpose
titleyesHeading, tab title, sidebar
descriptionrecommendedThe lede, and the search snippet
keywordsoptionalExtra words the search should match
sourcerecommendedFiles that implement this. Rendered as a footer
statusoptionaldraft renders a banner
Important

Fill in source. It is what lets the next person check the page against the code, and it is how a reader knows which of the two to believe.

Markdown

Standard GFM: tables, fenced code with language, task lists, footnotes.

Callouts use GitHub's blockquote syntax, so they still read correctly in a diff:

markdown
<div class="callout callout-note">
<div class="callout-label">Note</div>

Context you will want but could work without.

</div>

<div class="callout callout-warning">
<div class="callout-label">Warning</div>

Something that can cause a real problem.

</div>

Available: NOTE, TIP, IMPORTANT, WARNING, CAUTION.

Internal links must be absolute and end with a slash — /alerting/delivery/. The link checker enforces this.

Commands

bash
npm run dev      # localhost:3100, with the search index rebuilt first
npm run build    # generate API reference → build index → static export to out/
npm run check    # tsc + link checker

npm run build fails if the API reference cannot be generated from backend/internal/handler/router.go. A reference that is confidently stale is worse than one that is missing.

ProblemWhy it matters
A nav entry with no pageA 404 reached from the navigation
A prose link to a page that movedA 404 reached from a trail somebody laid
A page not in the navUsually a forgotten nav entry — reported, not fatal

Writing style

The house style, in five rules:

  1. Say what it does, then why it is that way. The second half is what stops somebody "fixing" it back.
  2. Name the failure. "Set For to 5" is advice. "A rule that is right but early teaches people to ignore it, and that habit does not stay confined to one rule" is a reason.
  3. Prefer a table to a list of paragraphs when the reader is comparing options.
  4. Link rather than repeat. One page owns each fact.
  5. No screenshots. They go stale silently, and a stale screenshot is worse than no screenshot. Describe the path: Monitor → Services → Add service.

Deploying

bash
npm run build     # → docs-site/out/

Static files. nginx serves them at docs.monitoring.qrdev.org. There is no runtime — deliberately, because this is the site people open when something else has already fallen over.

Where this behaviour lives: docs-site/. If the code and this page disagree, the code is right — please fix the page.

Part of Running AccelerUp — Operating the platform itself: architecture, deploys, backups.