Working on documentation

Who this is for: anyone writing or editing a page on this site. What you'll have at the end: the local dev loop, the archetype your page has to satisfy, the components you can use without importing them, and the lints that will fail your PR if you skip them. Time: thirty minutes, once.

The docs are an MDX corpus under content/docs/, rendered by Fumadocs on Next.js. Frontmatter at the top, Markdown plus JSX below. The only build steps are the two generators the dev server runs on start (gen:changelog and gen:llms).

Two things make this site different from most docs sites, and both are enforced rather than encouraged: every page declares an archetype and is reviewed against that archetype's contract, and every heading carries an explicit anchor so that a link cited by a human or cached by an agent keeps resolving after the heading is reworded.

The local loop

cd web
bun install
bun dev:docs        # docs only: http://localhost:3001/docs

Edit any .mdx file under apps/docs/content/docs/ and the dev server picks it up on save. To preview the marketing site and the docs together (the marketing app rewrites /docs to the docs app in dev), run bun dev and use http://localhost:3000/docs.

Pick the archetype first

Every page is exactly one of four kinds, and the kind determines the shape. Mixing two is the most common structural review comment, because a tutorial that pauses to explain tradeoffs stops being a guaranteed happy path, and an explanation that turns into a procedure stops being readable out of order.

The templates live in web/apps/docs/templates/. Copy the one you need, and keep the comment it puts directly under the frontmatter:

{/* archetype: how-to. See /web/apps/docs/templates/how-to.mdx */}

That comment is not decoration. It tells a reviewer, and an agent generating a page, which contract to check the page against.

The opening block every page has

Directly under the archetype comment, before anything else:

**Who this is for:** the reader this page assumes. **What you'll have at the
end:** the concrete outcome. **Time:** an honest estimate.

It exists so a reader who landed here from a search result can decide in five seconds whether to keep reading. "Time" is a real estimate; rounding it down to look welcoming is how a page loses trust in its first paragraph.

Pages on the reading path state what they assume on the next line:

<Prerequisites>
  A cache serving hits to your build. If you don't have one yet, start with
  [Getting started](/getting-started).
</Prerequisites>

Frontmatter and navigation

Two required fields, one optional:

---
title: My page
description: One sentence, written for a search result rather than for a reader who already opened the page.
---

full: true removes the right-hand table of contents. Use it on landing pages and wide generated references, not on ordinary pages.

Sidebar order comes from each section's meta.json:

{
  "title": "Section name",
  "pages": ["first", "second", "third"]
}

The top-level content/docs/meta.json orders the sections themselves; each section's meta.json gives it the title the sidebar shows. Do not list index in pages: a section's index.mdx becomes the link on the section title itself, and listing it would show the same page twice.

Components

All of these are provided globally. Never write an import in an .mdx file; an import statement is the usual reason a page compiles locally and fails in the MDX check.

<ConfigVersionSwitcher> is also registered, but only the generated configuration reference uses it.

Two syntax details that catch people:

<SourceLink> takes no children. It is always self-closing, and the label is the symbol prop. Pass dir instead of file to link a directory.

<SourceLink file="nativelink-util/src/store_trait.rs" symbol="StoreDriver" />

<Mermaid> takes a template literal, and literal angle brackets inside node text break the MDX parse; write < and >, or reword.

<Mermaid>{`graph LR
  a["Client"] --> b["CAS"]
`}</Mermaid>

Anchors are explicit, and a lint enforces it

Fumadocs derives a heading's id from its text. That is convenient and it is exactly the problem: the id is a function of the prose, so rewording a heading silently repoints every link that cited it. A human notices a dead in-page link and scrolls. An agent follows the cached URL, lands at the top of the page, and quotes whatever is there.

So every heading carries its id, and every FAQ entry carries an id:

## The three store traits [#the-three-store-traits]

<Accordion title="Why can't I use `tokio::spawn`?" id="why-not-tokio-spawn">

Once written, an anchor is a URL. Reword the heading freely; do not change the anchor without adding a redirect.

cd web
bun --filter @nativelink/docs lint:anchors          # check
bun --filter @nativelink/docs lint:anchors --fix    # freeze what exists

--fix writes the anchor Fumadocs would have generated anyway, so running it never moves an existing link; it only pins it. Generated pages are skipped.

Snippets are checked against the real schema

The configuration reference cannot drift from the binary, because it is generated from the same Rust types the binary deserializes. Prose pages can: a how-to showing a renamed field keeps showing it, and nothing fails until a reader copies it and the binary answers unknown field.

lint:snippets closes that gap. It harvests every field name out of the generated reference and checks every json/json5 fence under content/docs/ against it.

bun --filter @nativelink/docs lint:snippets

For a fence that legitimately is not NativeLink config (a meta.json, a Bazel lockfile, an API response), put the escape hatch on the line before it:

{/* lint-snippets: ignore */}

Keys nested under a free-form map (properties, platform_properties, env, …) are skipped automatically, since those names are the operator's to choose.

Generated pages: do not edit

Each MDX page among them opens with an AUTOGENERATED comment, which is also how the anchor lint knows to skip it. Fix the generator or the source doc comment; an edit to the output is overwritten on the next run.

gen:llms is the one to remember when you add a page: it builds the machine reader's index from meta.json and frontmatter, so a page missing from a meta.json is invisible to agents even if it renders fine.

bun --filter @nativelink/docs gen:llms

Style

Vale (.vale.ini, error level only) runs over the MDX in pre-commit and in the Vale CI check; typos excludes web/. The house rules on top of that are short:

Write prose, not bullet fragments. A bulleted list of six three-word items is a table that has not admitted it yet. Use a real table, or write sentences.

One idea per paragraph, and lead with the claim rather than building up to it.

Every code block gets a language tag. Markdown needs it for highlighting, and the snippet lint needs it to find the fence.

No em-dashes or en-dashes. Use a comma, a colon, parentheses, or two sentences instead.

Say the surprising thing plainly. If a default is wrong for most people, if a name points at the wrong crate, if a policy does not exist, write that down. A page that reads as a brochure is a page that stops being consulted.

Link the canonical page rather than restating it. Field-level truth lives in the generated reference; a reading-path page states intent and tradeoffs and links out for the types and defaults.

Before you open the PR

1. Run the lints from web/. These are what the Docs lint workflow runs on every PR that touches web/apps/docs/, and gen:llms must leave the tree unchanged:

   bun --filter @nativelink/docs lint:anchors
   bun --filter @nativelink/docs lint:links
   bun --filter @nativelink/docs lint:snippets
   bun --filter @nativelink/docs lint:boundaries
   bun --filter @nativelink/docs lint:navigation
   bun --filter @nativelink/docs gen:llms

2. Check that it compiles and typechecks. bun --filter @nativelink/docs build catches an MDX parse error or a stray import that the dev server tolerated.

3. Run pre-commit over what you changed, pre-commit run --files <paths>, for Vale.

4. Attach a screenshot of the rendered page. Reviewers read the MDX, but a broken table or an unrendered component only shows up in the render.

Then the normal flow: signed commits, an imperative title with no trailing period, a force-pushed amend rather than a follow-up commit. See contribution guidelines.

Common questions