@blaaiz/docs-core 0.1.1 → 0.3.0

package/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-core
-description: Work on a documentation site built with @blaaiz/docs-core. Use whenever a task touches docs.config.ts, content/docs.json, content/docs/**, or an import from @blaaiz/docs-core — adding or reordering doc pages, tabs, and groups; publishing an OpenAPI endpoint with the try-it playground; changing theme colours, the logo, or the favicon; setting up public or workspace authentication; turning on Ask AI, copy-page, search, or SEO; or fixing an error the framework raises.
+description: Work on a documentation site built with @blaaiz/docs-core. Use whenever a task touches docs.config.ts, content/docs.json, content/docs/**, or an import from @blaaiz/docs-core: adding or reordering doc pages, tabs, and groups; publishing an OpenAPI endpoint with the try-it playground; changing theme colours, the logo, or the favicon; setting up public or workspace authentication; turning on Ask AI, copy-page, search, or SEO; or fixing an error the framework raises.
 ---
 
 # docs-core
@@ -18,7 +18,7 @@ So: **never edit anything under `node_modules/@blaaiz/docs-core`.** Every change
 you make lands in `docs.config.ts`, `content/docs.json`, a content file, or one
 of the site's own wiring files. A change that seems to need a package edit is
 either a config field you have not found yet, or a framework change that belongs
-in the `docs-core` repository — say so instead of patching the install.
+in the `docs-core` repository. Say so instead of patching the install.
 
 ## The files that matter
 
@@ -30,20 +30,21 @@ in the `docs-core` repository — say so instead of patching the install.
 | `content/**/*-openapi.json`         | the site      | Add or change an API endpoint's spec                                           |
 | `content/docs/**/meta.json`         | see below     | Sidebar order                                                                  |
 | `content/nav.json`                  | see below     | Top-navigation links, one per tab                                              |
-| `content/api-methods.json`          | the generator | Sidebar method badges — never by hand                                          |
-| `content/docs/api/**`               | the generator | Generated endpoint pages — never by hand                                       |
+| `content/api-methods.json`          | the generator | Sidebar method badges. Never by hand                                           |
+| `content/docs/api/**`               | the generator | Generated endpoint pages. Never by hand                                        |
 | `app/**`, `lib/**`, `middleware.ts` | the site      | Wiring: routes, layouts, the page tree                                         |
 
 `meta.json` and `nav.json` are hand-written on a prose-only site. On a site with
 an API reference the generator writes them from `docs.json` on every run, so
-hand edits are lost — change `docs.json` instead. A site runs the generator when
+hand edits are lost; change `docs.json` instead. A site runs the generator when
 its `package.json` has a `predev` / `prebuild` script calling
 `@blaaiz/docs-core/generator`; check that first.
 
 ## docs.config.ts
 
-One call to `defineDocsConfig`. It returns its argument unchanged; it exists for
-type-checking and completion.
+One call to `defineDocsConfig`. It validates the whole config and throws
+`DocsConfigError` naming the exact field on a bad value; on success it returns
+the config unchanged.
 
 ```ts
 import { defineDocsConfig } from '@blaaiz/docs-core';
@@ -158,9 +159,9 @@ Naming a provider is a complete setup. Every other field has a default.
 
 Allowed models:
 
-- **anthropic** — `claude-sonnet-5`, `claude-haiku-4-5`, `claude-opus-5`,
+- **anthropic**: `claude-sonnet-5`, `claude-haiku-4-5`, `claude-opus-5`,
   `claude-opus-4-8`, `claude-sonnet-4-6`
-- **openai** — `gpt-5-mini`, `gpt-5`, `gpt-5.2`, `gpt-5-nano`, `gpt-4.1`,
+- **openai**: `gpt-5-mini`, `gpt-5`, `gpt-5.2`, `gpt-5-nano`, `gpt-4.1`,
   `gpt-4.1-mini`, `gpt-4o`, `gpt-4o-mini`
 
 The whole `ai` block is validated when the route is built, so a typo fails the
@@ -205,7 +206,7 @@ The navigation, and the only thing that decides what is published.
 Rules the parser enforces:
 
 - A tab needs a string `tab` title. It carries either `pages` or `groups`, never
-  both — `groups` wins if both appear.
+  both; `groups` wins if both appear.
 - A group needs a string `group` title and a `pages` array. Groups nest: a
   `pages` array may hold group objects.
 - A page string is either a content path relative to `content/docs`, without the
@@ -232,7 +233,7 @@ Rules the parser enforces:
 3. Add the tab's folder to the root `content/docs/meta.json` `pages` array, and
    give the folder its own `meta.json` with `"root": true`, a `title`, and an
    `icon`. On an API site, re-run the generator instead.
-4. Add the tab to `content/nav.json` — `{ text, url, icon }`, pointing at its
+4. Add the tab to `content/nav.json`: `{ text, url, icon }`, pointing at its
    first page. The generator writes this file on an API site.
 
 ### Add an API endpoint
@@ -252,11 +253,57 @@ An operation that exists in a spec but is not declared in `docs.json` gets no
 page. The navigation decides what is published. The API folder is deleted and
 rebuilt on every run, so a removed endpoint leaves no stale page.
 
+### Add, change, or remove the landing page
+
+The site root (`app/page.tsx`) has two valid shapes, and switching between
+them is a one-file change:
+
+- **A landing page**: render the hero inside `HomeLayout` from
+  `fumadocs-ui/layouts/home`: the same top bar as the docs (logo, links,
+  search, theme toggle) with no sidebar. Hero content is plain elements
+  carrying the `home-*` classes from `@blaaiz/docs-core/styles/home.css`.
+  Clicking a link enters the sidebar shell under `/docs`. Sites scaffolded by
+  `create-docs-core` ship this shape.
+- **No landing**: the file is a three-line `redirect('/docs')` and readers
+  land directly in the docs.
+
+Do not put the landing inside `content/docs/`: a page there always renders
+in the sidebar shell. For a wide page _inside_ the docs (sidebar kept, no
+title row, no table of contents), set `full: true` in that page's
+frontmatter instead. Mintlify's `mode: custom` frontmatter is not read by
+this stack; `HomeLayout` at the root is its equivalent.
+
+### The top-navigation links
+
+Both layouts build their links the same way. Never map `nav.json` by hand
+in a layout:
+
+```tsx
+links={docsNavLinks(navLinks).map((link) => ({
+  type: 'custom' as const,
+  children: <TopNavLink key={link.url} link={link} />,
+}))}
+```
+
+`docsNavLinks` (from `@blaaiz/docs-core/ui`) owns the policy: it prepends
+Home pointing at the landing (`home: false` on a site without one, or a
+custom entry to change its text or drop its icon), resolves icons (an entry
+without `icon` renders text-only), and computes each link's `match` path:
+exact for Home and the docs root, the section prefix for section links, so a
+section stays lit on every page of its section. `TopNavLink` is a small
+client component the site owns (like `components/logo.tsx`): it calls
+`isDocsNavLinkActive(link, usePathname())` and renders an anchor with the
+`topnav-link` class from `styles/docs.css`.
+
+One name means one page: Home is always the landing. Give the docs root its
+own tab in `docs.json` under a different name (Overview, Get started) rather
+than a second Home, so no page is reachable only by typing its URL.
+
 ### Change theme colours
 
 Edit `theme.colors` and `theme.darkColors` in `docs.config.ts`. Nothing else:
 the site's layout already turns the palette into CSS variables. Set `primary` in
-both palettes — a light-theme accent rarely has enough contrast on a dark
+both palettes; a light-theme accent rarely has enough contrast on a dark
 background.
 
 ### Enable Ask AI
@@ -296,7 +343,15 @@ background.
    ```
 
 `AskAi` accepts `endpoint`, `suggestions`, `label`, and `placeholder`, and all
-four have defaults.
+four have defaults. Write suggestions the corpus can actually answer. They
+are the first thing a reader clicks.
+
+On a site with an API reference, build the corpus with the merged OpenAPI
+document so endpoints carry their fields: in `lib/ask-ai.ts`, pass
+`openApiDocuments: { blaaiz: await getMergedSpec() }` to `mdxToMarkdown` (the
+key must match the `document="…"` name in the generated pages). Retrieval
+reads the last three user turns, so follow-ups keep their topic; answers
+render Markdown tables.
 
 ### Enable copy page
 
@@ -305,8 +360,42 @@ four have defaults.
    component, guarded by `config.features?.copyPage`.
 3. Serve the Markdown: `createMarkdownRoute({ read })` in
    `app/md/[[...slug]]/route.ts`, where `read` returns a page's raw MDX.
+4. On a site with an API reference, also pass `loadOpenApiDocuments`: an async
+   loader returning the merged OpenAPI documents by name (usually
+   `{ blaaiz: await getMergedSpec() }`, matching the `document="…"` the
+   generated pages reference). Without it, an API page's Markdown is only its
+   title and `METHOD /path`; with it, parameters, body fields, enums, and
+   responses are rendered in. The same `openApiDocuments` option exists on
+   `mdxToMarkdown` and belongs in the Ask AI corpus builder for the same
+   reason (see the Enable Ask AI recipe).
+
+### Wire search
+
+Fumadocs search is one route file, `app/api/search/route.ts`, re-exporting
+`createFromSource(source)` from `fumadocs-core/search/server`; the dialog comes
+from `RootProvider` and needs nothing else. For a custom surface (a command
+palette, a static index), the framework exports `buildSearchIndex` and
+`searchIndex` from `@blaaiz/docs-core`: pure functions, BM25 scoring with a
+light stemmer, safe to ship to the browser as JSON. Do not reimplement scoring.
+
+### Wire SEO
+
+Three framework builders read `docs.config.ts`; each mounts as one thin file:
+
+1. `buildMetadata(config)` exported as `metadata` from `app/layout.tsx`, and
+   `buildMetadata(config, { title, description, path })` from the page's
+   `generateMetadata`. Without the per-page call, every page shares one title.
+2. `buildRobots(config)` in `app/robots.ts`: `seo.noindex: true` disallows
+   crawling entirely; otherwise `/signin` and `/api/` are excluded.
+3. `buildSitemap(entries, config)` in `app/sitemap.ts`, with entries from
+   `source.getPages()`.
+
+`theme.favicon` flows through `buildMetadata`. Never add a
+`<link rel="icon">` by hand.
+
+### Set up workspace auth
 
-### Set up workspace auth with the shared secret
+Auth is config-only. The site's auth files ship installed and never change:
 
 1. In `docs.config.ts`:
 
@@ -314,17 +403,29 @@ four have defaults.
    auth: {
      mode: 'workspace',
      allowedDomains: ['example.com'],
-     providers: { secret: { secretEnv: 'DOCS_ACCESS_SECRET' } },
+     providers: { secret: {} },
    }
    ```
 
-2. Set `DOCS_SESSION_SECRET` (a long random value — `openssl rand -hex 32`) and
-   `DOCS_ACCESS_SECRET` in the server environment.
-3. Mount `createSecretSignIn` on a route, and `createAuthGate` in
-   `middleware.ts`. Import `@blaaiz/docs-core/styles/auth.css` for `AuthScreen`.
-4. Check the middleware matcher covers every route that must be gated. A matcher
-   that misses a route leaves that route open.
-5. Consider `seo: { noindex: true }` on a gated site.
+2. Set `DOCS_SESSION_SECRET` (a long random value, for example
+   `openssl rand -hex 32`) and
+   `DOCS_ACCESS_SECRET` in the server environment. Restart. Never write new
+   auth files.
+
+Providers combine freely: `email: true` (dev only), `secret`, and `google`
+(needs `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`). A declared provider whose
+env var is missing is offered as disabled, not broken; a missing session
+secret fails at startup naming the variable.
+
+On a site that adds docs-core to an existing Next.js app, mount
+`createSiteAuth(config.auth)` once in `lib/auth.ts`
+and re-export its handlers: `auth.gate` in `middleware.ts` (matcher must exempt
+static images or the sign-in page's own logo request gets redirected),
+`auth.secretSignIn` / `auth.emailSignIn` / `auth.google.start` /
+`auth.google.callback` / `auth.signOut` as routes under `app/api/auth/`, and
+`AuthScreen` (with `auth.secretEnabled` / `auth.googleEnabled`) on the sign-in
+page. Import `@blaaiz/docs-core/styles/auth.css`. Consider
+`seo: { noindex: true }` on a gated site.
 
 ## Verification habits
 
@@ -332,8 +433,8 @@ four have defaults.
   usually fails at build time by design.
 - After an API change, re-run the generator and confirm the page count it
   reports matches the endpoints you declared.
-- Never hand-edit `content/docs/api/**`, `content/api-methods.json`, or — on a
-  site that runs the generator — `meta.json` and `nav.json`. They are outputs.
+- Never hand-edit `content/docs/api/**`, `content/api-methods.json`, or, on a
+  site that runs the generator, `meta.json` and `nav.json`. They are outputs.
 - Check a content change in the browser at `/docs`: sidebar order, the top nav,
   and search.
 - A palette change needs a look in both light and dark mode.
@@ -342,19 +443,19 @@ four have defaults.
 
 Each message below is raised verbatim by the framework.
 
-| Message                                                                                    | Cause and fix                                                                                                                        |
-| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `ai.provider must be one of 'anthropic', 'openai', got '…'.`                               | Typo in `docs.config.ts`. Use one of the two names                                                                                   |
-| `ai.model must be one of '…' for provider '…', got '…'.`                                   | The model is not on that provider's allow-list. Use a listed id, or leave `model` out for the default                                |
-| `Ask AI is not configured: set the ANTHROPIC_API_KEY environment variable on the server.`  | The route is mounted but the key is missing. Set the env var named by `ai.apiKeyEnv` where the server runs — not in `docs.config.ts` |
-| `Target origin is not allow-listed: https://api.example.com`                               | The try-it request targets an origin missing from `proxy.allowedOrigins`. Add it, exactly, scheme included                           |
-| `Blocked host: localhost`                                                                  | The proxy refuses loopback, private, and link-local hosts on purpose. Point the playground at a reachable public origin              |
-| `docs.json navigation must have a "tabs" array.`                                           | `content/docs.json` is missing `navigation.tabs`. The older Mintlify `navigation` array form is not supported                        |
-| `Navigation entry at navigation.tabs[N].pages[M] must be a page string or a group object.` | That entry is neither a string nor an object with a `group` key. A common cause is `{ "page": "…" }`                                 |
-| `Group at <path> is missing a string "group" title.`                                       | Add the `group` title, or move a bare string into `pages`                                                                            |
-| `Duplicate operation POST /api/x across inputs.`                                           | Two OpenAPI files define the same method on the same route. The merge refuses to overwrite silently — delete one                     |
-| `Each OpenAPI input must have a "paths" object.`                                           | One spec file is not a real OpenAPI document. Even a one-operation file needs `paths`                                                |
-| `[docs-core] docs.json references POST /api/x, but <file> defines no such operation.`      | The `docs.json` entry and the spec disagree on method or route. Fix whichever is wrong                                               |
+| Message                                                                                    | Cause and fix                                                                                                                       |
+| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `ai.provider must be one of 'anthropic', 'openai', got '…'.`                               | Typo in `docs.config.ts`. Use one of the two names                                                                                  |
+| `ai.model must be one of '…' for provider '…', got '…'.`                                   | The model is not on that provider's allow-list. Use a listed id, or leave `model` out for the default                               |
+| `Ask AI is not configured: set the ANTHROPIC_API_KEY environment variable on the server.`  | The route is mounted but the key is missing. Set the env var named by `ai.apiKeyEnv` where the server runs, not in `docs.config.ts` |
+| `Target origin is not allow-listed: https://api.example.com`                               | The try-it request targets an origin missing from `proxy.allowedOrigins`. Add it, exactly, scheme included                          |
+| `Blocked host: localhost`                                                                  | The proxy refuses loopback, private, and link-local hosts on purpose. Point the playground at a reachable public origin             |
+| `docs.json navigation must have a "tabs" array.`                                           | `content/docs.json` is missing `navigation.tabs`. The older Mintlify `navigation` array form is not supported                       |
+| `Navigation entry at navigation.tabs[N].pages[M] must be a page string or a group object.` | That entry is neither a string nor an object with a `group` key. A common cause is `{ "page": "…" }`                                |
+| `Group at <path> is missing a string "group" title.`                                       | Add the `group` title, or move a bare string into `pages`                                                                           |
+| `Duplicate operation POST /api/x across inputs.`                                           | Two OpenAPI files define the same method on the same route. The merge refuses to overwrite silently. Delete one                     |
+| `Each OpenAPI input must have a "paths" object.`                                           | One spec file is not a real OpenAPI document. Even a one-operation file needs `paths`                                               |
+| `[docs-core] docs.json references POST /api/x, but <file> defines no such operation.`      | The `docs.json` entry and the spec disagree on method or route. Fix whichever is wrong                                              |
 
 Error classes are exported, so a site can branch on them:
 `InvalidNavigationError`, `OpenApiMergeError`, `ProxyTargetError`, and

package/styles/ask-ai.css

@@ -28,6 +28,10 @@
   bottom: 1.5rem;
   z-index: 9990;
   display: inline-flex;
+  /* A floating pill is always content-sized. Without this, some environments
+     stretch a fixed-position button past its content and the shortcut chip is
+     left floating mid-pill. */
+  width: max-content;
   align-items: center;
   gap: 9px;
   height: 42px;

package/styles/docs.css

@@ -245,3 +245,31 @@ body {
 .page-head > h1 {
   margin: 0;
 }
+
+/* Top-navigation links rendered by a site's TopNavLink component from
+   docsNavLinks data. Matches the fumadocs navbar look on theme tokens. */
+.topnav-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  border-radius: 8px;
+  color: var(--color-fd-muted-foreground);
+  font-size: 14px;
+  font-weight: 500;
+  text-decoration: none;
+  transition: color 0.15s ease;
+}
+
+.topnav-link:hover {
+  color: var(--color-fd-accent-foreground, var(--color-fd-foreground));
+}
+
+.topnav-link[data-active='true'] {
+  color: var(--color-fd-primary);
+}
+
+.topnav-link svg {
+  width: 15px;
+  height: 15px;
+}