docs: write docs.json by hand with a $ref to each repository's navigation

.github/workflows/tests.yml

@@ -0,0 +1,47 @@
+# Checks the site on every pull request and after every docs-sync push to main (the synced folders arrive without a PR).
+name: Tests
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Validate the site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: .nvmrc
+
+      - name: Install dependencies
+        run: |
+          npm install -g "$(node -p 'require("./package.json").packageManager')"
+          pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm run lint
+
+      # docs.json $refs, missing pages, invalid MDX and imports
+      - name: Validate the build
+        run: pnpm run validate
+
+      - name: Check the links
+        run: pnpm run broken-links
+
+      - name: Check accessibility
+        run: pnpm run a11y

.prettierignore

@@ -0,0 +1,7 @@
+# Owned by the source repositories, written by the docs-sync action at their releases.
+docs/
+guides/
+references/
+pnpm-lock.yaml
+# Written by pnpm.
+pnpm-workspace.yaml

README.md

@@ -1,8 +1,33 @@
-<a href="https://github.com/NanoForge-dev/docs/actions/workflows/package.yml"><img src="https://github.com/NanoForge-dev/docs/actions/workflows/package.yml/badge.svg" alt="Build status" /></a>
+<a href="https://github.com/NanoForge-dev/docs/actions/workflows/tests.yml"><img src="https://github.com/NanoForge-dev/docs/actions/workflows/tests.yml/badge.svg" alt="Tests status" /></a>
 
 # NanoForge Documentation
 
-Welcome to the official documentation for NanoForge, your go-to tool for building and managing ECS-based applications with ease. This documentation provides comprehensive guides, tutorials, and reference materials to help you get started and make the most out of NanoForge.
+The NanoForge documentation site, built with [Mintlify](https://mintlify.com): https://docs.nanoforge.eu
 
-https://docs.nanoforge.eu
+## How the site is made
 
+Each product's pages live in its own repository and reach this one through the `docs-sync` action of [NanoForge-dev/actions](https://github.com/NanoForge-dev/actions), at each release of that repository:
+
+| Folder                             | Written by      | Source                                                |
+| ---------------------------------- | --------------- | ----------------------------------------------------- |
+| `docs/engine`, `references/engine` | engine releases | `docs/docs`, the TypeDoc references (`pnpm run docs`) |
+| `docs/cli`, `guides/cli`           | cli releases    | `docs/docs`, `docs/guides`                            |
+| `docs/loader`                      | loader releases | `docs/docs`                                           |
+| `docs/editor`                      | editor releases | `docs/docs`                                           |
+
+- **Don't edit those folders here:** the next sync deletes and rewrites them. Change the pages in their repository.
+- Each synced folder holds a `navigation.json`, written from the source repository's own one. It sets the order and the groups of its pages.
+- `references/<product>/navigation.json` lists the reference versions: the latest release of each major.
+- This repository owns `docs.json` (theme, tabs, dropdowns, redirects), `index.mdx` and `custom.css`. `docs.json` includes each `navigation.json` with a `$ref`, so a new product is one entry there.
+
+## Commands
+
+Mintlify needs Node 24 (`.nvmrc`); it refuses Node 25+.
+
+```sh
+pnpm dev            # preview on port 3001
+pnpm validate       # docs.json, $refs, missing pages, MDX
+pnpm broken-links
+pnpm a11y
+pnpm lint
+```