@lukoweb/apitogo 0.2.47 → 0.2.50

package/docs/cli/shape.md

@@ -41,18 +41,19 @@ ready to go live.
 On a TTY, bare `npx apitogo config` opens the wizard. Each choice is written immediately; the loop
 continues until you type `done`:
 
-| Choice    | What it does                                                             |
-| --------- | ------------------------------------------------------------------------ |
-| `backend` | Set `gateway.origin`: API code folder, runtime and runtime version       |
-| `openapi` | Add an OpenAPI file to `gateway.specs`                                   |
-| `page`    | Create `apitogo/portal/pages/<slug>.mdx` (the sidebar follows the files) |
-| `plan`    | Add a plan to `apitogo/plans.json` (title, price, rate limit, quota)     |
+| Choice    | What it does                                                                            |
+| --------- | --------------------------------------------------------------------------------------- |
+| `backend` | Set `gateway.origin`: API code folder, runtime and runtime version                      |
+| `openapi` | Add an OpenAPI file to `gateway.specs`                                                  |
+| `page`    | Create the React page `apitogo/portal/pages/<slug>.tsx` (the sidebar follows the files) |
+| `plan`    | Add a plan to `apitogo/plans.json` (title, price, rate limit, quota)                    |
 
 Fonts and colors are **not** prompted. See [Colors & theme](../customization/colors-theme.mdx).
 
-**Paid plans:** a plan with a price needs `plans.billing.provider: "stripe"`, and **Starter** or
-**Professional** platform hosting on deploy. **Free** cannot publish paid gateway plans or custom
-domains.
+**Paid plans:** payments go through Stripe. Once a plan has a price, `npx apitogo deploy` asks for
+your Stripe secret key (if the project has none yet) and stores it as a project secret. Free and
+contact-us plans need no key. Paid plans also need **Starter** or **Professional** platform hosting;
+**Free** cannot publish paid gateway plans or custom domains.
 
 Full reference: [Make config (CLI)](../configuration/make-config.mdx) ·
 [Gateway plans](../configuration/plans.md)
@@ -87,7 +88,7 @@ After `npx apitogo config`, edit the manifest and site files directly:
 
 - **Services, backend, OpenAPI files** — `apitogo.config.json`
 - **Plans** — `apitogo/plans.json`
-- **Docs pages** — `apitogo/portal/pages/**/*.mdx`
+- **Docs pages** — `apitogo/portal/pages/**/*.{md,mdx,tsx}` (`.tsx` files are React pages)
 - **Home page** — the file in `portal.landing` (for example
   `apitogo/portal/landing/LandingPage.tsx`)
 

package/docs/cli/walkthrough.md

@@ -37,7 +37,7 @@ below use the installed CLI through `npx apitogo`.
 ```bash
 npx apitogo add identity
 npx apitogo add gateway --origin proxy --url https://httpbin.org --auth identity --create-spec
-npx apitogo add plans --template free --billing none
+npx apitogo add plans --template free
 ```
 
 | Service  | What it gives you                                                                               |
