Skip to content
Nxtstack docs

Documentation format

Generated repository documentation is a folder of plain files. This page describes the format, so that the same files can be read in a repository, rendered by a documentation site, and read by a coding agent.

This documentation site uses the same format.

Design rules

Section titled “Design rules”
  1. Plain files in the repository. Markdown pages in one folder, versioned with the code.
  2. Generated, never hand-edited. A page is always the output of the generator for one commit. Editing a page by hand has no lasting effect, because the next run replaces it.
  3. Traceable. Every page records the commit it was generated from and the source files it describes.
  4. Renderable anywhere. Standard Markdown, standard front matter, and Mermaid for diagrams. No custom syntax.

Folder layout

Section titled “Folder layout”
docs/
  index.md                 Overview of the repository
  architecture/
    index.md               Architecture map: what talks to what
    flows/
      <flow-name>.md       One sequence diagram per main flow
  modules/
    <module-path>.md       One page per module

The sidebar follows the folder structure. Folders become groups and files become pages, in the order given by each page’s front matter.

Page front matter

Section titled “Page front matter”

Every page starts with front matter.

---
title: Sign-in flow
description: How a user signs in with an email link.
generated:
  commit: 3f9c2a1
  sources:
    - src/server/email-auth.ts
    - src/server/service.ts
order: 2
---
Field Required Meaning
title Yes Page title.
description Yes One sentence, used in search results and link previews.
generated.commit Yes The commit the page was generated from.
generated.sources Yes The source files the page describes.
order No Position among sibling pages.

Diagrams

Section titled “Diagrams”

Diagrams are Mermaid code blocks, so they are text, they can be compared between commits, and they render on GitHub.

```mermaid
sequenceDiagram
  Browser->>App: Request sign-in link
  App->>Email service: Send link
  Browser->>App: Open link
  App->>Browser: Session cookie
```
Section titled “Links to source”

A statement about code links to the file and line it describes, at the commit the page was generated from. A reader, or an agent, can always check a page against the code.