Running and writing the docs

This site is Docusaurus 3. The configuration lives in website/; the content lives in docs/ at the repository root, so a documentation change is reviewable in the same pull request as the code it describes, and every page stays readable on GitHub.

Commands

Run all of these from the repository root:

pnpm docs:install   # install the site's dependencies (once)
pnpm docs:dev       # dev server on http://localhost:3000 with hot reload
pnpm docs:build     # production build into website/build
pnpm docs:serve     # serve that build locally, exactly as GitHub Pages will
pnpm docs:typecheck # type-check the site's own TSX and config
pnpm docs:clear     # clear the Docusaurus cache when a build goes strange
pnpm docs:deploy    # push a build to gh-pages by hand (CI does this for you)

pnpm docs:dev and pnpm docs:build install first, so a fresh clone needs no separate step.

The build is the link checker

onBrokenLinks, onBrokenAnchors and onBrokenMarkdownLinks are all set to throw. A link to a page that no longer exists — or to a heading that was renamed — fails pnpm docs:build, which is the same command CI runs on every pull request.

Layout

docs/                     ← the content, one folder per section
  intro.mdx
  getting-started/
  modeling/
  querying/
  multi-tenancy/
  runtime/
  reference/
  contributing/
website/
  docusaurus.config.ts    ← site config: URL, navbar, footer, search, Prism
  sidebars.ts             ← the sidebar, written by hand
  src/pages/index.tsx     ← the landing page
  src/css/custom.css      ← theme variables and the little site-specific chrome

The sidebar is explicit, not autogenerated: the order of the pages is an argument (model the graph, then query it, then run it in production), and an alphabetical listing cannot express that. A new page therefore needs two things — the file, and an entry in website/sidebars.ts.

Writing a page

Every page is MDX with front matter:

---
id: streaming
title: Streaming large results
sidebar_label: Streaming
sidebar_position: 4
description: One sentence. It becomes the meta description and the search snippet.
---

Conventions worth keeping:

• No # heading in the body. The title renders it; a second one duplicates it.
• Link with absolute doc paths — /docs/querying/streaming — rather than relative file paths. They survive a page being moved between sections.
• Show the Cypher. A claim about what a filter compiles to is worth more with the statement beside it, and these pages are read by people who will check.
• Admonitions carry the caveats: :::tip, :::note, :::warning, :::info. Prose carries the explanation.
• MDX parses { and < as code. Inside backticks or a fenced block they are literal, which covers almost everything — but a bare <name> in a sentence will fail the build.

Code blocks take a title, and Prism knows ts, cypher, graphql, json, bash and diff:

```ts title="src/entities.ts"
const books = await em.find(Book, {});
```

Deployment

Pushing to main builds the site and publishes it to GitHub Pages through .github/workflows/docs.yml. Pull requests build it too, without publishing, so a broken link never reaches main.

The workflow needs Pages set to "GitHub Actions" once, in Settings → Pages → Build and deployment → Source.