@@ -117,32 +117,21 @@ Professional plan with APItoGo, and your own Stripe account. Your customers pay
    opens the platform's checkout for the hosting fee. A project that already exists on the Free plan
    cannot be moved: create a new one. See
    [Selling paid plans needs Starter or Professional](./commands.md#selling-paid-plans-needs-starter-or-professional).
-2. In your Stripe account, copy the secret key (it starts with `sk_test_` while you test). Store it
-   as a project secret. The command asks for the value, so it stays out of the config:
-
-   ```bash
-   npx apitogo secrets set STRIPE_KEY
-   ```
-
-3. Turn billing on in `apitogo.config.json`:
-
-   ```json
-   "plans": {
-     "billing": { "provider": "stripe", "apiKey": "secret:STRIPE_KEY" }
-   }
-   ```
-
-4. Give a plan a price in `plans.json`: `"priceAmount": 49`, `"priceCurrency": "usd"` and
-   `"billingPeriod": "month"`. Its limits cannot be higher than your platform plan allows. A plan
-   with a price is refused while billing is off, so nobody is offered a plan they cannot pay for.
-5. Deploy: `npx apitogo deploy`. The output says whether Stripe is in test or live mode and prints
-   your portal's webhook address.
-6. In Stripe, add that address as a webhook endpoint with the events `checkout.session.completed`,
+2. Give a plan a price in `plans.json`: `"priceAmount": 49`, `"priceCurrency": "usd"` and
+   `"billingInterval": "month"`. Its limits cannot be higher than your platform plan allows.
+   Payments go through Stripe; nothing else in the config changes.
+3. Deploy: `npx apitogo deploy`. Because a plan now has a price, deploy asks for your Stripe secret
+   key (it starts with `sk_test_` while you test) and stores it as the project secret
+   `STRIPE_API_KEY`, so it stays out of your files. You can also store it beforehand with
+   `npx apitogo secrets set STRIPE_API_KEY`. The output says whether Stripe is in test or live mode
+   and prints your portal's webhook address.
+4. In Stripe, add that address as a webhook endpoint with the events `checkout.session.completed`,
    `customer.subscription.updated`, `customer.subscription.deleted` and `invoice.payment_failed`.
    Copy the signing secret (it starts with `whsec_`), store it with
-   `npx apitogo secrets set STRIPE_WEBHOOK`, add `"webhookSecret": "secret:STRIPE_WEBHOOK"` next to
-   `apiKey`, and deploy again. Until then a payment does not activate the plan, because the portal
-   cannot confirm it came from Stripe.
+   `npx apitogo secrets set STRIPE_WEBHOOK`, add
+   `"plans": { "billing": { "webhookSecret": "secret:STRIPE_WEBHOOK" } }` to `apitogo.config.json`,
+   and deploy again. Until then a payment does not activate the plan, because the portal cannot
+   confirm it came from Stripe.
 
 While you use a test key, pay with [Stripe's test cards](https://docs.stripe.com/testing). No real
 money moves. Never type a live key until you have tested the whole path.

package/docs/configuration/make-config.mdx

@@ -19,16 +19,18 @@ version 1 config, it stops and points to `apitogo create`.
 
 ## What goes where
 
-| You change          | Where it is written                                              |
-| ------------------- | ---------------------------------------------------------------- |
-| Portal display name | `portal.name` in `apitogo.config.json`                           |
-| API code (backend)  | `gateway.origin` (`mode: managed`, `source`, `runtime`, version) |
-| OpenAPI file        | `gateway.specs` in `apitogo.config.json`                         |
-| Docs page           | `apitogo/portal/pages/<slug>.mdx` (the config does not change)   |
-| Plan                | `apitogo/plans.json` (or the file in `plans.file`)               |
+| You change          | Where it is written                                                |
+| ------------------- | ------------------------------------------------------------------ |
+| Portal display name | `portal.name` in `apitogo.config.json`                             |
+| API code (backend)  | `gateway.origin` (`mode: managed`, `source`, `runtime`, version)   |
+| OpenAPI file        | `gateway.specs` in `apitogo.config.json`                           |
+| Docs page           | `apitogo/portal/pages/<slug>.tsx`, a React page (config unchanged) |
+| Plan                | `apitogo/plans.json` (or the file in `plans.file`)                 |
 
 The portal builds its sidebar from the pages folder, so adding a page needs no navigation entry. A
-page in `guides/quickstart.mdx` shows under a **Guides** section at `/guides/quickstart`.
+page in `guides/quickstart.tsx` shows under a **Guides** section at `/guides/quickstart`. New pages
+are React components by default; pass `--page-format mdx` for a Markdown page. See
+[Custom pages](../guides/custom-pages.md).
 
 Changing a gateway or plan needs that service in the project. Add it first with
 `apitogo add gateway` or `apitogo add plans`.
@@ -40,12 +42,13 @@ On a TTY, bare `npx apitogo config` opens the wizard. Each answer is applied at
 
 - **`backend`**: folder of your API code, runtime (`nodejs` / `python` / `dotnet`) and version
 - **`openapi`**: an OpenAPI file to add to `gateway.specs`
-- **`page`**: page title and URL path; writes `apitogo/portal/pages/<slug>.mdx`
+- **`page`**: page title and URL path; writes the React page `apitogo/portal/pages/<slug>.tsx`
 - **`plan`**: title, fixed or custom price, rate limit per minute, quota per 30 days; added to
   `plans.json`
 
-If you add a **paid** plan while `plans.billing.provider` is not `stripe`, the CLI warns that deploy
-will refuse it. Paid plans also need Starter or Professional platform hosting.
+Payments go through Stripe. When you add a **paid** plan, `npx apitogo deploy` asks for your Stripe
+secret key the first time (if the project has none yet). Free and contact-us plans need no key. Paid
+plans also need Starter or Professional platform hosting.
 
 ## Options
 
@@ -57,7 +60,8 @@ will refuse it. Paid plans also need Starter or Professional platform hosting.
 | `--runtime <name>`          | Runtime of `--source`: `nodejs` (default), `python` or `dotnet`       |
 | `--runtime-version <v>`     | Runtime version, for example `NODE_22_LTS`                            |
 | `--openapi <file>`          | Add an OpenAPI file to `gateway.specs`                                |
-| `--page-slug <path>`        | Add a page at `apitogo/portal/pages/<path>.mdx`                       |
+| `--page-slug <path>`        | Add a page at `apitogo/portal/pages/<path>.tsx`                       |
+| `--page-format <tsx\|mdx>`  | Format of a new page: `tsx` (React, the default) or `mdx`             |
 | `--page-title <title>`      | Title of the page (required when adding)                              |
 | `--page-content <markdown>` | Markdown body of the page                                             |
 | `--page-update`             | Change an existing page instead of adding one                         |

package/docs/configuration/navigation.mdx

@@ -61,7 +61,7 @@ one of several types. At the simplest level you may only have links and categori
 In a config version 2 project, the portal builds the sidebar from the pages under
 `apitogo/portal/pages/`: the index page first, then the other pages by name, then one section per
 folder. There is no `navigation` key to maintain. Add a page with **`npx apitogo config`** (see
-**[Make config (CLI)](./make-config.mdx)**) or by creating the `.md` / `.mdx` file.
+**[Make config (CLI)](./make-config.mdx)**) or by creating the `.md`, `.mdx` or `.tsx` (React) file.
 
 ## Navigation Items
 

package/docs/guides/custom-pages.md

@@ -11,16 +11,45 @@ components that APIToGo already has such as buttons, links and headers.
 
 Start by creating the page you want to add.
 
+## React pages in a project made by `apitogo create`
+
+Put a `.tsx` file next to your Markdown pages, in `apitogo/portal/pages/` (or any folder in
+`portal.docs.content`). Its default export is the page, and `export const title` is its label in the
+sidebar. The page's address follows its path, like a Markdown page: `guides/quickstart.tsx` is
+`/guides/quickstart`, under a **Guides** section.
+
+```tsx title="apitogo/portal/pages/guides/quickstart.tsx"
+import { useState } from "react";
+import { Button, Heading, Typography } from "@lukoweb/apitogo/components";
+
+export const title = "Quickstart";
+
+export default function QuickstartPage() {
+  const [count, setCount] = useState(0);
+  return (
+    <Typography>
+      <Heading level={1}>{title}</Heading>
+      <Button onClick={() => setCount(count + 1)}>Clicked {count} times</Button>
+    </Typography>
+  );
+}
+```
+
+- A file or folder whose name starts with `_` is not a page, so keep shared components there, for
+  example `apitogo/portal/pages/_components/Chart.tsx`. Test and story files are not pages either.
+- When a Markdown page and a React page have the same address, the Markdown page wins.
+- Nothing in `apitogo.config.json` changes: the sidebar is built from the files.
+
 ## CLI scaffold
 
-`npx apitogo config` can create a starter Markdown page at `apitogo/portal/pages/<slug>.mdx`. Choose
-`page` in the wizard loop, or pass `--page-slug` and `--page-title`. The sidebar is built from the
-pages folder, so no navigation entry is needed.
+`npx apitogo config` creates a starter React page at `apitogo/portal/pages/<slug>.tsx`. Choose
+`page` in the wizard loop, or pass `--page-slug` and `--page-title`. Add `--page-format mdx` for a
+Markdown page instead.
 
 Predefined UI components (Callout, Card, Button, Heading, and more) are documented under
 [/docs/components](/docs/components).
 
-## Setup a custom page
+## Setup a custom page (version 1 projects)
 
 Each custom page is a page component of its own and lives in a `src` directory at the root of your
 project. Let's create the `<MyCustomPage />` component as an example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lukoweb/apitogo",
-  "version": "0.2.47",
+  "version": "0.2.50",
   "type": "module",
   "sideEffects": [
     "**/*.css",

package/src/config/v2/__fixtures__/scenario-a-docs-only.json

@@ -1,6 +1,6 @@
-{
-  "version": 2,
-  "layout": "standalone",
-  "project": { "name": "my-docs" },
-  "portal": { "name": "My Docs" }
-}
+{
+  "version": 2,
+  "layout": "standalone",
+  "project": { "name": "my-docs" },
+  "portal": { "name": "My Docs" }
+}

package/src/config/v2/__fixtures__/scenario-b-managed-origin.json

@@ -1,14 +1,14 @@
-{
-  "version": 2,
-  "layout": "embedded",
-  "gateway": {
-    "origin": {
-      "mode": "managed",
-      "source": ".",
-      "runtime": "nodejs",
-      "runtimeVersion": "NODE_22_LTS",
-      "exclude": ["apitogo/**", "node_modules/**"]
-    },
-    "specs": ["openapi.yaml"]
-  }
-}
+{
+  "version": 2,
+  "layout": "embedded",
+  "gateway": {
+    "origin": {
+      "mode": "managed",
+      "source": ".",
+      "runtime": "nodejs",
+      "runtimeVersion": "NODE_22_LTS",
+      "exclude": ["apitogo/**", "node_modules/**"]
+    },
+    "specs": ["openapi.yaml"]
+  }
+}

package/src/config/v2/__fixtures__/scenario-c-proxy-oidc.json

@@ -1,15 +1,15 @@
-{
-  "version": 2,
-  "layout": "standalone",
-  "gateway": {
-    "origin": { "mode": "proxy", "url": "https://api.acme.com" },
-    "specs": ["apis/openapi.yaml"],
-    "auth": {
-      "mode": "oidc",
-      "metadataUrl": "https://idp.acme.com/.well-known/openid-configuration",
-      "issuers": ["https://idp.acme.com/"],
-      "audiences": ["api://acme-orders"]
-    },
-    "policies": { "rateLimit": { "calls": 60, "periodSeconds": 60 } }
-  }
-}
+{
+  "version": 2,
+  "layout": "standalone",
+  "gateway": {
+    "origin": { "mode": "proxy", "url": "https://api.acme.com" },
+    "specs": ["apis/openapi.yaml"],
+    "auth": {
+      "mode": "oidc",
+      "metadataUrl": "https://idp.acme.com/.well-known/openid-configuration",
+      "issuers": ["https://idp.acme.com/"],
+      "audiences": ["api://acme-orders"]
+    },
+    "policies": { "rateLimit": { "calls": 60, "periodSeconds": 60 } }
+  }
+}

package/src/config/v2/__fixtures__/scenario-h-full-stack.json

@@ -1,28 +1,28 @@
-{
-  "$schema": "https://apitogo.com/schema/config-v2.json",
-  "version": 2,
-  "layout": "embedded",
-  "project": { "id": "prj_123", "name": "acme-orders" },
-  "gateway": {
-    "origin": {
-      "mode": "managed",
-      "source": "server",
-      "runtime": "nodejs",
-      "runtimeVersion": "NODE_22_LTS"
-    },
-    "specs": ["server/docs/swagger.yaml"],
-    "auth": { "mode": "identity" }
-  },
-  "identity": { "native": true },
-  "plans": {
-    "billing": {
-      "provider": "stripe",
-      "apiKey": "secret:STRIPE_API_KEY",
-      "webhookSecret": "secret:STRIPE_WEBHOOK_SECRET"
-    }
-  },
-  "portal": {
-    "name": "Acme Orders",
-    "docs": { "content": ["docs/**/*.{md,mdx}"] }
-  }
-}
+{
+  "$schema": "https://apitogo.com/schema/config-v2.json",
+  "version": 2,
+  "layout": "embedded",
+  "project": { "id": "prj_123", "name": "acme-orders" },
+  "gateway": {
+    "origin": {
+      "mode": "managed",
+      "source": "server",
+      "runtime": "nodejs",
+      "runtimeVersion": "NODE_22_LTS"
+    },
+    "specs": ["server/docs/swagger.yaml"],
+    "auth": { "mode": "identity" }
+  },
+  "identity": { "native": true },
+  "plans": {
+    "billing": {
+      "provider": "stripe",
+      "apiKey": "secret:STRIPE_API_KEY",
+      "webhookSecret": "secret:STRIPE_WEBHOOK_SECRET"
+    }
+  },
+  "portal": {
+    "name": "Acme Orders",
+    "docs": { "content": ["docs/**/*.{md,mdx}"] }
+  }
+}

package/src/config/v2/billing.ts

@@ -0,0 +1,59 @@
+import { readFile } from "node:fs/promises";
+import type { ResolvedConfigV2 } from "./resolve.js";
+
+/**
+ * Billing (decision 21, narrowed): Stripe is the only payment provider. Billing is on exactly when the plan catalog has a
+ * plan with a price, so a project with free and contact-us plans needs no Stripe key and is never asked for one.
+ */
+
+/** The project secret that holds the Stripe key when `plans.billing.apiKey` names none. */
+export const DEFAULT_STRIPE_KEY_SECRET = "STRIPE_API_KEY";
+
+type PriceFields = { pricingModel?: unknown; priceAmount?: unknown };
+
+/** A plan someone pays for: a fixed price above 0. A contact-us (custom) plan is not paid here. */
+export function isPaidPlan(plan: PriceFields): boolean {
+  return (
+    plan.pricingModel !== "custom" &&
+    typeof plan.priceAmount === "number" &&
+    plan.priceAmount > 0
+  );
+}
+
+/** The skus of the paid plans in the plans file. A missing or unreadable file has none; the plans rules report it. */
+export async function paidPlanSkus(
+  resolved: ResolvedConfigV2,
+): Promise<string[]> {
+  const file = resolved.plans?.file;
+  if (!file) return [];
+  try {
+    const raw = JSON.parse(await readFile(file, "utf8")) as {
+      plans?: unknown;
+    };
+    if (!Array.isArray(raw.plans)) return [];
+    return raw.plans
+      .filter(
+        (plan): plan is PriceFields & { sku?: unknown } =>
+          typeof plan === "object" && plan !== null && isPaidPlan(plan),
+      )
+      .map((plan) => String(plan.sku ?? "?"));
+  } catch {
+    return [];
+  }
+}
+
+/** True when the plans service takes payments: Stripe is not switched off and a plan has a price. */
+export async function billingNeeded(
+  resolved: ResolvedConfigV2,
+): Promise<boolean> {
+  const plans = resolved.plans;
+  if (!plans?.enabled || plans.billing.provider !== "stripe") return false;
+  return (await paidPlanSkus(resolved)).length > 0;
+}
+
+/** The name of the secret that holds the Stripe key (`secret:NAME` in `plans.billing.apiKey`, default `STRIPE_API_KEY`). */
+export function stripeKeySecretName(resolved: ResolvedConfigV2): string {
+  const ref = resolved.plans?.billing.apiKey;
+  const match = ref ? /^secret:(.+)$/.exec(ref) : null;
+  return match?.[1] ?? DEFAULT_STRIPE_KEY_SECRET;
+}

package/src/config/v2/docs-navigation.ts

@@ -1,72 +1,95 @@
-import type { InputNavigationItem } from "../validators/InputNavigationSchema.js";
-
-/** Label of the one header tab that holds the sidebar made from the docs pages. */
-export const DOCS_NAVIGATION_LABEL = "Documentation";
-
-type Branch = { pages: Set<string>; folders: Map<string, Branch> };
-
-const emptyBranch = (): Branch => ({ pages: new Set(), folders: new Map() });
-
-/** "getting-started" becomes "Getting started". */
-export function folderLabel(name: string): string {
-  const words = name.replace(/[-_]+/g, " ").trim();
-  return words.charAt(0).toUpperCase() + words.slice(1);
-}
-
-const byName = (a: string, b: string) => a.localeCompare(b);
-
-const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
-  const pages = [...branch.pages].sort((a, b) =>
-    a === "index" ? -1 : b === "index" ? 1 : byName(a, b),
-  );
-  const folders = [...branch.folders.keys()].sort(byName);
-  return [
-    // The index page of a folder is the folder's own address, so the sidebar also shows on `/`.
-    ...pages.map(
-      (page): InputNavigationItem =>
-        page === "index"
-          ? {
-              type: "doc",
-              file: `${prefix}${page}`,
-              path: prefix === "" ? "/" : `/${prefix.slice(0, -1)}`,
-            }
-          : `${prefix}${page}`,
-    ),
-    ...folders.map(
-      (folder): InputNavigationItem => ({
-        type: "category",
-        label: folderLabel(folder),
-        collapsible: true,
-        collapsed: false,
-        items: toItems(
-          branch.folders.get(folder) ?? emptyBranch(),
-          `${prefix}${folder}/`,
-        ),
-      }),
-    ),
-  ];
-};
-
-/**
- * The sidebar for hosted docs, made from the pages themselves: the index page first, then the other pages by
- * name, then one section per folder. `routes` are the docs plugin's route paths (`/overview`, `/guides/style`).
- * Without pages there is nothing to navigate, so the result is empty.
- */
-export function docsNavigation(routes: string[]): InputNavigationItem[] {
-  const root = emptyBranch();
-  for (const route of routes) {
-    const parts = route.split("/").filter(Boolean);
-    const page = parts.pop();
-    if (!page) continue;
-    const branch = parts.reduce((current, folder) => {
-      const next = current.folders.get(folder) ?? emptyBranch();
-      current.folders.set(folder, next);
-      return next;
-    }, root);
-    branch.pages.add(page);
-  }
-  const items = toItems(root, "");
-  return items.length === 0
-    ? []
-    : [{ type: "category", label: DOCS_NAVIGATION_LABEL, items }];
-}
+import type { InputNavigationItem } from "../validators/InputNavigationSchema.js";
+
+/** Label of the one header tab that holds the sidebar made from the docs pages. */
+export const DOCS_NAVIGATION_LABEL = "Documentation";
+
+/** A React page in the sidebar. `element` is the placeholder the generated wrapper replaces with the component. */
+export type CustomDocsPage = { route: string; label: string; element: string };
+
+type Page = { kind: "doc" } | ({ kind: "custom" } & CustomDocsPage);
+type Branch = { pages: Map<string, Page>; folders: Map<string, Branch> };
+
+const emptyBranch = (): Branch => ({ pages: new Map(), folders: new Map() });
+
+/** "getting-started" becomes "Getting started". */
+export function folderLabel(name: string): string {
+  const words = name.replace(/[-_]+/g, " ").trim();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+const byName = (a: string, b: string) => a.localeCompare(b);
+
+const toItems = (branch: Branch, prefix: string): InputNavigationItem[] => {
+  const names = [...branch.pages.keys()].sort((a, b) =>
+    a === "index" ? -1 : b === "index" ? 1 : byName(a, b),
+  );
+  const folders = [...branch.folders.keys()].sort(byName);
+  const folderPath = prefix === "" ? "/" : `/${prefix.slice(0, -1)}`;
+  return [
+    ...names.map((name): InputNavigationItem => {
+      const page = branch.pages.get(name) as Page;
+      if (page.kind === "custom") {
+        return {
+          type: "custom-page",
+          // The index page of a folder is the folder's own address.
+          path: name === "index" ? folderPath : page.route,
+          label: page.label,
+          element: page.element,
+        };
+      }
+      // The index page of a folder is the folder's own address, so the sidebar also shows on `/`.
+      return name === "index"
+        ? { type: "doc", file: `${prefix}${name}`, path: folderPath }
+        : `${prefix}${name}`;
+    }),
+    ...folders.map(
+      (folder): InputNavigationItem => ({
+        type: "category",
+        label: folderLabel(folder),
+        collapsible: true,
+        collapsed: false,
+        items: toItems(
+          branch.folders.get(folder) ?? emptyBranch(),
+          `${prefix}${folder}/`,
+        ),
+      }),
+    ),
+  ];
+};
+
+const branchOf = (root: Branch, route: string) => {
+  const parts = route.split("/").filter(Boolean);
+  const page = parts.pop();
+  const branch = parts.reduce((current, folder) => {
+    const next = current.folders.get(folder) ?? emptyBranch();
+    current.folders.set(folder, next);
+    return next;
+  }, root);
+  return { branch, page };
+};
+
+/**
+ * The sidebar for hosted docs, made from the pages themselves: the index page first, then the other pages by
+ * name, then one section per folder. `routes` are the docs plugin's route paths (`/overview`, `/guides/style`);
+ * `customPages` are React pages placed the same way. A Markdown page wins over a React page at the same address.
+ * Without pages there is nothing to navigate, so the result is empty.
+ */
+export function docsNavigation(
+  routes: string[],
+  customPages: readonly CustomDocsPage[] = [],
+): InputNavigationItem[] {
+  const root = emptyBranch();
+  for (const route of routes) {
+    const { branch, page } = branchOf(root, route);
+    if (page) branch.pages.set(page, { kind: "doc" });
+  }
+  for (const custom of customPages) {
+    const { branch, page } = branchOf(root, custom.route);
+    if (page && !branch.pages.has(page))
+      branch.pages.set(page, { kind: "custom", ...custom });
+  }
+  const items = toItems(root, "");
+  return items.length === 0
+    ? []
+    : [{ type: "category", label: DOCS_NAVIGATION_LABEL, items }];
+}