Changelog

Analytics API

Pull your docs analytics into your own dashboards — three new endpoints under the public API, gated by the new analytics:read scope:

• GET /projects/{id}/analytics/overview — totals (views, unique visitors, searches, feedback), a bucketed timeseries (minute → month, timezone-aware), and the AI-vs-human split.

• GET /projects/{id}/analytics/breakdown — one endpoint, twelve dimensions: pages, searches, countries, regions, cities, browsers, os, devices, channels, referrers, campaigns, keywords.

• GET /projects/{id}/analytics/ai — the AI & LLMs card as data: crawler reads per family (GPTBot, ClaudeBot, …), most-read pages, llms.txt / .md export fetches, assistant usage, AI referrals.

Bot traffic is excluded by default (bots=included to keep it); every endpoint takes a from/to window and defaults to the last 30 days. Existing full-access keys get the new scope automatically — restricted keys need it ticked in Settings → API Keys.

Public REST API

The NookDocs API is live at https://api.nookdocs.com/v1 — every documented operation now works:

• Projects — list, get, create (plan-quota aware), update, delete, logo upload.

• Pages — list + full-text search (POST /projects/{id}/pages/search).

• Deployments — list, get, and trigger a deploy from the API (POST /projects/{id}/deployments).

• Keys now use the nook_ prefix, carry scopes you pick at creation and can edit later (Settings → API Keys), and expiry is enforced — an expired key returns 401, a missing scope returns 403.

• CORS enabled — call the API straight from your frontend or the docs Try It playground.

API keys are limited to the documented surface; dashboard-internal endpoints require a signed-in session.

API reference pages, rebuilt

• Response schemas drill into nested objects ("child attributes", recursive — arrays of objects included), and list endpoints document their item fields.

• Enums render every value as chips — no more enum (a, b, c ...) truncation.

• Response statuses are color-coded tabs (200 green, 4xx red) matching the example panel; application/json content-type labels on Body and Response.

• Authorizations renders as a real field row (Authorization · string · header · required).

• Hybrid pages render their MDX body — add Callouts, plan notes, or setup steps above any generated endpoint by writing below the openapi: frontmatter.

• Try It playground: top-anchored modal that grows with content, auth header always visible in the code sample (live-updates as you type your key), and field styling identical to the reference pages.

Analytics suite

The per-project Analytics page grew into a full suite:

• Date ranges — Today / Yesterday / last 7-30 days / month-to-date / custom calendar, plus a live Now view (per-minute, auto-refresh). Granularity adapts to the window.

• Locations — world map plus country / region / city breakdowns.

• Tech — browser / OS / device with real brand logos.

• Traffic sources — channel / referrer (with favicons) / campaign / keyword, powered by UTM capture. Visits arriving from ChatGPT, Perplexity & co. classify as the AI channel.

• AI & LLMs card — which AI crawlers read which pages, llms.txt / llms-full.txt / .md export fetch counts, Ask AI usage, and AI referrals.

• Cross-filtering — click any row (page, country, browser, referrer…) to filter the whole dashboard; stack filters and manage them from the always-visible Filters control.

• Deploys got faster too: syncs are incremental — a one-page edit processes one page, not the whole site.

Changelog + RSS feeds

• New /<page>/rss.xml endpoint on every docs page — auto-generated RSS 2.0 feed from <Update> components on that page.

• rss: true in page frontmatter renders an RSS subscribe button in the page header next to Copy page.

• <Update> component gains an rss prop for plain-text overrides of the feed description when the body contains JSX or code.

• Full docs at content/changelogs.

Three new content pages

• Redirects — full documentation for the redirects[] config: source/destination/permanent, wildcard tail preservation, 6 common patterns.

• Reusable snippets — honest v0 page: inline <Snippet> works today, file-based /_snippets/*.mdx resolution is Phase 4 roadmap.

• Personalization — <Visibility for="humans | agents"> ships today (audience split); authGroups / public:false are schema-scaffolded, roadmap.

Custom domain consolidation

Collapsed the 27+160-line custom-domain split into a single 252-line canonical guide at deploy/custom-domain. New content:

• CAA record requirement + dig command

• Cloudflare SSL mode gotcha (Full vs Full strict vs Flexible)

• Vercel TXT verification flow

• Canonical URL multi-domain primary selection

• 6-accordion troubleshooting section

/configuration/custom-domain now permanent-redirects (308) to the Deploy variant.

Also fixes a schema drift: redirects[] in public/schema.json claimed from/to but the renderer, validator, and dashboard panel all used source/destination. Schema now matches runtime.

CLI documentation section

Four pages documenting the real CLI surface (migration-first — preview / analytics / login subcommands claimed by the depth audit do not exist yet):

• CLI overview — what the CLI does today

• Install — npm / pnpm / yarn / bun + Node 18+

• Migrate command — platform detection + flag reference + report output

• Migrating from Mintlify — full docs.json ↔ nookdocs.config.json key matrix + 20-component mapping + post-migration checklist

Optimize section

New top-level Optimize nav group covering three affordances every tenant already ships:

• llms.txt — auto-generated /llms.txt + /llms-full.txt for AI crawlers

• Markdown export — every page available as raw MDX at /<slug>.md

• SEO — sitemap.xml + robots.txt + canonical URL + per-page frontmatter controls

Each page honest about what ships vs what's roadmap (no Accept: text/markdown header yet, no X-Llms-Txt discovery header, no JSON-LD schema.org emission).

Integrations split — 1 → 16 pages

Exploded the single configuration/integrations.mdx into per-provider pages under docs/integrations/ (13 analytics / 1 privacy / 2 support). Each page covers:

• What the provider does + vendor link

• Where to find the ID in the vendor dashboard

• Paste-ready JSON config

• CSP + loading strategy

• Gotchas (EU regions, double-tracking with GTM, SSL mode caveats)

Long-tail SEO win — "how to add Plausible to NookDocs" now ranks on its own page. LLM-readiness win — agents can wire any provider from a single page read.

AI Assistant depth pass (81 → 214 lines)

Expanded configuration/ai-assistant to cover the full retrieval pipeline (translate → FTS → stream), a BYOK provider/model recommendation table, 3 concrete system-prompt patterns, deep-linking MDX recipes, full API spec with TypeScript streaming client, analytics fields, limits, 4-accordion troubleshooting, privacy disclosure, roadmap.

Every claim matches the actual schema + api/v1/assistant/ask implementation — no fabricated features.

Theme documentation (29 → 177 lines)

Expanded configuration/theme with the full 10-theme catalog, appearance schema, brand color overrides, background (solid + gradient), typography (3 keys), paste-ready example JSON, precedence rules, and dashboard editing notes.

All fields rendered as <ParamField> with type/required/default — LLM-consumption ready.

Schema-reference auto-generator

New configuration/schema-reference — 636-line page auto-generated from public/schema.json every build. Every top-level key + nested property rendered as <ParamField> with type / required / default / description.

The LLM's single-paste reference for synthesising a valid nookdocs.config.json in one prompt. Closes the biggest LLM-readiness gap from the Mintlify competitive audit.

Regenerates via npm run build:schema-reference, wired into npm run build chain.

Automated drift detector

scripts/check-sync.mjs scans every nookdocs.config.json key across 5 layers (TypeScript types, JSON Schema, validator, renderer, docs, UI panel). Distinguishes hard drift (ships half-broken) from soft drift (missing validator rule). Runs on npm run build — hard drift aborts the build.

Fixed 7 hard drifts from the depth audit in the same commit: BackgroundConfig / TypographyConfig / AdvancedConfig types, typography CSS renderer in docs/layout.tsx, feedback reasons editor, interaction.drilldown migration, 3 missing docs (ai-assistant, contextual, typography + navbar sections in site-settings).