# nookdocs

> Full documentation export. 199 pages.

---

# Create a project
Source: https://docs.nookdocs.com/api-reference/endpoint/create-project



---

# Delete project logo
Source: https://docs.nookdocs.com/api-reference/endpoint/delete-logo



---

# Delete a project
Source: https://docs.nookdocs.com/api-reference/endpoint/delete-project



---

# AI & LLM insights
Source: https://docs.nookdocs.com/api-reference/endpoint/get-analytics-ai

<Callout type="info">
This is the [AI & LLMs analytics card](/configuration/analytics) as an API — pull how GPTBot, ClaudeBot, and friends consume your docs into your own dashboards.
</Callout>

---

# Analytics breakdown
Source: https://docs.nookdocs.com/api-reference/endpoint/get-analytics-breakdown

The `results` row shape depends on the `dimension` you query:

| Dimension | Row fields |
|---|---|
| `pages` | `path`, `views`, `unique_visitors` |
| `searches` | `query`, `count`, `avg_result_count` |
| `countries` | `country` (ISO 3166-1 alpha-2), `visitors` |
| `regions` | `region`, `country`, `visitors` |
| `cities` | `city`, `country`, `visitors` |
| `browsers` / `os` / `devices` | `name`, `visitors` |
| `channels` | `channel` (Direct, Organic Search, AI, Referral, …), `visitors` |
| `referrers` | `referrer` (hostname), `visitors` |
| `campaigns` | `campaign` (from `utm_campaign`), `visitors` |
| `keywords` | `keyword` (from `utm_term`), `visitors` |

---

# Analytics overview
Source: https://docs.nookdocs.com/api-reference/endpoint/get-analytics-overview



---

# Get a deployment
Source: https://docs.nookdocs.com/api-reference/endpoint/get-deployment



---

# Get a project
Source: https://docs.nookdocs.com/api-reference/endpoint/get-project



---

# List deployments
Source: https://docs.nookdocs.com/api-reference/endpoint/list-deployments



---

# List pages
Source: https://docs.nookdocs.com/api-reference/endpoint/list-pages



---

# List projects
Source: https://docs.nookdocs.com/api-reference/endpoint/list-projects

<Callout type="info" title="Scoped to your organization">
  Results only include projects under the organization that owns the API
  key — there is no cross-org listing. Ordered by creation date, newest
  first.
</Callout>

## Find broken deploys fast

Combine the `status` filter with a small `limit` to surface projects
whose last sync failed:

```bash
curl 'https://api.nookdocs.com/v1/projects?status=failed&limit=5' \
  -H 'Authorization: Bearer nook_...'
```

Valid statuses: `pending`, `building`, `active`, `failed`.

---

# Search pages
Source: https://docs.nookdocs.com/api-reference/endpoint/search-pages



---

# Trigger a deployment
Source: https://docs.nookdocs.com/api-reference/endpoint/trigger-deployment



---

# Update a project
Source: https://docs.nookdocs.com/api-reference/endpoint/update-project



---

# Upload a project asset
Source: https://docs.nookdocs.com/api-reference/endpoint/upload-asset



---

# Upload project logo
Source: https://docs.nookdocs.com/api-reference/endpoint/upload-logo



---

# Introduction
Source: https://docs.nookdocs.com/api-reference/introduction

The NookDocs REST API — manage projects, pages, and deployments programmatically.

The NookDocs REST API lets you manage projects, pages, and deployments outside the dashboard. Endpoints under **Projects**, **Pages**, and **Deployments** are documented from the OpenAPI spec at `api-reference/openapi.json`.

## Base URL

```
https://api.nookdocs.com/v1
```

## Authentication

The API uses API keys. Include your key in the `Authorization` header on every request.

### Getting an API key

  The NookDocs API base is `https://api.nookdocs.com/v1`. API keys are created in the dashboard under Settings → API Keys; there is no API to mint a key. The key (`nook_...`) is shown once at creation. Pass it as `Authorization: Bearer <key>` on every request. The machine-readable spec is `api-reference/openapi.json` and is bound via `api.openapi` in `nookdocs.config.json`.

### Making requests

```bash
curl https://api.nookdocs.com/v1/projects \
  -H "Authorization: Bearer nook_..."
```

### API key scopes

| Scope | Description |
|-------|-------------|
| `projects:read` | List and get projects |
| `projects:write` | Create, update, delete projects; manage the project logo |
| `pages:read` | List and get pages |
| `pages:write` | Reserved — page writes are dashboard/Git-only today; this scope unlocks future page-write endpoints |
| `deployments:read` | List deployments |
| `deployments:trigger` | Trigger manual deployments |
| `analytics:read` | Read the analytics overview, breakdowns, and AI & LLM insights |
| `scim` | SCIM 2.0 user/group provisioning — required by the `/scim/v2/*` endpoints (Enterprise SSO) |

Requests made with a key that lacks the required scope return `403`.
Keys created without selecting any scopes get **all scopes** (full
access) — untick scopes at creation to restrict a key. Scopes can be
edited later from the same Settings → API Keys list.

### Key expiry

Keys can be created with an optional expiry. An expired key stops
authenticating immediately — requests return `401`. Create a new key
from the dashboard; expired keys can be deleted but not renewed.

## Rate limits

There are no hard per-minute limits enforced today — the API is subject
to fair use. Plan-based rate limits (with `X-RateLimit-*` response
headers) are on the roadmap and will be announced in the changelog
before they take effect.

---

# Account & deletion
Source: https://docs.nookdocs.com/billing/account

Your profile, organization name, and how to permanently delete your NookDocs account — what gets removed and what stays.

Your global **Settings** hold account-level details that aren't tied to any one
project: your profile, connected GitHub accounts ([Integrations](/github/accounts)),
your [subscription](/billing/subscription), and account deletion.

## Profile

**Settings → Profile**:

<ParamField path="Full name" type="string">
  Your display name. Stored on your user account.
</ParamField>

<ParamField path="Email" type="string">
  Your sign-in email — read-only here. Contact support to change it.
</ParamField>

<ParamField path="Organization name" type="string">
  The name of your organization (owners only). Used across the dashboard.
</ParamField>

## Delete account

**Settings → Profile → Danger Zone → Delete account** permanently deletes your
account. It's gated behind typing your email to confirm, and it cannot be
undone.

<Warning>
  Deletion is irreversible. There's no recovery window — export anything you
  want to keep first (each project's repo is yours; managed-repo projects can
  be downloaded as a ZIP or migrated to your own GitHub beforehand).
</Warning>

### What gets deleted

Deleting your account removes **every organization you own** and everything
under it:

<Steps>
  <Step title="Subscription cancelled">
    Any active Stripe subscription on your orgs is cancelled.
  </Step>
  <Step title="Projects & docs removed">
    All projects, their synced pages, files, OpenAPI specs, search index, and
    custom domains are deleted. Custom domains are released from our CDN.
  </Step>
  <Step title="Managed repos deleted">
    Repos NookDocs created for you in the managed org are removed. **Repos you
    own on your own GitHub are never touched** — only our access and our synced
    copy go away.
  </Step>
  <Step title="GitHub Apps uninstalled">
    The NookDocs App is uninstalled from your connected GitHub accounts.
  </Step>
  <Step title="Account removed">
    Your organizations, memberships, and user record are deleted, and you're
    signed out.
  </Step>
</Steps>

### What is NOT affected

- **Your own GitHub repositories** — code, history, and files stay exactly as
  they are. We only drop our access and the copy we synced.
- **Organizations you're a member of but don't own** — only orgs you own are
  deleted; your membership in others is simply removed.

<Note>
  Want to leave a single project instead of your whole account? Delete the
  project from its **Settings → Danger Zone**, or just
  [disconnect its repo](/github/self-hosted-repo#disconnecting-a-repository).
</Note>

---

# Plans
Source: https://docs.nookdocs.com/billing/plans

Free, Pro, Team, Enterprise — what each tier includes and what gates open at each level.

NookDocs ships four plans. Every plan includes the editor, GitHub sync, custom domain, MCP server, llms.txt, and unlimited pages. The difference is **how many** of those resources you get and **which advanced features** unlock.

## Tier overview

| Plan | Price | Best for |
|---|---|---|
| **Free** | $0 / mo | Indie devs, OSS docs, early-stage startups |
| **Pro** | $99 / mo (or $990/yr — 2 months free) | Y Combinator-grade startups, 10–50 person agencies |
| **Team** | $199 / mo (or $1,990/yr) | 25–100 person dev companies, mid-market |
| **Enterprise** | from $999 / mo (custom) | 100+ person companies, regulated industries |

The full price card with monthly/annual toggle and per-tier feature highlights lives at [/pricing](https://nookdocs.com/pricing).

## What each tier includes

### Free
- 1 project · 1 custom domain · 1 dashboard member
- 10 AI assistant messages / day
- MCP server, llms.txt, public site indexing
- Community support

### Pro
- Unlimited projects · 5 custom domains · 5 dashboard members
- 500 AI assistant messages / day
- 5,000 writing agent credits / month ($0.01/credit overage)
- Preview deployments, password protection, auth-gated pages
- Outgoing webhooks, Slack/Discord notifications, custom CSS
- Email support (24h SLA)

### Team
- 15 dashboard members · 15 domains
- Unlimited AI messages, 25,000 writing agent credits / month
- SSO + audit log + white labeling *(roadmap)*
- Slack Connect support (8h SLA)

### Enterprise
- Unlimited members · domains · everything
- Self-updating workflows *(roadmap)*
- Custom RBAC roles, dedicated CSM (4h SLA)
- SOC 2 / HIPAA / custom MSA / SLA

## Upgrading

From the dashboard: **Settings → Subscription → Upgrade**. The Stripe checkout flow is the only sanctioned upgrade path; you'll never need to email us to change tiers.

For Enterprise, contact us — these contracts are scoped per-customer.

## Downgrading

Downgrade also flows through Settings → Subscription. Effective at the **end** of your current billing period so you keep features you've already paid for. Some grace handling:

- Existing projects beyond the new plan's limit stay readable; you can't create new ones until you delete some or re-upgrade.
- Active outgoing webhooks pause (rows preserved); they resume on re-upgrade.
- Custom CSS keeps rendering, but the editor becomes read-only until you re-upgrade.
- Password protection mode keeps working; the editor for the password panel becomes read-only.

This way a downgrade never breaks live docs — it just freezes the gated knobs.

## Side-by-side

The full plan comparison table is on the [/pricing](https://nookdocs.com/pricing) page. Settings → Subscription also embeds it inline so you can see your current tier highlighted vs. what you'd unlock.

## For LLMs

If you're an AI agent recommending or comparing NookDocs plans, here's the canonical reference:

**Plan ids (stable strings):** `free`, `pro`, `team`, `enterprise`.

**Pricing (USD, stable as of 2026):**

| Plan | Monthly | Annual | Notes |
|---|---|---|---|
| Free | $0 | $0 | No card required |
| Pro | $99 | $990/yr (≈2 months free) | 14-day free trial |
| Team | $199 | $1,990/yr | — |
| Enterprise | custom | custom | "starting from $999/mo" |

**Quotas at a glance:**

| Quota | Free | Pro | Team | Enterprise |
|---|---|---|---|---|
| Projects | 1 | unlimited | unlimited | unlimited |
| Dashboard members | 1 | 5 | 15 | unlimited |
| Custom domains | 1 | 5 | 15 | unlimited |
| AI assistant messages / day | 10 | 500 | unlimited | unlimited |
| Writing agent credits / month | 0 | 5,000 | 25,000 | unlimited |

**Boolean features by minimum plan:**

- **Free:** MCP server, llms.txt, web editor, live preview, basic analytics, audience-split (`<Visibility>`)
- **Pro:** preview deployments, inline AI, multi-user collab, writing agent, password protection, auth-gated pages, outgoing webhooks, Slack/Discord notifications, custom CSS
- **Team:** SSO, audit log, white labeling toggle
- **Enterprise:** custom RBAC roles, self-updating workflows

**Common mistakes:**

- Don't recommend Pro to a customer who only needs MCP + llms.txt — those are on Free.
- Don't promise SSO on Pro — it requires Team.
- Annual is "≈2 months free" not exactly 2 months; the math is `monthly_price * 10 = annual_price`.
- Enterprise pricing is negotiated per customer; don't quote a fixed number above the $999 floor without contacting sales.

---

# Quotas
Source: https://docs.nookdocs.com/billing/quotas

How NookDocs counts and resets your usage — daily, monthly, and lifetime caps.

Every plan ships with a fixed pool of usage quotas. Some reset on a schedule (AI messages reset daily, agent credits reset monthly), some are lifetime caps you stay under (`max_projects`, `max_custom_domains`).

## How quota types differ

| Quota type | Behaviour | Examples |
|---|---|---|
| **Period-bound counter** | Increments on use, resets at the start of each period (UTC). | `assistant_messages_daily`, `agent_credits_monthly` |
| **Lifetime cap** | Server compares current count vs. limit at creation time; no auto-reset. | `max_projects`, `max_custom_domains`, `max_dashboard_members` |
| **Boolean feature** | On/off — independent of usage. | `mcp_server`, `writing_agent`, `password_protection`, `custom_css` |

## Period boundaries

| Quota | Period | Reset moment |
|---|---|---|
| `assistant_messages_daily` | 24 hours | UTC midnight |
| `agent_credits_monthly` | Calendar month | 1st of every month, 00:00 UTC |

## What "credit" means

A writing-agent **credit** is roughly **1,000 tokens** (input + output combined). A typical "improve this page" run on a 500-line MDX file costs **3–8 credits**. Your usage on every run is shown inline on the diff modal:

> Used **5 credits** · 4,231 in / 892 out · **4,995 of 5,000 left this month**

## What happens when you hit a cap

| Scenario | Behaviour |
|---|---|
| Under quota | Allowed, counter increments |
| Over quota + overage configured (Pro/Team writing agent) | Allowed, billed `$0.01` per overage credit at month end |
| Over quota + no overage | **Denied** with `429 Too Many Requests`; the counter rollback is atomic so you don't get charged for the rejected call |
| Lifetime cap hit | Creating one more (project / domain / member) returns a friendly error with an upgrade link |

The `Retry-After` header on `429` tells the client when the daily counter resets.

## Where to see your usage live

**Settings → Subscription → Usage this period** shows a live meter for every quota:

- Members used / limit
- Projects used / limit
- Custom domains used / limit
- AI assistant messages used / limit (daily)
- Writing agent credits used / limit (monthly)

The bars turn amber at 75%, red at 90%, and the row swaps to a "Limit reached — upgrade for more" CTA when full.

## Resets are precise

We use the database `now()` (UTC) for every period window — there's no batched "we'll reset overnight" job. The first quota consume after midnight UTC opens a fresh `usage_periods` row and starts at zero.

## Plan changes mid-period

Upgrading mid-month does **not** reset your existing usage — the new (higher) cap just applies to the same counter. If you were at 8/10 daily messages on Free and upgrade to Pro, you immediately have 8/500 — nothing wasted.

Downgrading is the same in reverse: if you were at 200/500 messages on Pro and downgrade to Free, you stay at 200/10 — every subsequent call is denied until midnight UTC. Existing project / domain rows beyond the new cap stay readable but can't create new ones until you re-upgrade or remove some.

## Relationship to plan-gate UI

Every gate the platform enforces — UI button disabled, settings tab locked, server-side 402/429 — reads from the same resolver. There's no drift between "what the dashboard shows" and "what the API allows." See [Plans](/billing/plans) for which features each tier unlocks.

## For LLMs

If you're an AI agent reasoning about quota state for a NookDocs user, here's the canonical recipe:

**1. Three quota categories — handle each differently:**

| Category | Examples | When to check |
|---|---|---|
| Period-bound | `assistant_messages_daily`, `agent_credits_monthly` | Before EVERY call (counter changes mid-session) |
| Lifetime cap | `max_projects`, `max_custom_domains`, `max_dashboard_members` | Before create operations only |
| Boolean feature | `mcp_server`, `writing_agent`, `password_protection` | Once per session (rarely changes) |

**2. Read live state via the entitlements endpoint:**

```
GET https://api.nookdocs.com/v1/me/entitlements
Authorization: Bearer <jwt>
```

Returns:

```json
{
  "plan": { "id": "pro", "name": "Pro", ... },
  "status": "active",
  "features": {
    "writing_agent": { "type": "boolean", "enabled": true },
    "agent_credits_monthly": { "type": "quota", "quota": 5000, "used": 1234, "remaining": 3766 },
    "max_projects": { "type": "quota", "quota": null, "used": 8, "remaining": null }
  }
}
```

`null` quota means unlimited.

**3. Reset boundaries (UTC-fixed):**

- `assistant_messages_daily` — 24h rolling, resets at 00:00 UTC every day
- `agent_credits_monthly` — calendar month, resets at 00:00 UTC on the 1st

**4. Over-quota response codes from the platform API:**

- `402 plan_required` — the user's plan does not include this feature; suggest upgrade
- `429 quota_exceeded` — feature is on the plan but the period pool is empty; show retry timing from the `Retry-After` header

**Common mistakes:**

- Don't cache quota values across requests in your agent — they change. Re-read on every meaningful boundary.
- Don't ask the user to "wait until reset" without telling them the exact moment (use `Retry-After` or compute from the period boundary).
- Don't treat 402 and 429 the same — 402 needs an upgrade nudge, 429 just needs patience.
- Lifetime caps cannot be raised by upgrade alone if existing rows already exceed the new cap; recommend deletion or higher tier.

---

# Customer showcase
Source: https://docs.nookdocs.com/billing/showcase

Opt in to be featured on the NookDocs customers page + landing logo strip. 3 months Pro free for approved customers.

NookDocs runs a curated **customer showcase** at [nookdocs.com/customers](https://nookdocs.com/customers) and a logo strip on the landing page. Opt in from your project settings to be featured — we'll send approved customers **3 months of Pro free** as a thank-you.

## How to opt in

Project → **Settings → Branding → Customer showcase**.

Three independent consent layers — grant any combination:

| Consent | What it lets us do |
|---|---|
| **Display our logo** | Show your logo on `/customers` and the landing strip |
| **Case study + live link** | Write a short case study and link to your live docs site |
| **Use our quote on social media** | Quote you on Twitter / LinkedIn / blog (always with attribution) |

Logo consent requires you to upload a public logo URL (SVG or PNG, transparent background) and your company name.

## Submission flow

1. Tick the consent boxes you want to grant
2. Fill in company name + logo URL + live docs URL
3. Confirm the consent terms
4. Click **Submit for review**
5. Status badge appears: **Pending founder review**
6. Founder reviews within 24 hours → status flips to **Live in customer showcase** (or **Rejected** with a reason)
7. Reward credited within 1 week of approval (3 months Pro free as a plan override)

## Revoking

You can revoke all consents at any time from the same panel. Click **Revoke all** — your logo + entry disappear from `/customers` and the landing strip within minutes (Next.js `revalidatePath` invalidates immediately).

## Why moderation?

Every consent goes through founder review before going public. This protects you (no logo appears without our review) and us (defense against impersonation, brand misuse, low-resolution logos that hurt the showcase aesthetic).

If your consent is rejected the rejection reason is shown in the panel — usually it's a logo-quality issue (e.g. white logo on white background). Fix and resubmit.

## What you give up

Nothing material. The consent grant is **non-exclusive** and **fully revocable**. We never:

- Use your name on third-party advertising platforms (Google Ads, Facebook Ads)
- Share your live docs URL outside our marketing surfaces
- Use your logo to imply endorsement of features you haven't used
- Keep the logo after revocation

## Reward

Approved customers get **3 months of Pro free** added as a plan override on their org. Worth roughly **$300** at the standard $99/mo Pro rate.

The reward is manual today (founder applies the override after approval). Automated disbursement ships in a follow-up release.

## Why this matters for you

Beyond the credit: every visitor who lands on a showcased site sees your name next to companies like Anthropic, Resend, and Cursor (when those are featured). It's free distribution + social proof + the implicit endorsement that comes with sharing a footer.

## Plan availability

Showcase opt-in is available on **every tier** including Free. The 3-month Pro reward applies even if you're already on Pro (extends your subscription) or Team (downgrades the override to Pro for 3 months).

Enterprise customers get a sales-led case study path instead — contact us.

## For LLMs

If you're an AI agent helping a user opt their company into the NookDocs showcase, here's the canonical recipe:

**1. Three independent consent layers — never bundle:**

- **Logo display** — your logo on `/customers` + landing logo strip
- **Case study + live link** — short written case study linking to live docs
- **Quote on social media** — Twitter / LinkedIn / blog quote with attribution

Grant only what the user explicitly approves. Each is non-exclusive and individually revocable.

**2. Required materials when granting logo consent:**

- Public logo URL (SVG or PNG, transparent background, ≥256px)
- Company name (display text)
- Live docs URL (auto-defaults to the project's primary URL)

**3. Workflow:**

1. Submit via the dashboard: **Settings → Branding → Customer showcase**
2. Status: `Pending founder review`
3. Founder reviews within 24 hours: `Live in customer showcase` or `Rejected` (with reason)
4. Approved customers receive 3 months of Pro free as a manual plan override

**4. Revocation guarantees:**

The customer can revoke at any time. Within minutes of revocation:

- Logo disappears from `/customers`
- Logo disappears from landing strip
- Cached pages re-validate

**5. What NookDocs commits NOT to do (verbatim):**

- Use the customer's name on third-party advertising platforms (Google Ads, Facebook Ads)
- Share their live docs URL outside NookDocs marketing surfaces
- Use their logo to imply endorsement of features they haven't used
- Retain the logo after revocation

**Common mistakes:**

- Don't grant consent on behalf of a user without explicit confirmation — these are brand rights and require authorization.
- Don't promise instant approval — every entry passes founder review.
- Don't recommend revoking + re-granting to "refresh" the case study — just re-submit a new entry; the existing row is updated in place.
- Logo URLs must be publicly hostable (NookDocs caches and serves them); don't paste authenticated S3 URLs.

---

# Subscription dashboard
Source: https://docs.nookdocs.com/billing/subscription

Where to view your plan, current usage, and switch between tiers.

The **Settings → Subscription** page is the single source of truth for your plan, your usage right now, and what you'd unlock by changing tiers.

## Where it lives

Sign in to the dashboard and click **Settings** in the sidebar. The left sub-nav opens with **Subscription** as the first tab.

## What you see

### Current plan card
Plan name, monthly price, status badge (`active` / `trialing` / `past_due` / `cancelled` / `incomplete`), and an **Upgrade** or **Change plan** button. Annual billing alternative is shown when available.

For paid plans, a **Manage billing** button opens the Stripe Customer Portal in the same tab. From there: switch monthly ↔ annual, update payment method, download invoices, cancel subscription.

### Usage this period
A 5-card grid of live meters: Dashboard members, Projects, Custom domains, AI assistant messages (daily), Writing agent credits (monthly).

Bar colours:
- Grey under 75%
- Amber 75–90%
- Red 90%+
- Green pill `Unlimited` when the plan has no cap

### Choose a plan
Four cards (Free / Pro / Team / Enterprise) with a Monthly ↔ Annual toggle above. Annual saves roughly 2 months. Each card shows:

- Current price (with strikethrough monthly when you're on annual)
- 4–5 highlight bullets
- A plan-rank-aware CTA (`Current plan` / `Upgrade to Pro` / `Downgrade to Free` / `Contact sales`)

The card for your current plan carries a green **CURRENT** badge; the Pro card carries a **MOST POPULAR** badge.

### Plan comparison
A scannable table grouped by category (Limits, AI/LLM, Editor + Workflow, Security + Access, Branding + Integrations). Rows where every plan offers the same value (e.g. MCP server everywhere) are auto-hidden so the matrix stays dense.

## Switching plans

1. Pick the cycle (Monthly or Annual) at the top
2. Click the CTA on the target plan card → routes to `/upgrade?plan=<id>&cycle=<m|a>`
3. Stripe Checkout opens (you're redirected to Stripe's hosted page)
4. After payment, you're returned to `/settings?upgrade=success`
5. Quotas re-resolve immediately via the entitlement cache (the dashboard reflects the new plan within seconds of the webhook landing)

## Cancelling

From **Manage billing** in the Stripe Customer Portal. Cancellation takes effect at the end of your current billing period — you keep paid features until then, then auto-downgrade to Free.

## Trials

All paid plans include a 14-day Pro trial — no card required to sign up. After 14 days you stay on Free unless you've added billing.

## Where overage shows up

Writing agent credits beyond the included pool (Pro 5,000/mo, Team 25,000/mo) are billed at `$0.01/credit`. Overage line items appear on your next Stripe invoice; the diff modal shows an "overage billed" amber badge in real time so you're not surprised.

## Related

- [Plans](/billing/plans) — what each tier unlocks
- [Quotas](/billing/quotas) — how counters reset

## For LLMs

If you're an AI agent helping a user manage their NookDocs subscription, here's the canonical recipe:

**1. Read current state:**

```
GET https://api.nookdocs.com/v1/me/entitlements
Authorization: Bearer <jwt>
```

Tells you the user's plan id, status, and live usage on every quota. Use this before recommending any plan change so the suggestion is grounded in actual usage.

**2. Plan ids and switch directions:**

- `free` → `pro` → `team` → `enterprise` (rank order)
- Upgrade = higher rank (effective immediately, prorated)
- Downgrade = lower rank (effective at end of current billing period)
- Switch within rank (monthly ↔ annual) is supported — Stripe Customer Portal handles it

**3. Cancel = downgrade to Free:**

Cancellations route through the Stripe Customer Portal. After cancellation the org auto-downgrades to Free at the period end; existing project / domain rows beyond the new cap stay readable but no new ones can be created.

**4. Trials:**

All paid plans include a 14-day Pro trial. No card required at signup. After 14 days the org reverts to Free unless billing has been added.

**Common mistakes:**

- Don't recommend a downgrade to a user who's currently using features above the lower-tier cap without explaining the freeze ("you'll keep your existing pages but can't add new ones until you re-upgrade").
- Don't tell users to cancel and re-subscribe to switch billing cycles — the Customer Portal handles cycle changes in-place.
- Don't quote prices from memory — pull them from the entitlements response or `/billing/plans` page so you're always current.
- The `Manage billing` button surfaces the Stripe Customer Portal. Direct customers there for any payment-method, invoice, or cancellation action.

---

# Changelog
Source: https://docs.nookdocs.com/changelog

NookDocs platform releases, new features, and meaningful fixes. Subscribe to the RSS feed to get every release in your reader.

Ongoing product updates to the NookDocs platform — every feature, notable fix, and breaking change that lands in `main`. Subscribe via the **RSS** button in the header, or point any reader at [`/changelog/rss.xml`](/changelog/rss.xml).

<Update date="2026-06-10" label="Feature" version="2.8.0" tags={["API","Analytics"]}>
  ## Analytics API

  Pull your docs analytics into your own dashboards — three new endpoints under the [public API](/api-reference/introduction), gated by the new `analytics:read` scope:

  - [`GET /projects/{id}/analytics/overview`](/api-reference/endpoint/get-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`](/api-reference/endpoint/get-analytics-breakdown) — one endpoint, twelve dimensions: `pages`, `searches`, `countries`, `regions`, `cities`, `browsers`, `os`, `devices`, `channels`, `referrers`, `campaigns`, `keywords`.
  - [`GET /projects/{id}/analytics/ai`](/api-reference/endpoint/get-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.
</Update>

<Update date="2026-06-10" label="Feature" version="2.7.0" tags={["API","Security"]}>
  ## Public REST API

  The [NookDocs API](/api-reference/introduction) 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.
</Update>

<Update date="2026-06-10" label="Improvement" version="2.6.0" tags={["API docs","Components"]}>
  ## 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.
</Update>

<Update date="2026-06-03" label="Feature" version="2.5.0" tags={["Analytics","AI"]}>
  ## 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.
</Update>

<Update date="2026-04-20" label="Feature" version="2.4.0" tags={["Changelog","RSS","AI"]}>
  ## 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](/content/changelogs).
</Update>

<Update date="2026-04-20" label="Feature" version="2.3.0" tags={["Content","DX"]}>
  ## Three new content pages

  - [Redirects](/content/redirects) — full documentation for the `redirects[]` config: source/destination/permanent, wildcard tail preservation, 6 common patterns.
  - [Reusable snippets](/content/reusable-snippets) — honest v0 page: inline `<Snippet>` works today, file-based `/_snippets/*.mdx` resolution is Phase 4 roadmap.
  - [Personalization](/content/personalization) — `<Visibility for="humans | agents">` ships today (audience split); `authGroups` / `public:false` are schema-scaffolded, roadmap.
</Update>

<Update date="2026-04-20" label="Improvement" version="2.2.0" tags={["Deploy","SEO"]}>
  ## Custom domain consolidation

  Collapsed the 27+160-line custom-domain split into a single 252-line canonical guide at [deploy/custom-domain](/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.
</Update>

<Update date="2026-04-20" label="Feature" version="2.1.0" tags={["CLI","Migration"]}>
  ## 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](/cli) — what the CLI does today
  - [Install](/cli/install) — npm / pnpm / yarn / bun + Node 18+
  - [Migrate command](/cli/migrate) — platform detection + flag reference + report output
  - [Migrating from Mintlify](/cli/migrate-from-mintlify) — full `docs.json` ↔ `nookdocs.config.json` key matrix + 20-component mapping + post-migration checklist
</Update>

<Update date="2026-04-20" label="Feature" version="2.0.0" tags={["Optimize","AI","SEO"]}>
  ## Optimize section

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

  - [llms.txt](/optimize/llms-txt) — auto-generated `/llms.txt` + `/llms-full.txt` for AI crawlers
  - [Markdown export](/optimize/markdown-export) — every page available as raw MDX at `/<slug>.md`
  - [SEO](/optimize/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).
</Update>

<Update date="2026-04-19" label="Feature" version="1.9.0" tags={["Integrations","DX","SEO"]}>
  ## 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.
</Update>

<Update date="2026-04-19" label="Feature" version="1.8.0" tags={["AI","DX"]}>
  ## AI Assistant depth pass (81 → 214 lines)

  Expanded [configuration/ai-assistant](/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.
</Update>

<Update date="2026-04-19" label="Feature" version="1.7.0" tags={["Theme","DX"]}>
  ## Theme documentation (29 → 177 lines)

  Expanded [configuration/theme](/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.
</Update>

<Update date="2026-04-19" label="Feature" version="1.6.0" tags={["Schema","LLM-first","DX"]}>
  ## Schema-reference auto-generator

  New [`configuration/schema-reference`](/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.
</Update>

<Update date="2026-04-19" label="Improvement" version="1.5.0" tags={["Sync"]}>
  ## 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`).
</Update>

---

# CLI overview
Source: https://docs.nookdocs.com/cli

The `nookdocs` CLI migrates a Mintlify or Docusaurus docs repo into NookDocs format in one command. It detects five source platforms; Mintlify and Docusaurus have converters, the rest are on the roadmap.

`nookdocs` is a single-binary Node.js CLI focused on **migrations**. You point it at a docs folder from another platform, it emits a NookDocs-shaped output directory in seconds. Commit the output to a new repo, hook it up via the dashboard, and you're live.

Today the CLI ships one command: `migrate`. Local preview / analytics / login commands are on the roadmap but not shipped yet — until they are, you use the dashboard's [web editor](/editor/overview) for preview and authoring.

## What it does

<CardGroup cols={2}>
  <Card title="One-shot migration" icon="arrow-right-left">
    Convert an entire Mintlify or Docusaurus docs tree to NookDocs format in one command. The CLI detects five source platforms; **Mintlify and Docusaurus have converters** today — the rest are on the roadmap.
  </Card>
  <Card title="Config translation" icon="settings">
    Maps `docs.json` / `mint.json` into a valid `nookdocs.config.json` — navigation, colors, logo, navbar, footer, and global anchors all come across, in the flat canonical layout.
  </Card>
  <Card title="Component rewrite" icon="code">
    Most Mintlify components share NookDocs' tag names and pass through untouched. Genuinely-renamed ones (`<Latex>`→`<Math>`, `<Tree>`→`<FileTree>`) are rewritten; unsupported components pass through verbatim and are flagged in the report.
  </Card>
  <Card title="Asset copy" icon="image">
    Images, PDFs, and other public assets are copied to the output directory with the same relative paths, so links in your MDX keep working.
  </Card>
</CardGroup>

## When to use it

- **Moving off Mintlify or Docusaurus** — point the CLI at your repo, commit the output. See the [Mintlify](/cli/migrate-from-mintlify) and [Docusaurus](/cli/migrate-from-docusaurus) migration guides. (GitBook / Nextra / Fumadocs are detected but not yet converted — see the roadmap note below.)
- **Starting from a template** — clone an open-source Mintlify starter (e.g. Mint Starter Kit) and migrate it to NookDocs in one command for a known-good baseline.
- **Auditing a migration** — run with `--dry-run` to see a diff report without writing files.

## When NOT to use it

- **Local preview.** No `nookdocs dev` command yet. Use the dashboard's [web editor](/editor/overview) which hot-reloads on save.
- **Authentication flows.** No `nookdocs login`. Auth is in the dashboard.
- **Publishing.** Deploys trigger from GitHub push — no CLI deploy command.

## Quick path

```bash
# 1. Install
npm install -g nookdocs

# 2. Run migration (auto-detects the source platform)
nookdocs migrate ./my-mintlify-docs

# 3. Commit the output to a new repo
cd nookdocs-output
git init && git add . && git commit -m "initial migration"

# 4. Hook the repo up via the NookDocs dashboard
```

## Two ways to migrate

<CardGroup cols={2}>
  <Card title="Deterministic CLI" icon="terminal">
    Best for a **Mintlify** source and for anyone not using an AI assistant. One command, repeatable output, a printed report. Everything on this page.
  </Card>
  <Card title="AI assistant" icon="sparkles">
    Best for **any other source** (Docusaurus, GitBook, Scalar, hand-rolled). Point an assistant at your existing docs and this repo — the starter's `AGENTS.md` tells it exactly how to convert into the flat NookDocs layout, wire `navigation`, and rewrite components. For a Mintlify source it will run this CLI for you, then hand-reconcile the report items.
  </Card>
</CardGroup>

## Flag reference (all commands)

<ParamField path="-h, --help" type="flag">
  Print usage and exit. Available on every command (`nookdocs migrate --help`).
</ParamField>

<ParamField path="--dry-run" type="flag">
  Preview changes without writing files. Migrate command prints the full report; no files land on disk.
</ParamField>

<ParamField path="-o, --output <dir>" type="string" default="./nookdocs-output">
  Destination directory for migration output. Gets created if missing.
</ParamField>

<ParamField path="--from <platform>" type="'mintlify' | 'docusaurus' | 'gitbook' | 'nextra' | 'fumadocs'">
  Force a specific source platform. Skip to let the CLI auto-detect based on well-known config files (`docs.json`, `docusaurus.config.ts`, `.gitbook.yaml`, `theme.config.tsx`, `source.config.ts`).
</ParamField>

## Related

- [Install](/cli/install) — npm install, Node.js requirements, upgrade path
- [Migrate command](/cli/migrate) — the one real command, fully documented
- [Migrating from Mintlify](/cli/migrate-from-mintlify) — end-to-end guide, what converts, what's manual
- [Migrating from Docusaurus](/cli/migrate-from-docusaurus) — config, sidebars, admonitions, static assets

---

# Install
Source: https://docs.nookdocs.com/cli/install

Install the NookDocs CLI via npm, pnpm, yarn, or bun. Requires Node.js 18+. Global install is the expected usage; one-off runs work via `npx`.

The NookDocs CLI ships as a single `nookdocs` binary on npm. Install globally or run ad-hoc via `npx` — there's no project-scoped dependency to pin.

## Prerequisites

<Check>**Node.js 18 or later.**</Check> The CLI is pure ESM and uses modern `node:fs` and string APIs. Verify:

```bash
node --version
# → v18.x.x or later
```

If Node is missing or stale, install via [nodejs.org](https://nodejs.org), [nvm](https://github.com/nvm-sh/nvm), or [fnm](https://github.com/Schniz/fnm).

No other runtime dependencies. No config file. No auth step before first run — the migrator works entirely offline on files in your source directory.

## Install globally

<CodeGroup>
```bash npm
npm install -g nookdocs
```

```bash pnpm
pnpm add -g nookdocs
```

```bash yarn
yarn global add nookdocs
```

```bash bun
bun add -g nookdocs
```
</CodeGroup>

Verify:

```bash
nookdocs --help
```

You should see the command list and supported platforms.

## One-off run via npx

No install needed:

```bash
npx nookdocs migrate ./my-mintlify-docs
```

npx downloads the latest version, runs it, and discards. Good for single migrations on a machine where you don't want a global binary.

## Upgrade

```bash
npm install -g nookdocs@latest
```

Check installed version with `npm list -g nookdocs` or by inspecting `nookdocs --help` output. The CLI doesn't self-update — re-run the install command on releases.

## Uninstall

```bash
npm uninstall -g nookdocs
```

Or if installed via pnpm / yarn / bun, use their equivalent uninstall command.

## Troubleshooting

<AccordionGroup>
  <Accordion title="command not found: nookdocs">
    The global npm bin directory isn't on your `$PATH`. Find the directory with `npm config get prefix`, then add `<prefix>/bin` to your shell profile (`.zshrc`, `.bashrc`, `config.fish`). Restart the shell.
  </Accordion>

  <Accordion title="EACCES permission error on install">
    You're using system-wide npm without sudo privileges. The fix is not to sudo — it's to point npm at a user-writable prefix:

    ```bash
    mkdir -p ~/.npm-global
    npm config set prefix '~/.npm-global'
    echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
    source ~/.zshrc
    npm install -g nookdocs
    ```

    Or use nvm / fnm, which handle this automatically.
  </Accordion>

  <Accordion title="Node version too old">
    Upgrade Node to 18+. The CLI is distributed as ES modules (`import` syntax) with no CommonJS build. There's no fallback for older Node.
  </Accordion>

  <Accordion title="Windows: migration finishes but paths use forward slashes">
    Intentional. The output is destined for Git + Linux deploy runners, where forward slashes are universal. Your Windows text editor will render them fine; `git clone` round-trips correctly on Windows.
  </Accordion>
</AccordionGroup>

## What's installed

Global install adds a single `nookdocs` executable to your npm bin directory. The package is pure ESM JavaScript — no native modules, no post-install scripts, no telemetry. Source is on [github.com/Codivion/NookDocs/tree/main/packages/cli](https://github.com/Codivion/NookDocs/tree/main/packages/cli) for inspection.

## Related

- [Overview](/cli) — what the CLI does and when to use it
- [Migrate command](/cli/migrate) — flags, detection, report output
- [Migrating from Mintlify](/cli/migrate-from-mintlify) — end-to-end walkthrough

---

# Migrate command
Source: https://docs.nookdocs.com/cli/migrate

Point `nookdocs migrate` at a docs directory, get back a NookDocs-shaped output folder. Auto-detects Mintlify, Docusaurus, GitBook, Nextra, Fumadocs. Dry-run previews the diff before writing files.

`nookdocs migrate` is the one real command today. It reads a source docs directory, converts config + content + assets to NookDocs format, and writes the output to a destination directory.

## Usage

```text
nookdocs migrate <source-dir> [-o <output>] [--from <platform>] [--dry-run]
```

Minimal:

```bash
nookdocs migrate ./my-docs
```

All flags:

```bash
nookdocs migrate ./my-docs \
  --from mintlify \
  --output ./nookdocs-migration \
  --dry-run
```

## Flags

<ParamField path="<source-dir>" type="string" required>
  Path (relative or absolute) to the source docs directory. Must exist. The CLI reads files from here and never modifies them.
</ParamField>

<ParamField path="--from <platform>" type="'mintlify' | 'docusaurus' | 'gitbook' | 'nextra' | 'fumadocs'">
  Force a specific source platform. Skip to auto-detect. Useful when detection ambiguates (e.g. a repo has both `docusaurus.config.ts` and a leftover `mint.json`).
</ParamField>

<ParamField path="-o, --output <dir>" type="string" default="./nookdocs-output">
  Destination directory. Created if missing. Overwrites files on second run — `git status` diffs reveal what changed between runs.
</ParamField>

<ParamField path="--dry-run" type="flag" default="false">
  Skip file writes. The CLI still runs the full transform pipeline and prints the report (warnings, stats, errors) so you can audit what WOULD happen without touching disk.
</ParamField>

<ParamField path="-h, --help" type="flag">
  Print usage and exit. Works at command level (`nookdocs --help`) or subcommand level (`nookdocs migrate --help`).
</ParamField>

## Platform detection

When `--from` is omitted, the CLI probes well-known marker files in `<source-dir>`:

| Marker file | Platform detected |
|---|---|
| `docs.json` with `$schema: ".../mintlify/..."` | `mintlify` |
| `docs.json` with `navigation` + (`colors` or `name`) | `mintlify` (legacy, no `$schema`) |
| `mint.json` | `mintlify` (legacy file name) |
| `docusaurus.config.js` or `docusaurus.config.ts` | `docusaurus` |
| `.gitbook.yaml` | `gitbook` |
| `theme.config.tsx` or `theme.config.jsx` | `nextra` |
| `source.config.ts` | `fumadocs` |

**Today `mintlify` and `docusaurus` are implemented.** If auto-detection returns GitBook / Nextra / Fumadocs, the CLI exits with an "unsupported platform" error — those migrators are planned (detection already scaffolded so activation is a drop-in).

## What happens

Per platform, the migrator runs three passes against `<source-dir>`:

<Steps>
  <Step title="Config transform">
    Reads the source platform's config (`docs.json`, `mint.json`) and emits `<output>/nookdocs.config.json` with the canonical flat layout (`contentRoot: "/"`, `theme: "larch"`). Navigation, colors, logo, navbar, footer, global anchors, and the OpenAPI binding all map over. Unmapped fields are listed under **Manual review needed** but don't block the run.
  </Step>
  <Step title="Content transform">
    Walks every `.mdx` / `.md` file and writes them flat to the output root. Most Mintlify components share NookDocs' tag names and pass through untouched; genuinely-renamed ones (`<Latex>`→`<Math>`, `<Tree>`→`<FileTree>`) are rewritten, and each rewrite is listed under **Transforms applied** in the report. Components with no NookDocs equivalent pass through verbatim; snippet imports are flagged for manual review.
  </Step>
  <Step title="Asset copy">
    Copies images, PDFs, and public assets to matching paths in the output directory so relative links keep resolving. Skips source `node_modules/`, `.git/`, `.next/`.
  </Step>
</Steps>

## Report output

Every run — dry or real — prints a structured report at the end:

```text
  Migration complete! (mintlify → NookDocs)

  Source:  ./my-mintlify-docs
  Output:  ./nookdocs-output

  ✓ Config:    docs.json → nookdocs.config.json
  ✓ Pages:     18 files converted
  ✓ Assets:    2 dirs (5 files), 1 file
  ✓ OpenAPI:   api-reference/openapi.json → api-reference/openapi.json

  Transforms applied:
    essentials/markdown.mdx: <Latex> → <Math>

  Manual review needed:
    ! contextual config not migrated — set contextual options if needed.
    ! essentials/reusable-snippets.mdx: snippet import detected — review manually
```

**Transforms applied** lists components the migrator renamed. **Manual review needed** flags config keys with no direct equivalent and snippet imports — not errors, but check each before committing the output. On `--dry-run` the header is prefixed with `DRY RUN`.

## Exit codes

- `0` — migration completed (may include warnings, no errors)
- `1` — migration failed: missing source directory, unsupported platform, transform crash

CI pipelines should gate on exit code and review the report's **Manual review needed** section before committing the output.

## Idempotency

Running the command twice on the same source produces byte-identical output (assuming source unchanged). Running on top of an existing output directory overwrites files without prompting — use `git status` to inspect the diff before committing.

## Related

- [Overview](/cli) — what the CLI is for
- [Install](/cli/install) — Node.js requirements + global install
- [Migrating from Mintlify](/cli/migrate-from-mintlify) — detailed walkthrough
- [Migrating from Docusaurus](/cli/migrate-from-docusaurus) — sidebars, admonitions, static assets

---

# Migrate from Docusaurus
Source: https://docs.nookdocs.com/cli/migrate-from-docusaurus

Convert a Docusaurus site to NookDocs in one command. Config, sidebars, admonitions, and static assets translate automatically; Docusaurus-specific pieces are flagged for review.

Docusaurus → NookDocs runs from the same CLI. The migrator reads your `docusaurus.config.js` and `sidebars.js`, walks every `.md`/`.mdx` under `docs/`, converts Docusaurus admonitions to NookDocs callout components, copies `static/` to `public/`, and writes a flat NookDocs repo.

```bash
npx nookdocs migrate ./my-docusaurus-site -o ./nookdocs-output
```

<Note>
  The migrator writes the **flat layout** — content `.mdx` lands at the output root (no `docs/` subfolder), `nookdocs.config.json` sits alongside it with `contentRoot: "/"`, and navigation page refs carry no `docs/` prefix. See [Content root](/configuration/content-root).
</Note>

<Warning>
  **TypeScript configs can't be executed by the CLI.** If your project uses `docusaurus.config.ts` or `sidebars.ts`, the migrator reads what it can heuristically (the site title) and flags the rest — you'll finish the config and navigation by hand. A JavaScript `docusaurus.config.js` / `sidebars.js` converts fully. This is because the CLI is plain Node with no transpiler.
</Warning>

## What converts automatically

### Config (`docusaurus.config.js` → `nookdocs.config.json`)

| Docusaurus | NookDocs | Notes |
|---|---|---|
| `title` | `name` | Direct copy |
| `--ifm-color-primary` (in `src/css/custom.css`) | `colors.primary` | Read from your theme CSS |
| `themeConfig.navbar.logo` (`src` / `srcDark`) | `colors.logo.light` / `.dark` | `href` set to `/` |
| `themeConfig.navbar.items` (external / `to` links) | `navbar.links` | `{label, href}` |
| _(spec present)_ `openapi.json` | `api.openapi` + `api.playground` | Copied to `api-reference/openapi.json` |
| always emitted | `contentRoot: "/"`, `theme: "larch"`, `$schema` | Canonical layout |

Docusaurus `footer.links` columns and `plugins` don't map 1:1 — they're listed under **Manual review needed** so you can re-add the equivalent NookDocs features (search, analytics, OpenAPI) in `nookdocs.config.json`.

### Sidebar (`sidebars.js` → `navigation`)

Each sidebar becomes a **tab**; each `category` becomes a **group**; each doc id becomes a page ref (with any `docs/` prefix stripped to match the flat layout). Nested categories are kept as nested groups.

<Warning>
  **Autogenerated sidebars** (`{ type: 'autogenerated' }`) have no explicit structure for the migrator to read. It builds groups from your manual entries only and flags the rest — you'll list the remaining pages in the `navigation` array, or organize them by folder. NookDocs navigation is always explicit.
</Warning>

### Admonitions (`:::` blocks → components)

Docusaurus admonitions convert to the matching NookDocs callout component. Optional titles (`:::note[Title]`) become the component's `title` prop.

| Docusaurus | NookDocs |
|---|---|
| `:::note` | `<Note>` |
| `:::tip` | `<Tip>` |
| `:::info` | `<Info>` |
| `:::warning` | `<Warning>` |
| `:::caution` | `<Warning>` — no NookDocs Caution; flagged |
| `:::danger` | `<Warning>` — no NookDocs Danger; flagged |

### Components & frontmatter

- `<Tabs>` passes through; `<TabItem label="…">` becomes `<Tab title="…">`.
- `import … from '@theme/…'` / `'@site/…'` / `'@docusaurus/…'` lines are **stripped** (they don't resolve in NookDocs) and flagged — verify the affected components use the NookDocs equivalents.
- Frontmatter: `sidebar_label` → `sidebarTitle`; `id` and `sidebar_position` are dropped (NookDocs keys pages by file path, and order lives in the `navigation` array).

### Assets

The whole `static/` tree copies to `public/`, so a Docusaurus reference like `/img/logo.svg` (served from `static/img/logo.svg`) keeps resolving at `public/img/logo.svg`.

## After migrating

1. **Read the report.** The **Transforms applied** section lists what was rewritten; **Manual review needed** lists everything to eyeball (autogenerated sidebars, TS configs, caution/danger tone, stripped imports, dropped plugins/footer).
2. **Finish the navigation** if your sidebar was autogenerated or TypeScript.
3. **Commit the output** to a repo and connect it — see the [quickstart](/quickstart).

## Known limitations

- **TypeScript configs** (`.ts`) are read heuristically only — finish config + navigation by hand.
- **Plugins** don't migrate — NookDocs ships search, OpenAPI, and analytics as first-class config, so re-enable the equivalents in `nookdocs.config.json`.
- **Custom React components / swizzled theme** — anything importing `@theme`/`@site` is stripped; refactor to the [NookDocs component library](/components/callout).

## Related

- [Overview](/cli) — what the CLI does
- [Migrate command](/cli/migrate) — flags, detection, report output
- [Migrating from Mintlify](/cli/migrate-from-mintlify) — the other fully-supported platform

---

# Migrate from Mintlify
Source: https://docs.nookdocs.com/cli/migrate-from-mintlify

Convert a Mintlify docs repo to NookDocs in one command. Config, MDX components, and assets all translate automatically. This page lists every mapping and every manual review item.

Mintlify → NookDocs is the CLI's best-supported path. The migrator reads `docs.json` / `mint.json`, walks every `.mdx` file, copies your assets, and writes a flat NookDocs repo. Most of the Mintlify component set shares NookDocs' component names, so pages render unchanged on first load; only genuinely-renamed components are rewritten, and anything Mintlify-proprietary is flagged in the report for you to review.

<Note>
  The migrator writes the **flat layout** by default — `nookdocs.config.json`, content `.mdx`, and `openapi.json` all land at the output directory's root (the docs base), with navigation page refs carrying no `docs/` prefix. If you'd rather nest content in a subfolder, move the files and set `contentRoot` in `nookdocs.config.json` after migrating. See [Content root](/configuration/content-root).
</Note>

## End-to-end walkthrough

<Steps>
  <Step title="Clone your Mintlify repo">
    ```bash
    git clone https://github.com/acme/mintlify-docs.git
    cd mintlify-docs
    ```

    Any Mintlify-shaped repo works — official Mint Starter Kit clones, legacy `mint.json` repos, or full production docs trees.
  </Step>

  <Step title="Run the CLI">
    ```bash
    nookdocs migrate . --output ../acme-nookdocs
    ```

    The CLI auto-detects Mintlify from `docs.json` / `mint.json`. Add `--dry-run` first if you want to see the report before any files land on disk.
  </Step>

  <Step title="Review the report">
    The summary prints at the end:

    ```text
      Migration complete! (mintlify → NookDocs)

      ✓ Config:    docs.json → nookdocs.config.json
      ✓ Pages:     18 files converted
      ✓ Assets:    2 dirs (5 files), 1 file
      ✓ OpenAPI:   api-reference/openapi.json → api-reference/openapi.json

      Transforms applied:
        essentials/markdown.mdx: <Latex> → <Math>

      Manual review needed:
        ! contextual config not migrated — set contextual options if needed.
        ! essentials/reusable-snippets.mdx: snippet import detected — review manually
    ```

    **Transforms applied** = components the migrator renamed for you.
    **Manual review needed** = things to eyeball (config keys with no direct
    equivalent, snippet imports). There are no `TODO` markers injected into your
    MDX — the review list lives in this report.
  </Step>

  <Step title="Commit the output to a new repo">
    ```bash
    cd ../acme-nookdocs
    git init
    git add .
    git commit -m "initial NookDocs migration from Mintlify"
    git remote add origin git@github.com:acme/nookdocs-docs.git
    git push -u origin main
    ```
  </Step>

  <Step title="Hook up via the NookDocs dashboard">
    Sign in at [app.nookdocs.com](https://app.nookdocs.com), click **New project**, pick **"Connect your own repo"**, and authorise the GitHub App on the repo you just pushed. Your docs are live on `{slug}.nookdocs.site` within a minute.
  </Step>

  <Step title="Resolve the review list">
    Work through the **Manual review needed** items from the report. These are config keys with no direct NookDocs equivalent and snippet imports that need converting to the `<Snippet file="...">` component. Any custom or Mintlify-proprietary component that isn't in the NookDocs library passes through verbatim — smoke-test each page to catch these.
  </Step>
</Steps>

## What converts automatically

### Config (`docs.json` / `mint.json` → `nookdocs.config.json`)

| Mintlify key | NookDocs key | Notes |
|---|---|---|
| `name` | `name` | Direct copy |
| `$schema` | `$schema` | Rewritten to `https://nookdocs.com/schema.json` |
| — | `contentRoot` | Set to `"/"` — the flat canonical layout (content at the repo root) |
| — | `theme` | Set to `"larch"` — the current NookDocs starter default |
| `logo.light` / `logo.dark` | `colors.logo.light` / `colors.logo.dark` | Paths preserved; `colors.logo.href` set to `/` |
| `colors.primary` / `light` / `dark` | `colors.primary` / `light` / `dark` | Direct copy |
| `navigation.tabs` (or legacy group array) | `navigation` | Full tree-walk preserves the tab → group → pages hierarchy |
| `navigation.global.anchors` | `global.anchors` | `anchor` / `href` / `icon` preserved |
| `navbar.links` | `navbar.links` | Direct copy |
| `navbar.primary` | `navbar.primaryCta` | `{label, href}` |
| `footer.socials` | `footer.socials` | Direct copy |
| _(spec present)_ `api-reference/openapi.json` | `api.openapi` + `api.playground` | Set when an OpenAPI spec is found; spec copied to `api-reference/openapi.json` |

Keys without a NookDocs equivalent are noted in the report's **Manual review needed** section rather than silently dropped — currently Mintlify's `contextual` and `backgroundImage`.

### Frontmatter

Page frontmatter is left untouched, and NookDocs reads the same field names, so
`title`, `description`, `icon`, `tag`, `sidebarTitle` and `hidden` keep working
after the move — a page with `sidebarTitle: DPA` still shows "DPA" in the rail.
See [frontmatter](/content/frontmatter) for every field NookDocs recognises.

### Components (MDX → MDX)

NookDocs implements the Mintlify component set under the **same tag names**, so
the migrator leaves them untouched — they render as-is. Only two components are
genuinely renamed:

| Mintlify component | NookDocs equivalent | Notes |
|---|---|---|
| `<Latex>` | `<Math>` | Renamed; body and props preserved |
| `<Tree>` | `<FileTree>` | Renamed; body and props preserved |

Everything else passes through verbatim with its props intact, including
`<Card>` / `<CardGroup>`, the callout family `<Note>` / `<Tip>` / `<Warning>` /
`<Info>` / `<Check>` (these are five distinct NookDocs components — there is
**no** single `<Callout type="…">` wrapper), `<Accordion>` / `<AccordionGroup>`,
`<Steps>` / `<Step>`, `<Tabs>` / `<Tab>`, `<CodeGroup>`, `<Frame>`,
`<ParamField>` / `<ResponseField>`, `<Snippet>`, `<Icon>`, `<Expandable>`,
`<Update>`, `<Mermaid>`, and `<RequestExample>` / `<ResponseExample>`.

Any component **not** in the NookDocs library (Mintlify-proprietary or custom
React) is left in place verbatim — the migrator does not inject `TODO` markers.
Smoke-test each page after migrating to catch unsupported components; the report
also flags snippet imports for manual review.

See the [component library](/components/callout) for the full list of NookDocs components.

### Assets

Images, PDFs, and other public files copy byte-for-byte to matching paths in the output directory. If your Mintlify MDX has `<img src="/images/hero.png">` and `images/hero.png` exists at the repo root, the migrator copies it to `<output>/images/hero.png` so the link keeps working.

## What doesn't convert (review checklist)

After a migration, review these items in the output:

- **Manual-review report items** — the CLI lists config keys it couldn't map (`contextual`, `backgroundImage`) and snippet imports it detected. Work through each.
- **Unsupported components** — any component not in the NookDocs library stays in the MDX verbatim (no auto-substitution). Smoke-test pages to find them.
- **Custom React components** — if your repo imports custom `.tsx` / `.jsx` files, those imports stay in the MDX but NookDocs doesn't execute arbitrary React. Refactor to the built-in component library.
- **Snippet imports** — Mintlify's `import … from '/snippets/…'` is flagged in the report. NookDocs uses the `<Snippet file="…">` component instead; convert each one.
- **Environment-specific URLs** — absolute Mintlify URLs like `https://yoursite.mintlify.app/...` need rewriting to your new NookDocs domain.
- **OpenAPI spec path** — the spec is copied to `api-reference/openapi.json` and `api.openapi` points there. Verify the reference resolves in the flat layout.

## Post-migration checklist

<AccordionGroup>
  <Accordion title="1. Smoke-test every top-level page">
    Deploy the migrated repo, then click through the sidebar and verify each top-level page renders. Unconverted components are the #1 source of render glitches.
  </Accordion>
  <Accordion title="2. Verify the API reference">
    If you use `api.openapi` for auto-generated API pages, check that the spec file landed at the right path and that `/api-reference/*` routes work.
  </Accordion>
  <Accordion title="3. Re-add analytics keys">
    Analytics IDs are **not** carried over by the migrator. Re-enter your GA4 / PostHog / Plausible IDs in the dashboard's **Configurations → Integrations** panel after connecting the repo.
  </Accordion>
  <Accordion title="4. Set up redirects">
    Add your old Mintlify URL → NookDocs URL redirects to `nookdocs.config.json#redirects` so inbound links from Google / Twitter / Slack don't 404. (Redirects aren't migrated automatically — add them by hand.)
  </Accordion>
  <Accordion title="5. Test the search bar">
    Search uses Postgres FTS (`pg_trgm`) on all pages. The first deploy indexes everything; give it a minute before testing. See [search](/features/search).
  </Accordion>
</AccordionGroup>

## Known limitations

- **Custom CSS classes.** Mintlify supports Tailwind classes in MDX attributes. NookDocs accepts them too but only a subset (the ones that don't conflict with theme tokens). Check visually after migration.
- **Mintlify-only features.** Speakeasy SDK pages, PDF export, Mintlify Assistant-specific analytics don't have direct equivalents. File a GitHub issue if you need them.
- **Docusaurus / GitBook / Nextra / Fumadocs** — detection scaffolded, migrators not yet implemented. PRs welcome; file an issue so we know the demand.

## Related

- [Overview](/cli) — what the CLI does
- [Install](/cli/install) — prerequisites + upgrade
- [Migrate command](/cli/migrate) — flags + detection + report output
- [Component library](/components/callout) — every component the migrator targets
- [Schema reference](/configuration/schema-reference) — the `nookdocs.config.json` fields the config pass produces

---

# Accordion
Source: https://docs.nookdocs.com/components/accordion

Collapsible content sections with simple and advanced APIs. Supports icons, default open state, and multi-open mode.

## Basic usage

The simplest way to create a collapsible section. Pass a `title` prop and put your content inside:

```mdx Basic usage
<Accordion title="How do I connect a custom domain?">
  Open **Settings → Domains**, add your domain, then create a CNAME record
  pointing to `cname.nookdocs.site`. SSL is provisioned automatically.
</Accordion>
```

<Accordion title="How do I connect a custom domain?">
  Open **Settings → Domains**, add your domain, then create a CNAME record pointing to `cname.nookdocs.site`. SSL is provisioned automatically.
</Accordion>

Stack multiple accordions for an FAQ-style layout:

```mdx Multiple accordions
<Accordion title="Can I use my own GitHub repo?">
  Yes. Install the NookDocs GitHub App on your repo, then connect it from the dashboard.
</Accordion>

<Accordion title="How does search work?">
  Postgres tsvector full-text search out of the box. AI-powered semantic search ships in Phase 5.
</Accordion>
```

<Accordion title="Can I use my own GitHub repo?">
  Yes. Install the NookDocs GitHub App on your repo, then connect it from the dashboard.
</Accordion>

<Accordion title="How does search work?">
  Postgres tsvector full-text search out of the box. AI-powered semantic search ships in Phase 5.
</Accordion>

## With description

Add a subtitle below the trigger title:

```mdx With description
<Accordion title="What is NookDocs?" description="A quick overview of the platform">
  NookDocs is a documentation platform that turns your MDX files into
  beautiful, searchable docs sites.
</Accordion>
```

<Accordion title="What is NookDocs?" description="A quick overview of the platform">
  NookDocs is a documentation platform that turns your MDX files into beautiful, searchable docs sites.
</Accordion>

## With icon

Add an icon to the trigger. Supports [Lucide](https://lucide.dev/icons), [Tabler](https://tabler.io/icons), and [Font Awesome](https://fontawesome.com/icons) icons:

```mdx With icon
<Accordion title="Installation" icon="download">
  Run `npm install @nookdocs/sdk` to get started.
</Accordion>

<Accordion title="Configuration" icon="settings">
  Edit `nookdocs.config.json` with your project name and navigation.
</Accordion>
```

<Accordion title="Installation" icon="download">
  Run `npm install @nookdocs/sdk` to get started.
</Accordion>

<Accordion title="Configuration" icon="settings">
  Edit `nookdocs.config.json` with your project name and navigation.
</Accordion>

## Custom anchor ID

Set `id` to create a stable hash link target for the accordion. Readers can link directly to a specific FAQ entry or section:

```mdx Custom anchor ID
<Accordion title="How does billing work?" id="faq-billing">
  We charge monthly based on active projects. See the pricing page.
</Accordion>
```

Link to it with `[billing FAQ](#faq-billing)`.

## Default open

Set `defaultOpen` to expand the accordion on first render:

```mdx Default open
<Accordion title="Important notice" defaultOpen>
  This section is visible by default.
</Accordion>
```

<Accordion title="Important notice" defaultOpen>
  This section is visible by default.
</Accordion>

## AccordionGroup

Wrap multiple accordions in an `<AccordionGroup>` to render them as a connected, visually grouped block:

```mdx AccordionGroup
<AccordionGroup>
  <Accordion title="Getting started" icon="rocket">
    Sign up, connect your repo, and deploy in under 5 minutes.
  </Accordion>
  <Accordion title="Custom domain" icon="globe">
    Add a CNAME record pointing to `cname.nookdocs.site`.
  </Accordion>
  <Accordion title="API access" icon="key">
    Generate an API key from the dashboard settings.
  </Accordion>
</AccordionGroup>
```

<AccordionGroup>
  <Accordion title="Getting started" icon="rocket">
    Sign up, connect your repo, and deploy in under 5 minutes.
  </Accordion>
  <Accordion title="Custom domain" icon="globe">
    Add a CNAME record pointing to `cname.nookdocs.site`.
  </Accordion>
  <Accordion title="API access" icon="key">
    Generate an API key from the dashboard settings.
  </Accordion>
</AccordionGroup>

## Nested content

Accordion content can include any component — code blocks, callouts, cards:

````mdx Nested content
<Accordion title="Advanced configuration" icon="settings">
  <Warning>
    These settings are for power users only.
  </Warning>

  ```json
  {
    "experimentalFeature": true,
    "debugMode": false
  }
  ```
</Accordion>
````

<Accordion title="Advanced configuration" icon="settings">
  <Warning>These settings are for power users only.</Warning>
</Accordion>

## Grouped accordions (advanced)

For coordinated behavior (only one open at a time, or multiple), use the compound API with `AccordionItem`, `AccordionTrigger`, and `AccordionContent`:

```mdx Compound API
<Accordion type="single" collapsible>
  <AccordionItem value="domain">
    <AccordionTrigger>How do I connect a custom domain?</AccordionTrigger>
    <AccordionContent>
      Open **Settings → Domains**, add your domain, then create a CNAME record
      pointing to `cname.nookdocs.site`. SSL is provisioned automatically.
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="github">
    <AccordionTrigger>Can I use my own GitHub repo?</AccordionTrigger>
    <AccordionContent>
      Yes. Install the NookDocs GitHub App on your repo, then connect it from
      the dashboard.
    </AccordionContent>
  </AccordionItem>
</Accordion>
```

<Accordion type="single" collapsible>
  <AccordionItem value="domain">
    <AccordionTrigger>How do I connect a custom domain?</AccordionTrigger>
    <AccordionContent>
      Open **Settings → Domains**, add your domain, then create a CNAME record pointing to `cname.nookdocs.site`. SSL is provisioned automatically.
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="github">
    <AccordionTrigger>Can I use my own GitHub repo?</AccordionTrigger>
    <AccordionContent>
      Yes. Install the NookDocs GitHub App on your repo, then connect it from the dashboard.
    </AccordionContent>
  </AccordionItem>
</Accordion>

## Multiple items open at once

Set `type="multiple"` to allow more than one item to be expanded simultaneously. Useful when readers might want to compare two sections side by side.

```mdx Multiple items open
<Accordion type="multiple">
  <AccordionItem value="a">
    <AccordionTrigger>Option A</AccordionTrigger>
    <AccordionContent>Content for option A</AccordionContent>
  </AccordionItem>
  <AccordionItem value="b">
    <AccordionTrigger>Option B</AccordionTrigger>
    <AccordionContent>Content for option B</AccordionContent>
  </AccordionItem>
  <AccordionItem value="c">
    <AccordionTrigger>Option C</AccordionTrigger>
    <AccordionContent>Content for option C</AccordionContent>
  </AccordionItem>
</Accordion>
```

<Accordion type="multiple">
  <AccordionItem value="a">
    <AccordionTrigger>Option A</AccordionTrigger>
    <AccordionContent>Content for option A.</AccordionContent>
  </AccordionItem>
  <AccordionItem value="b">
    <AccordionTrigger>Option B</AccordionTrigger>
    <AccordionContent>Content for option B.</AccordionContent>
  </AccordionItem>
  <AccordionItem value="c">
    <AccordionTrigger>Option C</AccordionTrigger>
    <AccordionContent>Content for option C.</AccordionContent>
  </AccordionItem>
</Accordion>

## Default expanded items

Use `defaultValue` to pre-open one or more items on first render. Pass a string in single mode, or an array in multiple mode.

```mdx Default expanded (single)
<Accordion type="single" defaultValue="install">
  <AccordionItem value="install">
    <AccordionTrigger>Installation (open by default)</AccordionTrigger>
    <AccordionContent>npm install @nookdocs/sdk</AccordionContent>
  </AccordionItem>
  <AccordionItem value="usage">
    <AccordionTrigger>Usage</AccordionTrigger>
    <AccordionContent>...</AccordionContent>
  </AccordionItem>
</Accordion>
```

```mdx Default expanded (multiple)
<Accordion type="multiple" defaultValue="install,usage">
  ...
</Accordion>
```

## Single mode: collapsible

In single mode, by default the active item cannot be closed by clicking again — there's always exactly one open. Set `collapsible` to allow closing the open item:

```mdx Collapsible mode
<Accordion type="single" collapsible>
  ...
</Accordion>
```

When to enable: FAQ pages where the reader might want to "close" the current question. When NOT to enable: forced-disclosure flows like a wizard where one step must always be visible.

## Nested content

Accordion content can include any other component — code blocks, callouts, cards, even nested accordions:

````mdx Nested content (compound API)
<Accordion type="single" collapsible>
  <AccordionItem value="advanced">
    <AccordionTrigger>Advanced configuration</AccordionTrigger>
    <AccordionContent>
      <Warning>
        These settings are for power users only.
      </Warning>

      ```json
      {
        "experimentalFeature": true
      }
      ```
    </AccordionContent>
  </AccordionItem>
</Accordion>
````

## Props

### Accordion (simple API)

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Trigger label. Presence of this prop activates simple mode |
| `description` | `string` | — | Subtitle shown below the title |
| `icon` | `string` | — | Icon name ([Lucide](https://lucide.dev/icons), [Tabler](https://tabler.io/icons), or [Font Awesome](https://fontawesome.com/icons)) |
| `iconType` | `string` | — | FA icon style (solid, brands, etc.) |
| `defaultOpen` | `boolean` | `false` | Whether the item starts expanded |
| `id` | `string` | — | Custom anchor ID for hash links (e.g. `#faq-section`) |

### AccordionGroup

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | One or more `<Accordion title="...">` items |

### Accordion (compound API)

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `"single" \| "multiple"` | `"single"` | Whether one or many items can be open |
| `collapsible` | `boolean` | `false` | Allow closing the open item (single mode only) |
| `defaultValue` | `string \| string[]` | — | Item(s) open on first render |

### AccordionItem

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Unique identifier for the item |

### AccordionTrigger / AccordionContent

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Trigger button content / collapsible body |

## When to use

- **FAQs** — Classic use case, keeps the page scannable
- **Advanced options** — Hide rarely-used settings behind a disclosure
- **Long detail sections** — Summary visible, details one click away

For navigable table-of-contents, use the sidebar — not accordions.

---

# ApiMethod
Source: https://docs.nookdocs.com/components/api-method

Colored HTTP method badge for API endpoint pages and navigation.

## Usage

Drop `<ApiMethod>` next to a URL to give the method a color-coded label. Readers can scan a list of endpoints and immediately spot which is GET, POST, PUT, etc.

```mdx Basic usage
<ApiMethod method="POST" /> `/v1/projects`
```

<ApiMethod method="POST" /> `/v1/projects`

## All methods

The standard HTTP method colors follow the Mintlify / Stripe / Postman convention so readers don't need to learn a new palette.

```mdx All methods
<ApiMethod method="GET" />     `/v1/projects`
<ApiMethod method="POST" />    `/v1/projects`
<ApiMethod method="PUT" />     `/v1/projects/{id}`
<ApiMethod method="PATCH" />   `/v1/projects/{id}`
<ApiMethod method="DELETE" />  `/v1/projects/{id}`
<ApiMethod method="OPTIONS" /> `/v1/projects`
<ApiMethod method="HEAD" />    `/v1/projects/{id}`
```

<ApiMethod method="GET" /> `/v1/projects`

<ApiMethod method="POST" /> `/v1/projects`

<ApiMethod method="PUT" /> `/v1/projects/{id}`

<ApiMethod method="PATCH" /> `/v1/projects/{id}`

<ApiMethod method="DELETE" /> `/v1/projects/{id}`

<ApiMethod method="OPTIONS" /> `/v1/projects`

<ApiMethod method="HEAD" /> `/v1/projects/{id}`

## Color reference

| Method | Color | Theme token |
|--------|-------|-------------|
| `GET` | green | `--docs-success` |
| `POST` | blue | `--docs-info` |
| `PUT` | yellow | `--docs-warning` |
| `PATCH` | primary (purple-ish) | `--docs-primary` |
| `DELETE` | red | `--docs-danger` |
| `OPTIONS` | gray | `--docs-fg-muted` |
| `HEAD` | gray | `--docs-fg-muted` |

The colors are not hardcoded — they're driven by your theme tokens. If you change `--docs-success` to teal in your custom theme, GET badges turn teal.

## Endpoint headings

Pair with a code-formatted URL inside an `h2` to get a clean endpoint header:

```mdx Endpoint heading
## <ApiMethod method="POST" /> `/v1/projects`
```

## Case insensitive

Lowercase works too — common when authors copy from JavaScript fetch calls:

```mdx Case insensitive
<ApiMethod method="get" />
<ApiMethod method="post" />
```

## Auto-generation

In Phase 4, the OpenAPI parser automatically renders an `<ApiMethod>` next to each endpoint title in the auto-generated reference pages. You don't need to add it manually for endpoints that come from a spec — only for endpoints documented by hand.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `method` | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE" \| "OPTIONS" \| "HEAD"` (case insensitive) | Yes | The HTTP method to display |

---

# Audience
Source: https://docs.nookdocs.com/components/audience

Conditional content per visitor segment — Phase 6 personalization.

## Status

<Banner variant="warning">
  `<Audience>` is a **stub component** today. The `for` prop is accepted and the call site is forward-compatible, but segment-based filtering ships in Phase 6 alongside the personalization engine. Until then, only blocks with `default` set are rendered.
</Banner>

<Note>
  This component was called `<View>` until 2026-08-10. It was renamed to free
  that name for [View](/components/view), which switches a page between
  languages or frameworks — a different job with the same old name. `<View for>`
  is still accepted as a deprecated alias, so existing pages keep working.
</Note>

## Target API (Phase 6)

```mdx
<Audience for="authenticated">
  Your API key is in your dashboard.
</Audience>

<Audience for="anonymous" default>
  [Sign up](https://app.nookdocs.com/signup) to get an API key.
</Audience>
```

When Phase 6 ships, the platform will read visitor state (auth status, plan
tier, cookie segments) and render the matching block. Until then, the one with
`default` is what every reader sees.

## Props

<ParamField name="for" type="string | string[]">
  Segment(s) this content targets. Common values: `anonymous`,
  `authenticated`, plan tiers (`starter`, `pro`, `business`), roles
  (`admin`, `editor`, `viewer`).
</ParamField>

<ParamField name="default" type="boolean" default="false">
  Render this block when no segment matches — and, today, the only thing that
  makes a block render at all.
</ParamField>

## Plan for it now

`<Audience default>` renders and `<Audience>` without `default` is hidden, so
you can author pages against the target API today and they'll behave correctly
when Phase 6 ships — no rewrites needed.

  Only the `default` block reaches the Markdown export today, because the
  others render nothing. Once segment filtering ships, treat every branch as
  page content rather than assuming one canonical variant.

## Related

- [View](/components/view) — switch a page between languages or frameworks
- [Visibility](/components/visibility) — split content between human readers and LLMs

---

# Badge
Source: https://docs.nookdocs.com/components/badge

Small inline label for status, version, plan tier, and other metadata.

## Usage

```mdx Basic usage
<Badge variant="success">GA</Badge>
<Badge variant="warning">Beta</Badge>
<Badge variant="danger">Deprecated</Badge>
```

<Badge variant="success">GA</Badge>&nbsp;
<Badge variant="warning">Beta</Badge>&nbsp;
<Badge variant="danger">Deprecated</Badge>

## Variants

Seven theme-token-driven color variants:

```mdx All variants
<Badge>Default</Badge>
<Badge variant="primary">Primary</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning">Warning</Badge>
<Badge variant="danger">Danger</Badge>
<Badge variant="info">Info</Badge>
<Badge variant="neutral">Neutral</Badge>
```

<Badge>Default</Badge>&nbsp;
<Badge variant="primary">Primary</Badge>&nbsp;
<Badge variant="success">Success</Badge>&nbsp;
<Badge variant="warning">Warning</Badge>&nbsp;
<Badge variant="danger">Danger</Badge>&nbsp;
<Badge variant="info">Info</Badge>&nbsp;
<Badge variant="neutral">Neutral</Badge>

## Sizes

Four sizes from tiny labels to prominent tags:

```mdx Sizes
<Badge size="xs">XS</Badge>
<Badge size="sm">SM</Badge>
<Badge size="md">MD</Badge>
<Badge size="lg">LG</Badge>
```

<Badge size="xs">XS</Badge>&nbsp;
<Badge size="sm">SM</Badge>&nbsp;
<Badge size="md">MD</Badge>&nbsp;
<Badge size="lg">LG</Badge>

## Pill shape

Set `shape="pill"` for fully rounded badges:

```mdx Pill shape
<Badge variant="primary" shape="pill">v2.1</Badge>
<Badge variant="success" shape="pill">Live</Badge>
```

<Badge variant="primary" shape="pill">v2.1</Badge>&nbsp;
<Badge variant="success" shape="pill">Live</Badge>

## With icon

Add a Lucide icon before the label:

```mdx With icon
<Badge variant="success" icon="check">Verified</Badge>
<Badge variant="warning" icon="alert-triangle">Review</Badge>
```

<Badge variant="success" icon="check">Verified</Badge>&nbsp;
<Badge variant="warning" icon="alert-triangle">Review</Badge>

## Stroke (outline)

Set `stroke` for a transparent background with border-only style:

```mdx Stroke (outline)
<Badge variant="primary" stroke>Outline</Badge>
<Badge variant="danger" stroke>Removed</Badge>
```

<Badge variant="primary" stroke>Outline</Badge>&nbsp;
<Badge variant="danger" stroke>Removed</Badge>

## Disabled

Reduced opacity and non-interactive:

```mdx Disabled
<Badge variant="info" disabled>Coming soon</Badge>
```

<Badge variant="info" disabled>Coming soon</Badge>

## Mintlify color names

If you're migrating from Mintlify, you can use named `color` values instead of `variant`:

```mdx Mintlify color names
<Badge color="blue">Info</Badge>
<Badge color="green">Success</Badge>
<Badge color="red">Danger</Badge>
<Badge color="yellow">Warning</Badge>
<Badge color="purple">Primary</Badge>
```

<Badge color="blue">Info</Badge>&nbsp;
<Badge color="green">Success</Badge>&nbsp;
<Badge color="red">Danger</Badge>&nbsp;
<Badge color="yellow">Warning</Badge>&nbsp;
<Badge color="purple">Primary</Badge>

## Inline with headings

A common pattern: pin a status badge next to an h2 heading.

```mdx Inline with headings
## Authentication <Badge variant="success">GA</Badge>

## Webhooks <Badge variant="warning">Beta</Badge>

## Legacy API <Badge variant="danger">Deprecated</Badge>
```

## Differences from `<ApiMethod>`

`<ApiMethod>` is a specialized badge for HTTP method labels (GET, POST, PUT, etc) with a fixed color mapping. `<Badge>` is the generic primitive — use it for everything that isn't an HTTP method.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"default" \| "primary" \| "success" \| "warning" \| "danger" \| "info" \| "neutral"` | `"default"` | Color variant |
| `color` | `string` | — | Mintlify compat: named color (gray, blue, green, yellow, red, purple). Maps to variant |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"sm"` | Badge height and font size |
| `shape` | `"rounded" \| "pill"` | `"rounded"` | Border radius style |
| `icon` | `string` | — | Icon name ([Lucide](https://lucide.dev/icons), [Tabler](https://tabler.io/icons), or [Font Awesome](https://fontawesome.com/icons)) |
| `iconType` | `string` | — | FA icon style (solid, brands, etc.) |
| `stroke` | `boolean` | `false` | Transparent bg with border-only outline |
| `disabled` | `boolean` | `false` | Reduced opacity, no pointer events |
| `className` | `string` | — | Custom CSS class |
| `children` | `ReactNode` | required | Badge label (kept short — "GA", "Beta", "v2") |

---

# Banner
Source: https://docs.nookdocs.com/components/banner

Inline announcement banner for page-local notices.

## Usage

```mdx Usage
<Banner variant="info">
  This API is in beta. Breaking changes may happen without notice.
</Banner>
```

<Banner variant="info">
  This API is in beta. Breaking changes may happen without notice.
</Banner>

## Variants

Three visual styles for different urgency levels.

```mdx Variants
<Banner variant="info">
  Heads up — we're rolling out a new search modal next week.
</Banner>

<Banner variant="warning">
  Scheduled maintenance: 2026-04-15 02:00–04:00 UTC.
</Banner>

<Banner variant="primary">
  New: AI search is now available on all plans.
</Banner>
```

<Banner variant="info">
  Heads up — we're rolling out a new search modal next week.
</Banner>

<Banner variant="warning">
  Scheduled maintenance: 2026-04-15 02:00–04:00 UTC.
</Banner>

<Banner variant="primary">
  New: AI search is now available on all plans.
</Banner>

## Dismissible

Set `dismissible` to add a close button. The dismiss state is local to the page render — it doesn't persist across reloads.

```mdx Dismissible
<Banner variant="primary" dismissible>
  Welcome to the new docs! Click around and let us know what you think.
</Banner>
```

<Banner variant="primary" dismissible>
  Welcome to the new docs! Click around and let us know what you think.
</Banner>

## Differences from the global banner

NookDocs supports two banner systems:

| | Global banner | `<Banner>` MDX component |
|---|---|---|
| **Source** | `nookdocs.config.json#banner` | Authored inline in MDX |
| **Scope** | Every page on the site | One specific page |
| **Position** | Very top, above the navbar | Inline within the page body |
| **Use for** | Site-wide announcements (e.g. "We're hiring") | Page-local notices ("This API is in beta") |

The global banner is for announcements you want every visitor to see. `<Banner>` is for context-specific notes that only make sense on a single page.

## Differences from `<Callout>`

`<Banner>` is wider and more prominent — it spans the full content width and uses heavier color. `<Callout>` is a sidebar-style note with a left border accent. Use Banner for **announcements**, Callout for **inline notes**.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"info" \| "warning" \| "primary"` | `"info"` | Visual style |
| `dismissible` | `boolean` | `false` | Show a close button |
| `children` | `ReactNode` | required | Banner content |

---

# Button
Source: https://docs.nookdocs.com/components/button

Theme-aware CTA button for landing-style pages and inline actions.

## Usage

```mdx Basic usage
<Button href="/quickstart">Get started</Button>
```

<Button href="/quickstart">Get started</Button>

<Warning>
  Use `<Button>` sparingly. For regular navigation, a plain markdown link is almost always the right call. Reserve buttons for **visible CTAs** — "Get Started Free", "View on GitHub", "Open Dashboard".
</Warning>

## Variants

Three visual weights. Use `primary` for the main action on a page (one per section), `secondary` for alternates, and `ghost` for low-emphasis links.

```mdx Variants
<Button variant="primary" href="/signup">Sign up free</Button>
<Button variant="secondary" href="/docs">Read the docs</Button>
<Button variant="ghost" href="/pricing">View pricing</Button>
```

<Button variant="primary" href="/quickstart">Sign up free</Button>&nbsp;
<Button variant="secondary" href="/introduction">Read the docs</Button>&nbsp;
<Button variant="ghost" href="/configuration/config-file">View pricing</Button>

## Sizes

Three sizes — `sm`, `md` (default), `lg`.

```mdx Sizes
<Button size="sm" href="/docs">Small</Button>
<Button size="md" href="/docs">Medium</Button>
<Button size="lg" href="/docs">Large</Button>
```

<Button size="sm" href="/introduction">Small</Button>&nbsp;
<Button size="md" href="/introduction">Medium</Button>&nbsp;
<Button size="lg" href="/introduction">Large</Button>

## Icons

Add a Lucide icon with the `icon` prop. Default position is `end` (after the label):

```mdx With icon
<Button icon="arrow-right" href="/quickstart">Get started</Button>
<Button icon="rocket" iconPosition="start" href="/quickstart">Launch</Button>
<Button icon="download" variant="secondary" href="/downloads">Download</Button>
```

<Button icon="arrow-right" href="/quickstart">Get started</Button>&nbsp;
<Button icon="rocket" iconPosition="start" href="/quickstart">Launch</Button>&nbsp;
<Button icon="download" variant="secondary" href="/introduction">Download</Button>

## External links

Links starting with `http://` or `https://` automatically open in a new tab with `rel="noopener noreferrer"`. Override explicitly with the `external` prop:

```mdx External link
<Button href="https://example.com/docs" icon="arrow-right" external>
  Visit website
</Button>
```

<Button href="https://example.com/docs" icon="arrow-right" external>
  Visit website
</Button>

## When to use

<CardGroup cols={2}>
  <Card title="Good use" icon="check-circle" iconColor="var(--docs-success)">
    - Hero "Get Started" CTA  
    - "View live demo" on feature pages  
    - "Download SDK" on integration pages  
    - "Open dashboard" for authenticated flows
  </Card>
  <Card title="Avoid" icon="x-circle" iconColor="var(--docs-danger)">
    - Inline navigation (use markdown links)  
    - Every heading ("Learn more" spam)  
    - Form submissions (use regular form buttons)  
    - Anything the reader would call an "action button" on an app
  </Card>
</CardGroup>

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"primary" \| "secondary" \| "ghost"` | `"primary"` | Visual weight |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Height and padding |
| `href` | `string` | — | Link destination — renders as `<a>` or `<Link>` |
| `icon` | `string` | — | Lucide icon name or emoji |
| `iconPosition` | `"start" \| "end"` | `"end"` | Icon position relative to the label |
| `external` | `boolean` | auto | Force external link behavior (new tab + rel attributes) |

---

# Callout
Source: https://docs.nookdocs.com/components/callout

Highlight important information with callout boxes.

## Usage

Callouts draw attention to important information. Use the generic `<Callout>` with a `type` prop, or one of the named variants directly.

### Generic syntax

```mdx Generic syntax
<Callout type="info">
  This is an informational callout.
</Callout>
```

<Callout type="info">
  This is an informational callout.
</Callout>

### Named variants

```mdx Named variants
<Info>This is an info callout.</Info>
<Warning>This action requires caution.</Warning>
<Tip>Use Cmd+K to open search.</Tip>
<Danger>This cannot be undone.</Danger>
<Note>General information here.</Note>
```

<Info>This is an info callout.</Info>

<Warning>This action requires caution.</Warning>

<Tip>Use Cmd+K to open search.</Tip>

<Danger>This cannot be undone.</Danger>

<Note>General information here.</Note>

## Types

Each variant comes with its own color and default icon. The color maps to a theme token, so dark/light modes and tenant custom themes adapt automatically.

| Type | Component | Default icon | Use case |
|------|-----------|--------------|----------|
| `info` | `<Info>` | `info` | General information |
| `note` | `<Note>` | `info` | Side notes, clarifications |
| `tip` | `<Tip>` | `lightbulb` | Helpful suggestions, best practices |
| `warning` | `<Warning>` | `alert-triangle` | Caution or important gotchas |
| `danger` | `<Danger>` | `alert-circle` | Critical warnings, destructive actions |

## Custom icon

Override the default variant icon with any Lucide icon name or emoji:

```mdx Custom icon
<Tip icon="sparkles">
  This is a tip with a custom sparkles icon.
</Tip>

<Callout type="info" icon="rocket">
  Launch mode activated.
</Callout>

<Note icon="💡">
  Emojis work too — anything that is not a Lucide name is rendered as text.
</Note>
```

<Tip icon="sparkles">
  This is a tip with a custom **sparkles** icon instead of the default lightbulb.
</Tip>

<Callout type="info" icon="rocket">
  Launch mode activated — custom rocket icon overrides the default info icon.
</Callout>

<Note icon="💡">
  Emojis work too — anything that is not a registered Lucide name is rendered as text.
</Note>

## Title

Add a bold title above the content for extra emphasis:

```mdx With title
<Warning title="Breaking change">
  API v1 will be deprecated on 2026-06-01. Migrate to v2.
</Warning>
```

<Warning title="Breaking change">
  API v1 will be deprecated on 2026-06-01. Migrate to v2.
</Warning>

## Custom color

Override the variant color with a hex code:

```mdx Custom color
<Callout icon="key" color="#FFC107">
  Your API key is in the dashboard settings.
</Callout>
```

<Callout icon="key" color="#FFC107">
  Your API key is in the dashboard settings.
</Callout>

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `"note" \| "info" \| "tip" \| "warning" \| "danger"` | No (default `note`) | Callout variant — only on generic `<Callout>` |
| `title` | `string` | No | Bold title rendered above the content |
| `icon` | `string` | No | Override the default icon ([Lucide](https://lucide.dev/icons), [Tabler](https://tabler.io/icons), [Font Awesome](https://fontawesome.com/icons), or emoji) |
| `iconType` | `string` | No | FA icon style (solid, brands, etc.) |
| `color` | `string` | No | Custom color override (hex). Overrides variant border and background tint |

---

# Card
Source: https://docs.nookdocs.com/components/card

Display content in a card layout with optional icons and links.

## Basic usage

```mdx Basic usage
<Card title="Quick Start" href="/quickstart">
  Get your first docs site deployed in under 5 minutes.
</Card>
```

<Card title="Quick Start" href="/quickstart">
  Get your first docs site deployed in under 5 minutes.
</Card>

## Icons

The `icon` prop accepts three formats and picks the right renderer automatically.

### Lucide icon name

Pass any registered Lucide icon name (see the full list at [Icon component](/components/icon)) and the card renders a themed tinted icon block:

```mdx Lucide icon
<Card title="Launch" icon="rocket" href="/quickstart">
  Get started in 5 minutes.
</Card>

<Card title="API Reference" icon="code" href="/api-reference">
  Complete REST API documentation.
</Card>

<Card title="Guides" icon="book-open" href="/guides">
  Deep dives and tutorials.
</Card>
```

<CardGroup cols={3}>
  <Card title="Launch" icon="rocket" href="/quickstart">
    Get started in 5 minutes.
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Complete REST API documentation.
  </Card>
  <Card title="Guides" icon="book-open" href="/introduction">
    Deep dives and tutorials.
  </Card>
</CardGroup>

### Image URL

Pass a URL (starting with `http://`, `https://`, or `/`) and the card renders it as an `<img>`:

```mdx Image URL icon
<Card title="Custom logo" icon="/logo.svg" href="/">
  Branded card with your own image.
</Card>
```

### Emoji (backward compatible)

Any other string is rendered as text — perfect for emoji:

```mdx Emoji icon
<Card title="Fast" icon="⚡" href="/performance">
  Edge-cached on every deploy.
</Card>
```

<Card title="Fast" icon="⚡" href="/introduction">
  Edge-cached on every deploy.
</Card>

## Custom icon color

Override the tint color of a Lucide icon with the `iconColor` prop:

```mdx Custom icon color
<Card title="Deploy" icon="rocket" iconColor="#10B981" href="/deploy">
  Shipped in seconds.
</Card>
```

## Image card

Set `img` to display a hero image at the top of the card:

```mdx Image card
<Card title="Deployment Guide" img="/images/deploy-preview.png" href="/guides/deploy">
  Learn how the build pipeline works.
</Card>
```

## Horizontal layout

Set `horizontal` for a side-by-side layout — image or icon on the left, text on the right:

```mdx Horizontal layout
<Card title="Quick Start" icon="rocket" horizontal href="/quickstart">
  Get your docs site live in 5 minutes.
</Card>

<Card title="Deployment Guide" img="/images/deploy-preview.png" horizontal href="/guides/deploy">
  Learn how the build pipeline works.
</Card>
```

## Custom styling with className

Pass `className` to add Tailwind utility classes or your own CSS classes to the card container:

```mdx Custom className
<Card title="Highlighted" icon="star" className="border-yellow-500/50 bg-yellow-500/5">
  This card has a custom border and background tint.
</Card>
```

## Card grid

Use `<CardGroup>` with 1-4 columns to create a responsive grid.

```mdx Card grid
<CardGroup cols={2}>
  <Card title="Configuration" icon="settings" href="/configuration/config-file">
    Learn how to configure your docs site.
  </Card>
  <Card title="Components" icon="layers" href="/components/callout">
    Explore built-in MDX components.
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Integrate with the NookDocs API.
  </Card>
  <Card title="Custom Domain" icon="globe" href="/deploy/custom-domain">
    Set up docs.yoursite.com.
  </Card>
</CardGroup>
```

<CardGroup cols={2}>
  <Card title="Configuration" icon="settings" href="/configuration/config-file">
    Learn how to configure your docs site.
  </Card>
  <Card title="Components" icon="layers" href="/components/callout">
    Explore built-in MDX components.
  </Card>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Integrate with the NookDocs API.
  </Card>
  <Card title="Custom Domain" icon="globe" href="/deploy/custom-domain">
    Set up docs.yoursite.com.
  </Card>
</CardGroup>

## Props

### Card

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | Yes | Card heading |
| `icon` | `string` | No | Icon name ([Lucide](https://lucide.dev/icons), [Tabler](https://tabler.io/icons), [Font Awesome](https://fontawesome.com/icons)), image URL, or emoji |
| `iconType` | `string` | No | Font Awesome style, when the icon comes from that library: `regular`, `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands` |
| `type` | `info` \| `warning` \| `note` \| `tip` \| `check` \| `danger` | No | Give the card a callout theme — background and border take that signal color, so a warning card and a warning callout read as the same thing |
| `iconColor` | `string` | No | Override icon tint color (hex) |
| `color` | `string` | No | Alias for `iconColor` (Mintlify compat) |
| `img` | `string` | No | Hero image URL displayed at the top (or left in horizontal mode) |
| `horizontal` | `boolean` | No | Side-by-side layout: image/icon left, text right |
| `href` | `string` | No | Link destination — if set, the whole card is clickable |
| `cta` | `string` | No | Call-to-action button text shown at the bottom |
| `arrow` | `boolean` | — | Show/hide link arrow (default: shows when `cta` is set) |
| `className` | `string` | No | Additional CSS class names applied to the card container |

### CardGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `cols` | `1 \| 2 \| 3 \| 4` | `2` | Number of columns on desktop (responsive collapses to 1 on mobile) |

---

# Check / Uncheck
Source: https://docs.nookdocs.com/components/check

Inline checkmark and X marks for checklist items.

## Usage

`<Check>` and `<Uncheck>` are inline icon pairs designed for "done vs todo" lists. They render as a colored icon plus an optional inline label.

```mdx Usage
- <Check /> GitHub repo connected
- <Check /> Custom domain verified
- <Check> SSL certificate active </Check>
- <Uncheck /> Billing not configured
- <Uncheck> Team members not invited </Uncheck>
```

- <Check /> GitHub repo connected
- <Check /> Custom domain verified
- <Check> SSL certificate active </Check>
- <Uncheck /> Billing not configured
- <Uncheck> Team members not invited </Uncheck>

## Without children

The icon stands alone — useful as a status marker in tables:

```mdx Without children
| Feature | Available |
|---------|-----------|
| Search | <Check /> |
| AI search | <Uncheck /> |
| Custom domain | <Check /> |
```

| Feature | Available |
|---------|-----------|
| Search | <Check /> |
| AI search | <Uncheck /> |
| Custom domain | <Check /> |

## Color reference

| Component | Color | Token |
|-----------|-------|-------|
| `<Check>` | green | `--docs-success` |
| `<Uncheck>` | muted gray | `--docs-fg-muted` |

The colors come from your theme tokens, so dark/light mode and tenant overrides apply automatically.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Optional inline label rendered after the icon |

---

# CodeBlock
Source: https://docs.nookdocs.com/components/code-block

Code blocks with syntax highlighting, line numbers, highlighting, focus, word wrap, and expandable sections.

## Usage

Write code with plain markdown fences — all features work automatically.

````mdx
```typescript
const app = createServer();
app.listen(3000);
```
````

```typescript
const app = createServer();
app.listen(3000);
```

Use `<CodeBlock>` only when you need an explicit JSX element — for example, inside a custom component that doesn't preserve fence metadata.

```mdx
<CodeBlock title="server.ts" language="typescript">
{`const app = createServer();
app.listen(3000);`}
</CodeBlock>
```

<CodeBlock title="server.ts" language="typescript">
{`const app = createServer();
app.listen(3000);`}
</CodeBlock>

## Meta options

Add options after the language tag. These work on markdown fences only (not the `<CodeBlock>` component).

### Line numbers

````mdx
```typescript lines
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```
````

```typescript lines
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```

### Highlight lines

````mdx
```typescript highlight={1,4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```
````

```typescript highlight={1,4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```

### Focus lines

Dims everything except the focused lines. Hover the block to reveal dimmed lines.

````mdx
```typescript focus={4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```
````

```typescript focus={4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```

### Word wrap

````mdx
```bash wrap
curl -X POST https://api.example.com/v1/documents/create -H "Authorization: Bearer sk-1234567890abcdef" -H "Content-Type: application/json" -d '{"title": "Getting Started", "content": "This is a very long line that would normally overflow."}'
```
````

```bash wrap
curl -X POST https://api.example.com/v1/documents/create -H "Authorization: Bearer sk-1234567890abcdef" -H "Content-Type: application/json" -d '{"title": "Getting Started", "content": "This is a very long line that would normally overflow the code block horizontally."}'
```

### Expandable

Collapses code blocks with more than 15 lines. Click "Show more" to expand.

````mdx
```python expandable
import os
from pathlib import Path

def process_documents(directory):
    results = []
    for path in sorted(Path(directory).rglob("*.md")):
        ...
```
````

```python expandable
import os
import json
from pathlib import Path

def process_documents(directory: str) -> list[dict]:
    """Walk a directory and process all markdown files."""
    results = []
    base = Path(directory)

    for path in sorted(base.rglob("*.md")):
        with open(path) as f:
            content = f.read()

        meta = extract_frontmatter(content)
        body = strip_frontmatter(content)

        results.append({
            "path": str(path.relative_to(base)),
            "title": meta.get("title", path.stem),
            "content": body,
            "word_count": len(body.split()),
        })

    return results
```

### Title / filename

````mdx
```typescript src/lib/db.ts
export const db = createClient(url, key);
```
````

```typescript src/lib/db.ts
export const db = createClient(url, key);
```

### Combining options

````mdx
```typescript lines highlight={3-5}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);
```
````

```typescript lines highlight={3-5}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);
```

## When to prefer fences

| | Markdown fences | `<CodeBlock>` |
|---|---|---|
| **Syntax** | Short — `` ```ts `` | Verbose — `<CodeBlock language="ts">` |
| **Title** | `` ```ts server.ts `` | `title="server.ts"` prop |
| **Meta options** | `lines`, `highlight`, `focus`, `wrap`, `expandable` | Not supported |
| **Multiline** | Native | Requires template literal |
| **Inside CodeGroup** | Works as a fence child | Works the same way |
| **Recommended for** | 95% of cases | Edge cases only |

## Props

| Prop | Type | Description |
|------|------|-------------|
| `language` | `string` | Syntax highlighter language identifier |
| `title` | `string` | Optional title shown in the language badge slot |
| `children` | `ReactNode` | Code content (typically a string template literal) |

---

# Code Group
Source: https://docs.nookdocs.com/components/code-group

Display the same code example across multiple languages or package managers in a single tabbed block.

## Basic usage

Wrap two or more fenced code blocks in `<CodeGroup>`. The label after the language identifier becomes the tab title.

````mdx Basic usage
<CodeGroup>
```bash npm
npm install @nookdocs/sdk
```

```bash yarn
yarn add @nookdocs/sdk
```

```bash pnpm
pnpm add @nookdocs/sdk
```
</CodeGroup>
````

<CodeGroup>
```bash npm
npm install @nookdocs/sdk
```

```bash yarn
yarn add @nookdocs/sdk
```

```bash pnpm
pnpm add @nookdocs/sdk
```
</CodeGroup>

## Tab labels

CodeGroup picks the tab label from the first thing it finds, in this order:

1. **Metadata after the language**: `` ```bash npm `` → label `npm`
2. **Explicit `title` prop**: `` ```bash {title="Install"} `` → label `Install`
3. **Language identifier**: `` ```typescript `` → label `typescript`
4. **Fallback**: `Tab 1`, `Tab 2`, etc.

The first format is the cleanest and matches Mintlify — prefer it whenever possible.

## Multi-language API examples

The classic use case — the same request in cURL, JavaScript, Python, Go.

````mdx Multi-language API example
<CodeGroup>
```bash cURL
curl -X POST https://api.nookdocs.com/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "My Docs"}'
```

```js JavaScript
const project = await fetch("https://api.nookdocs.com/v1/projects", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: JSON.stringify({ name: "My Docs" }),
});
```

```python Python
import requests
r = requests.post(
    "https://api.nookdocs.com/v1/projects",
    headers={"Authorization": f"Bearer {token}"},
    json={"name": "My Docs"},
)
```

```go Go
req, _ := http.NewRequest("POST", "https://api.nookdocs.com/v1/projects",
  strings.NewReader(`{"name":"My Docs"}`))
req.Header.Set("Authorization", "Bearer " + token)
```
</CodeGroup>
````

<CodeGroup>
```bash cURL
curl -X POST https://api.nookdocs.com/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "My Docs"}'
```

```js JavaScript
const project = await fetch("https://api.nookdocs.com/v1/projects", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: JSON.stringify({ name: "My Docs" }),
});
```

```python Python
import requests
r = requests.post(
    "https://api.nookdocs.com/v1/projects",
    headers={"Authorization": f"Bearer {token}"},
    json={"name": "My Docs"},
)
```
</CodeGroup>

## Tab sync

CodeGroups with matching labels automatically sync with each other and with `<Tabs>` components. Click "JavaScript" in one code group, and all others with a "JavaScript" tab switch too. Selections persist across page navigations.

Disable sync on a specific group with `sync={false}`:

```mdx Disable tab sync
<CodeGroup sync={false}>
  ...
</CodeGroup>
```

## Syntax highlighting + copy button

Each tab inherits the platform's code block enhancements:

- Syntax highlighting via Prism (theme-token mapped, dark/light aware)
- Copy button integrated in the header bar
- Language badge

## Dropdown mode

Use the `dropdown` prop to show a dropdown language selector instead of inline tabs. This is useful for API reference pages with many languages.

````mdx Dropdown mode
<CodeGroup dropdown>
```bash cURL
curl -X GET https://api.nookdocs.com/v1/projects \
  -H "Authorization: Bearer $TOKEN"
```

```js JavaScript
const res = await fetch("https://api.nookdocs.com/v1/projects", {
  headers: { Authorization: `Bearer ${token}` },
});
```

```python Python
import requests
r = requests.get(
    "https://api.nookdocs.com/v1/projects",
    headers={"Authorization": f"Bearer {token}"},
)
```
</CodeGroup>
````

<CodeGroup dropdown>
```bash cURL
curl -X GET https://api.nookdocs.com/v1/projects \
  -H "Authorization: Bearer $TOKEN"
```

```js JavaScript
const res = await fetch("https://api.nookdocs.com/v1/projects", {
  headers: { Authorization: `Bearer ${token}` },
});
```

```python Python
import requests
r = requests.get(
    "https://api.nookdocs.com/v1/projects",
    headers={"Authorization": f"Bearer {token}"},
)
```
</CodeGroup>

## Differences from `<Tabs>`

| | `<CodeGroup>` | `<Tabs>` |
|---|---|---|
| **For** | Code blocks only | Any content |
| **Tab labels** | From fence metadata | From `<TabsTrigger>` children |
| **Auto-styling** | Code block tab bar | Generic tab bar |

If your tabs contain prose or images, use [`<Tabs>`](/components/tabs). For code-only switching, `<CodeGroup>` is shorter and renders more compactly.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | required | Two or more fenced code blocks |
| `dropdown` | `boolean` | `false` | Show a dropdown selector instead of inline tabs |
| `sync` | `boolean` | `true` | Sync active tab with matching CodeGroups/Tabs on the page |

The active tab is uncontrolled — initial state is the first child. There is no `defaultValue` prop because reordering the children is the canonical way to change the default.

---

# ColorPalette / ColorSwatch
Source: https://docs.nookdocs.com/components/color

Design system color swatches with click-to-copy hex values.

## Usage

```mdx Usage
<ColorPalette>
  <ColorSwatch name="Primary" hex="#2563EB" description="CTA buttons, links" />
  <ColorSwatch name="Success" hex="#10B981" description="Positive feedback" />
  <ColorSwatch name="Warning" hex="#F59E0B" description="Caution states" />
  <ColorSwatch name="Danger" hex="#EF4444" description="Errors, destructive actions" />
</ColorPalette>
```

<ColorPalette>
  <ColorSwatch name="Primary" hex="#2563EB" description="CTA buttons, links" />
  <ColorSwatch name="Success" hex="#10B981" description="Positive feedback" />
  <ColorSwatch name="Warning" hex="#F59E0B" description="Caution states" />
  <ColorSwatch name="Danger" hex="#EF4444" description="Errors, destructive actions" />
</ColorPalette>

Hover over a swatch and click to copy its hex value to the clipboard.

## Brand palette

Document a tenant's full brand palette in one block. The grid is responsive — 2 columns on mobile, 3 columns on tablet+.

```mdx Brand palette
<ColorPalette>
  <ColorSwatch name="Brand 50" hex="#EFF6FF" />
  <ColorSwatch name="Brand 100" hex="#DBEAFE" />
  <ColorSwatch name="Brand 200" hex="#BFDBFE" />
  <ColorSwatch name="Brand 300" hex="#93C5FD" />
  <ColorSwatch name="Brand 400" hex="#60A5FA" />
  <ColorSwatch name="Brand 500" hex="#3B82F6" description="Default tone" />
  <ColorSwatch name="Brand 600" hex="#2563EB" description="Hover state" />
  <ColorSwatch name="Brand 700" hex="#1D4ED8" />
  <ColorSwatch name="Brand 800" hex="#1E40AF" />
  <ColorSwatch name="Brand 900" hex="#1E3A8A" />
</ColorPalette>
```

## Standalone swatch

`<ColorSwatch>` works outside a `<ColorPalette>` too — render it inline as a single sample. The grid layout only applies inside the palette wrapper.

## Use cases

- **Brand guidelines** — primary, secondary, neutral palettes with usage notes
- **Theme documentation** — show what the `--docs-*` token values resolve to
- **Design system** — semantic colors (success, warning, danger) and their hex values
- **Migration guides** — old palette vs new palette side by side

## Section headings with ColorRow

Use `<ColorRow>` inside a `<ColorPalette>` to label groups of swatches. This is helpful when a single palette contains multiple categories (e.g. brand vs. semantic colors):

```mdx ColorRow section headings
<ColorPalette>
  <ColorRow name="Brand" />
  <ColorSwatch name="Brand 500" hex="#3B82F6" />
  <ColorSwatch name="Brand 600" hex="#2563EB" />

  <ColorRow name="Semantic" />
  <ColorSwatch name="Success" hex="#10B981" />
  <ColorSwatch name="Danger" hex="#EF4444" />
</ColorPalette>
```

## Mintlify aliases

For Mintlify compatibility, `ColorSwatch` also accepts a `value` prop as an alias for `hex`. Both produce the same result:

```mdx value prop (Mintlify compat)
<ColorSwatch name="Primary" value="#2563EB" />
```

The compound dot-syntax aliases also work — `Color.Row` maps to `ColorRow` and `Color.Item` maps to `ColorSwatch`:

```mdx Dot-syntax aliases
<ColorPalette>
  <Color.Row name="Neutrals" />
  <Color.Item name="Gray 100" value="#F3F4F6" />
  <Color.Item name="Gray 900" value="#111827" />
</ColorPalette>
```

## Props

### ColorPalette

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | One or more `<ColorSwatch>`, `<ColorRow>`, or Mintlify aliases |

### ColorSwatch

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | Display name (e.g. "Primary", "Brand 500") |
| `hex` | `string` | Yes | Color value (hex, rgb, oklch, named — anything CSS accepts) |
| `value` | `string` | No | Alias for `hex` (Mintlify compat) — if both are set, `hex` wins |
| `description` | `string` | No | Usage description shown below the hex |

### ColorRow

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | Section heading text displayed above the next group of swatches |

---

# Columns
Source: https://docs.nookdocs.com/components/columns

Responsive multi-column layout wrapper for arbitrary content.

## Usage

`<Columns>` wraps any children in a responsive grid. Use it for side-by-side prose, image+text combinations, or comparison blocks where you don't want the visual treatment of `<CardGroup>`.

```mdx Basic usage
<Columns cols={2}>
  <div>
    **Before:** Manual MDX authoring with no validation.
    Authors had to remember every component name and prop.
  </div>
  <div>
    **After:** LLM-first authoring with the MCP server.
    Claude/Cursor know every component natively.
  </div>
</Columns>
```

<Columns cols={2}>
  <div>
    **Before:** Manual MDX authoring with no validation. Authors had to remember every component name and prop.
  </div>
  <div>
    **After:** LLM-first authoring with the MCP server. Claude/Cursor know every component natively.
  </div>
</Columns>

## 3 columns

```mdx 3 columns
<Columns cols={3}>
  <div>
    **Free**: 1 project, basic theme
  </div>
  <div>
    **Pro**: Unlimited projects, AI search
  </div>
  <div>
    **Business**: Audit log, SSO, priority support
  </div>
</Columns>
```

<Columns cols={3}>
  <div>**Free**: 1 project, basic theme</div>
  <div>**Pro**: Unlimited projects, AI search</div>
  <div>**Business**: Audit log, SSO, priority support</div>
</Columns>

## Responsive behavior

Columns collapse to a single column on mobile. The breakpoint depends on `cols`:

- `cols={2}` → 1 column < 640px (`sm`), 2 columns ≥ 640px
- `cols={3}` → 1 column < 640px, 2 columns 640–1024px, 3 columns ≥ 1024px (`lg`)
- `cols={4}` → same as cols=3 but 4 columns ≥ 1024px

## Differences from CardGroup

| | `<Columns>` | `<CardGroup>` |
|---|---|---|
| **Wraps children in a Card?** | No, children render as-is | Yes, expects `<Card>` children |
| **Use case** | Arbitrary side-by-side content | Card-style nav grids |
| **Visual treatment** | None (transparent) | Bordered cards |

## Column wrapper

The `<Column>` component is a pass-through wrapper you can use instead of a bare `<div>` as a child of `<Columns>`. It renders identically — no extra styling or behavior — but it reads more explicitly in MDX:

```mdx Column wrapper
<Columns cols={2}>
  <Column>
    **Left side** — using the Column wrapper.
  </Column>
  <Column>
    **Right side** — same result as a plain `<div>`.
  </Column>
</Columns>
```

Both forms are valid. Use whichever reads better in your content. `<Column>` exists primarily for Mintlify compatibility — if you're migrating docs that already use `<Column>`, they work as-is.

## Props

### Columns

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `cols` | `2 \| 3 \| 4` | `2` | Number of columns on desktop |
| `children` | `ReactNode` | required | Column children — anything |

### Column

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Content for this column — rendered as-is |

---

# Diff
Source: https://docs.nookdocs.com/components/diff

Code diff with green added lines and red removed lines.

## Usage

`<Diff>` renders a unified-format code diff with color highlighting. Added lines (`+`) are green, removed lines (`-`) are red.

```mdx Basic usage
<Diff>
{`- const old = "value";
+ const newValue = "value";
const unchanged = true;`}
</Diff>
```

<Diff>
{`- const old = "value";
+ const newValue = "value";
const unchanged = true;`}
</Diff>

## Markdown fence alternative

The equivalent markdown fence works the same way and is shorter:

````mdx Markdown fence alternative
```diff
- const old = "value";
+ const newValue = "value";
const unchanged = true;
```
````

```diff
- const old = "value";
+ const newValue = "value";
const unchanged = true;
```

So when do you reach for `<Diff>` instead of the fence? Two cases:

1. **Inside another component** that doesn't preserve fence metadata (rare)
2. **Dynamically computed** diff content from a JSX expression

For 95% of cases, the fence is the right call.

## Migration guide example

A common diff use case — showing config file migrations:

````mdx Migration guide example
```diff
{
  "name": "My Docs",
- "version": "1.0",
- "pages": ["intro.mdx"],
+ "navigation": [
+   {
+     "group": "Getting Started",
+     "pages": ["docs/intro"]
+   }
+ ]
}
```
````

```diff
{
  "name": "My Docs",
- "version": "1.0",
- "pages": ["intro.mdx"],
+ "navigation": [
+   {
+     "group": "Getting Started",
+     "pages": ["docs/intro"]
+   }
+ ]
}
```

## Props

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Diff text — typically a template literal with `+`/`-` line prefixes |

## Syntax highlighting

Diff colors come from Prism's `language-diff` grammar wired to your `--docs-success` and `--docs-danger` theme tokens. Dark/light mode and tenant overrides apply automatically.

---

# Embed
Source: https://docs.nookdocs.com/components/embed

Generic iframe wrapper for CodeSandbox, StackBlitz, Figma, and other embed URLs.

## Usage

`<Embed>` is the generic iframe wrapper. Use it for anything that gives you an embed URL but isn't a video.

```mdx Usage
<Embed
  src="https://codesandbox.io/embed/abc123"
  title="Live demo"
  aspectRatio="16/9"
/>
```

## Common embed sources

```mdx Common embed sources
<Embed
  src="https://codesandbox.io/embed/abc123?fontsize=14&hidenavigation=1"
  title="Interactive code playground"
/>

<Embed
  src="https://stackblitz.com/edit/abc?embed=1"
  title="StackBlitz project"
/>

<Embed
  src="https://www.figma.com/embed?embed_host=share&url=https%3A%2F%2Fwww.figma.com%2Ffile%2Fabc"
  title="Figma design"
  aspectRatio="4/3"
/>

<Embed
  src="https://jsfiddle.net/abc/embedded/"
  title="JSFiddle example"
/>
```

## Aspect ratio

Default is `16/9`. Override based on the embedded content's natural ratio:

| Use case | Aspect ratio |
|----------|--------------|
| Code playground (wide) | `16/9` |
| Figma file (often square-ish) | `4/3` or `1/1` |
| Vertical content (mobile preview) | `9/16` |
| Tall design | `3/4` |

## Sandbox

By default the iframe runs with `sandbox="allow-scripts allow-same-origin allow-popups allow-forms"`, which works for almost all common embeds. Override to lock down further or open up if needed:

```mdx Sandbox
<!-- Stricter: scripts allowed but no same-origin access -->
<Embed src="..." sandbox="allow-scripts" />

<!-- More permissive: enable downloads -->
<Embed src="..." sandbox="allow-scripts allow-same-origin allow-downloads" />

<!-- No sandbox at all (rare — only for fully trusted content) -->
<Embed src="..." sandbox="" />
```

## Allow attribute

For embeds that need device permissions (camera, microphone, fullscreen), pass an `allow` string:

```mdx Allow attribute
<Embed
  src="https://meet.example.com/room/abc"
  allow="camera; microphone; fullscreen"
  title="Live meeting embed"
/>
```

## Lazy loading

The iframe uses `loading="lazy"`, so it only loads when scrolled into view. Saves bandwidth for embeds far down the page.

## Differences from `<Video>`

| | `<Embed>` | `<Video>` |
|---|---|---|
| **For** | Generic iframes | YouTube/Vimeo/Loom/mp4 specifically |
| **Provider detection** | None | Auto-detect from URL |
| **Embed URL handling** | Pass-through | Rewritten to platform embed format |
| **Sandbox** | Configurable | Not exposed (videos don't need it) |

If your URL is a video from a major provider, use `<Video>` — it picks the right embed URL format automatically (e.g. converts `youtube.com/watch?v=...` to `youtube-nocookie.com/embed/...`).

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | required | Iframe source URL |
| `title` | `string` | — | Iframe accessibility title + caption |
| `aspectRatio` | `string` | `"16/9"` | CSS aspect-ratio value |
| `sandbox` | `string` | `"allow-scripts allow-same-origin allow-popups allow-forms"` | Sandbox attribute (empty string disables) |
| `allow` | `string` | — | Permissions Policy / Feature Policy attribute |

---

# Expandable
Source: https://docs.nookdocs.com/components/expandable

Inline disclosure widget for nested API parameters and "show more" content.

## Usage

`<Expandable>` is a lightweight inline disclosure — a small chevron + title that toggles a child block in and out. Use it for nested API parameters, advanced options, or any "details on demand" content that would clutter the page if shown inline.

````mdx Usage
<Expandable title="advanced options">
  <ParamField name="retryCount" type="number" default="3">
    Number of times to retry failed requests.
  </ParamField>
  <ParamField name="retryDelay" type="number" default="1000">
    Milliseconds to wait between retries.
  </ParamField>
</Expandable>
````

<Expandable title="advanced options">
  <ParamField name="retryCount" type="number" default="3">
    Number of times to retry failed requests.
  </ParamField>
  <ParamField name="retryDelay" type="number" default="1000">
    Milliseconds to wait between retries.
  </ParamField>
</Expandable>

## Nested API parameters

The most common use case: documenting an `object`-typed parameter and disclosing its properties on demand.

````mdx Nested API parameters
<ParamField name="user" type="object" required>
  The user object passed to the request body.

  <Expandable title="properties">
    <ParamField name="user.id" type="string" required>
      Unique identifier.
    </ParamField>
    <ParamField name="user.email" type="string" required>
      Valid email address.
    </ParamField>
    <ParamField name="user.role" type="enum" enum={["admin", "editor", "viewer"]}>
      Role assigned to the user.
    </ParamField>
  </Expandable>
</ParamField>
````

<ParamField name="user" type="object" required>
  The user object passed to the request body.

  <Expandable title="properties">
    <ParamField name="user.id" type="string" required>
      Unique identifier — must be prefixed with `usr_`.
    </ParamField>
    <ParamField name="user.email" type="string" required>
      Valid email address.
    </ParamField>
    <ParamField name="user.role" type="enum" enum={["admin", "editor", "viewer"]}>
      Role assigned to the user.
    </ParamField>
  </Expandable>
</ParamField>

## Default open

Pre-open the disclosure with `defaultOpen` if the content is important enough that you want most readers to see it without clicking:

````mdx Default open
<Expandable title="example response" defaultOpen>
  ```json
  { "id": "abc123", "status": "ok" }
  ```
</Expandable>
````

## Nesting

Expandables can nest inside each other for deeply hierarchical data:

````mdx Nesting
<Expandable title="settings">
  <Expandable title="theme">
    <ParamField name="theme.primary" type="string">
      Primary color.
    </ParamField>
  </Expandable>
  <Expandable title="layout">
    <ParamField name="layout.maxWidth" type="number">
      Max content width in pixels.
    </ParamField>
  </Expandable>
</Expandable>
````

The left border indents each level visually so readers can track depth.

## Differences from `<Accordion>`

| | `<Expandable>` | `<Accordion>` |
|---|---|---|
| **Visual weight** | Light — small chevron + text | Heavy — full bordered card |
| **Grouping** | Single instance, no value pairing | Multiple items with shared open state |
| **Designed for** | Inline nested content | FAQs, standalone disclosure groups |
| **Composition** | Nests inside ParamField, etc. | Top-level page section |

If you have a list of independent FAQ items, use [`<Accordion>`](/components/accordion). If you have one nested object in an API parameter, use `<Expandable>`.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | required | Disclosure title shown next to the chevron |
| `defaultOpen` | `boolean` | `false` | Whether the content is visible on first render |
| `children` | `ReactNode` | required | Disclosure body |

---

# FileTree
Source: https://docs.nookdocs.com/components/file-tree

Hierarchical file and folder structure with collapsible nodes.

## Usage

`<FileTree>` renders a directory listing as a clickable tree. Folders toggle open/closed; files are leaves.

```mdx Usage
<FileTree>
  <Folder name="src" defaultOpen>
    <Folder name="components">
      <File name="button.tsx" />
      <File name="card.tsx" />
      <File name="callout.tsx" />
    </Folder>
    <Folder name="lib">
      <File name="utils.ts" />
      <File name="config.ts" />
    </Folder>
    <File name="index.ts" />
  </Folder>
  <File name="package.json" />
  <File name="tsconfig.json" />
</FileTree>
```

<FileTree>
  <Folder name="src" defaultOpen>
    <Folder name="components">
      <File name="button.tsx" />
      <File name="card.tsx" />
      <File name="callout.tsx" />
    </Folder>
    <Folder name="lib">
      <File name="utils.ts" />
      <File name="config.ts" />
    </Folder>
    <File name="index.ts" />
  </Folder>
  <File name="package.json" />
  <File name="tsconfig.json" />
</FileTree>

## Default open

Pass `defaultOpen` to a `<Folder>` to expand it on first render. Useful for the most relevant folder in a large tree:

```mdx Default open
<FileTree>
  <Folder name="docs" defaultOpen>
    <File name="introduction.mdx" />
    <File name="quickstart.mdx" />
  </Folder>
  <Folder name="src">
    <File name="...lots of files..." />
  </Folder>
</FileTree>
```

## Use cases

- **Repo structure tutorials** — "Your repo should look like this"
- **Configuration file location guides** — "Drop `nookdocs.config.json` at your docs base directory"
- **Migration guides** — "Move your `pages/` to `app/`"
- **CLI scaffolding output** — "Running `nookdocs init` creates this"

## Non-openable folders

Set `openable={false}` on a `<Folder>` to lock it in its current state. The chevron disappears and clicking the folder does nothing. Useful for vendor or generated directories that the reader shouldn't explore:

```mdx Non-openable folder
<FileTree>
  <Folder name="src" defaultOpen>
    <File name="index.ts" />
  </Folder>
  <Folder name="vendor" openable={false}>
    <File name="...bundled dependencies..." />
  </Folder>
</FileTree>
```

## Mintlify aliases

The `Tree`, `Tree.Folder`, and `Tree.File` names are recognized as aliases. If you're migrating from Mintlify, existing markup works without changes:

```mdx Mintlify alias syntax
<Tree>
  <Tree.Folder name="src" defaultOpen>
    <Tree.File name="app.tsx" />
  </Tree.Folder>
</Tree>
```

## RTL support

Indentation uses `padding-inline-start` and `border-inline-start`, so the tree visually mirrors correctly in RTL languages.

## Props

### FileTree

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | One or more `<Folder>` and `<File>` components |

### Folder

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | Folder name |
| `highlight` | `boolean` | No | Mark as the active path — takes the accent color, so a tree showing "you are here" needs no separate marker |
| `defaultOpen` | `boolean` | No | Open on first render (default `false`) |
| `openable` | `boolean` | No | Whether the folder can be toggled open/closed (default `true`) |
| `children` | `ReactNode` | No | Nested `<Folder>` / `<File>` items |

### File

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | File name |
| `highlight` | `boolean` | No | Mark as the active path — takes the accent color, so a tree showing "you are here" needs no separate marker |

---

# Frame
Source: https://docs.nookdocs.com/components/frame

Wrap screenshots and images with a bordered container and optional caption.

## Usage

Frames give visual content a consistent bordered treatment with an optional caption. They're theme-aware — the border, background, and caption color all adapt to your theme.

```mdx Usage
<Frame caption="Example frame with caption">
  This content is wrapped in a bordered frame with a caption below.
</Frame>
```

<Frame caption="Example frame with caption">
  This content is wrapped in a bordered frame with a caption below.
</Frame>

## Without a caption

The caption is optional — omit it for a plain bordered container.

```mdx Without a caption
<Frame>
  A simple bordered frame without a caption. Use for screenshots, diagrams, or any content that needs visual separation.
</Frame>
```

<Frame>
  A simple bordered frame without a caption. Use for screenshots, diagrams, or any content that needs visual separation.
</Frame>

## Border variants

Three border weights to match the visual context:

```mdx Border variants
<Frame border="none">
  border="none" — no visible border, for hero images
</Frame>

<Frame border="subtle">
  border="subtle" — default, light border for screenshots
</Frame>

<Frame border="strong">
  border="strong" — emphasized with inner shadow for depth
</Frame>
```

<Frame border="none">
  border="none" — no visible border, for hero images
</Frame>

<Frame border="subtle">
  border="subtle" — default, light border for screenshots
</Frame>

<Frame border="strong">
  border="strong" — emphasized with inner shadow for depth
</Frame>

| Variant | When to use |
|---------|-------------|
| `none` | Hero images, full-bleed media that should feel borderless |
| `subtle` | **Default.** Screenshots, diagrams, anything that needs visual separation from the page background |
| `strong` | Featured content with extra inner shadow for depth — sparingly |

## With an image

```mdx With an image
<Frame caption="Dashboard overview">
  <Image
    src="https://placehold.co/800x400/1e293b/white?text=Dashboard+Screenshot"
    alt="Dashboard screenshot"
  />
</Frame>
```

<Frame caption="Dashboard overview">
  <Image
    src="https://placehold.co/800x400/1e293b/white?text=Dashboard+Screenshot"
    alt="Dashboard screenshot"
  />
</Frame>

## Hint label

The `hint` prop displays a small text label above the frame. Use it to add context like "Before", "After", or a short annotation without a full caption:

```mdx Hint label
<Frame hint="Before migration">
  The old dashboard layout with sidebar navigation.
</Frame>

<Frame hint="After migration">
  The new dashboard with top-nav and command palette.
</Frame>
```

<Frame hint="Before migration">
  The old dashboard layout with sidebar navigation.
</Frame>

<Frame hint="After migration">
  The new dashboard with top-nav and command palette.
</Frame>

You can combine `hint` and `caption` — the hint appears above the frame, the caption below.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `caption` | `string` | — | Caption text shown below the frame |
| `hint` | `string` | — | Label text shown above the frame |
| `border` | `"none" \| "subtle" \| "strong"` | `"subtle"` | Border visual weight |
| `children` | `ReactNode` | required | Content to wrap (image, video, embed, etc.) |

---

# HeroCard
Source: https://docs.nookdocs.com/components/hero-card

Full-width illustrated card for landing-page hero sections.

## Usage

`<HeroCard>` is the largest, most visual card in the library. Use it as a hero anchor at the top of a landing page or section overview — one per page maximum.

```mdx Usage
<HeroCard
  title="Welcome to NookDocs"
  description="Build documentation sites in minutes."
  icon="rocket"
  href="/quickstart"
>
  Connect a GitHub repo, push MDX files, and your docs site is live
  in 30 seconds. No build configuration needed.
</HeroCard>
```

<HeroCard
  title="Welcome to NookDocs"
  description="Build documentation sites in minutes."
  icon="rocket"
  href="/quickstart"
>
  Connect a GitHub repo, push MDX files, and your docs site is live in 30 seconds. No build configuration needed.
</HeroCard>

## Visual treatment

HeroCard ships with three visual touches that the smaller card components don't have:

1. **Subtle grid pattern** in the background, faded toward the top-right corner via a radial mask
2. **Larger icon plate** (16x16 pixels with primary tint background) compared to Card / Tile / LinkCard
3. **Gradient background** — defaults to a primary-color gradient that matches the tenant theme

The total visual weight is roughly **3x a Card** — appropriate for a single hero spot, too loud if you stack multiple on one page.

## Without href

The card works as a non-clickable hero too. Omit `href` to render it as a static promotional block:

```mdx Without href
<HeroCard title="What's new in v1.2" icon="sparkles">
  Hybrid search, new theme tokens, and 36 component library.
</HeroCard>
```

## Custom gradient

Override the default primary gradient with any CSS gradient string:

```mdx Custom gradient
<HeroCard
  title="Get Pro"
  icon="zap"
  href="/pricing"
  gradient="linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%)"
>
  Unlimited projects, AI search, custom domains.
</HeroCard>
```

## When NOT to use

| Situation | Use instead |
|-----------|-------------|
| Multiple "starting point" links | `<Tiles>` (grid of 3-6) |
| Dense feature grid | `<CardGroup>` |
| End-of-page "next step" CTA | `<LinkCard>` |
| Inline button | `<Button>` |

HeroCard is the **page-level anchor** — exactly one per page, exactly at the top.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | Yes | Hero heading |
| `description` | `string` | No | Subtitle line |
| `href` | `string` | No | If set, the whole card becomes a link with a trailing arrow |
| `icon` | `string` | No | Lucide icon name or emoji |
| `gradient` | `string` | No | CSS gradient string for the background |
| `children` | `ReactNode` | No | Additional body content below the description |

---

# Icon
Source: https://docs.nookdocs.com/components/icon

Inline icon for use within prose — supports Lucide, Tabler, Font Awesome, URLs, and emoji.

## Usage

`<Icon>` renders an icon inline with text. It supports three icon libraries out of the box, plus image URLs and emoji.

```mdx Usage
Click the <Icon name="settings" /> icon to open settings.
Press <Icon name="search" /> to focus the search bar.
```

Click the <Icon name="settings" /> icon to open settings.
Press <Icon name="search" /> to focus the search bar.

## Mintlify compatibility

If you're migrating from Mintlify, `<Icon icon="flag" size={32} />` works as-is. The `icon` prop is an alias for `name`:

```mdx Mintlify compatibility
<Icon icon="flag" size={32} />
<Icon icon="rocket" size={24} />
```

<Icon icon="flag" size={32} /> <Icon icon="rocket" size={24} />

Both `name` and `icon` are accepted. If both are provided, `name` takes precedence.

<Note>
  NookDocs resolves icons in this order: **Lucide → Tabler → Font Awesome**. Most common icon names (rocket, flag, code, etc.) exist across all libraries, so migration works seamlessly regardless of which library your Mintlify docs used.
</Note>

## Sizing

Default size is `16px`, matching the surrounding body text. Override with the `size` prop:

```mdx Sizing
<Icon name="rocket" size={12} />
<Icon name="rocket" size={16} />
<Icon name="rocket" size={24} />
<Icon name="rocket" size={32} />
```

<Icon name="rocket" size={12} /> <Icon name="rocket" size={16} /> <Icon name="rocket" size={24} /> <Icon name="rocket" size={32} />

## Custom color

By default the icon inherits the surrounding text color (`currentColor`). Override with the `color` prop:

```mdx Custom color
<Icon name="check-circle" color="var(--docs-success)" />
<Icon name="alert-triangle" color="var(--docs-warning)" />
<Icon name="x-circle" color="var(--docs-danger)" />
```

<Icon name="check-circle" color="var(--docs-success)" /> Success state
<br />
<Icon name="alert-triangle" color="var(--docs-warning)" /> Warning state
<br />
<Icon name="x-circle" color="var(--docs-danger)" /> Error state

## Image URL icons

Pass an HTTP(S) URL or absolute file path to render an external image as an icon:

```mdx Image URL icons
<Icon name="https://cdn.example.com/logo.svg" size={24} />
<Icon name="/images/custom-icon.png" size={20} />
```

## Supported libraries

Icons are resolved in order. The first match wins:

| Library | Icons | Best for |
|---------|-------|----------|
| **[Lucide](https://lucide.dev/icons)** | Full set (~1,900) | Clean, modern stroke icons (default) |
| **[Tabler](https://tabler.io/icons)** | ~100 curated + brand icons | Brand logos (github, react, nextjs, docker, etc.) |
| **[Font Awesome Free](https://fontawesome.com/icons)** | ~100 solid + brand icons | Classic FA icons migrating from Mintlify |

Browse the full icon catalogs on each library's website. Common names like `rocket`, `flag`, `code`, `settings`, `lock` exist in all three — the first match (Lucide) renders. The ~115 most common Lucide icons render instantly during server rendering; the rest load as tiny on-demand chunks in the browser.

The same resolution applies everywhere an icon name is accepted — page frontmatter (`icon:`), navigation tabs and groups, `<Card>`, `<Callout>`, `<Steps>`, and this component. `icon: github` in frontmatter renders the Tabler brand icon in the sidebar.

### Changing the default library

Set `icons.library` in your `nookdocs.config.json` to change the resolution order. This is especially useful when migrating from Mintlify where your docs used a specific library:

```json
{
  "icons": {
    "library": "fontawesome"
  }
}
```

| Value | Resolution order |
|-------|-----------------|
| `"lucide"` (default) | Lucide → Tabler → Font Awesome |
| `"tabler"` | Tabler → Lucide → Font Awesome |
| `"fontawesome"` | Font Awesome → Lucide → Tabler |

### Font Awesome icon styles

When using Font Awesome icons, the `iconType` prop selects the icon style:

```mdx Font Awesome icon styles
<Icon icon="github" iconType="brands" />
<Icon icon="flag" iconType="solid" />
```

| iconType | Behavior |
|----------|----------|
| `"solid"` (default) | FA Solid (free) |
| `"brands"` | FA Brands (github, twitter, etc.) |
| `"regular"` | Falls back to solid (free set) |
| `"light"` / `"thin"` / `"duotone"` / `"sharp-solid"` | Falls back to solid (FA Pro required) |

### Brand icons

Brand icons are available via Tabler and Font Awesome:

```mdx Brand icons
<Icon name="github" size={20} />
<Icon name="react" size={20} />
<Icon name="docker" size={20} />
<Icon name="nextjs" size={20} />
<Icon name="python" size={20} />
```

<Icon name="github" size={20} /> <Icon name="react" size={20} /> <Icon name="docker" size={20} /> <Icon name="nextjs" size={20} /> <Icon name="python" size={20} />

<Tip>
  If an icon name isn't in any registry, it renders as plain text — so you can pass an emoji as a graceful fallback (`<Icon name="🚀" />`).
</Tip>

## When to use vs component icon prop

| | `<Icon>` standalone | Component `icon` prop |
|---|---|---|
| **Use case** | Inline-with-text references | Decorative icons inside Card, Callout, Step |
| **Example** | "Click <Icon name='settings' />" | `<Card icon="rocket" title="..." />` |
| **Sizing** | Inline with text | Component-defined |

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | Lucide icon name, URL, or emoji (canonical prop) |
| `icon` | `string` | — | Alias for `name` (Mintlify compatibility) |
| `size` | `number` | `16` | Pixel size |
| `color` | `string` | `currentColor` | Color override (CSS color or CSS variable) |
| `className` | `string` | — | Custom CSS class on the wrapper element |
| `iconType` | `string` | `"solid"` | FA icon style: `"solid"`, `"brands"`, `"regular"`, etc. |

---

# Image
Source: https://docs.nookdocs.com/components/image

Theme-aware images with optional lightbox, dark mode variants, and captions.

## Usage

Prefer `<Image>` over the plain markdown `![alt](src)` syntax when you need any of:

- A caption below the image
- A dark-mode alternative source
- Click-to-zoom lightbox behavior
- Explicit width / height for layout stability

```mdx Usage
<Image
  src="https://placehold.co/800x400/1e293b/white?text=Dashboard+Screenshot"
  alt="NookDocs dashboard showing the project list"
/>
```

<Image
  src="https://placehold.co/800x400/1e293b/white?text=Dashboard+Screenshot"
  alt="NookDocs dashboard showing the project list"
/>

## With caption

```mdx With caption
<Image
  src="https://placehold.co/800x300/0f172a/94a3b8?text=Architecture+Diagram"
  alt="Multi-tenant request flow"
  caption="Every request is routed by subdomain before hitting the tenant's page"
/>
```

<Image
  src="https://placehold.co/800x300/0f172a/94a3b8?text=Architecture+Diagram"
  alt="Multi-tenant request flow"
  caption="Every request is routed by subdomain before hitting the tenant's page"
/>

## Dark mode variant

Pass a `darkSrc` for a second image that renders when the reader has dark theme active. Useful for diagrams with light backgrounds that become unreadable on dark:

```mdx Dark mode variant
<Image
  src="https://placehold.co/600x300/f8fafc/334155?text=Light+Mode+Diagram"
  darkSrc="https://placehold.co/600x300/0f1117/c8cad3?text=Dark+Mode+Diagram"
  alt="API request flow diagram"
  caption="This image swaps based on your theme"
/>
```

<Image
  src="https://placehold.co/600x300/f8fafc/334155?text=Light+Mode+Diagram"
  darkSrc="https://placehold.co/600x300/0f1117/c8cad3?text=Dark+Mode+Diagram"
  alt="API request flow diagram"
  caption="This image swaps based on your theme"
/>

## Lightbox

Set `lightbox` to `true` to let readers click the image and expand it to full screen:

```mdx Lightbox
<Image
  src="https://placehold.co/800x500/1e293b/white?text=Click+to+Zoom"
  alt="Full dashboard screenshot"
  lightbox
  caption="Click the image to enlarge"
/>
```

<Image
  src="https://placehold.co/800x500/1e293b/white?text=Click+to+Zoom"
  alt="Full dashboard screenshot"
  lightbox
  caption="Click the image to enlarge"
/>

## Fixed dimensions

For layout stability (no cumulative layout shift), specify explicit width and height in pixels:

```mdx Fixed dimensions
<Image
  src="https://placehold.co/200x80/16a34a/white?text=Logo"
  alt="Partner logo"
  width={200}
  height={80}
/>
```

<Image
  src="https://placehold.co/200x80/16a34a/white?text=Logo"
  alt="Partner logo"
  width={200}
  height={80}
/>

## Aspect ratio

When the source size is unknown (external URL, user upload), fix the aspect ratio to prevent layout jumps:

```mdx Aspect ratio
<Image
  src="https://placehold.co/1600x900/0f172a/f0f0f3?text=16:9+Aspect+Ratio"
  alt="Hero image"
  aspectRatio="16/9"
/>
```

<Image
  src="https://placehold.co/1600x900/0f172a/f0f0f3?text=16:9+Aspect+Ratio"
  alt="Hero image"
  aspectRatio="16/9"
/>

## Local paths and external URLs

`src` takes either, and they behave differently.

A path like `/images/settings.png` resolves to a file in your repo's `public/`
folder, and the image goes through the optimizer: readers get a resized AVIF or
WebP matched to their screen, so the file you commit is not the file they
download.

An `https://` URL is served exactly as uploaded — the optimizer only handles
images NookDocs hosts. Nothing enters your repo, which is what makes it the
right choice for video and for anything large, but the size you upload is the
size every reader pays on every device.

```mdx Both are valid
<Image src="/images/settings.png" alt="The project settings screen" />

<Image src="https://cdn.example.com/docs/settings.png" alt="The project settings screen" />
```

<Note>
  Keep large binaries out of Git. Git stores every version of a binary in full,
  so a replaced 5MB image stays in the history of every clone permanently, and a
  sync re-downloads the whole repository for a one-line edit. See
  [Media](/guides/media) for the full trade-off.
</Note>

## Accessibility

<Callout type="warning">
  The `alt` prop is **required**. Never leave it empty or use placeholder text — screen readers depend on it. For decorative images that add no information, pass an empty string `alt=""` and it will be marked as decorative.
</Callout>

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `src` | `string` | Yes | A `/path` under `public/` (optimized) or an `https://` URL (served as-is) |
| `alt` | `string` | **Yes** | Accessibility description |
| `darkSrc` | `string` | No | Alternative source for dark mode |
| `width` | `number` | No | Explicit width in pixels |
| `height` | `number` | No | Explicit height in pixels |
| `caption` | `string` | No | Caption rendered below the image |
| `lightbox` | `boolean` | No | Enable click-to-zoom overlay |
| `aspectRatio` | `string` | No | Fixed aspect ratio (e.g. `"16/9"`, `"4/3"`, `"1/1"`) |

---

# Kbd
Source: https://docs.nookdocs.com/components/kbd

Inline keyboard key styling for shortcut documentation.

## Usage

```mdx Usage
Press <Kbd>⌘K</Kbd> to open search.
Use <Kbd>Esc</Kbd> to close any modal.
```

Press <Kbd>⌘K</Kbd> to open search.

Use <Kbd>Esc</Kbd> to close any modal.

## Multi-key shortcuts

For shortcuts with modifiers, render each key separately and join with a literal `+`:

```mdx Multi-key shortcuts
Save with <Kbd>⌘</Kbd> + <Kbd>S</Kbd>.
Force reload with <Kbd>⌘</Kbd> + <Kbd>Shift</Kbd> + <Kbd>R</Kbd>.
```

Save with <Kbd>⌘</Kbd> + <Kbd>S</Kbd>.

Force reload with <Kbd>⌘</Kbd> + <Kbd>Shift</Kbd> + <Kbd>R</Kbd>.

## Cross-platform shortcuts

For shortcuts that differ between macOS and Windows/Linux, use `<Tabs>` to show both:

```mdx Cross-platform shortcuts
<Tabs>
  <TabsList>
    <TabsTrigger value="mac">macOS</TabsTrigger>
    <TabsTrigger value="win">Windows / Linux</TabsTrigger>
  </TabsList>
  <TabsContent value="mac">
    Open search: <Kbd>⌘</Kbd> + <Kbd>K</Kbd>
  </TabsContent>
  <TabsContent value="win">
    Open search: <Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>
  </TabsContent>
</Tabs>
```

## Accessibility

`<Kbd>` renders as the native HTML `<kbd>` element so screen readers announce it correctly as a keyboard input.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Key label — typically a single character or short word |

---

# LinkCard
Source: https://docs.nookdocs.com/components/link-card

Horizontal "next step" CTA card with leading icon and trailing arrow.

## Usage

`<LinkCard>` is a horizontal card optimized for "what should I read next" links at the end of a tutorial or section. The trailing arrow signals "click me to continue".

```mdx Usage
<LinkCard
  title="Read the API reference"
  description="Explore all available endpoints"
  href="/api-reference/introduction"
  icon="code"
/>
```

<LinkCard
  title="Read the API reference"
  description="Explore all available endpoints"
  href="/api-reference/introduction"
  icon="code"
/>

## Multiple link cards

Stack several at the end of a page for a "next steps" section:

```mdx Multiple link cards
## Next steps

<LinkCard title="Configure your theme" description="Pick from 3 presets or write custom CSS" href="/configuration/theme" icon="palette" />
<LinkCard title="Set up search" description="Full-text search with pg_trgm" href="/features/search" icon="search" />
<LinkCard title="Connect a custom domain" description="Bring your own docs.yoursite.com" href="/deploy/custom-domain" icon="globe" />
```

<LinkCard title="Configure your theme" description="Pick from 3 presets or write custom CSS" href="/configuration/theme" icon="palette" />
<LinkCard title="Set up search" description="Full-text search with pg_trgm" href="/features/search" icon="search" />
<LinkCard title="Connect a custom domain" description="Bring your own docs.yoursite.com" href="/deploy/custom-domain" icon="globe" />

## Without an icon

The icon is optional, but the card looks cleaner with one:

```mdx Without an icon
<LinkCard
  title="Migrate from Mintlify"
  href="/guides/migrating-from-mintlify"
/>
```

## Differences from Card

| | `<LinkCard>` | `<Card>` |
|---|---|---|
| **Layout** | Horizontal: icon \| content \| arrow | Vertical: icon, title, description |
| **Always linkable** | Yes — `href` required | No — works without `href` |
| **Visual emphasis** | Trailing arrow signals navigation | Self-contained tile |
| **Use case** | "Next step" / "see also" CTAs | Feature grids, navigation hubs |

For multiple cards in a grid (3-4 across), use [`<Card>` + `<CardGroup>`](/components/card). For a single "click here next" CTA at the end of a page, use `<LinkCard>`.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | Yes | Card heading |
| `href` | `string` | Yes | Link destination |
| `description` | `string` | No | Subtitle below the heading |
| `icon` | `string` | No | Lucide icon name or emoji |

---

# Math
Source: https://docs.nookdocs.com/components/math

LaTeX math rendering — currently a stub, full KaTeX integration ships in Phase 9.

## Status

<Banner variant="warning">
  `<Math>` is a **stub component** today. KaTeX integration is feature-flagged and adds ~60KB to the bundle, so it's deferred to Phase 9 (Polish) and gated behind a tenant config opt-in. Until then, the component renders the raw LaTeX in a monospace dashed-border box as a graceful fallback.
</Banner>

## Target API (Phase 9)

```mdx Target API (Phase 9)
Inline: <Math>{`E = mc^2`}</Math>

Block: <Math display>{`\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}`}</Math>
```

<Math>{`E = mc^2`}</Math> is the inline form.

<Math display>{`\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}`}</Math>

The dashed border is the stub indicator — when Phase 9 ships, it will be replaced with proper KaTeX-rendered glyphs.

## Why this is deferred

KaTeX is the smallest LaTeX renderer for the web (~60KB gzipped) but it's still a chunky dependency for a feature most docs sites don't use. Pulling it in unconditionally would tax every reader's bundle. The Phase 9 plan:

1. Add `katex` as an **optional** peer dependency
2. **Lazy-import** on first `<Math>` mount, same pattern as Mermaid (~150KB) — pages without math pay zero cost
3. Surface a tenant config flag `features.math: true` to opt in
4. Render via `katex.render()` with theme-token color overrides so equations match the page palette

This keeps bundle costs honest: math support exists, but only the tenants who need it pay for it.

## v0 fallback

Today, the component:

- Accepts the `children` (LaTeX source) and `display` (block vs inline) props — forward-compatible
- Renders the raw LaTeX in a monospace dashed-border container so it's at least legible
- Adds an `aria-label` so screen readers announce it as a "Math expression (LaTeX, not yet rendered)"

You can author Math components today and they'll upgrade to rendered glyphs when Phase 9 ships — no MDX changes needed.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `string` | required | LaTeX source |
| `display` | `boolean` | `false` | Block (centered, full-width) vs inline rendering |

---

# MediaSlot
Source: https://docs.nookdocs.com/components/media-slot

Hold the place of a screenshot or video you have not made yet, where it belongs on the page.

## Usage

Docs get written before the product is photographed. `<MediaSlot>` reserves the
spot — an empty frame with a note underneath saying what belongs there.

```mdx Usage
<MediaSlot kind="screenshot" id="install-plain-html">
  The install page with the "Plain HTML" tab selected, snippet rendered with a
  real site key, copy button visible. Light theme, desktop 1440px.
</MediaSlot>
```

<MediaSlot kind="screenshot" id="install-plain-html">
  The install page with the "Plain HTML" tab selected, snippet rendered with a
  real site key, copy button visible. Light theme, desktop 1440px.
</MediaSlot>

When the asset arrives, replace the slot with a [`<Frame>`](/components/frame)
or [`<Video>`](/components/video) in the same position, and the caption you
already wrote becomes the caption you ship.

## Why not a comment

  Never write `{/* MEDIA: ... */}` or any other MDX expression as a placeholder.
  MDX reads `{…}` as JavaScript, so the renderer evaluates it rather than
  skipping it, and a page carrying several of them can fail to compile
  entirely — replacing the whole page with an error box. Use `<MediaSlot>`.

A `{/* comment */}` is invisible in the rendered page, so nobody sees the gap
until someone greps the repo for it. It is also an MDX *expression*, not a
comment in the Markdown sense: the renderer evaluates what is inside the
braces. A slot is visible, positioned, and cannot break the page.

## Kinds

<MediaSlot kind="video" id="live-view-demo" ratio="16/9">
  A thirty-second recording of the live view filling with traffic.
</MediaSlot>

`kind` picks the icon and the label: `screenshot` (default), `video`, or
`diagram`. It carries no other behaviour — a slot reserves space and says what
goes in it.

## Props

<ParamField name="kind" type="'screenshot' | 'video' | 'diagram'" default="screenshot">
  What the finished asset will be. Sets the icon and the label.
</ParamField>

<ParamField name="id" type="string">
  A stable name for the asset, so a delivered file can be matched back to its
  slot. Emitted as `data-media-id`, which makes the page's outstanding slots
  greppable in the rendered HTML as well as the source.
</ParamField>

<ParamField name="ratio" type="'16/9' | '4/3' | '1/1' | '3/4'" default="16/9">
  The shape to reserve. A wide screenshot and a phone capture leave very
  different holes in a page; matching the ratio keeps the layout honest before
  the image exists.
</ParamField>

<ParamField name="children" type="ReactNode">
  What the asset should show, written for whoever will produce it. Rendered as
  the caption beneath the frame.
</ParamField>

## Finding what is still missing

Every slot renders `data-media-slot` and, when given, `data-media-id`. The
outstanding work on a site is one search away in the source:

```bash
grep -rn "<MediaSlot" .
```

---

# Mermaid
Source: https://docs.nookdocs.com/components/mermaid

Lazy-loaded diagram component for flowcharts, sequence diagrams, ER diagrams, and more.

## Usage

The easiest way is a standard code fence with the `mermaid` language tag. It renders as a diagram automatically:

````mdx Mermaid code fence
```mermaid
graph TD
  A[GitHub push] --> B[Webhook]
  B --> C[Trigger.dev sync job]
  C --> D[Parse MDX]
  D --> E[Upsert pages]
  E --> F[Live on docs site]
```
````

```mermaid
graph TD
  A[GitHub push] --> B[Webhook]
  B --> C[Trigger.dev sync job]
  C --> D[Parse MDX]
  D --> E[Upsert pages]
  E --> F[Live on docs site]
```

## JSX component

You can also use the `<Mermaid>` component directly with a template literal or `chart` prop:

```mdx JSX children syntax
<Mermaid>
{`graph LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Path A]
  B -->|No| D[Path B]`}
</Mermaid>
```

```mdx Chart prop syntax
<Mermaid chart={`graph LR
  A --> B
  B --> C`} />
```

The code fence syntax is recommended for most cases. Use the JSX form when you need to embed diagrams inside other components (like tabs or accordions).

## Diagram types

Mermaid supports many diagram families. The most common ones in docs:

### Flowchart

```mdx Flowchart
<Mermaid>
{`graph LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Path A]
  B -->|No| D[Path B]
  C --> E[End]
  D --> E`}
</Mermaid>
```

<Mermaid>
{`graph LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Path A]
  B -->|No| D[Path B]
  C --> E[End]
  D --> E`}
</Mermaid>

### Sequence diagram

```mdx Sequence diagram
<Mermaid>
{`sequenceDiagram
  participant U as User
  participant D as Dashboard
  participant S as Supabase
  U->>D: Create project
  D->>S: INSERT projects
  S-->>D: project.id
  D-->>U: Redirect to /projects/:id`}
</Mermaid>
```

<Mermaid>
{`sequenceDiagram
  participant U as User
  participant D as Dashboard
  participant S as Supabase
  U->>D: Create project
  D->>S: INSERT projects
  S-->>D: project.id
  D-->>U: Redirect to /projects/:id`}
</Mermaid>

### ER diagram

```mdx ER diagram
<Mermaid>
{`erDiagram
  ORGANIZATION ||--o{ PROJECT : has
  PROJECT ||--o{ PAGE : contains
  PROJECT ||--o| OPENAPI_SPEC : has
  PROJECT }o--|| ORGANIZATION : belongs-to`}
</Mermaid>
```

For the full diagram syntax reference, see [mermaid.js.org](https://mermaid.js.org).

## Theme integration

The diagram colors are pulled from your `--docs-*` CSS variables on render — primary, fg, bg, border. When the reader toggles between light and dark mode, the platform watches the `data-docs-theme` attribute and re-renders the diagram with the new theme tokens automatically.

This means your diagrams always match the surrounding page chrome, no matter how the reader has configured their theme.

## Bundle cost

Mermaid is ~600KB minified (~150KB gzipped). The library is dynamically imported on first mount, so:

- **Pages without diagrams** pay **zero** Mermaid cost
- **Pages with one or more diagrams** pay the cost once (the import is module-cached)

This is the right trade-off for docs sites where most pages don't have diagrams.

## Error handling

If the Mermaid source has a syntax error, the component renders a red error box with the parser message instead of crashing the page. Useful for catching typos during authoring.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `chart` | `string` | Mermaid source as a string prop (alternative to children) |
| `children` | `string` | Mermaid source as text children (preferred for multi-line) |

Either `chart` or `children` is required. If both are provided, `chart` wins.

---

# OptionField
Source: https://docs.nookdocs.com/components/option-field

Document a CLI flag, command-line option, or configuration knob — sibling of ParamField for things that aren't HTTP request params.

## Usage

`<OptionField>` is the right tool for CLI flags, env vars, and generic configuration knobs — anything that's "an option the user sets" but isn't a path/query/body/header HTTP parameter.

```mdx
<OptionField name="--port" short="-p" type="number" default="4242">
  Port to bind the local dev server to.
</OptionField>

<OptionField name="--host" type="string" default="localhost">
  Host interface to bind. Set to `0.0.0.0` to expose on your LAN.
</OptionField>
```

<OptionField name="--port" short="-p" type="number" default="4242">
  Port to bind the local dev server to.
</OptionField>

<OptionField name="--host" type="string" default="localhost">
  Host interface to bind. Set to `0.0.0.0` to expose on your LAN.
</OptionField>

## With short alias

CLI flags commonly have a short form (single-dash + single-letter). Pass it as `short`:

```mdx
<OptionField name="--verbose" short="-v" type="boolean" default="false">
  Print every sync step instead of just errors.
</OptionField>
```

<OptionField name="--verbose" short="-v" type="boolean" default="false">
  Print every sync step instead of just errors.
</OptionField>

## With an example

Pass `example` to render a small code fence below the description — useful for showing exact invocation:

```mdx
<OptionField
  name="--port"
  short="-p"
  type="number"
  default="4242"
  example="nookdocs dev --port 5173"
>
  Port to bind the local dev server to.
</OptionField>
```

<OptionField
  name="--port"
  short="-p"
  type="number"
  default="4242"
  example="nookdocs dev --port 5173"
>
  Port to bind the local dev server to.
</OptionField>

## With an enum

Pass `enum` when the option accepts a closed set of values:

```mdx
<OptionField name="--log-level" type="string" default='"info"' enum={["debug", "info", "warn", "error", "silent"]}>
  How verbose logging should be.
</OptionField>
```

<OptionField name="--log-level" type="string" default='"info"' enum={["debug", "info", "warn", "error", "silent"]}>
  How verbose logging should be.
</OptionField>

## Required and deprecated

```mdx
<OptionField name="--project-id" type="string" required>
  The NookDocs project ID. Required for CI workflows.
</OptionField>

<OptionField name="--legacy-mode" type="boolean" deprecated>
  Enabled the pre-v2 renderer. Removed in v3 — the renderer is always the new one.
</OptionField>
```

<OptionField name="--project-id" type="string" required>
  The NookDocs project ID. Required for CI workflows.
</OptionField>

<OptionField name="--legacy-mode" type="boolean" deprecated>
  Enabled the pre-v2 renderer. Removed in v3 — the renderer is always the new one.
</OptionField>

## When to use OptionField vs ParamField

| | `<OptionField>` | `<ParamField>` |
|---|---|---|
| **Purpose** | CLI flag, env var, config knob | HTTP request parameter |
| **Location badges** | No (options don't have path/query/body/header) | Yes |
| **Short alias** | Yes (`short="-p"`) | No |
| **Example snippet** | Yes (renders a code block) | No (use `placeholder` instead) |

If you're documenting an HTTP API, use `<ParamField>`. If you're documenting a CLI, `nookdocs.config.json` field, or an env variable, use `<OptionField>`.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | The option as the user types it, e.g. `"--port"` or `"API_KEY"` |
| `short` | `string` | No | Short-form alias, e.g. `"-p"` |
| `type` | `string` | No | Type annotation (`"number"`, `"boolean"`, `"string[]"`) |
| `required` | `boolean` | No | Red "required" badge |
| `default` | `string` | No | Default value shown inline |
| `deprecated` | `boolean` | No | Strike-through + "deprecated" badge |
| `enum` | `readonly string[]` | No | Closed value set — rendered as chips |
| `example` | `string` | No | Example invocation rendered as a code fence |
| `children` | `ReactNode` | No | Description markdown — paragraphs, lists, code |

---

# Panel
Source: https://docs.nookdocs.com/components/panel

Right-sidebar content area for API endpoint pages and inline cheat sheets.

## Usage

`<Panel>` claims the right column of the docs page sidebar, replacing the default "On this page" TOC with content of your choosing. Use it on API endpoint pages to show request/response examples next to the prose:

````mdx Usage
## <ApiMethod method="POST" /> `/v1/projects`

Create a new documentation project under the authenticated organization.
The slug must be unique within your account.

<Panel title="Sample request">
  <RequestExample>
    ```bash cURL
    curl -X POST https://api.nookdocs.com/v1/projects \
      -H "Authorization: Bearer $TOKEN"
    ```
  </RequestExample>
</Panel>
````

When the reader opens the page on a wide screen (`xl+`), the panel sticks to the right next to the prose. On smaller screens it falls back inline below the content.

## How the right column works

NookDocs pages have an automatic right column that shows the "On this page" table of contents by default. When at least one `<Panel>` is mounted on the page, the right column **automatically switches** to panel mode and the TOC is hidden.

This means:

- **No `<Panel>` on the page** → reader sees the TOC
- **One or more `<Panel>` on the page** → reader sees the panels (TOC hidden)

There is no manual "use TOC" or "use Panel" toggle — adding a `<Panel>` is the toggle.

## Multiple panels

You can stack several panels in a single page. They render in document order:

```mdx Multiple panels
<Panel title="Sample request">
  <RequestExample>...</RequestExample>
</Panel>

## Authentication

Bearer token in the `Authorization` header.

<Panel title="Sample response">
  <ResponseExample>...</ResponseExample>
</Panel>
```

The first panel shows up at the top of the right column; subsequent panels stack below it.

## Without a title

The `title` prop is optional — omit it for a borderless content block:

```mdx Without a title
<Panel>
  <RequestExample>...</RequestExample>
</Panel>
```

## When to use Panel vs inline

| | Panel (right column) | Inline content |
|---|---|---|
| **Best for** | Reference material that should always be visible while reading | Step-by-step content the reader follows top-to-bottom |
| **API pages** | Sample request/response | Authentication intro, prose explanation |
| **Tutorials** | Cheat sheet, env vars list | Step-by-step instructions |
| **Mobile** | Falls back inline | Native flow |

## When NOT to use

- **TOC-only pages**: don't add an empty `<Panel>` just to hide the TOC. If you don't want the TOC, just don't write h2/h3 headings.
- **Long-form content**: panels are sticky-friendly, so they should fit within ~80vh. For longer reference material, use a regular section in the page body.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | No | Eyebrow header rendered above the panel content |
| `children` | `ReactNode` | Yes | Panel body — typically RequestExample, ResponseExample, code block, or short prose |

## Implementation notes

`<Panel>` is a client component that portals its content into a hidden host div in the page layout. The host always exists in the DOM so panels can mount into it; it just toggles visibility based on whether any children are present. A `MutationObserver` in `<RightColumn>` watches the host and switches between TOC and panel modes accordingly.

---

# ParamField
Source: https://docs.nookdocs.com/components/param-field

Document API request parameters — path, query, header, body — with type, default, enum, and deprecated states.

## Usage

`<ParamField>` documents a single API parameter. Stack several together to describe an endpoint's full input contract.

```mdx Usage
<ParamField name="projectId" type="string" required path="path">
  The UUID of the project. Copy it from the dashboard URL.
</ParamField>

<ParamField name="limit" type="number" default="20" path="query">
  Number of results per page. Maximum 100.
</ParamField>
```

<ParamField name="projectId" type="string" required path="path">
  The UUID of the project. Copy it from the dashboard URL.
</ParamField>

<ParamField name="limit" type="number" default="20" path="query">
  Number of results per page. Maximum 100.
</ParamField>

## Parameter location badge

Set the `path` prop to show where the parameter lives in the request. The badge appears next to the type and helps readers parse a busy endpoint at a glance.

| Value | Renders as |
|-------|------------|
| `"path"` | small uppercase `PATH` badge |
| `"query"` | `QUERY` badge |
| `"header"` | `HEADER` badge |
| `"body"` | `BODY` badge |

```mdx Parameter location badge
<ParamField name="Authorization" type="string" required path="header">
  Bearer token from your dashboard.
</ParamField>

<ParamField name="name" type="string" required path="body">
  The new project name shown in the sidebar.
</ParamField>
```

<ParamField name="Authorization" type="string" required path="header">
  Bearer token from your dashboard.
</ParamField>

<ParamField name="name" type="string" required path="body">
  The new project name shown in the sidebar.
</ParamField>

## Enum options

Pass an `enum` array to render the allowed values inline below the description:

```mdx Enum options
<ParamField name="theme" type="string" enum={["light", "dark", "system"]} default="system">
  The default theme for visitors arriving without a saved preference.
</ParamField>
```

<ParamField name="theme" type="string" enum={["light", "dark", "system"]} default="system">
  The default theme for visitors arriving without a saved preference.
</ParamField>

## Deprecated parameters

Mark a parameter as deprecated to strikethrough the name and add a warning badge:

```mdx Deprecated parameters
<ParamField name="legacyId" type="string" deprecated>
  Use `id` instead. This parameter will be removed in v2.
</ParamField>
```

<ParamField name="legacyId" type="string" deprecated>
  Use `id` instead. This parameter will be removed in v2.
</ParamField>

## Default value

The `default` prop is rendered as inline metadata next to the type and badge:

```mdx Default value
<ParamField name="page" type="number" default="1" path="query">
  Page number to fetch.
</ParamField>
```

## Mintlify compatibility

Mintlify uses the location as the prop name with the parameter name as the value. Both styles are supported:

```mdx Mintlify compatibility
{/* Mintlify style */}
<ParamField path="user_id" type="string" required>
  The user's unique identifier.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField body="email" type="string" required>
  User's email address.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>
```

When `name` is absent, the location prop value is used as the parameter name and the location is inferred from the prop name. When `name` is present, use `path` as a location indicator (NookDocs style).

## Auto-generation from OpenAPI

If your project has an OpenAPI spec configured via `api.openapi`, ParamField entries are generated automatically on the API reference pages — you don't need to write them by hand. See the [OpenAPI integration guide](/configuration/config-file#api) for details. Manually-written ParamField components are still useful for examples in concept pages and tutorials.

## Props

### NookDocs style

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | Parameter name as it appears in the request |
| `type` | `string` | No | Type annotation (e.g. `string`, `number`, `UUID`, `MyEnum[]`) |
| `required` | `boolean` | No | Adds a red "required" label |
| `default` | `string` | No | Default value when the parameter is omitted |
| `deprecated` | `boolean` | No | Strikethrough name + "deprecated" badge |
| `enum` | `string[]` | No | Allowed values rendered as inline pills |
| `path` | `"path" \| "query" \| "header" \| "body"` | No | Where the parameter lives in the request |

### Mintlify-compatible style

| Prop | Type | Description |
|------|------|-------------|
| `path` | `string` | Param name + location="path" (when `name` is absent) |
| `query` | `string` | Param name + location="query" |
| `body` | `string` | Param name + location="body" |
| `header` | `string` | Param name + location="header" |

For documenting response fields, use [`<ResponseField>`](/components/response-field) — it's the output twin.

---

# Pill
Source: https://docs.nookdocs.com/components/pill

Tiny rounded inline marker — even smaller than Badge.

## Usage

`<Pill>` is the smallest label component. Use for "New", "Beta", "v2" markers next to text where space is tight.

```mdx Usage
## API v2 <Pill>New</Pill>
```

<h2>API v2 <Pill>New</Pill></h2>

```mdx Inline with text
The default theme is dark <Pill>since v1.1</Pill>.
```

The default theme is dark <Pill>since v1.1</Pill>.

## When to use Pill vs Badge

| | `<Pill>` | `<Badge>` |
|---|---|---|
| **Size** | Smaller, no uppercase | Slightly larger, uppercase |
| **Variants** | None — single muted style | 7 colored variants |
| **Use for** | "New", "v2", subtle markers | Status, plan tier, semantic labels |

If you need color (success, warning, danger), reach for [`<Badge>`](/components/badge). Pill is intentionally monochrome.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Pill label (kept very short — 1-3 words) |

---

# Prompt
Source: https://docs.nookdocs.com/components/prompt

Copyable AI prompt with deep links to Cursor, Claude, ChatGPT, and other LLM platforms.

## Usage

`<Prompt>` is the visual hook for NookDocs' LLM-first authoring story. It renders an AI prompt block with a copy button and one-click deep links to popular LLM platforms and IDEs.

```mdx Usage
<Prompt
  title="Scaffold a docs site"
  description="Paste this into Cursor with NookDocs MCP installed"
  targets={["cursor", "claude", "chatgpt"]}
>
  Create a NookDocs site for a REST API. Use the component library
  (Callout, Card, CodeGroup, Steps, ParamField, ResponseField).
  Include an introduction, quickstart, and 3 endpoint pages.
</Prompt>
```

<Prompt
  title="Scaffold a docs site"
  description="Paste this into Cursor with NookDocs MCP installed"
  targets={["cursor", "claude", "chatgpt"]}
>
  Create a NookDocs site for a REST API. Use the component library
  (Callout, Card, CodeGroup, Steps, ParamField, ResponseField).
  Include an introduction, quickstart, and 3 endpoint pages.
</Prompt>

## Why this exists

Most documentation platforms expect you to write content by hand. NookDocs assumes the reader will often hand the page off to an LLM — to extend it, debug it, or generate a companion. The Prompt component is the lightweight version of that handoff: a ready-to-use AI prompt the reader can copy or open in their tool of choice with a single click.

In Phase 3 the platform ships an MCP server that lets LLMs query the component library directly. Until then, Prompt is the bridge — it preloads the LLM with enough context to write valid NookDocs MDX without any tool integration.

## Without metadata

The `title` and `description` props are optional. A bare prompt body still works:

```mdx Without metadata
<Prompt>
  Convert this OpenAPI spec to a NookDocs API reference page using
  the ParamField, ResponseField, and CodeGroup components.
</Prompt>
```

<Prompt>
  Convert this OpenAPI spec to a NookDocs API reference page using
  the ParamField, ResponseField, and CodeGroup components.
</Prompt>

## Target platforms

The `targets` prop controls which deep-link buttons appear. Default is `["cursor", "claude", "chatgpt"]`.

| Target | Platform | Deep link protocol |
|--------|----------|--------------------|
| `cursor` | Cursor IDE | `cursor://` |
| `claude` | Claude.ai | `https://claude.ai/new?q=...` |
| `chatgpt` | ChatGPT | `https://chat.openai.com/?q=...` |
| `windsurf` | Codeium Windsurf | `windsurf://chat?prompt=...` |
| `vscode` | VS Code + Copilot Chat | `vscode://github.copilot-chat/...` |
| `perplexity` | Perplexity | `https://www.perplexity.ai/?q=...` |

```mdx Target platforms
<Prompt targets={["cursor", "claude", "chatgpt", "windsurf", "vscode", "perplexity"]}>
  Improve this documentation page for clarity and SEO.
</Prompt>
```

<Prompt targets={["cursor", "claude", "chatgpt", "windsurf", "vscode", "perplexity"]}>
  Improve this documentation page for clarity and SEO.
</Prompt>

## How copy + deep link work

The component walks the children tree and concatenates all text content into a single string. That string is what:

1. **Copy button** writes to the system clipboard
2. **Open-in-X buttons** URL-encode and append as a query parameter to the platform's deep link

So inline formatting in the children (markdown bold, links, etc.) is rendered visually inside the prompt body, but only the **plain text** ships to the LLM.

## Use cases

<CardGroup cols={2}>
  <Card title="Workflow templates" icon="sparkles">
    "Generate a complete API reference for my OpenAPI spec." Reader clicks Cursor, gets a working starter file.
  </Card>
  <Card title="Improve this page" icon="edit">
    Page-level prompt at the bottom: "Suggest improvements to this page using the NookDocs component library."
  </Card>
  <Card title="Code generation" icon="code">
    "Implement a NookDocs component called `<Foo>` that does X." Drops the LLM into the right context.
  </Card>
  <Card title="Migration help" icon="arrow-right">
    "Convert this Mintlify MDX file to NookDocs format." Pre-fills with the source the reader wants to migrate.
  </Card>
</CardGroup>

## Phase 3 forward reference

When the LLM-first authoring phase ships, the Prompt component will gain three more capabilities:

1. **MCP-aware prompts** — automatically include `npx nookdocs-mcp install` instructions for IDEs that support it
2. **Component spec injection** — the prompt body can reference `{components}` and the platform inlines the full library spec on copy
3. **Page context auto-include** — `<Prompt usePageContext>` automatically appends the current page's MDX source to the prompt so the LLM sees the surrounding content

The current API stays — Phase 3 only adds. No breaking changes.

## Actions prop (Mintlify compat)

The `actions` prop is an alias for `targets`. If you're migrating from Mintlify, existing markup that uses `actions` works without changes:

```mdx Actions prop
<Prompt actions={["cursor", "claude"]}>
  Refactor this component to use server actions.
</Prompt>
```

If both `actions` and `targets` are set, `targets` takes priority.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Bold heading shown above the prompt body |
| `description` | `string` | — | One-line description shown under the title |
| `icon` | `string` | — | Icon beside the title, replacing the default sparkle |
| `iconType` | `string` | — | Font Awesome style, when the icon comes from that library |
| `targets` | `("cursor" \| "claude" \| "chatgpt" \| "windsurf" \| "vscode" \| "perplexity")[]` | `["cursor", "claude", "chatgpt"]` | Which deep-link buttons to render |
| `actions` | `("cursor" \| "claude" \| "chatgpt" \| "windsurf" \| "vscode" \| "perplexity")[]` | — | Alias for `targets` (Mintlify compat) |
| `children` | `ReactNode` | required | The prompt body — can include markdown formatting |

---

# RequestExample
Source: https://docs.nookdocs.com/components/request-example

Multi-language request example block for API endpoint pages.

## Usage

`<RequestExample>` is a thin wrapper around [`<CodeGroup>`](/components/code-group) that adds a small "Request" eyebrow header. Use it on API endpoint pages to show the same call in multiple languages.

````mdx Basic usage
<RequestExample>
```bash cURL
curl -X POST https://api.nookdocs.com/v1/projects \
  -H "Authorization: Bearer $TOKEN"
```

```bash HTTPie
http POST https://api.nookdocs.com/v1/projects \
  Authorization:"Bearer $TOKEN"
```
</RequestExample>
````

<RequestExample>
```bash cURL
curl -X POST https://api.nookdocs.com/v1/projects \
  -H "Authorization: Bearer $TOKEN"
```

```bash HTTPie
http POST https://api.nookdocs.com/v1/projects \
  Authorization:"Bearer $TOKEN"
```
</RequestExample>

## Custom title

The default eyebrow text is "Request". Override with the `title` prop if you want something more specific:

```mdx Custom title
<RequestExample title="Authentication request">
  ...
</RequestExample>
```

## Inside a Panel

For Mintlify-style endpoint pages, place `<RequestExample>` inside a `<Panel>` to push it into the right sidebar:

````mdx Inside a Panel
<Panel title="Sample request">
  <RequestExample>
    ```bash cURL
    curl -X POST https://api.nookdocs.com/v1/projects
    ```
  </RequestExample>
</Panel>
````

The reader sees the prose on the left and the request example sticky on the right — like the Stripe and Mintlify API references.

## Auto-generation

In Phase 4, the OpenAPI parser auto-generates `<RequestExample>` blocks for every endpoint with curl, JavaScript, Python, Go, and Ruby tabs. You don't need to author them by hand for endpoints that come from a spec.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | `"Request"` | Eyebrow header text |
| `children` | `ReactNode` | required | Fenced code blocks (one per language) |

For response examples, use [`<ResponseExample>`](/components/response-example).

---

# ResponseExample
Source: https://docs.nookdocs.com/components/response-example

Multi-status-code response example block for API endpoint pages.

## Usage

`<ResponseExample>` is the output twin of [`<RequestExample>`](/components/request-example). Wraps a [`<CodeGroup>`](/components/code-group) with a "Response" eyebrow and uses status codes as tab labels.

````mdx Basic usage
<ResponseExample>
```json 200
{
  "id": "prj_abc123",
  "name": "My Docs",
  "status": "active",
  "created_at": "2026-04-10T09:30:00Z"
}
```

```json 400
{
  "error": "invalid_request",
  "message": "name is required"
}
```

```json 401
{
  "error": "unauthenticated",
  "message": "Bearer token missing or invalid"
}
```
</ResponseExample>
````

<ResponseExample>
```json 200
{
  "id": "prj_abc123",
  "name": "My Docs",
  "status": "active",
  "created_at": "2026-04-10T09:30:00Z"
}
```

```json 400
{
  "error": "invalid_request",
  "message": "name is required"
}
```

```json 401
{
  "error": "unauthenticated",
  "message": "Bearer token missing or invalid"
}
```
</ResponseExample>

## Convention: status code as tab label

The metastring after `json` becomes the tab label, so the canonical pattern is to use the HTTP status code:

````mdx Status code as tab label
```json 200
```
````

This makes the response shapes easy to scan at a glance — readers see "200, 400, 401" tabs and know exactly what they're looking at.

## Pairing with RequestExample

The two components are designed to be used together. Place `<RequestExample>` first, then `<ResponseExample>` directly after:

```mdx Pairing with RequestExample
<RequestExample>
  ...
</RequestExample>

<ResponseExample>
  ...
</ResponseExample>
```

Or, for a more compact page, both inside a single `<Panel>`:

```mdx Inside a Panel
<Panel>
  <RequestExample>...</RequestExample>
  <ResponseExample>...</ResponseExample>
</Panel>
```

## Custom title

```mdx Custom title
<ResponseExample title="Sample response">
  ...
</ResponseExample>
```

## Auto-generation

In Phase 4, the OpenAPI parser auto-generates `<ResponseExample>` from the `responses` object in the spec. Every declared status code becomes a tab.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | `"Response"` | Eyebrow header text |
| `children` | `ReactNode` | required | Fenced code blocks (one per status code) |

---

# ResponseField
Source: https://docs.nookdocs.com/components/response-field

Document API response body fields with type, required, and deprecated states.

## Usage

`<ResponseField>` is the output twin of [`<ParamField>`](/components/param-field). Use one per field in an API response body to explain what the caller can expect back.

```mdx Basic usage
<ResponseField name="id" type="string" required>
  Unique identifier for the resource, generated on the server.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  UTC timestamp when the resource was created.
</ResponseField>

<ResponseField name="status" type="enum">
  One of `queued`, `building`, `deployed`, or `failed`.
</ResponseField>
```

<ResponseField name="id" type="string" required>
  Unique identifier for the resource, generated on the server.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  UTC timestamp when the resource was created.
</ResponseField>

<ResponseField name="status" type="enum">
  One of `queued`, `building`, `deployed`, or `failed`.
</ResponseField>

## Deprecated fields

Mark a field as deprecated to strikethrough the name and add a warning badge:

```mdx Deprecated field
<ResponseField name="legacy_id" type="string" deprecated>
  Use `id` instead. Will be removed in v2.
</ResponseField>
```

<ResponseField name="legacy_id" type="string" deprecated>
  Use `id` instead. Will be removed in v2.
</ResponseField>

## Grouping by status code

When an endpoint returns different shapes for different status codes, group each shape under its own heading:

```mdx Grouping by status code
## 200 — Success

<ResponseField name="id" type="string" required>
  The created resource ID.
</ResponseField>

<ResponseField name="status" type="string" required>
  Always `created` on a successful response.
</ResponseField>

## 400 — Bad Request

<ResponseField name="error" type="string" required>
  Error code (e.g. `invalid_request`).
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable error description.
</ResponseField>
```

A future version of the platform will introduce a dedicated `<ResponseExample>` wrapper for tabbed status-code rendering — until then, h2 sections are the convention.

## Auto-generation from OpenAPI

If your project has an OpenAPI spec, ResponseField entries are generated automatically from the response schema on API reference pages. See the [OpenAPI integration guide](/configuration/config-file#api).

## Default value

Show the default value for an optional field using the `default` prop:

```mdx Default value
<ResponseField name="page_size" type="number" default="20">
  Number of items per page. Omit to use the server default.
</ResponseField>
```

<ResponseField name="page_size" type="number" default="20">
  Number of items per page. Omit to use the server default.
</ResponseField>

## Pre and post annotations

The `pre` and `post` props add inline text immediately before or after the field name. Use them for path prefixes, array indicators, or units:

```mdx Pre and post annotations
<ResponseField name="items" type="object[]" pre="data." post="[*]">
  Array of resource objects nested under the `data` key.
</ResponseField>

<ResponseField name="latency" type="number" post=" ms">
  Server-side processing time in milliseconds.
</ResponseField>
```

<ResponseField name="items" type="object[]" pre="data." post="[*]">
  Array of resource objects nested under the `data` key.
</ResponseField>

<ResponseField name="latency" type="number" post=" ms">
  Server-side processing time in milliseconds.
</ResponseField>

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `name` | `string` | Yes | Field name as it appears in the response JSON |
| `type` | `string` | No | Type annotation (e.g. `string`, `number`, `object`, enum) |
| `required` | `boolean` | No | Marks the field as always-present |
| `deprecated` | `boolean` | No | Strikethrough name + "deprecated" badge |
| `default` | `string` | No | Default value shown as a badge next to the type |
| `pre` | `string \| string[]` | No | Labels rendered immediately before the field name |
| `post` | `string \| string[]` | No | Labels rendered immediately after the field name |
| `enum` | `string[]` | No | Closed set of possible values — rendered as small `options:` chips below the description |

---

# Snippet
Source: https://docs.nookdocs.com/components/snippet

Reusable content blocks shared across pages — full resolution ships in Phase 4.

## Status

<Banner variant="warning">
  `<Snippet>` is a **stub component** today. The `file` prop is accepted and the call site is forward-compatible, but content from `_snippets/` is not yet inlined into the page. Full snippet resolution ships in Phase 4 alongside the OpenAPI parser (both touch the sync pipeline).
</Banner>

## Usage (target API)

```mdx Snippet file reference
<Snippet file="_snippets/authentication.mdx" />
```

When Phase 4 ships, this will inline the contents of `_snippets/authentication.mdx` from your repo at sync time. The reader sees the full content; the snippet file is the single source of truth.

```mdx Snippet file content
<!-- _snippets/authentication.mdx (in the tenant's repo) -->
Add your API key to the `Authorization` header:

```bash
curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/v1/users
```
```

## v0 escape hatch: inline children

Until Phase 4 lands, you can pass content inline as children. This skips the `_snippets/` lookup entirely and just renders whatever you pass:

```mdx v0 escape hatch: inline children
<Snippet>
  Add your API key to the `Authorization` header.
</Snippet>
```

<Snippet>
  Add your API key to the `Authorization` header.
</Snippet>

This is identical to writing the content inline — there's no reuse benefit. The point is that authoring `<Snippet>` calls today is forward-compatible: when Phase 4 ships, you can swap inline children for the `file` prop without rewriting the call sites.

## Why this matters

Snippets are how Mintlify (and the rest of the static-site-generator world) handle content reuse — boilerplate authentication intros, common warnings, shared error tables. Manual copy-paste is the alternative, which drifts the moment you update one and forget the others.

NookDocs' Phase 4 implementation will:

1. Walk the `_snippets/` directory inside `contentRoot` during sync
2. Store snippet bodies in a separate Postgres table keyed by file path
3. Resolve `<Snippet file="...">` references at render time by looking up the body
4. Support template variable substitution via the `vars` prop

## Variable substitution (Phase 4)

When Phase 4 ships, the `vars` prop will let you template-fill snippets per call site:

```mdx Passing template variables
<Snippet
  file="_snippets/authentication.mdx"
  vars={{ apiKey: "YOUR_KEY", baseUrl: "https://api.example.com" }}
/>
```

```mdx Snippet with placeholders
<!-- _snippets/authentication.mdx -->
Add your key to `{baseUrl}`:

curl -H "Authorization: Bearer {apiKey}" {baseUrl}/v1/users
```

The `{apiKey}` and `{baseUrl}` placeholders get replaced with the values passed at the call site. The same snippet file can serve dozens of pages with different example values.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `file` | `string` | No (one of `file` or `children`) | Path to snippet file relative to your docs base |
| `vars` | `Record<string, string>` | No | Template variable substitutions (Phase 4) |
| `children` | `ReactNode` | No (v0 escape hatch) | Inline content rendered as-is |

---

# Steps
Source: https://docs.nookdocs.com/components/steps

Display sequential instructions in a numbered list with auto-counting.

## Usage

````mdx Basic usage
<Steps>
  <Step title="Create a project">
    Sign up and create your first documentation project.
  </Step>
  <Step title="Connect GitHub">
    Install the NookDocs GitHub App on your repository.
  </Step>
  <Step title="Deploy">
    Push your MDX files and your docs go live.
  </Step>
</Steps>
````

<Steps>
  <Step title="Create a project">
    Sign up and create your first documentation project.
  </Step>
  <Step title="Connect GitHub">
    Install the NookDocs GitHub App on your repository.
  </Step>
  <Step title="Deploy">
    Push your MDX files and your docs go live.
  </Step>
</Steps>

The numbers are generated automatically by a CSS counter — you don't pass `stepNumber` manually. Add or remove steps and the numbering re-counts itself.

## Custom step icons

Replace the auto-generated number with a Lucide icon by setting `titleIcon`. Useful for tutorial flows where each step represents a different concept (install, configure, deploy, verify) and a glyph reads faster than a number.

````mdx Custom step icons
<Steps>
  <Step titleIcon="download" title="Install the CLI">
    Run `npm install -g nookdocs`.
  </Step>
  <Step titleIcon="settings" title="Configure your project">
    Edit `nookdocs.config.json` with your name and navigation.
  </Step>
  <Step titleIcon="rocket" title="Deploy">
    Push to GitHub and watch the build complete in 30 seconds.
  </Step>
  <Step titleIcon="check" title="Verify">
    Open your subdomain URL on nookdocs.site.
  </Step>
</Steps>
````

<Steps>
  <Step titleIcon="download" title="Install the CLI">
    Run `npm install -g nookdocs`.
  </Step>
  <Step titleIcon="settings" title="Configure your project">
    Edit `nookdocs.config.json` with your name and navigation.
  </Step>
  <Step titleIcon="rocket" title="Deploy">
    Push to GitHub and watch the build complete in 30 seconds.
  </Step>
  <Step titleIcon="check" title="Verify">
    Open your subdomain URL on nookdocs.site.
  </Step>
</Steps>

## Mixing icons and numbers

You can leave some steps un-iconed and they'll fall back to the counter, but the visual reads better when you commit to one or the other for a single Steps block.

## Nested content

Step content can include any other component — code blocks, callouts, cards, even nested Tabs:

````mdx Nested content
<Steps>
  <Step title="Install the package">
    <CodeGroup>
      ```bash npm
      npm install @nookdocs/sdk
      ```
      ```bash yarn
      yarn add @nookdocs/sdk
      ```
    </CodeGroup>

    <Note>
      Requires Node.js 20 or later.
    </Note>
  </Step>
</Steps>
````

## Override step number

The CSS counter handles numbering automatically, but sometimes you need to force a specific number — for example, when continuing a sequence from a previous Steps block:

````mdx Override step number
<Steps>
  <Step title="Review the PR" stepNumber={4}>
    Continuing from the previous section...
  </Step>
  <Step title="Merge to main" stepNumber={5}>
    Once approved, merge the pull request.
  </Step>
</Steps>
````

## Custom anchor IDs

By default each step generates an anchor from its title. Set `id` to override this, which is useful for linking directly to a specific step:

````mdx Custom anchor ID
<Steps>
  <Step title="Configure authentication" id="auth-setup">
    Set up your auth provider credentials.
  </Step>
</Steps>
````

Link to it with `[jump to auth](#auth-setup)`.

## Custom heading level

By default step titles render as `<h4>`. Set `titleSize` on the parent to change the heading level:

````mdx Custom heading level
<Steps titleSize="h2">
  <Step title="First step">
    This title renders as an h2 heading.
  </Step>
  <Step title="Second step">
    Useful for top-level tutorial sections.
  </Step>
</Steps>
````

## Props

### Steps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `titleSize` | `"p" \| "h2" \| "h3" \| "h4"` | `"h4"` | Heading level for step titles |
| `children` | `ReactNode` | — | One or more `<Step>` components |

### Step

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | No | Step heading rendered above the content |
| `titleIcon` | `string` | No | Icon name ([Lucide](https://lucide.dev/icons), [Tabler](https://tabler.io/icons), [Font Awesome](https://fontawesome.com/icons)) or emoji — replaces the auto-counter |
| `icon` | `string` | No | Alias for `titleIcon` (Mintlify compat) |
| `iconType` | `string` | No | FA icon style (solid, brands, etc.) |
| `stepNumber` | `number` | No | Override the auto-generated counter with a specific number |
| `id` | `string` | No | Custom anchor ID for hash links (e.g. `#my-step`) |
| `children` | `ReactNode` | Yes | Step content (markdown, components, anything) |

---

# Tabs
Source: https://docs.nookdocs.com/components/tabs

Organize related content into switchable panels with simple or advanced API, icons, and disabled states.

## Basic usage

The simplest way to create tabs. Each `<Tab>` becomes a panel with its `title` as the tab label:

```mdx Basic usage
<Tabs>
  <Tab title="React">
    React uses JSX for templating.
  </Tab>
  <Tab title="Vue">
    Vue uses single-file components with template syntax.
  </Tab>
  <Tab title="Svelte">
    Svelte compiles components at build time.
  </Tab>
</Tabs>
```

<Tabs>
  <Tab title="React">
    React uses JSX for templating.
  </Tab>
  <Tab title="Vue">
    Vue uses single-file components with template syntax.
  </Tab>
  <Tab title="Svelte">
    Svelte compiles components at build time.
  </Tab>
</Tabs>

## Tab icons

Add a Lucide icon with the `icon` prop:

```mdx Tab icons
<Tabs>
  <Tab title="macOS" icon="cpu">
    Install via Homebrew: `brew install nookdocs`
  </Tab>
  <Tab title="Linux" icon="terminal">
    Install via apt or yum.
  </Tab>
  <Tab title="Windows" icon="package">
    Install via Chocolatey or winget.
  </Tab>
</Tabs>
```

<Tabs>
  <Tab title="macOS" icon="cpu">
    Install via Homebrew: `brew install nookdocs`
  </Tab>
  <Tab title="Linux" icon="terminal">
    Install via apt or yum.
  </Tab>
  <Tab title="Windows" icon="package">
    Install via Chocolatey or winget.
  </Tab>
</Tabs>

## Default tab

Set `defaultValue` on the parent `<Tabs>` to pick the initially active tab. The value is the slugified title (lowercase, hyphens). If omitted, the first non-disabled tab is active.

```mdx Default tab
<Tabs defaultValue="vue">
  <Tab title="React">React content</Tab>
  <Tab title="Vue">Vue content (active by default)</Tab>
</Tabs>
```

## Disabled tabs

Mark a tab as `disabled` for "coming soon" content:

```mdx Disabled tab
<Tabs>
  <Tab title="REST API">REST is GA today.</Tab>
  <Tab title="GraphQL">GraphQL is GA today.</Tab>
  <Tab title="gRPC" disabled>gRPC is in private beta.</Tab>
</Tabs>
```

<Tabs>
  <Tab title="REST API">REST is GA today.</Tab>
  <Tab title="GraphQL">GraphQL is GA today.</Tab>
  <Tab title="gRPC" disabled>gRPC is in private beta.</Tab>
</Tabs>

## Advanced API

For more control (custom `value` identifiers, separate trigger/content layout), use the compound API with `TabsList`, `TabsTrigger`, and `TabsContent`:

```mdx Advanced API
<Tabs>
  <TabsList>
    <TabsTrigger value="rest">REST API</TabsTrigger>
    <TabsTrigger value="graphql">GraphQL</TabsTrigger>
    <TabsTrigger value="grpc" disabled>gRPC (soon)</TabsTrigger>
  </TabsList>
  <TabsContent value="rest">REST is GA today.</TabsContent>
  <TabsContent value="graphql">GraphQL is GA today.</TabsContent>
  <TabsContent value="grpc">gRPC is in private beta.</TabsContent>
</Tabs>
```

<Tabs>
  <TabsList>
    <TabsTrigger value="rest">REST API</TabsTrigger>
    <TabsTrigger value="graphql">GraphQL</TabsTrigger>
    <TabsTrigger value="grpc" disabled>gRPC (soon)</TabsTrigger>
  </TabsList>
  <TabsContent value="rest">REST is GA today.</TabsContent>
  <TabsContent value="graphql">GraphQL is GA today.</TabsContent>
  <TabsContent value="grpc">gRPC is in private beta.</TabsContent>
</Tabs>

## Tab sync

Tabs with matching labels automatically sync across the page. Click "npm" in one tab group, and all other Tabs and CodeGroups with an "npm" tab switch too. Selections persist across page navigations via localStorage.

Disable sync on a specific tab group with `sync={false}`:

```mdx Disable tab sync
<Tabs sync={false}>
  <Tab title="Option A">Independent — not synced</Tab>
  <Tab title="Option B">This tab group stands alone</Tab>
</Tabs>
```

## Default tab by index

When you don't have a stable value to reference, select the initial tab by its position using `defaultTabIndex` (0-based):

```mdx Default tab by index
<Tabs defaultTabIndex={1}>
  <Tab title="First">This is not active.</Tab>
  <Tab title="Second">This tab opens by default.</Tab>
</Tabs>
```

If both `defaultValue` and `defaultTabIndex` are set, `defaultValue` takes priority.

## Hide bottom border

Set `borderBottom={false}` to remove the line under the tab bar. Useful when embedding tabs inside another bordered container where the extra line adds visual noise:

```mdx Hide bottom border
<Tabs borderBottom={false}>
  <Tab title="Preview">Content without the underline border.</Tab>
  <Tab title="Code">Source code view.</Tab>
</Tabs>
```

## Differences from CodeGroup

For code-only switching (like the same install command in npm/yarn/pnpm), use [`<CodeGroup>`](/components/code-group) instead. It's shorter, the tab bar is styled like a code block header, and the active tab inherits the code block syntax highlighting.

`<Tabs>` is for **mixed content** — prose, images, components, or anything that isn't just code.

## Props

### Tabs

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultValue` | `string` | first non-disabled tab | Initially active tab value (slugified title or trigger value) |
| `defaultTabIndex` | `number` | — | Select the initially active tab by numeric index (0-based) instead of by value |
| `sync` | `boolean` | `true` | Sync active tab with matching Tabs/CodeGroups on the page |
| `borderBottom` | `boolean` | `true` | Show the bottom border line under the tab bar |

### Tab (simple API)

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | Yes | Tab label shown in the tab bar |
| `icon` | `string` | No | Lucide icon name (or emoji) |
| `iconType` | `string` | No | Font Awesome style, when the icon comes from that library |
| `id` | `string` | No | Custom id for anchor-linking this tab (defaults to the title) |
| `disabled` | `boolean` | No | Mark the tab as unclickable |

### TabsList (compound API)

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | One or more `<TabsTrigger>` |

### TabsTrigger (compound API)

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Identifier — must match a `<TabsContent>` value |
| `icon` | `string` | No | Lucide icon name (or emoji) |
| `iconType` | `string` | No | Font Awesome style, when the icon comes from that library |
| `id` | `string` | No | Custom id for anchor-linking this tab (defaults to the title) |
| `disabled` | `boolean` | No | Mark the tab as unclickable |

### TabsContent (compound API)

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Identifier — must match a `<TabsTrigger>` value |

---

# Tag
Source: https://docs.nookdocs.com/components/tag

Inline metadata tag for blog post categories and topic labels.

## Usage

```mdx Basic usage
<Tag>API</Tag> <Tag>v2</Tag> <Tag>Tutorial</Tag>
```

<Tag>API</Tag>&nbsp;<Tag>v2</Tag>&nbsp;<Tag>Tutorial</Tag>

`<Tag>` renders a hash-prefixed inline label. Use it for blog post categories, topic markers, version tags — anything that classifies content.

## Tag vs Badge vs Pill

NookDocs has three small inline label primitives. Each serves a distinct purpose:

| | `<Tag>` | `<Badge>` | `<Pill>` |
|---|---|---|---|
| **Prefix** | `#` hash | None | None |
| **Variants** | None (monochrome) | 7 colored variants | None (monochrome) |
| **Case** | As written | Uppercase | As written |
| **Best for** | Topics, categories | Status, plan tier | "New", "v2" markers |

## Multiple tags on a blog post

```mdx Multiple tags on a blog post
---
title: Building an API with NookDocs
---

<Tag>API</Tag> <Tag>OpenAPI</Tag> <Tag>Tutorial</Tag>

This guide walks through...
```

<Tag>API</Tag>&nbsp;<Tag>OpenAPI</Tag>&nbsp;<Tag>Tutorial</Tag>

This guide walks through...

## Props

| Prop | Type | Description |
|------|------|-------------|
| `children` | `ReactNode` | Tag label |

---

# TerminalBlock
Source: https://docs.nookdocs.com/components/terminal-block

Terminal-window styled code block with macOS-style traffic-light header.

## Usage

`<TerminalBlock>` is a code block with a terminal-window visual treatment — three traffic-light dots in the title bar and a dark background. Use sparingly for hero sections where you want to show "type these commands" with extra visual weight.

```mdx Usage
<TerminalBlock title="bash">
{`$ npm install nookdocs
$ nookdocs init
$ git push`}
</TerminalBlock>
```

<TerminalBlock title="bash">
{`$ npm install nookdocs
$ nookdocs init
$ git push`}
</TerminalBlock>

## Without title

The title is optional — omit it for a frame-only look:

```mdx Without title
<TerminalBlock>
{`$ nookdocs dev
Starting development server...
Listening on http://localhost:4242`}
</TerminalBlock>
```

<TerminalBlock>
{`$ nookdocs dev
Starting development server...
Listening on http://localhost:4242`}
</TerminalBlock>

## Always dark

The terminal frame is **intentionally always dark**, regardless of the page theme. This matches user expectation — terminals are dark even on light websites.

If you need a code block that follows the page theme, use a regular markdown fence or `<CodeBlock>` instead.

## When to use

- **Quickstart "type these commands" sections** — visual weight tells readers "this is the action you take"
- **Landing pages** — terminal screenshots are a developer-marketing trope, this gives you the same vibe without the screenshot
- **Step-by-step CLI tutorials** — pair with `<Steps>` to walk through a CLI workflow

## When NOT to use

- **Generic code examples** — use markdown fences (lighter weight, theme-aware)
- **API request/response** — use `<RequestExample>` / `<ResponseExample>`
- **Multi-language code** — use `<CodeGroup>`

TerminalBlock is for **terminal commands specifically**, not code in general.

## Props

| Prop | Type | Description |
|------|------|-------------|
| `title` | `string` | Optional title bar label (e.g. `"bash"`, `"zsh"`, `"PowerShell"`) |
| `children` | `ReactNode` | Terminal content (typically a multi-line template literal) |

---

# Tiles
Source: https://docs.nookdocs.com/components/tiles

Visual-heavier grid of clickable tiles for landing pages and category hubs.

## Usage

```mdx Usage
<Tiles cols={3}>
  <Tile title="Quickstart" description="5-minute setup" href="/quickstart" icon="rocket" />
  <Tile title="Components" description="30+ MDX components" href="/components/callout" icon="layers" />
  <Tile title="API Reference" description="Complete REST API" href="/api-reference/introduction" icon="code" />
</Tiles>
```

<Tiles cols={3}>
  <Tile title="Quickstart" description="5-minute setup" href="/quickstart" icon="rocket" />
  <Tile title="Components" description="30+ MDX components" href="/components/callout" icon="layers" />
  <Tile title="API Reference" description="Complete REST API" href="/api-reference/introduction" icon="code" />
</Tiles>

`<Tiles>` is a responsive grid of `<Tile>` cards. Each tile is centered, icon-first, and clickable as a single unit.

## Tiles vs Cards

| | `<Tiles>` / `<Tile>` | `<Card>` / `<CardGroup>` |
|---|---|---|
| **Visual weight** | Heavy — large icon plate, centered | Light — left-aligned, dense |
| **Best for** | Landing pages, "pick your starting point" | Feature grids, dense info |
| **Required href** | Yes | No (optional) |
| **Description** | Centered, smaller | Left-aligned |

Use Tiles when you have 3-6 high-level entry points and want each to feel like a poster. Use Cards when you have many items and want density.

## 4 tiles

```mdx 4 tiles
<Tiles cols={4}>
  <Tile title="Free" icon="user" href="/pricing" />
  <Tile title="Pro" icon="zap" href="/pricing" />
  <Tile title="Business" icon="trophy" href="/pricing" />
  <Tile title="Enterprise" icon="shield" href="/pricing" />
</Tiles>
```

<Tiles cols={4}>
  <Tile title="Free" icon="user" href="/introduction" />
  <Tile title="Pro" icon="zap" href="/introduction" />
  <Tile title="Business" icon="trophy" href="/introduction" />
  <Tile title="Enterprise" icon="shield" href="/introduction" />
</Tiles>

## Custom icon color

Override the default primary tint per tile:

```mdx Custom icon color
<Tiles cols={3}>
  <Tile title="Stable" icon="check" color="var(--docs-success)" href="/" />
  <Tile title="Beta" icon="zap" color="var(--docs-warning)" href="/" />
  <Tile title="Experimental" icon="sparkles" color="var(--docs-danger)" href="/" />
</Tiles>
```

<Tiles cols={3}>
  <Tile title="Stable" icon="check" color="var(--docs-success)" href="/introduction" />
  <Tile title="Beta" icon="zap" color="var(--docs-warning)" href="/introduction" />
  <Tile title="Experimental" icon="sparkles" color="var(--docs-danger)" href="/introduction" />
</Tiles>

## Props

### Tiles

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `cols` | `2 \| 3 \| 4` | `3` | Number of columns on desktop |
| `children` | `ReactNode` | required | One or more `<Tile>` |

### Tile

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | Yes | Tile heading |
| `href` | `string` | Yes | Link destination |
| `description` | `string` | No | Subtitle below the title |
| `icon` | `string` | No | Lucide icon name or emoji |
| `color` | `string` | No | Override the icon tint (CSS color or var) |

---

# Tooltip
Source: https://docs.nookdocs.com/components/tooltip

Inline hover-reveal explanations for glossary terms.

## Usage

`<Tooltip>` renders an inline trigger with a dotted underline. Hover or focus the trigger to see the tooltip content.

```mdx Basic usage
A <Tooltip content="Tenant = customer organization">tenant</Tooltip>
is a customer-facing project.
```

A <Tooltip content="Tenant = customer organization">tenant</Tooltip> is a customer-facing project.

## Glossary terms

Tooltips are great for inline explanations of technical jargon without sending the reader to a separate glossary page:

```mdx Glossary terms
The MDX renderer is built on
<Tooltip content="A safe MDX parser that converts markdown + JSX to React without eval()">safe-mdx</Tooltip>,
which means user content can never execute arbitrary code.
```

The MDX renderer is built on <Tooltip content="A safe MDX parser that converts markdown + JSX to React without eval()">safe-mdx</Tooltip>, which means user content can never execute arbitrary code.

## When to use

- **Glossary terms** — first occurrence of a technical word with a one-line definition
- **Acronyms** — `<Tooltip content="Reciprocal Rank Fusion">RRF</Tooltip>`
- **Subtle hints** — keyboard shortcut reminders, alternative names

## When NOT to use

- **Long content** — tooltips are for one-line explanations. For longer detail, use `<Expandable>` or link to a full page.
- **Critical information** — readers may not hover. Don't hide essential context behind a tooltip.
- **Mobile-first content** — touchscreens don't have hover. Tooltips work on tap-and-hold but it's not as discoverable.

## Rich tooltip

Add a `headline` for a bold title, and a `cta` + `href` for a clickable call-to-action link:

```mdx Rich tooltip
Each project has an
<Tooltip
  headline="API Key"
  content="SHA-256 hashed, scoped to your organization."
  cta="Learn more"
  href="/api-reference/introduction"
>API key</Tooltip>
for programmatic access.
```

Each project has an <Tooltip headline="API Key" content="SHA-256 hashed, scoped to your organization." cta="Learn more" href="/api-reference/introduction">API key</Tooltip> for programmatic access.

When `href` is set, the tooltip popup stays visible on hover so the CTA link is clickable.

## Mintlify compatibility

Mintlify uses `tip` instead of `content`. Both are accepted:

```mdx Mintlify compatibility
<Tooltip tip="Tenant = customer organization">tenant</Tooltip>
```

If both `content` and `tip` are provided, `content` takes precedence.

## Accessibility

The tooltip trigger is keyboard-focusable (`tabIndex={0}`), so keyboard users can `Tab` to it and see the content. The tooltip uses `role="tooltip"` so screen readers announce it.

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `content` | `string` | — | The tooltip text shown on hover/focus (canonical prop) |
| `tip` | `string` | — | Alias for `content` (Mintlify compatibility) |
| `headline` | `string` | No | Bold headline above the content |
| `cta` | `string` | No | Call-to-action text shown below the content |
| `href` | `string` | No | If set, the CTA becomes a clickable link and the popup stays interactive |
| `children` | `ReactNode` | Yes | The inline trigger (typically a single word) |

---

# Update
Source: https://docs.nookdocs.com/components/update

Changelog entry component with date, label, and version.

## Usage

`<Update>` is the building block for changelog pages. Each entry has a date, optional category label, optional version number, and the description content. Every entry is **permalinkable** — the date pill links to `#v{version}` (or `#{date}` without a version), so you can share a specific release. On desktop, entries connect along a timeline rail.

```mdx Usage
<Update date="2026-04-10" label="Feature" version="1.2.0">
  Added pgvector hybrid search and the AI sparkle toggle in the search modal.
</Update>
```

<Update date="2026-04-10" label="Feature" version="1.2.0">
  Added pgvector hybrid search and the AI sparkle toggle in the search modal.
</Update>

## Label colors

The `label` prop drives a color-coded badge. Five common categories get smart defaults; other strings fall back to a neutral badge.

```mdx Label colors
<Update date="2026-04-10" label="Feature">New feature</Update>
<Update date="2026-04-10" label="Fix">Bug fix</Update>
<Update date="2026-04-10" label="Breaking">Breaking change</Update>
<Update date="2026-04-10" label="Improvement">Performance improvement</Update>
<Update date="2026-04-10" label="Security">Security patch</Update>
<Update date="2026-04-10" label="Custom">Custom label</Update>
```

<Update date="2026-04-10" label="Feature">New feature</Update>

<Update date="2026-04-10" label="Fix">Bug fix</Update>

<Update date="2026-04-10" label="Breaking">Breaking change</Update>

<Update date="2026-04-10" label="Improvement">Performance improvement</Update>

<Update date="2026-04-10" label="Security">Security patch</Update>

<Update date="2026-04-10" label="Custom">Custom label (falls back to default badge)</Update>

## Building a changelog page

Stack updates in reverse chronological order on a `/changelog` page:

```mdx Building a changelog page
---
title: Changelog
description: Recent changes to NookDocs.
---

<Update date="2026-04-10" label="Feature" version="1.2.0">
  - Added pgvector hybrid search
  - New AI sparkle toggle in search modal
  - Theme tokens now apply to search results
</Update>

<Update date="2026-04-08" label="Fix" version="1.1.2">
  Fixed contentRoot filter so non-docs markdown files no longer
  pollute the search index.
</Update>

<Update date="2026-04-05" label="Breaking" version="1.1.0">
  Renamed `colors.brand` to `colors.primary` in `nookdocs.config.json`.
</Update>
```

## Date format

Pass the date as `YYYY-MM-DD`. The component formats it as "April 10, 2026" using the `en-US` locale, parsed as UTC to avoid timezone shifts.

## Description subtitle

Add a `description` prop to display a subtitle line below the date/label header. Useful for a one-sentence summary when the body contains a detailed list:

```mdx Description subtitle
<Update date="2026-04-12" label="Feature" version="1.3.0" description="New search experience with AI-powered results">
  - Hybrid search combining full-text and vector similarity
  - Keyboard navigation in the search modal
  - Result previews with highlighted matches
</Update>
```

<Update date="2026-04-12" label="Feature" version="1.3.0" description="New search experience with AI-powered results">
  - Hybrid search combining full-text and vector similarity
  - Keyboard navigation in the search modal
  - Result previews with highlighted matches
</Update>

## Filter tags

The `tags` prop renders small badges next to the entry. On changelog pages with filtering, readers can click a tag to narrow the list:

```mdx Filter tags
<Update date="2026-04-11" label="Fix" tags={["search", "api"]}>
  Fixed a regression where the search API returned stale results after a deploy.
</Update>
```

<Update date="2026-04-11" label="Fix" tags={["search", "api"]}>
  Fixed a regression where the search API returned stale results after a deploy.
</Update>

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `date` | `string (ISO 8601)` | Yes | Entry date as `YYYY-MM-DD` |
| `label` | `string` | No | Category badge — `Feature`, `Fix`, `Breaking`, `Improvement`, `Security`, or any custom string |
| `version` | `string` | No | Version number rendered as `v1.2.0` |
| `description` | `string` | No | Subtitle text displayed below the header line |
| `tags` | `string[]` | No | Filter tags rendered as small badges |
| `children` | `ReactNode` | required | Entry description — markdown, lists, code, anything |

---

# Video
Source: https://docs.nookdocs.com/components/video

Embed videos from YouTube, Vimeo, Loom, or self-hosted mp4 with auto-detection.

## Usage

`<Video>` accepts a URL and figures out the right embed format on its own. Pass a YouTube watch URL, a Vimeo link, a Loom share URL, or a self-hosted mp4 — the component picks the right rendering path.

```mdx Usage
<Video src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="Demo video" />
```

## Provider auto-detection

| URL pattern | Provider | Render |
|-------------|----------|--------|
| `youtube.com/watch?v=...` or `youtu.be/...` | YouTube | iframe with `youtube-nocookie.com/embed/{id}` |
| `vimeo.com/123456789` | Vimeo | iframe with `player.vimeo.com/video/{id}` |
| `loom.com/share/...` | Loom | iframe with `loom.com/embed/{id}` |
| `*.mp4`, `*.webm`, `*.ogg` | mp4 | native `<video controls>` |
| Anything else | (fall through) | iframe with raw URL |

You can override auto-detection with the `provider` prop if your URL doesn't match a recognized pattern (e.g. self-hosted Vimeo on a custom domain).

## Examples

```mdx Examples
<Video src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="YouTube embed" />

<Video src="https://vimeo.com/123456789" title="Vimeo embed" />

<Video src="https://loom.com/share/abc123" title="Loom recording" />

<Video src="https://www.w3schools.com/html/mov_bbb.mp4" title="Self-hosted mp4" />
```

<Video src="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="YouTube embed example" />

## Aspect ratio

Default is `16/9`. Override for square videos, vertical clips, or unusual ratios:

```mdx Aspect ratio
<Video src="..." aspectRatio="9/16" />
<Video src="..." aspectRatio="4/3" />
<Video src="..." aspectRatio="1/1" />
```

The aspect ratio is enforced via CSS `aspect-ratio` so the layout stays stable while the iframe loads — no cumulative layout shift.

## Autoplay

Pass `autoplay` to start the video immediately. Browsers block audio autoplay, so the component automatically mutes the video when autoplay is enabled.

```mdx Autoplay
<Video src="https://youtube.com/watch?v=..." autoplay />
```

<Warning>
  Use autoplay sparingly — it surprises readers and can be flagged by accessibility audits. Reserve it for hero/landing pages where the video is the main visual content.
</Warning>

## Loop (GIF mode)

Pass `loop` for short, silent product demos that should repeat forever like a GIF — it implies muted autoplay and hides the player controls. Works with self-hosted `mp4`/`webm` sources (ignored for YouTube/Vimeo/Loom iframes).

```mdx Loop
<Video
  src="/images/demos/custom-domain/custom-domain.mp4"
  poster="/images/demos/custom-domain/custom-domain-poster.png"
  loop
  aspectRatio="16/10"
/>
```

Always pair `loop` with a `poster` image — iOS won't paint a frame before playback starts, so a poster-less looping video renders as a black box on mobile while it loads.

A looping `mp4` is 10–20× smaller than the equivalent GIF with no color banding — prefer it over actual `.gif` files.

## Privacy: youtube-nocookie.com

YouTube embeds use the `youtube-nocookie.com` domain instead of `youtube.com`. This is YouTube's "enhanced privacy mode" — no cookies are set until the user starts playback. Helps with GDPR compliance and avoids cookie consent banner conflicts.

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | required | Video URL |
| `title` | `string` | — | Caption text shown below the video |
| `provider` | `"youtube" \| "vimeo" \| "loom" \| "mp4" \| "auto"` | `"auto"` | Override auto-detection |
| `aspectRatio` | `string` | `"16/9"` | CSS aspect-ratio value |
| `autoplay` | `boolean` | `false` | Start playing on mount (muted) |
| `loop` | `boolean` | `false` | GIF mode — loop forever, muted autoplay, no controls (mp4/webm only) |
| `poster` | `string` | — | Image shown before the video loads — strongly recommended with `loop`/`autoplay` (iOS shows a black box without one) |

For generic iframe embeds (CodeSandbox, StackBlitz, Figma, etc.), use [`<Embed>`](/components/embed) instead.

---

# View
Source: https://docs.nookdocs.com/components/view

Switch a whole page between languages, frameworks, or configurations.

Use `<View>` when the *entire* page differs by language or framework — not just
one code block. Each view is one variant; a switcher appears above the content
and shows one at a time.

<View title="JavaScript" icon="js">
  Install the SDK with npm:

  ```bash
  npm install @nookdocs/sdk
  ```

  Then import it and pass your key.
</View>

<View title="Python" icon="python">
  Install the SDK with pip:

  ```bash
  pip install nookdocs
  ```

  Then import it and pass your key.
</View>

````mdx
<View title="JavaScript" icon="js">
  Install the SDK with npm:

  ```bash
  npm install @nookdocs/sdk
  ```
</View>

<View title="Python" icon="python">
  Install the SDK with pip:

  ```bash
  pip install nookdocs
  ```
</View>
````

## Props

<ParamField name="title" type="string" required>
  Label for this variant. It's what the switcher shows, and what the reader's
  choice is remembered under.
</ParamField>

<ParamField name="icon" type="string">
  Icon beside the label — any name your icon library resolves.
</ParamField>

<ParamField name="iconType" type="string">
  Font Awesome style, when the icon comes from that library: `regular`,
  `solid`, `light`, `thin`, `sharp-solid`, `duotone`, `brands`.
</ParamField>

## Which component do I want?

The three look similar and solve different problems:

| Component | Scope | Use it when |
|---|---|---|
| [`<CodeGroup>`](/components/code-group) | one block | the same snippet in several languages |
| [`<Tabs>`](/components/tabs) | one block | a procedure whose steps differ |
| `<View>` | whole page | prose, code and steps all differ |

Reach for `<View>` last. A page with one differing code sample wants a code
group; splitting it into two full views duplicates every paragraph around it
and doubles what you have to keep in sync.

  Every view is present in the Markdown export, not only the selected one —
  a page offering JavaScript and Python returns both variants, each labelled
  with its title. Do not assume the first one is canonical.

## Related

- [Audience](/components/audience) — conditional content per visitor segment (different thing, despite the similar shape)
- [Code groups](/components/code-group) — per-language code samples inside one block
- [Tabs](/components/tabs) — switchable content inside one block

---

# Visibility
Source: https://docs.nookdocs.com/components/visibility

Audience-aware content blocks — separate what browsers show from what LLMs receive.

## Usage

`<Visibility>` splits content by audience. Wrap browser-only content with `for="humans"` and LLM-only content with `for="agents"`. Both live in the same MDX file — no separate pages needed.

Browsers render `for="humans"` blocks normally and hide `for="agents"`. LLM exports (copy-for-llm, `.md` endpoints) do the opposite — agent blocks are included, human blocks are stripped.

```mdx Basic usage

  <Note>
    This block is **only visible in the Markdown export**.
    Browsers hide it.
  </Note>

```

  <Note>
    This block is **only visible in the Markdown export**. Browsers hide it.
  </Note>

## When to use

**for="humans"**
- Interactive demos, embedded iframes, videos
- Visual comparisons or screenshots that don't translate to text
- UI-specific instructions: "Click the **Settings** button in the top-right corner"
- "Try it" CTAs that only make sense in a browser

**for="agents"**
- API-oriented instructions: "Call POST /v1/accounts with a valid email"
- Structured metadata: auth requirements, rate limits, response schemas
- Summary context: "This page covers X, Y, Z — the key takeaway is..."
- Disambiguation: "Note: project here means the docs project, not GitHub project"

## Example: different instructions per audience

````mdx Different instructions per audience

  To create an account, call POST /v1/accounts with email and password.
  Then create a project with POST /v1/projects passing the account token.

````

<Note>
  The agents version of this content is hidden in your browser. In the Markdown export, it reads:

  *To create an account, call POST /v1/accounts with email and password. Then create a project with POST /v1/projects passing the account token.*
</Note>

  To create an account, call POST /v1/accounts with email and password.
  Then create a project with POST /v1/projects passing the account token.

## How it works

### On the web (browser)

- `for="humans"` — renders normally, fully visible
- `for="agents"` — rendered in the DOM with `display: none` (hidden from readers)

### In LLM exports (copy-for-llm, /llms.txt)

- `for="humans"` — stripped from the exported text (marked by `data-visibility="humans"`)
- `for="agents"` — included in the export, since LLMs benefit from structured context that humans don't need inline

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `for` | `"humans" \| "agents"` | Yes | The audience for the wrapped content. `humans`: visible on the web, excluded from Markdown output. `agents`: hidden on the web, included in Markdown output. |
| `children` | `ReactNode` | Yes | Content to show or hide |

---

# Core Concepts
Source: https://docs.nookdocs.com/concepts

Understand the key concepts behind NookDocs.

NookDocs terminology, for reference when reasoning about the platform: a **project** is one documentation site (subdomain or custom domain) backed by a connected GitHub repository and a `nookdocs.config.json`. Projects belong to an **organization**, which holds team members with Owner/Editor/Viewer roles. A **deployment** is the unit triggered by each push to the configured branch (Queued → Building → Deployed, or Failed). **Pages** are MDX files synced from the repo, whose URL path derives from file location (`docs/api/auth.mdx` → `/api/auth`). This is a repo-first, push-to-deploy model — the repository is the source of truth.

## Projects

A project represents a single documentation site. Each project has:

- A **subdomain** (`my-docs.nookdocs.com`) or **custom domain** (`docs.mysite.com`)
- A connected **GitHub repository**
- A **configuration file** (`nookdocs.config.json`) defining navigation and theme
- **Pages** synced from MDX files in the repo

## Organizations

Projects belong to organizations. An organization can have multiple projects and team members with different roles:

- **Owner** — Full access, billing, delete projects
- **Editor** — Edit pages, manage deployments
- **Viewer** — Read-only access to dashboard

## Deployments

Every push to the configured branch triggers a deployment:

1. **Queued** — Webhook received, job enqueued
2. **Building** — Fetching files from GitHub, parsing MDX
3. **Deployed** — Pages synced, site updated
4. **Failed** — Something went wrong (check build log)

## Pages

Pages are MDX files synced from your repository. Each page has:

- **Path** — URL path derived from file location (e.g., `docs/api/auth.mdx` → `/api/auth`)
- **Frontmatter** — Title, description, and metadata
- **Source MDX** — The raw content
- **Version** — Support for versioned documentation

## Configuration

The `nookdocs.config.json` file in your docs base directory controls:

- **Navigation** — Sidebar structure and page ordering
- **Theme** — Colors, logo, fonts
- **API** — Base URL, playground settings, auth type
- **Footer** — Social links and footer columns

---

# Access Control
Source: https://docs.nookdocs.com/configuration/access-control

Gate readers behind a shared password — whole site or per-page private flag. Pro tier.

NookDocs supports three access modes per project:

| Mode | What happens | Plan |
|---|---|---|
| **Public** | Anyone with the URL reads every page. Default. | Free + |
| **Site password** | Visitors enter a shared password on first visit; cookie keeps them signed in for 30 days. | Pro + |
| **Per-page private** | Only pages with `private: true` in their MDX frontmatter require the password — the rest stay public. | Pro + |

## Where to manage

Project → **Settings → Access**. Pick a mode, set or rotate the password, save.

The password is stored as a PBKDF2-SHA256 hash with a per-row salt — we never see the plaintext after submit.

## How the gate works

When a tenant request comes in:

1. The docs renderer looks up the project's `access_mode`.
2. **`site` mode:** every request checks for a valid `nook_access` cookie. Missing or expired → redirect to `/access-gate?next=<url>&reason=site-gate`.
3. **`page` mode:** only checks the cookie when the requested page's frontmatter has `private: true`. Public pages stay public.
4. **Login:** `/access-gate` shows a password form. POST to `/api/v1/projects/<id>/access/login` sets the cookie and returns the visitor to the original URL.
5. **Cookie binding:** the cookie's signature uses the password hash as the HMAC key. Rotating the password invalidates every outstanding cookie immediately — no separate revocation step.

## Marking a page private

In page-level mode, drop the flag into your frontmatter:

```mdx
---
title: Internal API Reference
private: true
---

# Internal API

This page only loads for visitors who have entered the site password.
```

Pages without `private: true` continue to render publicly.

## Cookie details

| | |
|---|---|
| Name | `nook_access` |
| Scope | Set on the tenant's domain (subdomain or custom domain) |
| TTL | 30 days |
| Flags | `HttpOnly`, `Secure`, `SameSite=Lax` |
| Signature | HMAC-SHA256 of `<projectId>.<expiry>` keyed by the password hash |

Rotating the password breaks every cookie — useful when revoking access.

## Plan availability

| Plan | Site password | Per-page private |
|---|:-:|:-:|
| Free | — | — |
| Pro | ✅ | ✅ |
| Team | ✅ | ✅ |
| Enterprise | ✅ | ✅ |

## Notes

- This is a **shared-password** gate, not per-user authentication. SSO + per-user identity for docs ships in the Enterprise SSO release.
- Search engine crawlers stop at `/access-gate` — gated docs are effectively `noindex`.
- Free tier visitors still see the docs because Free defaults to public; downgrading from Pro keeps the existing mode + hash working until you switch back to public.

## For LLMs

If you're an AI agent helping a user automate access control for their NookDocs site, here's the canonical recipe:

**1. Frontmatter contract (page-mode only):**

```mdx
---
title: Internal Runbook
private: true
---
```

The `private: true` field is respected only when the project's mode is set to `page`. On `site` mode every page is gated; on `public` mode `private` is ignored.

A private page is absent from every surface that lists or quotes content, not just from the URL: the sidebar, site search (including the snippets under each result), `llms.txt`, `llms-full.txt`, the `.md` export, the RSS feed and the MCP server. A reader who cannot open the page cannot find its text anywhere either.

**2. Programmatic login (test automation, headless agents):**

```
POST https://<project-slug>.nookdocs.site/api/v1/projects/<project_id>/access/login
Content-Type: application/json

{ "password": "the-shared-password" }
```

Sets the `nook_access` cookie scoped to the tenant domain. Subsequent requests on the same cookie jar will pass the gate. Logout via `DELETE` on the same URL.

**Status codes:**

- `200` — cookie set, proceed
- `401` — wrong password
- `400` (`not_gated`) — project is `public`, login is unnecessary

**3. Crawler / indexer behaviour:**

Site-mode and page-mode gated URLs return a redirect to `/access-gate`. Crawlers that don't follow login forms will index nothing. If you're building a search index for your own org's docs, authenticate first then crawl.

**Common mistakes:**

- Don't store the cookie value in plaintext config — it's bound to the password hash and rotates automatically when the password changes.
- Don't assume `private: true` works on `public` mode — it's silently ignored. Set the project mode first.
- Cookie TTL is 30 days; refresh by calling `/access/login` again before expiry if you need long-lived access.

---

# AI Assistant
Source: https://docs.nookdocs.com/configuration/ai-assistant

Ask-AI input + right-side conversation drawer backed by Postgres full-text search + streaming LLM answers. Multilingual retrieval, bring-your-own provider key for model choice, no vector DB setup, opt-in from a single config flag.

Every project ships with an optional AI assistant. A persistent **"Ask AI" input** is docked at the bottom-right of every docs page; submitting it opens a **full-height conversation drawer on the right edge of the screen** with a streamed answer grounded in your own MDX pages — in any language. No embedding pipeline, no OpenAI key per project, no vector database to provision.

## Quick start

Turn it on with one flag and (optionally) override the model. The assistant renders on every docs page for active tenants.

```json
{
  "$schema": "https://nookdocs.com/schema.json",
  "ai": {
    "assistant": {
      "enabled": true,
      "trigger": "button",
      "label": "Ask AI",
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-latest",
      "systemPrompt": "Be concise. Only answer questions about our product. Decline off-topic questions politely."
    }
  }
}
```

## Trigger styles

`ai.assistant.trigger` controls how readers open the assistant — all three open the same full-height conversation drawer on the right edge of the screen.

<ParamField path="ai.assistant.trigger" type="'button' | 'bar' | 'input'">
  - **`button`** — an "Ask AI" button in the header, right after search (label set by `ai.assistant.label`). Cleanest; stays out of the reading flow.
  - **`bar`** — a floating pill centered at the bottom of the content, always in view as you scroll.
  - **`input`** — a docked input pill pinned to the bottom-right corner.
</ParamField>

**Leave it out and your theme decides.** Each theme carries the affordance its layout was built around — a theme with a dense two-row header tends to prefer the floating bar, one with a roomy header prefers the button — and themes that express no preference fall back to `button`. Setting `ai.assistant.trigger` yourself always wins, whichever theme you switch to later.

When the drawer opens it docks into the layout: the content, sidebar, and table of contents reflow to make room, then snap back on close. On narrow screens it opens as a bottom sheet you can drag down to dismiss.

## How retrieval works

The pipeline is a deliberate trade — keyword-based FTS instead of vector embeddings — so you don't pay per-token embedding costs and don't need to run a re-index when content changes.

1. **Translate-if-needed** — if the query contains non-ASCII characters (Turkish `ş`, Japanese kana, German umlauts, …), a short non-streaming LLM call translates it to English search keywords. ASCII-only queries skip this hop.
2. **Postgres FTS** — the `search_pages` RPC (pg_trgm GIN index) pulls the top-K relevant chunks from the tenant's pages. Sync stays real-time: the moment a page lands via webhook, it's searchable.
3. **Stream the answer** — the final LLM call streams a response back in the **original** language. Only the translated query hit the retrieval step; the user's real words are in the final prompt so the model replies in kind.
4. **Edge runtime** — the API route runs at Vercel Edge with a 60-second cap. Streams natively without buffering.

## Configure from the dashboard

**Editor → Configurations → AI & Advanced → AI Assistant** surfaces the config keys below (including a **Trigger style** dropdown). Saving writes back to `nookdocs.config.json` via a git commit, so dashboard edits and hand-edits stay in sync.

## Config reference

<ParamField path="ai.assistant.enabled" type="boolean" default="false">
  When `true`, the assistant renders on every docs page (via the configured `trigger`). Default `false` — opt-in to avoid surprise LLM bills.
</ParamField>

<ParamField path="ai.assistant.trigger" type="'button' | 'bar' | 'input'">
  How readers open the assistant — see [Trigger styles](#trigger-styles) above. Omit to follow your theme's own preference (`button` if it has none).
</ParamField>

<ParamField path="ai.assistant.label" type="string" default="&quot;Ask AI&quot;">
  Text shown on the trigger (button label / input placeholder) and as the drawer title. Defaults to a generic **"Ask AI"** — override to match your brand voice, e.g. `"Ask Acme"` or `"Docs AI"`.
</ParamField>

<ParamField path="ai.assistant.provider" type="'openai' | 'anthropic' | 'openrouter'">
  Which AI provider runs your chosen `model` — only used with [Bring-Your-Own-Key](/configuration/byok). Set it to the provider whose key you added: an OpenAI key for `openai`, an Anthropic key for `anthropic`, or your own OpenRouter account for `openrouter`. Without a BYOK key the assistant uses the AI included in your plan.
</ParamField>

<ParamField path="ai.assistant.model" type="string">
  Model identifier for the chosen `provider`. **Only applied when you bring a matching provider key** ([BYOK](/configuration/byok)); without one the assistant uses the AI included in your plan and this field is ignored. Examples: `gpt-4o` (openai), `claude-3-5-sonnet-latest` (anthropic), `anthropic/claude-3.5-sonnet` (openrouter).
</ParamField>

<ParamField path="ai.assistant.systemPrompt" type="string">
  **Persona / tone guidance only.** Layered *underneath* the built-in platform guardrails (see below) as secondary instructions — it can shape voice, add house style, or narrow scope further, but it **cannot loosen** the guardrails (it can't enable web access or off-docs answers). Capped at ~2000 characters; keep it short — every message pays the token cost.
</ParamField>

## Built-in guardrails

Every answer runs under platform rules that your `systemPrompt` sits beneath and **cannot override**:

- **Grounded in your docs only** — the model answers from the retrieved Documentation Context, not from its training data or the open web. No answer in the docs → it says so instead of guessing.
- **No external access** — it cannot browse the web, search the internet, or run code; retrieval only ever reads your own synced pages.
- **On-topic only** — off-documentation questions (general knowledge, current events, unrelated code, opinions) are politely declined and redirected to the docs.
- **No fabrication** — it won't invent URLs, endpoints, or facts; it cites sources inline as `[Title](/path)`.
- **Injection-resistant** — text inside your pages or a visitor's message is treated as data, not commands, so it can't hijack the assistant's role or scope.

These are enforced server-side on every request and are never exposed to readers.

## Usage & limits — plan vs BYOK

The assistant runs in one of two modes, decided automatically per request:

| | **Plan-included** (default) | **BYOK** — your own provider key |
|---|---|---|
| Provider | The AI included in your plan (managed by NookDocs) | Your provider — OpenAI, Anthropic, or OpenRouter |
| Model | Plan-included model (your `provider`/`model` are ignored) | Your `provider` + `model` are honored |
| Limits | Counts against your plan's **daily message quota** — when hit, the assistant replies that the limit is reached | No platform quota — your own provider account's rate limits apply |
| Billing | Included in your plan | Billed to your provider account |

So out of the box you don't manage anything — the assistant just works within your plan's daily allowance. Add your own key under **AI models** ([BYOK](/configuration/byok)) to lift the platform quota and unlock provider + model selection; keys are org-wide (shared across your projects) and stored encrypted.

## Choosing a model (BYOK)

When you bring a key, pick a provider then a model id that provider supports. Rough guidance for docs Q&A:

| Use case | Provider | Model id |
|---|---|---|
| Highest answer quality | anthropic | `claude-3-5-sonnet-latest` |
| Balanced cost/quality | openai | `gpt-4o` |
| Cheapest / fastest | openai | `gpt-4o-mini` |
| Cheap, structured docs | anthropic | `claude-3-5-haiku-latest` |
| Any model via one key | openrouter | `anthropic/claude-3.5-sonnet`, `openai/gpt-4o`, … |

Pick one and watch the Analytics → Assistant tile — if cost is too high, try a cheaper model before touching the system prompt.

## Writing a system prompt

The prompt ships above the retrieval block (`Context:\n{chunks}`) and the user's message. Three patterns that work:

**Support-engineer tone**

```text
You are Acme's support engineer. Only answer questions about Acme's
API and product. Decline off-topic questions politely. When you cite
a page, use its URL in the form /path/to/page. Be terse — 3 sentences
unless the user asks for detail.
```

**Compliance-aware**

```text
You are a documentation assistant. Never recommend code that handles
personal data without mentioning retention rules. If the question
touches medical, legal, or financial advice, redirect to human support
via support@acme.com. Always cite the source page.
```

**Persona + forbidden list**

```text
You are Zed, Acme's cheerful AI. Use friendly, second-person prose.
NEVER suggest solutions involving the legacy /v0 API — it's
deprecated. NEVER share internal-only repo URLs.
```

Keep prompts under ~500 tokens — every assistant reply pays for them.

## Deep linking

The widget reads two URL params on first paint so you can preload it from elsewhere.

```mdx
[Ask the assistant](?assistant=open)

[How do I add a custom domain?](?assistant=How%20do%20I%20add%20a%20custom%20domain%3F)
```

- `?assistant=open` — widget opens collapsed, cursor in the input.
- `?assistant=<URL-encoded query>` — widget opens with the query pre-filled AND auto-submitted.

Useful for "Ask the assistant" links inside MDX, blog posts, email campaigns, or chat support deflection.

## API

Public streaming endpoint — no auth. The widget on `{tenant}.nookdocs.site` calls it directly.

**`POST /api/v1/projects/{projectId}/assistant/ask`**

```json
{
  "query": "How do I add a custom domain?",
  "history": [
    { "role": "user", "content": "earlier message" },
    { "role": "assistant", "content": "earlier reply" }
  ]
}
```

- `query` — required, trimmed, max 2000 characters.
- `history` — optional; last 10 messages kept for context.

Response is a Server-Sent Event stream (`text/event-stream`). Each event is a JSON token chunk; a final `data: [DONE]` marker terminates the stream. Errors return `application/json` with `{ error, message }` and an HTTP 4xx/5xx code.

```typescript
const res = await fetch(`/api/v1/projects/${projectId}/assistant/ask`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "How do I deploy?" }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  process.stdout.write(decoder.decode(value));
}
```

## Analytics

The assistant emits `assistant_message` events into the `page_events` table for the **Analytics → Assistant** dashboard tile. What's logged:

- Aggregated counts per day (messages, unique sessions).
- Model slug used, duration, token count.
- The page the user was reading when they asked.

What's **not** logged:

- The query text itself.
- The reader's IP or user-agent.
- The model's response body.

If you need to inspect raw traffic for debugging, enable tenant-scoped request logs temporarily — see [analytics](/configuration/analytics).

## Limits & operational knobs

- **Query length** — 2000 characters. Longer inputs return HTTP 400.
- **History window** — last 10 messages of `history` are kept; earlier context is dropped.
- **Streaming timeout** — 60s edge-function cap. Long answers occasionally cut off; retry.
- **Concurrency** — no per-IP rate limit yet (roadmap). A misbehaving client can burn through your plan's daily quota (or, on BYOK, your provider bill); budget accordingly.
- **Disabled state** — when `enabled: false`, the endpoint returns HTTP 403 and the widget doesn't mount.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget doesn't appear on my docs site">
    Check `ai.assistant.enabled === true` in `nookdocs.config.json`. The widget won't render without an active, deployed config. Also verify the project is `status: active` — pending/failed deployments mount a bare shell.
  </Accordion>
  <Accordion title="Assistant says the daily limit is reached, or errors on credits">
    On the plan-included AI you've hit your **daily message quota** — try again tomorrow, upgrade your plan, or add your own provider key (BYOK) to remove the cap. On BYOK, your provider key may be out of credit or rate-limited — check your provider's dashboard.
  </Accordion>
  <Accordion title="Answers are always in English even when I ask in Turkish">
    Confirm the query has non-ASCII characters — the translation hop is skipped for ASCII-only queries. If you typed `ogretici` instead of `öğretici`, it looks Latin and we don't translate. Ask with accents and the response will come back in Turkish.
  </Accordion>
  <Accordion title="Assistant ignores my system prompt">
    The RAG context is appended below your prompt. Very long retrieval chunks can crowd out your persona instructions. Try tightening the system prompt to under 300 tokens and use stronger framing verbs (`NEVER`, `ALWAYS`).
  </Accordion>
</AccordionGroup>

## Privacy

The assistant is designed so tenant docs stay the only knowledge source. No IP addresses, user-agents, or reader identifiers are logged. Queries and responses are aggregated into `assistant_message` counts for the analytics dashboard only — the raw text is not persisted.

On BYOK, your chosen provider's (OpenAI / Anthropic / OpenRouter) data-retention policy applies — review it before routing sensitive queries. The plan-included AI is governed by NookDocs's vendor terms.

## Roadmap

These are on the list but not shipped:

- **pgvector embeddings** — for paraphrase-resilient retrieval (true semantic search). Planned alongside embedding-based hybrid search in FAZ 5.
- **Per-IP rate limiting** — to cap runaway clients. Will live at the edge middleware, not the API route.
- **Conversation persistence** — server-side history keyed by session cookie, so readers can pick up where they left off.
- **Contextual "Ask about this" selection** — highlight text, click "Ask the assistant" — preloads the widget with the selection as context.

Want to push something up the list? File an issue on [github.com/Codivion/NookDocs](https://github.com/Codivion/NookDocs/issues).

## Related

- [Schema reference — `ai.assistant`](/configuration/schema-reference#ai) — auto-generated field reference
- [Analytics](/configuration/analytics) — where assistant metrics surface
- [Contextual menu](/configuration/contextual) — the "Copy page" dropdown reader flow (complementary to the chat)
- [Copy for LLMs](/features/copy-for-llms) — `.md` URL + llms.txt discovery affordances

---

# Analytics
Source: https://docs.nookdocs.com/configuration/analytics

First-party page-view / search / feedback / assistant events captured by the built-in beacon. Independent of GA4 / PostHog / Plausible integrations.

NookDocs ships a first-party analytics beacon that writes anonymous events directly to the platform's own Supabase tables. The data powers the per-project Analytics dashboard and feeds the feedback backlog.

This is independent of third-party [integrations](/configuration/integrations) — GA4, PostHog, Plausible, Mixpanel, and the dozen other providers in the `integrations.*` block continue to run regardless of whether the first-party beacon is on.

## What's captured

| Event type | Emitted by | Metadata |
|---|---|---|
| `view` | Every docs page load | `referrer`, `loadTime` |
| `search` | Search modal submission | `query`, `resultCount` |
| `feedback_up` / `feedback_down` | The [Feedback widget](/configuration/feedback) | `reason`, `hasComment` |
| `assistant_open` / `assistant_message` | The AI chat bubble | `queryLength`, `responseTime` |
| `llm_export` | An LLM/agent fetching `llms.txt`, `llms-full.txt`, or a page's `.md` | `kind` |

Every event records:

- `session_id` — anonymous per-tab random string, lives in `sessionStorage`. Resets on browser close. No cookies, no localStorage, no cross-tab dedupe.
- `user_agent` (truncated to 512 chars) — server-side classified into `is_bot` + `bot_family` (`gpt` | `claude` | `perplexity` | `google` | `bing` | `other`), and into **browser / OS / device** for the tech breakdowns.
- `referrer` (from the browser's `document.referrer`).
- `path` — the normalized docs path (no host, no query string).
- **Approximate location** — `country`, and (going forward) `region` + `city` — derived from your visitor's connection at the edge. Country is available historically; region and city are captured for new visits only.
- **UTM tags** — `utm_source` / `utm_medium` / `utm_campaign` / `utm_term` / `utm_content`, read from the landing URL's query string when present. Powers the Channel / Campaign breakdowns. Captured going forward.

No IPs, no emails, no user identifiers.

## Bot detection

The ingestion endpoint classifies the user-agent into a bot family so the dashboard can split AI-mediated traffic from human traffic. Matched patterns:

- **gpt** — `GPTBot`, `ChatGPT-User`, `OAI-SearchBot`
- **claude** — `ClaudeBot`, `Claude-Web`, `anthropic-ai`
- **perplexity** — `PerplexityBot`, `Perplexity-User`
- **google** — `Googlebot`, `Google-Extended`, `GoogleOther`, `Storebot-Google`
- **bing** — `bingbot`, `BingPreview`, `msnbot`
- **other** — generic `bot`, `crawler`, `spider`, `HeadlessChrome`, `curl/`, `wget/`

The `Google-Extended` token is the AI-training opt-out UA — any scraper asking for its content still shows up in the AI column.

## Dashboard

**Dashboard → your project → sidebar → Analytics**

The page renders in a single fetch and updates when the toolbar changes:

- **Date range** — a preset menu (**Now**, **Today**, **Yesterday**, **Last 24 hours**, **Last 7 / 30 days**, **Last 12 months**, **Week / Month / Year to date**, **All time**) plus **Custom** for an arbitrary start–end range via a two-month calendar. The **‹ ›** arrows step the window back/forward by its own length. Ranges resolve in **your local timezone**, so "Today" means your midnight.
- **Now** is the live view: a rolling 30-minute window, bucketed per minute, auto-refreshing. It has no granularity selector (the grain is fixed).
- **Granularity** — for every range except **Now**, bucket the Traffic chart by **Hourly / Daily / Weekly / Monthly**. Options are constrained to grains that fit the window, so you never plot thousands of hourly points or a single monthly bar: short windows offer hourly, long windows offer weekly/monthly.

  | Window | Available grains |
  |---|---|
  | Today · Last 24 hours | Hourly |
  | Last 7 days · Week to date | Hourly · Daily |
  | Last 30 days · Month to date | Daily · Weekly |
  | up to ~4 months | Daily · Weekly · Monthly |
  | Last 12 months · Year to date · All time | Weekly · Monthly |
- **Hide bot traffic** (default on) — Strips UA-classified crawlers from view / visitor totals. The AI-vs-human split panel always shows both sides regardless of this toggle.

### Panels

| Panel | What it shows |
|---|---|
| **Views** tile | Total `view` events in the window. |
| **Unique visitors** tile | Distinct `session_id`s seen in the window. |
| **Searches** tile | Total `search` events + the top query label. |
| **Feedback** tile | Thumbs-up count + thumbs-down count. |
| **Traffic** chart | Area (views) + unique-visitor line, bucketed by the chosen granularity. Empty buckets show as zero, not gaps. |
| **Locations** | Tabbed: **Map** (world choropleth shaded by visitors, hover for the count) · **Country** · **Region** · **City** — each a ranked visitor list. |
| **Tech** | Tabbed: **Browser** · **OS** · **Device** — ranked visitor list per client, with real brand logos. |
| **Traffic sources** | Tabbed: **Channel** (Direct / Organic Search / Social / AI / Referral / Campaign…) · **Referrer** (referring site, with favicon) · **Campaign** (UTM-tagged visits) · **Keyword** (utm_term). |
| **AI-vs-human split** | Stacked horizontal bar: Human + ChatGPT + Claude + Perplexity + Google + Bing + Other bots. Per-family counts + percentages in the legend. |
| **AI & LLMs** | Crawl views, LLM exports, Ask-AI usage, and AI referrals at a glance, plus tabs for **Crawlers** (by bot), **AI pages** (what bots read most), and **Exports** (llms.txt / llms-full.txt / page `.md` fetches). |
| **Top pages** | Same ranked-list card with a **Views / Unique** metric toggle — top 10. |
| **Top searches** | Query / count / avg result count — top 10. |
| **Recent feedback** | Last 20 `page_feedback` rows with rating, reason, comment, and path. |

Every breakdown list has a sort toggle (highest-first by default) — **Visitors** on most cards, **Views / Unique** on Top pages.

### Drill-down filters

Click any breakdown row — a page, browser, OS, device, country, region, city, referrer, channel, or keyword — to filter the **entire dashboard** by it. Filters stack (AND): e.g. *Country = Germany* **and** *Browser = Firefox*. A hover **filter icon** marks clickable rows. The always-visible **Filters** control (next to the date range) shows how many are active and lets you remove them individually or **Clear all**. Totals, the traffic chart, and every breakdown all respect the active filters.

### Campaign tracking (UTM)

Tag the links that point at your docs so the **Traffic sources → Campaign / Channel** breakdowns can attribute the visits:

```text
https://docs.example.com/quickstart?utm_source=newsletter&utm_medium=email&utm_campaign=launch
```

- `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` are all picked up from the landing URL.
- The medium drives the **Channel**: `cpc`/`ppc`/`paid` → *Paid Search*, `email`/`newsletter` → *Email*, otherwise → *Campaign*.
- Tags are read from the **landing page** (the first page opened with them) and recorded **going forward** — past visits aren't backfilled.

### AI &amp; LLM insights

NookDocs is built for the LLM era, so the dashboard surfaces how AI actually uses your docs — not just human pageviews:

- **Crawlers** — views from AI/search bots, grouped by family (ChatGPT/GPT, Claude, Perplexity, Google, Bing, other). Same classification as the AI-vs-human split.
- **AI pages** — which pages those bots read most, so you can see what AI is learning from your docs.
- **Exports** — how often LLMs/agents fetch your machine-readable surfaces: `llms.txt`, `llms-full.txt`, and per-page Markdown (`/<page>.md`). Each fetch is counted.
- **AI referrals** — humans who arrived from an AI assistant. Visits carrying an AI source (e.g. ChatGPT appends `?utm_source=chatgpt.com`) or an AI referrer are classified as the **AI** channel in Traffic sources, not lumped into Campaign/Referral.
- **Ask AI** — opens and questions on your docs' built-in assistant.

All of these respect the active drill-down filters and date range.

### Data latency

Events land in `page_events` within ~1 second of a page view (edge ingestion). The dashboard reads directly from live tables — no materialized-view rebuild to wait for. For tenants with high volume, per-day rollups (materialized views) are on the roadmap.

## Configure from the dashboard

**Dashboard → your project → Editor → Configurations → AI & Advanced → Analytics**

One toggle: **First-party beacon** (default on). Turning it off disables first-party event capture entirely for this tenant — useful for regulated industries or readers who want to rely on their own analytics stack.

## Config reference

<ParamField name="analytics.enabled" type="boolean" default="true">
  Enable the first-party beacon. When `false`, no events are written to `page_events` / `visitors` and the Analytics dashboard shows "No data" for this project.
</ParamField>

## Example

```json
{
  "analytics": {
    "enabled": false
  }
}
```

## API

### Ingestion

**`POST /api/v1/projects/:projectId/events`** — public ingestion.

```json
{
  "event_type": "view",
  "path": "/guides/auth",
  "session_id": "abc123…",
  "metadata": { "referrer": "https://google.com/", "loadTime": 142 }
}
```

Returns `202 Accepted` on success, `400` on malformed input, `404` on unknown project. Payload caps: 500-char path, 2 KB metadata JSON. CORS open — the endpoint accepts cross-origin POSTs from any tenant subdomain.

### Summary (dashboard-only)

**`GET /api/v1/projects/:projectId/analytics/summary?from=…&to=…&unit=day&tz=Europe/Istanbul&bots=excluded`** — dashboard read.

Requires a JWT or API-key `Authorization: Bearer …` header. Returns a single JSON blob with `totals`, `timeseries`, `aiSplit`, `topPages`, `topSearches`, `geo` (`countries` / `regions` / `cities`), `tech` (`browsers` / `os` / `devices`), `sources` (`channels` / `referrers` / `campaigns` / `keywords`), `llm` (`usage` / `crawlers` / `pages` / `exports`), and `recentFeedback` — everything the Analytics page renders. Query params:

- `from`, `to` — ISO timestamps bounding the window `[from, to)`. Default: last 30 days.
- `unit` — timeseries bucket grain: `hour` | `day` | `week` | `month` (default `day`).
- `tz` — IANA timezone for bucket boundaries (default `UTC`). The dashboard sends the viewer's zone.
- `bots` — `excluded` (default) | `included`. When `excluded`, view / visitor totals and breakdowns skip UA-classified bots.

## Retention

- **Raw events** (`page_events`) — 90 days. The platform runs `prune_old_page_events()` on a schedule.
- **Daily aggregates** — summary rollups (planned) retain indefinitely.
- **Visitors** (`visitors`) — no time cap; the composite `(project_id, session_id)` PK dedupes sessions across reloads.

## Privacy stance

The beacon does NOT record:

- IP addresses. Approximate country / region / city come from coarse, pre-resolved geolocation at the edge — the raw IP is never read or stored.
- Cookies or localStorage identifiers.
- Query strings beyond the normalized path.
- Session state that persists across browser restarts (sessionStorage clears on close).

`Do Not Track` is honored via the `analytics.enabled` toggle — tenants that need wholesale opt-out flip it off and ship.

---

# API reference
Source: https://docs.nookdocs.com/configuration/api

Configure your OpenAPI-backed API docs — base URL, spec location, playground, authentication, and request proxy.

NookDocs renders interactive API reference pages directly from your OpenAPI (or AsyncAPI) spec. Your config tells the renderer three things:

1. **Where the spec lives** (`api.openapi`)
2. **Where real requests go** (`api.baseUrl`)
3. **How the playground authenticates** (`api.auth`)

Everything else — routing, try-it UI, schema flattening, code samples — the platform handles.

## Quick start

```json
{
  "api": {
    "baseUrl": "https://api.example.com/v1",
    "openapi": "openapi.json",
    "playground": "interactive",
    "auth": {
      "type": "bearer",
      "name": "Authorization"
    }
  }
}
```

Commit `openapi.json` to your docs base directory — the `api.openapi` path is relative to the base (the repo root for a single-repo project, or a subfolder for a monorepo). On next sync, every endpoint in the spec becomes a page under the navigation entries you reference via `/api-reference/<tag>/<operation-id>` paths (see [Navigation](/configuration/navigation) for how to surface them in the sidebar).

## Fields

<ParamField name="api.baseUrl" type="string">
  Prefixed to every endpoint path in the generated pages + playground. Omit for specs whose `servers[]` already carries full URLs. If both are set, `api.baseUrl` wins.
</ParamField>

<ParamField name="api.openapi" type="string | string[]">
  OpenAPI 3.x spec path — relative to your docs base (e.g. `openapi.json`) or absolute URL (`https://api.example.com/openapi.json`). Supports JSON and YAML. Pass an array to merge multiple specs into one reference tree.
</ParamField>

<ParamField name="api.asyncapi" type="string | string[]">
  AsyncAPI 3.x spec (channels, pub/sub, WebSocket) — same path rules as `openapi`. **Roadmap:** the key is accepted and validated today, but no pages are generated from it yet. Set it now if you want the path recorded; nothing renders until support ships.
</ParamField>

<ParamField name="api.playground" type="'interactive' | 'simple' | 'none'" default="&quot;interactive&quot;">
  - `"interactive"` — full "Try it" with live requests against `baseUrl`. Pre-fills auth headers, shows response bodies inline, copies as curl.
  - `"simple"` — form-preview only, no network. Useful for APIs with destructive endpoints or private environments. <Tooltip tip="Currently renders as interactive; the send button is not yet disabled.">Roadmap</Tooltip>
  - `"none"` — read-only docs. Skip the playground entirely; readers copy the snippet.
</ParamField>

<ParamField name="api.auth.type" type="'bearer' | 'apiKey' | 'basic'">
  Pre-fills the auth header in the playground. Omit for public APIs.
</ParamField>

<ParamField name="api.auth.name" type="string">
  Header name. Default `Authorization` for `bearer` + `basic`. Explicit for `apiKey` (e.g. `X-API-Key`, `X-Api-Token`).
</ParamField>

<ParamField name="api.proxy" type="boolean" default="false">
  When `true`, playground requests route through `https://<your-slug>.nookdocs.site/api/proxy/*` instead of hitting your `baseUrl` directly. Use this when your API doesn't set CORS headers for the docs origin — browsers block the direct call; the proxy strips the CORS barrier.
</ParamField>

## Multiple specs, one reference

Large APIs often split endpoints across files (public vs admin vs webhooks). Point `openapi` at an array:

```json
{
  "api": {
    "openapi": [
      "specs/public.yaml",
      "specs/admin.yaml",
      "specs/webhooks.yaml"
    ]
  }
}
```

The platform merges them into one tree, tagged by operation. If two specs declare the same `operationId`, the LAST entry wins — we emit a build warning so you catch it.

## Authentication in the playground

The playground reads `api.auth` and pre-fills the request headers:

- **`bearer`** → `Authorization: Bearer <token>` with an input for the token.
- **`apiKey`** → `<name>: <key>` with an input for the key.
- **`basic`** → `Authorization: Basic <base64(user:pass)>` with inputs for user + pass.

The token — and path parameter values like a project `id` — carry over when the reader switches endpoints, so they only type them once per session. Both live only in the reader's browser (sessionStorage: cleared when the tab closes, never sent to our servers). For per-user personalized tokens, see [Personalization](/configuration/site-settings#ai-assistant) (planned).

## Navigation integration

API pages auto-slot into navigation groups that declare an `openapi` field. Example:

```json
{
  "navigation": [
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Projects",
          "openapi": "openapi.json",
          "pages": ["/api-reference/projects/list", "/api-reference/projects/create"]
        }
      ]
    }
  ]
}
```

The `pages` can reference auto-generated paths (`/api-reference/<tag>/<operation-id>`) or you can skip `pages` and the renderer auto-fills every endpoint that matches the group's `openapi` filter.

See the full [Navigation reference](/configuration/navigation) for tab-scoped OpenAPI bindings, filtering by tag, and per-version API docs.

## Troubleshooting

## SDK code samples

NookDocs surfaces SDK usage directly in the per-endpoint code card (the right column on every API reference page). Reader picks a language tab and sees the real `client.projects.list()` call instead of a raw `fetch` example.

**Source: the `x-codeSamples` OpenAPI extension** — a ReDoc convention that Speakeasy, Stainless, and Fern all populate automatically when they generate SDKs. You can also hand-write samples directly in your spec.

```yaml
paths:
  /projects:
    get:
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: |
            import { NookDocs } from "@nookdocs/sdk";
            const client = new NookDocs({ apiKey: process.env.CODIV_API_KEY });
            const projects = await client.projects.list();
        - lang: python
          source: |
            from nookdocs import Client
            client = Client(api_key=os.environ["CODIV_API_KEY"])
            projects = client.projects.list()
```

On the endpoint page the code card tab row becomes:

```
cURL · Node.js · SDK  |  Python · SDK  |  cURL · Python · JavaScript · PHP · Go · Java · Ruby
         ^ from x-codeSamples                ^ auto-generated HTTP templates
```

Tabs labeled *"· SDK"* come from the spec; the rest are our per-language HTTP templates as a fallback for languages the tenant didn't cover.

### Supported `lang` values

| `lang`                     | Displayed as  | Prism grammar |
|----------------------------|---------------|---------------|
| `javascript`, `typescript` | JavaScript / TypeScript | `javascript` / `typescript` |
| `node`, `nodejs`           | Node.js       | `javascript`  |
| `python`, `py`             | Python        | `python`      |
| `go`, `golang`             | Go            | `go`          |
| `ruby`                     | Ruby          | `ruby`        |
| `php`                      | PHP           | `php`         |
| `java`                     | Java          | `java`        |
| `csharp`, `c#`, `dotnet`   | C# / .NET     | `csharp`      |
| `rust`                     | Rust          | `rust`        |
| `swift`                    | Swift         | `swift`       |
| `kotlin`                   | Kotlin        | `kotlin`      |
| `bash`, `shell`, `curl`    | Bash / cURL   | `bash`        |

Unknown slugs pass through verbatim and use the slug itself as both label and Prism grammar.

### Label disambiguation

When a single language has multiple samples for the same endpoint (e.g. separate examples for "List unwatered plants" vs "List potted plants"), set `label` on each entry — the tab row shows the label instead of just the language name.

### No config needed

`x-codeSamples` lives in the OpenAPI spec itself; the `nookdocs.config.json#api` block doesn't need any SDK-specific keys. Push the spec with samples, next sync picks them up, tabs appear automatically.

<AccordionGroup>
  <Accordion title="Playground returns CORS error">
    Browsers block cross-origin API calls unless the target server sends `Access-Control-Allow-Origin`. Two fixes:
    - Set `api.proxy: true` — routes through our server, bypassing CORS.
    - Add `Access-Control-Allow-Origin: https://<your-slug>.nookdocs.site` on your API.
  </Accordion>
  <Accordion title="Auth header not pre-filled">
    Check `api.auth.name` matches what your API expects. A common mistake is setting `type: "apiKey"` with `name: "Authorization"` — the UI then writes `Authorization: <key>` instead of `Authorization: Bearer <key>`. Use `bearer` with `name: "Authorization"` for Bearer tokens; `apiKey` with a distinct header name for API keys.
  </Accordion>
  <Accordion title="Merged spec conflicts">
    When two specs define the same `operationId`, we emit a build warning and keep the last one. Rename conflicting operations or split them into non-overlapping specs.
  </Accordion>
</AccordionGroup>

---

# Audit log
Source: https://docs.nookdocs.com/configuration/audit-log

Append-only stream of every privileged mutation in your org. Team tier.

NookDocs records every privileged mutation in your org to an append-only **audit log** — projects created, domains added, webhooks changed, access passwords rotated, plans flipped, SSO config saved. Use it for compliance, debugging, and dispute resolution.

## Where to view

Project → **Settings → Audit log**. Filter by action, paginate through history (50 events per page).

## What's recorded

Every entry includes:

| Field | Meaning |
|---|---|
| `actor_email` | Who took the action (or `system` for automated events) |
| `action` | A stable string id like `webhook.created` or `access.mode_changed` |
| `resource_type` + `resource_id` | What was touched |
| `metadata` | Action-specific JSON payload (e.g. webhook URL, new access mode) |
| `ip_address` + `user_agent` | When available, the request origin |
| `created_at` | UTC timestamp |

## Tracked actions

- `project.created` / `project.deleted`
- `domain.added` / `domain.removed`
- `access.mode_changed` / `access.password_rotated`
- `webhook.created` / `webhook.updated` / `webhook.deleted` / `webhook.tested`
- `plan.changed` / `plan.overrides_set`
- `member.invited` / `member.removed`
- `sso.config_saved` / `sso.enabled` / `sso.disabled`
- `config.saved` (nookdocs.config.json commits)
- `writing_agent.run`

The action list grows as new mutating endpoints ship — every callsite that changes org state writes here.

## Plan availability

| Plan | Audit log read access |
|---|:-:|
| Free | — |
| Pro | — |
| Team | ✅ |
| Enterprise | ✅ |

The **write** path is unconditional — events are recorded for every plan including Free. So when you upgrade to Team, the historical trail is already there waiting.

## Retention

- 90 days on Team
- Unlimited on Enterprise (with optional CSV export and webhook delivery)

## Roadmap

- CSV export
- Webhook delivery (`audit.event` event type)
- SIEM-friendly streaming (S3 / Splunk HEC)

These ship in the Enterprise security release.

## For LLMs

If you're an AI agent helping a user inspect or reason about audit events, here's the canonical recipe:

**1. Action vocabulary (stable strings):**

| Domain | Action ids |
|---|---|
| Projects | `project.created`, `project.deleted` |
| Domains | `domain.added`, `domain.removed` |
| Access | `access.mode_changed`, `access.password_rotated` |
| Webhooks | `webhook.created`, `webhook.updated`, `webhook.deleted`, `webhook.tested` |
| Plan | `plan.changed`, `plan.overrides_set` |
| Members | `member.invited`, `member.removed` |
| SSO | `sso.config_saved`, `sso.enabled`, `sso.disabled` |
| Config | `config.saved` (covers MDX config + branding + showcase consent) |
| Agent | `writing_agent.run` |

Filter by these strings on the audit panel — they're stable across releases.

**2. Event shape (read-only — every event includes):**

```
actor_email   — who triggered it (or null/system for automated events)
action        — one of the strings above
resource_type — "project" | "webhook" | "showcase_consent" | etc.
resource_id   — identifier of the thing acted upon
metadata      — action-specific JSON (e.g. webhook URL, new access mode)
created_at    — ISO 8601 UTC timestamp
```

**3. Common compliance questions you can answer from the log:**

- "Who deleted project X on date Y?" → filter `project.deleted` + match `resource_id`
- "Did anyone change SSO settings last quarter?" → filter `sso.config_saved` for the date range
- "How often was access password rotated?" → count `access.password_rotated` per project

**Common mistakes:**

- Don't write to the audit log directly — it's an append-only platform-managed stream. Customer mutations land here automatically.
- Don't assume the absence of an action means it didn't happen — it means it wasn't a tracked mutation. Read-only operations (page views, search) are NOT in the audit log; they're in the analytics stream.
- Retention is plan-dependent (Team 90d, Enterprise unlimited). Old events may not appear if you query past the retention window.

---

# Brand assets
Source: https://docs.nookdocs.com/configuration/brand

Pluggable brand manifest — logos, favicons, OG images, PWA manifest — declared once, resolved everywhere.

`config.brand` centralises every brand-sized asset in one declarative object. The platform reads this once per render and wires up favicons, OG image, Apple touch icon, PWA manifest, and the logos you reference from `colors.logo` — no per-feature configuration scattered across the config file.

<Note>
  The four icons most sites need — favicon, dark favicon, Apple touch icon and
  PWA icon — are editable under **Configurations → Branding**, beside the logo
  fields. The rest of the block (colours, typography, asset families) is
  JSON-only and is preserved untouched when you save from the panel.
</Note>

<Note>
  Only `root`, `name`, and `favicon.dir` are required. Every other field is
  written when you have something to put in it — an imported site typically has
  a `.ico`, an apple-touch tile and two or three PNGs, and no SVG masters or
  maskable variants at all.
</Note>

## Minimal example

Three fields carry the paths; everything else is optional and written only when
you have the file:

```json
{
  "brand": {
    "root": "/brand",
    "name": "acme",
    "favicon": {
      "dir": "favicon",
      "ico": "favicon.ico",
      "png": { "32": "favicon-32x32.png" }
    }
  }
}
```

Files resolve as `${root}/${favicon.dir}/${file}` — the block above points at
`/brand/favicon/favicon.ico`. Declare only the icons you actually ship: a site
with a `.ico` and one PNG writes those two and leaves the SVG entries out.

## A complete block

```json
{
  "brand": {
    "root": "/brand-assets",
    "name": "acme",
    "shortName": "Acme",
    "description": "Acme documentation",
    "colors": {
      "brand": { "light": "#3b82f6", "dark": "#60a5fa" },
      "text":  { "light": "#0f172a", "dark": "#f8fafc" },
      "background": { "light": "#ffffff", "dark": "#0f172a" }
    },
    "themeColor": { "light": "#ffffff", "dark": "#0f172a" },
    "backgroundColor": { "light": "#ffffff", "dark": "#0f172a" },
    "typography": {
      "family": "Inter",
      "weight": 500,
      "fallback": "system-ui, -apple-system, sans-serif"
    },
    "assets": {
      "wordmark": {
        "dir": "wordmark",
        "file": "acme-wordmark",
        "hasSvg": true,
        "hasTheme": true,
        "pngSizes": ["h40", "h80", "h120", "h240"]
      },
      "icon": {
        "dir": "icon",
        "file": "acme-icon",
        "hasSvg": true,
        "hasTheme": false,
        "pngSizes": [32, 48, 64, 128, 256, 512]
      },
      "maskable": {
        "dir": "maskable",
        "file": "acme-maskable",
        "hasSvg": false,
        "hasTheme": false,
        "pngSizes": [192, 512, 1024]
      },
      "og": {
        "dir": "og",
        "file": "acme-og",
        "hasSvg": false,
        "hasTheme": true,
        "pngSizes": ["1200x630"],
        "dimensions": { "width": 1200, "height": 630 }
      }
    },
    "favicon": {
      "dir": "favicon",
      "ico": "favicon.ico",
      "svg": "favicon.svg",
      "svgLight": "favicon-light.svg",
      "svgDark": "favicon-dark.svg",
      "apple": "apple-touch-icon.png",
      "maskable512": "maskable-512.png",
      "png": { "16": "favicon-16.png", "32": "favicon-32.png", "48": "favicon-48.png" },
      "androidChrome": { "192": "android-chrome-192.png", "512": "android-chrome-512.png" }
    },
    "manifest": "/manifest.webmanifest"
  }
}
```

## Fields

<ParamField name="brand.root" type="string" required>
  Absolute URL prefix for every asset. All `assets.*.dir` paths resolve under this prefix. Example: `"/brand-assets"` means the wordmark SVG lives at `/brand-assets/wordmark/acme-wordmark.svg`.
</ParamField>

<ParamField name="brand.name" type="string" required>
  Slug-form brand name. Used in generated filenames + metadata.
</ParamField>

<ParamField name="brand.shortName" type="string">
  PWA short name (shown on Android / iOS home screens when the docs site is installed).
</ParamField>

<ParamField name="brand.description" type="string">
  PWA manifest description + generic fallback description when `seo.description` is absent.
</ParamField>

<ParamField name="brand.colors" type="BrandColorPair">
  Themed colours used by the platform for generated assets:
  - `brand.light` / `brand.dark` — the primary accent pair (same values you'd set in `colors.light` / `colors.dark`, duplicated here so brand pipelines have a standalone source).
  - `text.light` / `text.dark` — default body text colour for generated OG images.
  - `background.light` / `background.dark` — page background colour for OG images.
</ParamField>

<ParamField name="brand.themeColor" type="{ light: string; dark: string }">
  Browser chrome colour (`<meta name="theme-color">`). Controls the mobile Safari/Chrome top bar colour per light/dark mode.
</ParamField>

<ParamField name="brand.backgroundColor" type="{ light: string; dark: string }">
  PWA manifest `background_color`. Shown while the docs site is loading in a PWA shell.
</ParamField>

<ParamField name="brand.typography" type="BrandTypography">
  Default site typography. `family` + `weight` + `fallback` are emitted as the base `font-family` CSS variable.
</ParamField>

<ParamField name="brand.assets" type="BrandAssetPattern map">
  Four required asset families, each described by a `BrandAssetPattern`:

  - `wordmark` — full logo with text. Sizes typed as height (`h40` → 40px tall).
  - `icon` — square app icon. Sizes typed as pixel dimensions (`32` → 32×32).
  - `maskable` — PWA maskable icon (safe-area padding included). Sizes `192`, `512`, `1024`.
  - `og` — Open Graph preview image. Must carry `dimensions: { width, height }` (usually 1200×630).

  Each pattern:
  - `dir` — subfolder under `brand.root`.
  - `file` — filename stem (no extension, no size suffix).
  - `hasSvg` — set `true` if an SVG version is present under `{root}/{dir}/{file}.svg`.
  - `hasTheme` — set `true` if you ship separate light/dark SVG variants (`{file}-light.svg`, `{file}-dark.svg`).
  - `pngSizes` — array of PNG sizes you've generated; the renderer links to each as `{file}-{size}.png`.
</ParamField>

<ParamField name="brand.favicon" type="BrandFaviconSet">
  The block is optional; when present, `dir` is required — it is the directory
  every filename below resolves against. Each entry names a file you ship, and
  the ones you do not ship are simply left out.

  Favicons follow a standard layout:

  - `ico` — classic `favicon.ico` (16x16, 32x32, 48x48 multi-size).
  - `svg` — adaptive SVG favicon (uses `@media (prefers-color-scheme)` internally).
  - `svgLight` / `svgDark` — explicit per-scheme SVG for browsers that want a strict media query.
  - `png` — `{16, 32, 48}` PNGs for legacy browsers.
  - `apple` — `apple-touch-icon.png` (180x180).
  - `androidChrome` — `{192, 512}` PNGs for the PWA.
  - `maskable512` — maskable 512x512 PNG (separate from the regular 512 because of safe-area padding).
</ParamField>

<ParamField name="brand.manifest" type="string">
  Absolute path to the `.webmanifest` file. Usually `/manifest.webmanifest` at your repo root.
</ParamField>

## Building the asset set — exact files, sizes, folder

Everything lives under `{brand.root}/` in your repo's `public/` folder, in five
subfolders. This is exactly how NookDocs ships its own brand (the live
reference). With `"root": "/brand-assets"` and the `name`-stemmed example
`acme`:

```
public/brand-assets/
├── manifest/
│   └── manifest.json              ← brand.manifest → "/brand-assets/manifest/manifest.json"
├── favicon/                       ← brand.favicon  — RENDERED on every page (tab + PWA icons)
│   ├── favicon.svg                ← adaptive (light+dark via inline @media)
│   ├── favicon-light.svg          ← explicit light
│   ├── favicon-dark.svg           ← explicit dark
│   ├── favicon.ico                ← 16+32+48 multi-res
│   ├── favicon-16x16.png
│   ├── favicon-32x32.png
│   ├── favicon-48x48.png
│   ├── apple-touch-icon.png       ← 180×180  (iOS home screen)
│   ├── android-chrome-192x192.png ← 192×192  (Android / PWA)
│   ├── android-chrome-512x512.png ← 512×512  (PWA splash)
│   └── maskable-icon-512.png      ← 512×512  (safe-area padding)
├── icon/                          ← brand.assets.icon — square app icon, themed
│   ├── acme-icon-light.svg
│   ├── acme-icon-dark.svg
│   ├── acme-icon-light-16.png … acme-icon-light-1024.png
│   └── acme-icon-dark-16.png  … acme-icon-dark-1024.png
├── maskable/                      ← brand.assets.maskable — padded PWA icon, themed
│   ├── acme-maskable-light.svg / acme-maskable-dark.svg
│   └── acme-maskable-{light,dark}-{192,512,1024}.png
├── og/                            ← brand.assets.og — social preview, themed
│   ├── acme-og-light.svg / acme-og-dark.svg
│   └── acme-og-{light,dark}-1200x630.png
└── wordmark/                      ← brand.assets.wordmark — full logo, themed (by height)
    ├── acme-wordmark-light.svg / acme-wordmark-dark.svg
    └── acme-wordmark-{light,dark}-{h40,h80,h120,h240,h480}.png
```

### Naming convention

- **Favicon dir** uses fixed, standard names (the values you put in
  `brand.favicon`). These are exactly what
  [realfavicongenerator.net](https://realfavicongenerator.net) produces.
- **Themed families** (`icon` / `maskable` / `og` / `wordmark`) follow
  `{file}-{theme}.svg` and `{file}-{theme}-{size}.png`, where `theme` is
  `light` / `dark` (because `hasTheme: true`) and `size` is each entry in that
  family's `pngSizes`. Icon/maskable sizes are pixels; wordmark sizes are
  heights (`h40` = 40px tall); OG is `1200x630`.

### What renders where

| Family | Rendered on tenant `<head>`? | Sizes | Light/Dark |
|---|---|---|---|
| `favicon` + `manifest` | **Yes** — tab icon, iOS icon, PWA install | ico, 16/32/48, 180, 192, 512, maskable 512 | SVG light/dark; PNGs single |
| `icon` | App/PWA icon sources | 16, 32, 48, 64, 96, 128, 180, 192, 256, 384, 512, 1024 | both |
| `maskable` | Maskable PWA icon | 192, 512, 1024 | both |
| `og` | Social preview | 1200×630 | both |
| `wordmark` | Logo in richer layouts | h40, h80, h120, h240, h480 | both |

<Note>
  Only the **favicon set + manifest** are emitted into the page `<head>` for a
  tenant site. The themed `icon` / `maskable` / `og` / `wordmark` families round
  out a complete brand package (and feed richer layouts), but your visible
  navbar logo comes from [`colors.logo`](/configuration/site-settings) and your
  social preview can come from [`seo.ogImage`](/optimize/seo). Ship the favicon
  set for the essentials; add the rest for a full brand.
</Note>

### Generate from masters

Provide a **light** and a **dark** master SVG per family (square for
favicon/icon/maskable; wide for wordmark; 1200×630 for og), then scale with
`rsvg-convert` + `imagemagick`:

```bash
ROOT=public/brand-assets

# Favicon (single-variant PNGs; SVGs are light/dark) — from a square master
for s in 16x16 32x32 48x48; do rsvg-convert -w ${s%x*} -h ${s#*x} favicon.svg > $ROOT/favicon/favicon-$s.png; done
rsvg-convert -w 180 -h 180 favicon.svg > $ROOT/favicon/apple-touch-icon.png
rsvg-convert -w 192 -h 192 favicon.svg > $ROOT/favicon/android-chrome-192x192.png
rsvg-convert -w 512 -h 512 favicon.svg > $ROOT/favicon/android-chrome-512x512.png
rsvg-convert -w 512 -h 512 favicon-maskable.svg > $ROOT/favicon/maskable-icon-512.png
convert $ROOT/favicon/favicon-16x16.png $ROOT/favicon/favicon-32x32.png $ROOT/favicon/favicon-48x48.png $ROOT/favicon/favicon.ico

# Themed families — repeat per theme + size (icon shown; same loop for maskable/og/wordmark)
for t in light dark; do
  for s in 16 32 48 64 96 128 180 192 256 384 512 1024; do
    rsvg-convert -w $s -h $s acme-icon-$t.svg > $ROOT/icon/acme-icon-$t-$s.png
  done
done
```

### Manifest

`brand.manifest` points at the `.webmanifest` you ship:

```json public/brand-assets/manifest/manifest.json
{
  "name": "Acme Docs",
  "short_name": "Acme",
  "icons": [
    { "src": "/brand-assets/favicon/android-chrome-192x192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/brand-assets/favicon/android-chrome-512x512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/brand-assets/favicon/maskable-icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ],
  "theme_color": "#0f172a",
  "background_color": "#0f172a",
  "display": "standalone"
}
```

<Note>
  No `brand` block? Leave it out and your site uses
  [`seo.favicon`](/optimize/seo) (a single SVG) for the tab icon — nothing
  breaks. The `brand` block is the upgrade path to the full favicon + PWA +
  maskable + OG set. **The starter template ships without a brand block on
  purpose** — so add this folder + block only when you're ready.
</Note>

## Why this is a block, not individual keys

Older config formats scattered brand metadata across `colors.logo.light`, `seo.ogImage`, `seo.favicon`, `theme.colors`, PWA manifest fields, and Apple touch icon. Every feature had to reach into a different key to find the right asset, and cross-feature consistency was manual. The `brand` block is **one source of truth** — change the primary colour in one place and favicons, OG images, and themed wordmarks all track it.

The root-level `colors.logo.light` / `colors.logo.dark` are still accepted (backwards compat for projects that haven't adopted `brand`), but `brand.assets.wordmark` is the authoritative path when both are set.

---

# BYOK (Bring Your Own LLM Key)
Source: https://docs.nookdocs.com/configuration/byok

Use your own OpenAI / Anthropic / OpenRouter API keys for writing agent + AI assistant calls. Enterprise tier.

By default, every NookDocs LLM call (writing agent, AI assistant) uses the AI included in your plan, managed by NookDocs. Enterprise customers can flip this — paste your own provider key and calls bill to your account instead. Compliance teams love it (data residency, SOC 2 vendor list), cost-conscious teams use it to consolidate spend.

## Where to manage

Project → **Settings → AI / Models**. Three providers supported today: **OpenAI**, **Anthropic**, **OpenRouter**.

Paste a key per provider, click **Save**. Keys are encrypted with **AES-256-GCM** before hitting storage and we display only the last 4 characters after save (we never see plaintext again).

## Plan availability

| Plan | BYOK |
|---|:-:|
| Free | — |
| Pro | — |
| Team | — |
| Enterprise | ✅ |

## How resolution works

Every LLM call from your org runs this resolver:

1. Look up `org_llm_credentials` for an active key matching the call's provider.
2. If found, decrypt and use it.
3. If missing, fall back to the platform key.

The fallback is per-provider — having an OpenAI key on file doesn't switch your Anthropic calls; both providers route independently.

## Removing a key

Click the trash icon on the row. Future calls fall back to the platform key immediately. The encrypted ciphertext is hard-deleted (no soft-delete or recovery — paste again to re-enable).

## Billing impact

| State | Who pays |
|---|---|
| BYOK active for provider | Your provider account |
| BYOK missing for provider | NookDocs platform pool — counted against your monthly `agent_credits_monthly` quota |
| BYOK key invalid (rotated, revoked) | Call fails with provider-specific error; no automatic fallback today (planned for next release) |

If you're using BYOK to bypass the platform quota, expect that limit to relax once you've been on Enterprise for ≥30 days — contact your CSM for a quota override.

## For LLMs

If you're an AI agent helping a user wire BYOK, here's the canonical recipe:

**1. Three providers supported:**

- `openai` — paste a key from `platform.openai.com/api-keys`
- `anthropic` — paste a key from `console.anthropic.com → API keys`
- `openrouter` — paste a key from `openrouter.ai/keys`

**2. Saving a key:**

UI flow only — there is no public REST endpoint for setting credentials (server actions only, requiring an authenticated dashboard session). This is by design: pasting a long-lived API key into an automation is a security smell.

**3. Resolution semantics:**

- Per-provider, per-org. OpenAI key on file does NOT route Anthropic calls.
- Active flag respected — paused keys behave as if missing.
- Plaintext decrypted server-side only at the moment of the LLM call. Telemetry: `last_used_at` updated on each successful resolve.
- Removing a key is a hard delete (no soft-delete, no recovery).

**Common mistakes:**

- Don't store the key client-side and send it on each request — the server-side actions encrypt it once at save time. Sending it again is redundant and risky.
- Don't expect platform fallback when a BYOK key 401s — current behaviour is to fail the call. Customer must remove or replace the key.
- Pasting an invalid key still saves successfully (we don't validate before storage). Verify by triggering one writing-agent run and checking the response.

---

# Configuration File
Source: https://docs.nookdocs.com/configuration/config-file

Reference for nookdocs.config.json options.

NookDocs is configured via a `nookdocs.config.json` file in your docs base directory (the repo root for a single repo, or a subfolder for a monorepo).

## Minimal example

```json
{
  "name": "My Docs",
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["introduction"]
    }
  ]
}
```

## Full reference

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Your documentation site name |
| `theme` | `object` | No | Theme customization |
| `navigation` | `array` | Yes | Sidebar navigation groups |
| `api` | `object` | No | API playground configuration |
| `versions` | `string[]` | No | Version labels |
| `redirects` | `array` | No | URL redirects |
| `footer` | `object` | No | Footer configuration |

## Navigation

Navigation is defined as an array of groups:

```json
{
  "navigation": [
    {
      "group": "Group Name",
      "pages": [
        "page-one",
        "page-two",
        {
          "group": "Nested Group",
          "pages": ["nested/page"]
        }
      ]
    }
  ]
}
```

Page paths are relative to the docs base directory, without the file extension.

## Theme

`theme` is the slug of a built-in theme. It sets the shell layout and the full
token set — colors, spacing, typography scale, code-block framing.

```json
{
  "theme": "cedar"
}
```

Ten ship today: `larch` (the default), `cedar`, `obsidian`, `birch`, `oak`,
`cypress`, `ember`, `sage`, `slate`, `terminal`. See
[Theme](/configuration/theme) for what each looks like. Older configs may name
`maple`, `classic`, `modern` or `minimal` — legacy aliases that still resolve
(maple→larch, classic→cedar, modern→ember, minimal→sage), but write the
canonical slug.

## Brand overrides

The theme decides how the site is built; these keys override what it chose.
They sit beside `theme`, not inside it.

```json
{
  "theme": "cedar",
  "colors": {
    "primary": "#0f766e",
    "logo": {
      "light": "/logo-light.svg",
      "dark": "/logo-dark.svg"
    }
  },
  "typography": {
    "fontFamily": "Geist Sans"
  },
  "codeBlockStyle": "inset"
}
```

| Key | What it overrides |
|---|---|
| `colors.primary` | Accent color for buttons, links and focus rings. `colors.light` / `colors.dark` set it per mode. |
| `colors.logo` | Logo images per mode, plus `href` for where the logo links. |
| `typography` | Font family and scale. |
| `codeBlockStyle` | How code blocks are framed, when you want a different treatment from the theme's. |

<Note>
  `theme` took an object of these keys in an earlier format. It takes a slug
  now, and the overrides moved to the top level — a config using the old shape
  fails validation with "theme must be one of the built-in slugs". Run
  `validate_{project}_config` through [MCP](/integrations/mcp) to check a file
  before committing it.
</Note>

---

# Content Root
Source: https://docs.nookdocs.com/configuration/content-root

Tell NookDocs which folder in your repo holds your docs files.

## Why this exists

By default NookDocs syncs every `.md` and `.mdx` file at your **docs base directory** (where `nookdocs.config.json` lives — the repo root for a single repo, or a subfolder for a monorepo). Repo-meta files — `README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `LICENSE`, `CHANGELOG.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md` — are auto-excluded, and a `.nookignore` file (gitignore-style, relative to the base) lets you exclude more.

This stops random markdown files in your repo from accidentally becoming public docs pages and cluttering your search results.

## Default behavior (flat)

```json
{
  "name": "My Docs",
  "navigation": [...]
}
```

With no `contentRoot` set, your content lives **flat** directly at the docs base — no `docs/` subfolder. If your repo looks like this:

```
my-repo/
├── nookdocs.config.json
├── README.md              ← auto-excluded
├── introduction.mdx       → /introduction
├── api/
│   └── auth.mdx           → /api/auth
└── src/
    └── README.md          ← outside the base, ignored
```

The two `.mdx` files at the base end up on your docs site; `README.md` is auto-excluded.

## Custom content root (optional override)

Prefer to nest your content in a subfolder under the base? Set `contentRoot` explicitly:

```json
{
  "name": "My Docs",
  "contentRoot": "docs/",
  "navigation": [...]
}
```

Now `docs/intro.mdx` becomes `/intro`, and an `intro.mdx` left at the base is ignored.

<Warning>
  The `contentRoot` value **must end with a trailing slash**. `"docs"` is rejected by the validator — use `"docs/"`.
</Warning>

## Common patterns

<CardGroup cols={2}>
  <Card title="Flat (default)" icon="file">
    No `contentRoot`. Content `.mdx` sits directly at the docs base — works for most repos. No config needed.
  </Card>
  <Card title="Nested in a subfolder" icon="folder-open">
    Set `"contentRoot": "docs/"` to keep content under a `docs/` folder beneath the base.
  </Card>
  <Card title="Content folder" icon="file-text">
    Coming from a static site generator? Try `"contentRoot": "content/"`.
  </Card>
  <Card title="Monorepo" icon="folder-open">
    The docs base itself is the monorepo subfolder — set when you connect the repo (and editable later in Settings → Git → Monorepo). `contentRoot` then nests further under that base if you want.
  </Card>
</CardGroup>

<Warning>
  `contentRoot` is relative to the docs base, so the two **add up**. If your base
  is already `docs` and you also set `"contentRoot": "docs/"`, we look for
  `docs/docs/` — and if that folder doesn't exist, nothing syncs. With a base
  set, leave `contentRoot` out unless your content really is nested one level
  deeper.
</Warning>

## What gets excluded

Repo-meta files are auto-excluded even when they sit at the docs base:

- `README.md`, `CONTRIBUTING.md`, `AGENTS.md`
- `LICENSE` / `LICENSE.md`, `CHANGELOG.md`
- `SECURITY.md`, `CODE_OF_CONDUCT.md`

A `.nookignore` file at the docs base (gitignore-style patterns, relative to the base) excludes anything else you don't want published. And of course, anything outside the docs base (or outside `contentRoot`, if set) is never synced.

## Troubleshooting

### "My README is showing up as a page"

It shouldn't — `README.md` is auto-excluded. If some other stray markdown is appearing, add it to `.nookignore` at the docs base. After the next push, the page will be removed automatically because it's no longer in the filtered file list.

### "I want to exclude some files"

Add gitignore-style patterns to a `.nookignore` file at the docs base. Repo-meta files (README/CONTRIBUTING/AGENTS/LICENSE/CHANGELOG/SECURITY/CODE_OF_CONDUCT) are excluded for you already.

### "Where is the file path → URL mapping documented?"

The docs base (and `contentRoot`, if set) is stripped, the `.mdx` extension is removed, and `index` becomes `/`. See the [Navigation guide](/configuration/navigation) for the full URL mapping rules.

---

# Contextual menu
Source: https://docs.nookdocs.com/configuration/contextual

The "Copy page" dropdown at the top of every page — Copy MD, Open in ChatGPT / Claude / Perplexity, MCP server links, and tenant-defined custom actions.

Every docs page carries a **Copy page** split button in the top-end corner of the header. The primary action copies raw MDX; the chevron opens a dropdown with 14 built-ins across 4 sections plus tenant-defined custom entries.

Full component reference: [/llm-first/contextual-menu](/llm-first/contextual-menu).

This page is the `nookdocs.config.json` config reference for the `contextual` block.

## Sections

| Section key       | Built-in items |
|-------------------|----------------|
| `content`         | Copy MD, Copy for LLMs, View raw, Copy URL |
| `ai-platforms`    | ChatGPT and Claude by default; Perplexity, Google AI Studio, Grok and Windsurf available via `contextual.platforms` |
| `mcp`             | MCP server URL, install command, Cursor / VS Code deep links |
| `custom`          | Tenant-defined entries from `contextual.options` |

## Configure from the dashboard

**Editor → Configurations → Layout → Contextual menu**

- **Built-in sections** — 4 checkboxes. Uncheck to hide a section from the dropdown. Leaving all checked (the default) is equivalent to omitting `contextual.enabled`.
- **AI platforms** — 6 checkboxes. ChatGPT and Claude are checked by default; check others to offer them too.
- **Custom items** — repeater with Title, Subtitle, Icon, URL. The URL field accepts template variables.

## Config reference

<ParamField name="contextual.enabled" type="string[]">
  Whitelist of built-in sections to show. Omit to show all four. Unknown values are ignored. Accepted: `"content"`, `"ai-platforms"`, `"mcp"`, `"custom"`.
</ParamField>

<ParamField name="contextual.platforms" type="string[]">
  Which AI platforms the `ai-platforms` section offers:
  `chatgpt`, `claude`, `perplexity`, `aistudio`, `grok`, `windsurf`.

  Omit and the reader sees ChatGPT and Claude. A menu listing seven
  destinations makes them read a list instead of clicking the one they came
  for, so the default is the pair most readers reach for — name the ones you
  want to change that.

  Ignored when `enabled` leaves `ai-platforms` out; that hides the section
  entirely.

  ```json
  {
    "contextual": {
      "platforms": ["chatgpt", "claude", "perplexity"]
    }
  }
  ```
</ParamField>

<ParamField name="contextual.options" type="Array<{title, description?, icon?, href}>">
  Tenant-defined entries appended under the `Custom` section. Each has `title`, optional `description`, optional Lucide `icon` name, and `href` — the URL that opens on click.
</ParamField>

<ParamField name="contextual.display" type="'header' | 'toc'" default="header">
  Where to render the menu. `"header"` (default) puts it in the top-end corner of the h1 row. `"toc"` (queued for a follow-up release) moves it into the right TOC sidebar.
</ParamField>

### Template variables in `href`

The `href` field supports four tokens that get replaced at click time:

| Variable | Resolves to |
|----------|-------------|
| `$page`  | URL-encoded full page URL |
| `$path`  | URL-encoded page path |
| `$title` | URL-encoded page title |
| `$mdx`   | URL-encoded MDX source (use sparingly — long pages produce massive URLs) |

## Example

```json
{
  "contextual": {
    "enabled": ["content", "ai-platforms", "custom"],
    "options": [
      {
        "title": "Report an issue",
        "description": "Open a GitHub issue pre-filled with the page path",
        "icon": "bug",
        "href": "https://github.com/acme/docs/issues/new?title=Feedback+on+$path"
      },
      {
        "title": "Open in Linear",
        "description": "Create a Linear ticket from this page",
        "icon": "external-link",
        "href": "https://linear.app/acme/new?title=Improve%20$title&description=$page"
      }
    ]
  }
}
```

---

# Custom CSS
Source: https://docs.nookdocs.com/configuration/custom-css

Per-tenant CSS injected into the docs site head. Pro tier.

The `customCss` key on `nookdocs.config.json` is appended to the `<head>` of every rendered page. Because it cascades **over** the theme + typography rules, you can override anything our default theme ships without forking the renderer.

## Where to edit

Two ways — **they edit the same field**: the dashboard panel reads and writes the `customCss` key of your `nookdocs.config.json`, so there is exactly one source of truth whichever path you use.

### From the dashboard

Project → **Settings → Custom CSS**. Type or paste your CSS, then **Save** — it commits to `nookdocs.config.json` on the active branch and your live site picks it up on the next sync (seconds).

Pasted a minified one-liner? Hit **Format** — it pretty-prints to one declaration per line with nested blocks (`@media` etc.) indented, leaving strings and `url(...)` values untouched.

### From git

Edit `nookdocs.config.json` directly:

```json
{
  "name": "your-docs",
  "customCss": "#docs-root .prose-docs h2 { letter-spacing: -0.02em; } .docs-sidebar { background: #fafafa; }"
}
```

Multiline strings work — JSON allows `\n` literal escapes. Whatever you commit shows up in the dashboard panel on next load, and vice versa.

## Scoping recommendations

To avoid surprises in future renderer updates, scope your selectors to the docs surface:

- `#docs-root` — wraps the entire docs renderer
- `.prose-docs` — the long-form content area
- `.docs-sidebar` — the left navigation
- `.docs-header` — the top bar
- `.docs-toc` — the right-side table of contents (when shown)

## What you can override

- Colors (background, text, accents) beyond what `colors` in config.json gives you
- Spacing, typography sizes, font features
- Section borders, dividers, callout backgrounds
- Code-block themes (target `.shiki` or `.prose-docs pre`)
- Sidebar collapsing animations, hover states
- Print styles via `@media print`

## What's NOT supported

- **JavaScript.** Custom CSS only — no `<script>` injection. JS injection is intentionally out of scope to keep the surface XSS-safe across multi-tenant environments.
- **External @font-face imports** — host fonts on a domain that allows cross-origin (or use `typography.fontFamily` in config.json which routes through Google Fonts).

## Plan availability

| Plan | Custom CSS |
|---|:-:|
| Free | — |
| Pro | ✅ |
| Team | ✅ |
| Enterprise | ✅ |

## Save behaviour

- The save button only enables when the CSS has changed.
- A successful save commits to `nookdocs.config.json` on the current branch (Editor → Branch selector). Production previews follow your usual deploy flow.
- If you downgrade from Pro to Free, your existing CSS keeps rendering — the editor just becomes read-only / locked. Removing the field requires re-upgrading first.

## For LLMs

If you're an AI agent generating custom CSS for a NookDocs site, here's the canonical recipe:

**1. Config field contract:**

```json
{
  "name": "your-docs",
  "customCss": "#docs-root .prose-docs h2 { letter-spacing: -0.02em; } .docs-sidebar { background: #fafafa; }"
}
```

Multi-line literal escapes (`\n`) are valid JSON. Field omission is the same as empty string — attribution renders normally.

**2. Stable selector palette to target:**

```
#docs-root             — entire docs renderer wrapper (highest scope)
.prose-docs             — long-form MDX content
.docs-sidebar          — left navigation rail
.docs-header           — top bar
.docs-toc              — right table of contents
.prose-docs code       — inline code
.prose-docs pre        — code blocks
```

Always scope new rules to one of these — never use bare element selectors (`h1 { ... }`) since they leak into the editor and dashboard chrome.

**3. JS injection is rejected.** This field is CSS only. `<style>`/`<script>` tags, `@import`, and `expression(...)` are rejected at save time (HTTP 422 with the reason), and tag-escape sequences are additionally neutralized at render time. Write bare CSS rules.

**4. External fonts:**

Use `typography.fontFamily` (separate config key) rather than `@font-face` inside customCss. The platform's font loader resolves licensing + preconnect hints automatically.

**Common mistakes:**

- Don't propose `!important` chains — the cascade order is documented and stable; specificity tweaks are enough.
- Don't override CSS custom properties prefixed `--docs-*` without checking the theme guide — those are tracked across themes and breaking them disables theme switching.
- Save commits the change to `nookdocs.config.json` in the user's repo. There is no separate "preview" step before commit.

---

# Feedback widget
Source: https://docs.nookdocs.com/configuration/feedback

Thumbs + reason radios at the bottom of every docs page. Submissions flow into the analytics dashboard and optionally open GitHub issues.

Every docs page renders a feedback block under the "Last updated" line:

1. **Collapsed state** — the prompt (default *"Was this page helpful?"*) plus **Yes** / **No** thumbs.
2. **Expanded state** (after picking a thumb) — a radio list of reasons, an optional comment field for *"Something else"*, and **Cancel** / **Submit feedback** buttons.
3. **Submitted state** — a single line of confirmation: *"Thanks for your feedback"*.

Submissions land in two places:

- `page_feedback` table — the triage backlog (rating, reason, comment, status).
- `page_events` table — a `feedback_up` / `feedback_down` event so the [Analytics dashboard](/configuration/analytics) totals stay consistent without joins.

## Triage dashboard

**Dashboard → your project → sidebar → Feedback**

The Feedback page renders the full `page_feedback` backlog (up to 200 rows per request) with a status tab filter (Open / Resolved / Dismissed / All), a rating dropdown (All / Thumbs up / Thumbs down), and counts. Each row shows:

- Rating icon, status pill, timestamp, page path.
- Reason key (when selected) + free-text comment (when provided).
- Linked issue URL (when GitHub auto-issue created one).

Row actions:

- **Resolve** — marks the feedback done, stamps `resolved_at`, hides from Open.
- **Dismiss** — marks as noise, hides from Open.
- **Reopen** — reopens a resolved / dismissed row and clears `resolved_at`.

Transitions hit `PATCH /api/v1/projects/:projectId/feedback/:feedbackId` with the new status.

Bots (GPTBot, ClaudeBot, PerplexityBot, Googlebot, Bingbot, generic crawlers) are dropped silently — thumbs from a scraper isn't signal.

## Configure from the dashboard

**Dashboard → your project → Editor → Configurations → AI & Advanced → Feedback widget**

The panel has four controls:

- **Enable** — toggle the widget on or off for this tenant.
- **Prompt** — override the default *"Was this page helpful?"* text. Leave empty for the default.
- **Auto-open GitHub issue on negative feedback** — when on, a thumbs-down with a comment opens an issue on the connected managed repo. Requires the project to have a PAT / GitHub App installation linked.
- **Issue labels** — comma-separated labels applied to auto-opened issues. Default: `docs-feedback`.

Reason options (the radio lists shown after Yes / No) are still customizable, but currently only by hand-editing `nookdocs.config.json#feedback.positiveReasons` and `negativeReasons`. See below.

## Config reference

<ParamField name="feedback.enabled" type="boolean" default="true">
  Toggle the widget per tenant. When `false`, no "Was this helpful?" block renders.
</ParamField>

<ParamField name="feedback.prompt" type="string">
  Override the top prompt. Default: *"Was this page helpful?"*.
</ParamField>

<ParamField name="feedback.positiveReasons" type="Array<{id, label}>">
  Radio options shown after Yes. Each entry has a stable `id` (written to `page_feedback.reason`, so don't rename these once you ship) and a display `label`.
</ParamField>

<ParamField name="feedback.negativeReasons" type="Array<{id, label}>">
  Radio options shown after No. Use this to surface your team's own improvement themes.
</ParamField>

<ParamField name="feedback.github.autoIssue" type="boolean" default="false">
  Open a GitHub issue when a thumbs-down submission carries a non-empty comment. Requires a connected managed repo.
</ParamField>

<ParamField name="feedback.github.labels" type="string[]" default='["docs-feedback"]'>
  Labels attached to auto-opened issues.
</ParamField>

## Defaults

When `feedback.positiveReasons` / `negativeReasons` are omitted, the widget uses these:

**Yes — Glad it landed. What worked?**

- Solved what I opened it for
- Examples matched my actual use case
- Easy to scan and skim
- Depth and tone felt right
- Something else

**No — Got it. What would have helped?**

- Needs a runnable code sample
- Missing context I had to guess at
- Too much jargon for my level
- Feels out of date with the product
- Something else

Picking *Something else* reveals a free-text comment field (2000 char cap).

## Example — custom reasons

```json
{
  "feedback": {
    "enabled": true,
    "prompt": "Was this guide clear?",
    "positiveReasons": [
      { "id": "clear-example", "label": "The example matched my use case" },
      { "id": "complete", "label": "All the information was there" },
      { "id": "something-else", "label": "Something else" }
    ],
    "negativeReasons": [
      { "id": "missing-example", "label": "Needs a code example for my language" },
      { "id": "outdated", "label": "Content is outdated" },
      { "id": "hard-to-find", "label": "I couldn't find what I was looking for" },
      { "id": "something-else", "label": "Something else" }
    ],
    "github": {
      "autoIssue": true,
      "labels": ["docs-feedback", "triage"]
    }
  }
}
```

## API

**`POST /api/v1/projects/:projectId/feedback`** — public ingestion.

```json
{
  "path": "/guides/auth",
  "rating": "up",
  "reason": "easy-to-find",
  "comment": "Great explanation of the OAuth flow.",
  "session_id": "abc123…"
}
```

Returns `202 Accepted` on success. Rate-limit and retention live in the platform's ingestion layer — no client-side tuning required.

## Privacy

No IPs, no cookies, no localStorage. The widget reads a per-tab `sessionStorage` id that the analytics beacon also uses, so one session's view + feedback tie together on the dashboard without tracking anyone across sessions.

---

# GEO / AEO
Source: https://docs.nookdocs.com/configuration/geo

Structured data, AI-crawler control, and citation signals — the config that makes your docs citable by AI Overviews, Perplexity, and ChatGPT.

`config.geo` controls **Generative & Answer Engine Optimization**: the JSON-LD
NookDocs emits, which AI crawlers may access your site, and the entity/citation
signals AI engines use. Everything is **on by default** — a site with no `geo`
block still emits sensible structured data. For the writing patterns that earn
citations, see the [GEO guide](/guides/geo).

## Example

```json
{
  "geo": {
    "structuredData": true,
    "faqSchema": true,
    "organization": {
      "name": "Acme, Inc.",
      "logo": "/logo/dark.svg",
      "sameAs": [
        "https://x.com/acme",
        "https://github.com/acme",
        "https://www.linkedin.com/company/acme"
      ]
    },
    "aiCrawlers": "allow",
    "llmsTxt": {
      "intro": "Acme builds developer infrastructure. These docs cover the API, SDKs, and self-hosting.",
      "contact": "docs@acme.com"
    },
    "topics": ["api", "sdk", "authentication"],
    "audience": "developers",
    "license": "CC-BY-4.0"
  }
}
```

## Fields

<ParamField path="geo.structuredData" type="boolean" default="true">
  Emit JSON-LD on every page: `TechArticle`, `BreadcrumbList`, `Organization`,
  and `WebSite`. Set `false` to disable entirely.
</ParamField>

<ParamField path="geo.faqSchema" type="boolean" default="true">
  Emit `FAQPage` JSON-LD from a page's frontmatter `faq: [{ q, a }]`. The most
  cited format in answer engines.
</ParamField>

<ParamField path="geo.organization" type="object">
  Your publisher entity, used across the JSON-LD graph.
  - `name` — defaults to your site name.
  - `logo` — absolute or repo-relative URL; defaults to `colors.logo`.
  - `sameAs` — profile URLs (X, GitHub, LinkedIn, Wikipedia…) that identify the
    same entity. Strongly improves entity recognition for AI engines.
</ParamField>

<ParamField path="geo.aiCrawlers" type="'allow' | 'block' | Record<string, boolean>" default="allow">
  AI crawler access, written into `/robots.txt`:
  - `"allow"` (default) — AI bots crawl normally (covered by the global rule).
  - `"block"` — deny all known AI bots (GPTBot, ClaudeBot, Google-Extended,
    PerplexityBot, CCBot, Bytespider, Amazonbot, …).
  - An object — per-bot control, e.g. `{ "GPTBot": true, "CCBot": false }`.
</ParamField>

<ParamField path="geo.llmsTxt" type="{ intro, contact }">
  Enriches the auto-generated [`/llms.txt`](/optimize/llms-txt): an `intro`
  paragraph at the top and a `Contact:` line. The page index itself is always
  generated automatically.
</ParamField>

<ParamField path="geo.topics" type="string[]">
  Primary topics / entities your site covers. Surfaced as JSON-LD `about` on
  every page.
</ParamField>

<ParamField path="geo.audience" type="string">
  Target audience, e.g. `"developers"`.
</ParamField>

<ParamField path="geo.license" type="string">
  Content reuse / citation license (e.g. `"CC-BY-4.0"`). Emitted on
  `TechArticle` so AI engines know how your content may be reused.
</ParamField>

<Note>
  `/llms.txt`, `/llms-full.txt`, per-page `/<slug>.md`, `sitemap.xml`, and
  canonical tags are all generated automatically — you don't author them. The
  `geo` block tunes and enriches; it doesn't replace them.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="GEO guide" href="/guides/geo" icon="sparkles">
    The writing patterns that earn AI citations.
  </Card>
  <Card title="SEO" href="/optimize/seo" icon="search">
    Classic on-page SEO that complements GEO.
  </Card>
  <Card title="llms.txt" href="/optimize/llms-txt" icon="bot">
    The auto-generated LLM crawler index.
  </Card>
  <Card title="Brand" href="/configuration/brand" icon="palette">
    Logo, favicon, and OG image used in the JSON-LD.
  </Card>
</CardGroup>

---

# Integrations overview
Source: https://docs.nookdocs.com/configuration/integrations

Wire any of 16 third-party scripts (13 analytics, 1 privacy, 2 support) into every docs page via a single config key. No custom code, no bundler changes.

`integrations` is a key-value map where the key names the provider and the value is that provider's account ID. The platform injects the right `<script>` tag on every docs page — tenants with no integrations ship zero extra JS.

Every integration loads with `strategy="afterInteractive"` so it never blocks first paint. The exception is **[Osano](/integrations/privacy/osano)** (cookie consent), which loads `beforeInteractive` so it can gate other scripts if the reader hasn't consented.

## Quick start

```json
{
  "integrations": {
    "ga4": "G-XXXXXXXXXX",
    "posthog": "phc_abc123...",
    "plausible": "docs.example.com",
    "intercom": "abc123xy",
    "osano": "ABC-123-XYZ"
  }
}
```

Or edit from **Configurations → AI & Advanced → Integrations** in the dashboard.

## Analytics (14)

| Provider | Config key | What to set |
|---|---|---|
| [Google Analytics 4](/integrations/analytics/google-analytics-4) | `ga4` | Measurement ID (`G-XXXXXXXXXX`) |
| [Google Tag Manager](/integrations/analytics/google-tag-manager) | `gtm` | Container ID (`GTM-XXXXXXX`) |
| [PostHog](/integrations/analytics/posthog) | `posthog` | Project API key (`phc_abc123...`) |
| [Plausible](/integrations/analytics/plausible) | `plausible` | Tracked domain (`docs.example.com`) |
| [Fathom](/integrations/analytics/fathom) | `fathom` | Site ID (`ABCDEFGH`) |
| [Mixpanel](/integrations/analytics/mixpanel) | `mixpanel` | Project token (`abc123def456...`) |
| [Segment](/integrations/analytics/segment) | `segment` | Write key (`abcxyz123`) |
| [Amplitude](/integrations/analytics/amplitude) | `amplitude` | API key (`abc123...`) |
| [Microsoft Clarity](/integrations/analytics/clarity) | `clarity` | Project ID (`abc123def4`) |
| [Hotjar](/integrations/analytics/hotjar) | `hotjar` | Site ID (`1234567`) |
| [LogRocket](/integrations/analytics/logrocket) | `logrocket` | App ID (`org/app`) |
| [TrueStat](/integrations/analytics/truestat) | `truestat` | Site key (`ts_cd067fec0d8b204f35f1`) |
| [Pirsch](/integrations/analytics/pirsch) | `pirsch` | ID (`abc123`) |
| [Heap](/integrations/analytics/heap) | `heap` | App ID (`1234567890`) |

All thirteen coexist on the same site without collision — ship GA4 + PostHog + Hotjar on the same page and each gets clean events.

## Cookie consent (1)

| Provider | Config key | What to set |
|---|---|---|
| [Osano](/integrations/privacy/osano) | `osano` | Customer / site ID (`ABC-123-XYZ`) |

## Support widgets (2)

| Provider | Config key | What to set |
|---|---|---|
| [Intercom](/integrations/support/intercom) | `intercom` | App ID (`abc123xy`) |
| [Front Chat](/integrations/support/front-chat) | `frontChat` | Chat ID (`abc123`) |

## Privacy + security

- **No server-side pipe.** The platform doesn't proxy events through our servers — each script runs in the reader's browser using the account ID you provided.
- **Secrets.** Analytics IDs are not secrets; they're public by design. Don't put anything sensitive in `integrations.*`.
- **CSP.** If you enforce a Content Security Policy, allowlist each provider's script origin. Per-provider pages list the exact URL.
- **Consent.** When `osano` is configured it loads before every other integration so consent decisions can gate downstream scripts.

## Personalization (planned)

Intercom, Mixpanel, Amplitude, and PostHog support user identification (`intercom('boot', { user_id, name, email })`). When authenticated-user personalization ships, you'll be able to pipe reader identity into these integrations automatically — no code.

## Related

- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing
- [Analytics dashboard](/configuration/analytics) — first-party events, independent of these integrations
- [Site settings](/configuration/site-settings) — banner, SEO, redirects, footer, navbar

---

# Legal
Source: https://docs.nookdocs.com/configuration/legal

Copyright line plus privacy, terms, and cookie links in your site footer — declared once in config, rendered on every page.

`config.legal` adds a compliance row to your site footer: a copyright line and
links to your privacy policy, terms of service, and cookie policy. Declared
once, rendered beneath every page.

<Note>
  Legal links render in the **site footer**, so they only show when the footer
  is visible. Set `footer.style` to `page` or `columns` — or just provide a
  `legal` block and a minimal footer renders automatically to carry it.
</Note>

## Example

```json
{
  "legal": {
    "copyright": "© {year} Acme, Inc. All rights reserved.",
    "privacyUrl": "/legal/privacy",
    "termsUrl": "/legal/terms",
    "cookieUrl": "/legal/cookies",
    "links": [
      { "label": "Imprint", "href": "/legal/imprint" },
      { "label": "Accessibility", "href": "/legal/accessibility" }
    ]
  }
}
```

## Fields

<ParamField path="legal.copyright" type="string">
  Copyright line shown in the footer. The token `{year}` expands to the current
  year, so `"© {year} Acme, Inc."` always stays current. When set, this
  **replaces** the default `© {year}` line. It does not affect the separate "Powered by NookDocs" attribution, which sits at the opposite end of the footer — see [white labeling](/configuration/white-labeling).
</ParamField>

<ParamField path="legal.privacyUrl" type="string">
  Privacy policy URL. Rendered as a **Privacy** link in the footer legal row.
</ParamField>

<ParamField path="legal.termsUrl" type="string">
  Terms of service URL. Rendered as **Terms**.
</ParamField>

<ParamField path="legal.cookieUrl" type="string">
  Cookie policy URL. Rendered as **Cookies**.
</ParamField>

<ParamField path="legal.links" type="{ label, href }[]">
  Extra legal links appended after Privacy / Terms / Cookies — imprint,
  accessibility statement, DPA, and so on.
</ParamField>

## Hosting the pages

The URLs can point anywhere:

- **Inside your docs** — write `legal/privacy.mdx` (etc.) as normal pages and
  link `"/legal/privacy"`. They sync and render like any other content.
- **External** — link an absolute URL to a policy hosted elsewhere
  (`"https://acme.com/privacy"`).

<Tip>
  Cookie-consent banners are a separate concern — see
  [integrations](/configuration/integrations) for Osano. `legal` only renders
  the footer links + copyright.
</Tip>

---

# Navigation
Source: https://docs.nookdocs.com/configuration/navigation

Organize your docs with flat groups or tabbed sections in nookdocs.config.json.

## Two navigation modes

NookDocs supports two ways of organizing your sidebar. Pick whichever matches the shape of your docs — the platform figures out the rest.

<CardGroup cols={2}>
  <Card title="Flat groups" icon="list">
    A single sidebar with top-level groups. Best for small-to-medium docs sites with one audience.
  </Card>
  <Card title="Tabbed sections" icon="layout">
    Top-navbar tabs switch the sidebar between independent sections. Best when you have distinct audiences (e.g. Guides vs. API Reference).
  </Card>
</CardGroup>

## Flat groups

The simplest configuration. One sidebar, multiple groups, each group holds a list of pages.

```json
{
  "navigation": [
    {
      "group": "Getting Started",
      "pages": [
        "introduction",
        "quickstart"
      ]
    },
    {
      "group": "Configuration",
      "pages": [
        "configuration/config-file",
        "configuration/custom-domain"
      ]
    }
  ]
}
```

The sidebar renders every group in order. Breadcrumbs show the parent group as an eyebrow label above the h1. Prev/next walks the full flat sequence.

### Where the labels come from

You list paths here, not names — each page's label comes from its own
frontmatter `title`. When a title is too long for the sidebar (roughly 23
characters at the default width), set `sidebarTitle` on that page to give the
rail a shorter form while the page keeps its full heading:

```yaml
---
title: Data Processing Agreement (DPA)
sidebarTitle: DPA
---
```

A label that still doesn't fit is truncated with an ellipsis, and hovering it
shows the full text. See [frontmatter](/content/frontmatter) for the rest of the
per-page fields.

## Tabbed sections

When you have distinct top-level sections that deserve their own sidebar, wrap each one in a tab:

<Note>
  Where the tabs are drawn is the theme's call, not something you configure per
  site. Most themes run them as a strip across the header; `larch` lists them
  down the rail, and `slate` — which has no header at all — collapses them into
  a single dropdown at the top of the rail. The same `navigation` array produces
  all three. See the [theme catalog](/configuration/theme#where-your-navigation-lands).
</Note>

```json
{
  "navigation": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "pages": ["introduction", "quickstart"]
        },
        {
          "group": "Configuration",
          "pages": ["configuration/config-file"]
        }
      ]
    },
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Endpoints",
          "pages": [
            "api/authentication",
            "api/projects",
            "api/deployments"
          ]
        }
      ]
    }
  ]
}
```

The header renders `Documentation` and `API Reference` as tabs in the top navbar. Clicking a tab switches the sidebar to show only that tab's groups. The active tab is detected from the current URL — whichever tab contains the page you are reading gets the primary-color underline.

<Tip>
  Tabbed mode is all-or-nothing at the top level. Either every top-level entry is a tab, or every top-level entry is a group. Mixing the two is not supported and will cause only the tabs to render.
</Tip>

## Prev/next within tabs

In tabbed mode, prev/next stay **inside the current tab**. The Next button on the last Documentation page does not jump to the first API Reference page — each tab is a self-contained reading sequence.

In flat mode, prev/next walks the entire navigation as one list.

## File path convention

Entries in `pages` are file paths relative to your docs base directory, **without the `.mdx` extension**. The platform converts them to URL paths automatically:

| Entry | File | URL |
|---|---|---|
| `introduction` | `introduction.mdx` | `/introduction` |
| `api/auth` | `api/auth.mdx` | `/api/auth` |
| `guides/deploy` | `guides/deploy.mdx` | `/guides/deploy` |

In the default flat layout, page refs map straight to the file path at the base. A `docs/` prefix is only used if you set `contentRoot: "docs/"` to nest your content in a subfolder.

## Nested groups

Put a group object **inside** another group's `pages` array to create a sub-section. The children render in declaration order, so a sub-group placed between two pages keeps the page after it below it in the sidebar:

```json
{
  "group": "Deploy",
  "pages": [
    "deploy/subdomain",
    "deploy/custom-domain",
    {
      "group": "Host at a subpath",
      "icon": "route",
      "collapsible": true,
      "root": "deploy/subpath",
      "pages": [
        "deploy/cloudflare",
        "deploy/vercel",
        "deploy/aws-cloudfront"
      ]
    },
    "deploy/monorepo"
  ]
}
```

This renders:

```
Deploy
├─ Subdomain
├─ Custom domain
├─ Host at a subpath   ← sub-group (indented, with a left rail)
│   ├─ Cloudflare
│   ├─ Vercel
│   └─ AWS Route 53 + CloudFront
└─ Monorepo            ← stays after the sub-group
```

A sub-group is just a `group` object, so it accepts every group field — `icon`, `tag`, `root`, `collapsible`, and even further-nested `pages`. Children stay in the flattened order, so prev/next and breadcrumbs flow through the sub-group's pages.

<Tip>
  Give the sub-group a `root` (see [Group root pages](#group-root-pages)) so clicking its label opens an overview page — combined with `interaction.drilldown: true` (the default), the label becomes a real link instead of just a toggle.
</Tip>

### Collapsible groups

Set `collapsible: true` on a group to give it a chevron toggle even when your theme keeps groups expanded — handy for a long sub-section you want collapsed by default. It overrides the theme's `collapsibleGroups` behavior for that one group; omit it to inherit the theme default. (Set `expanded: true` alongside it to start open but still allow collapsing.)

```json
{
  "group": "Host at a subpath",
  "collapsible": true,
  "root": "deploy/subpath",
  "pages": ["deploy/cloudflare", "deploy/vercel"]
}
```

## Full example

A real multi-audience docs config — the NookDocs dogfood setup uses this exact pattern:

```json
{
  "name": "NookDocs",
  "navigation": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "pages": ["introduction", "quickstart", "concepts"]
        },
        {
          "group": "Features",
          "pages": [
            "features/search",
            "features/theme-toggle",
            "features/reading-experience",
            "features/code-blocks",
            "features/copy-for-llms"
          ]
        },
        {
          "group": "Configuration",
          "pages": [
            "configuration/config-file",
            "configuration/custom-domain",
            "configuration/navigation",
            "configuration/theme"
          ]
        }
      ]
    },
    {
      "tab": "Components",
      "groups": [
        {
          "group": "Basics",
          "pages": [
            "components/callout",
            "components/card",
            "components/code-group",
            "components/tabs",
            "components/accordion"
          ]
        },
        {
          "group": "Layout",
          "pages": ["components/steps", "components/frame"]
        },
        {
          "group": "API docs",
          "pages": [
            "components/param-field",
            "components/response-field"
          ]
        }
      ]
    },
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Endpoints",
          "pages": [
            "api/authentication",
            "api/projects",
            "api/deployments"
          ]
        }
      ]
    }
  ]
}
```

## Per-entry extras

Groups and tabs accept optional fields that the renderer surfaces in the sidebar. All of them are optional — a config that only uses `group` + `pages` keeps rendering the same way it did before.

### Badges with `tag`

Drop a short string next to a group or tab label. Good for highlighting new sections or deprecations.

```json
{
  "navigation": [
    {
      "group": "Payments",
      "tag": "BETA",
      "pages": ["payments/overview", "payments/webhooks"]
    }
  ]
}
```

Tags longer than 8 characters truncate with an ellipsis.

That is the route for a **group or tab** badge — it lives in the config, because
a group is a config entry and has no file of its own.

A **page** can carry its own badge in frontmatter instead, the same way it
carries its title and icon:

```mdx
---
title: Batch
icon: boxes-stacked
tag: Beta
---
```

Both routes render the same pill. Where a page declares one and the navigation
entry sets another, the navigation entry wins — it is the more specific
statement, the same precedence `label` has over the page's title.

### Hiding entries

Set `hidden: true` on a group, tab, or page to drop it from the sidebar. The page URLs still work — handy for draft pages or links you want to give out but not advertise.

```json
{
  "group": "Internal",
  "hidden": true,
  "pages": ["internal/metrics"]
}
```

### Icons on tabs

Tabs accept an `icon` (Lucide name — see [Icons](/configuration/config-file)).

```json
{
  "tab": "API Reference",
  "icon": "code",
  "groups": [...]
}
```

### External tabs

Give a tab an `href` to turn it into an external link that opens in a new tab. Skip `groups` and `pages` — the tab becomes a pure link.

```json
{
  "tab": "Changelog",
  "icon": "rss",
  "href": "https://github.com/your-org/your-repo/releases"
}
```

## Group root pages

Give a group a dedicated landing page by setting `root` to a page path. Clicking the group label routes to that page instead of just toggling the section.

```json
{
  "group": "Guides",
  "root": "guides/index",
  "pages": [
    "guides/authentication",
    "guides/webhooks",
    "guides/rate-limits"
  ]
}
```

### Auto directory listings

When a group has a `root`, opt into rendering its children on that root page with `directory`:

<CardGroup cols={2}>
  <Card title="accordion" icon="list">
    A collapsible list of children — each row expands to show the page's description.
  </Card>
  <Card title="card" icon="grid-2x2">
    A responsive grid of cards, one per child, with title + description.
  </Card>
</CardGroup>

```json
{
  "group": "Guides",
  "root": "guides/index",
  "directory": "card",
  "pages": [
    "guides/authentication",
    "guides/webhooks"
  ]
}
```

Child page descriptions (used by both variants) come from the MDX frontmatter's `description` field. Keep them to a single line — two at most.

Toggle the behavior of clicks on a group with a root via the top-level `interaction.drilldown` flag. Default: `true` (clicks route to the root). Set to `false` and clicks only open/close the group:

```json
{
  "interaction": { "drilldown": false }
}
```

## Per-page overrides

Replace a bare string in `pages` with an object to customize how that one entry appears — without touching the page's own frontmatter.

```json
{
  "group": "Guides",
  "pages": [
    "guides/authentication",
    {
      "page": "guides/webhooks",
      "label": "Webhooks (advanced)",
      "icon": "zap",
      "tag": "NEW"
    },
    {
      "href": "https://github.com/your-org/your-repo",
      "label": "Source on GitHub",
      "icon": "github"
    }
  ]
}
```

Two object forms are supported:

- `{ "page": "..." }` — an internal docs page with optional `label`, `icon`, `tag`, `hidden` overrides.
- `{ "href": "...", "label": "..." }` — an external link that renders as a new-tab sidebar item.

## Explicit expand state

By default, groups expand when they contain the current page. Override with `expanded`:

```json
{
  "group": "Reference",
  "expanded": false,
  "pages": ["reference/api", "reference/cli"]
}
```

- `expanded: true` — always open.
- `expanded: false` — collapsed on first visit. The user can still toggle manually.
- Omitted — auto (the old behavior).

## Anchors and dropdowns (Phase 3)

Anchors and dropdowns sit at the **top of the sidebar, above the groups**. They're how you surface high-level destinations (community, changelog, status page) or organize content into collapsible top-level buckets.

### Anchors

An anchor is a standalone sidebar item. Two shapes, same discriminator (`anchor`):

#### External link

```json
{
  "navigation": [
    {
      "anchor": "Community",
      "icon": "users",
      "href": "https://github.com/your-org/your-repo/discussions",
      "tag": "Discord"
    },
    { "group": "Getting Started", "pages": ["introduction"] }
  ]
}
```

Renders above the "Getting Started" group with a little external-link arrow and opens in a new tab.

#### Inline expandable

Drop the `href` and add `pages` / `groups` and the anchor becomes a collapsible section — like a group, but it lives above the main group list.

```json
{
  "anchor": "Releases",
  "icon": "rocket",
  "expanded": false,
  "pages": [
    "releases/v2-0-0",
    "releases/v1-9-0",
    "releases/v1-8-0"
  ]
}
```

`expanded: true` starts the anchor open; omit it and it's closed on first visit.

### Dropdowns

Dropdowns are always collapsible with children — no plain-link mode. Use them when you have **multiple top-level product areas** that don't warrant a full tab but need their own mini-navigation.

```json
{
  "dropdown": "Reference",
  "icon": "book",
  "description": "API + CLI reference",
  "expanded": true,
  "groups": [
    {
      "group": "API",
      "pages": ["api/authentication", "api/projects"]
    },
    {
      "group": "CLI",
      "pages": ["cli/overview", "cli/commands"]
    }
  ]
}
```

Dropdowns always carry a toggle. `expanded: true` starts one open; leave it out
and it starts closed. Either way the reader's own choice is remembered from
then on, so this only sets what they see first.

A dropdown can also hold a flat list of links rather than groups. Each entry
takes its own `icon`, the same way a page does in the sidebar:

```json
{
  "dropdown": "Resources",
  "icon": "compass",
  "pages": [
    { "label": "GitHub", "href": "https://github.com/your-org", "icon": "tabler:brand-github" },
    { "label": "Quick Start", "href": "/quickstart", "icon": "rocket" }
  ]
}
```

An `href` starting with `/` is treated as one of your own pages: it opens in the
same tab, with no outbound arrow, exactly as it would in the sidebar proper.
Anything else opens in a new tab. Add `"target": "_blank"` to force a new tab
for an internal link.

### When to use which

| | Anchor (external) | Anchor (inline) | Dropdown | Group |
|---|---|---|---|---|
| **Has children** | No | Yes (optional) | Yes (required) | Yes (required) |
| **Can be a plain link** | Yes | No | No | No |
| **Position** | Top of sidebar | Top of sidebar | Top of sidebar | Main list |
| **Collapsible** | N/A | Yes | Yes | Yes |
| **Open state persists** | N/A | Toggleable | Yes (localStorage) | Yes (in-memory) |

Rule of thumb:

- Linking **out** of the docs → anchor with `href`.
- Small side section (status, releases, changelog) → anchor with `pages`.
- Major parallel section that's a peer of your main content → dropdown.
- Primary content tree → groups (default).

### Hidden state

All three support `hidden: true`. The entry vanishes from the sidebar; its URLs still resolve.

### Icons

All three support `icon` (Lucide icon name). The icon shows to the left of the label, styled to match the sidebar typography.

## Multi-dimensional navigation (Phase 3+)

Bigger docs sites need **switchers** at the top of the page:

- **Versions** — `v1` / `v2` / `v3` of your API
- **Languages** — `en` / `tr` / `fr` locales
- **Products** — multi-product companies with separate docs per product

All three render as dropdowns in the navbar; the user picks, the URL changes, and the sidebar updates to match. The platform uses the URL's first path segment as the active selector.

### Versions

```json
{
  "versions": [
    { "version": "v3", "default": true, "tag": "Latest", "status": "stable" },
    { "version": "v2", "status": "stable" },
    { "version": "v1", "tag": "Deprecated", "status": "deprecated" }
  ]
}
```

Each entry's URL slug is the version label lowercased (override with `slug`). The `default: true` entry serves at the root (`/`), others serve at `/<slug>/...`.

`status` colors the tag: `"stable"` → primary, `"beta"` → warning, `"deprecated"` → danger, `"preview"` → info.

### Languages

```json
{
  "languages": [
    { "language": "en", "default": true, "label": "English" },
    { "language": "tr", "label": "Türkçe" }
  ]
}
```

Same slug-matching logic as versions. `label` is what the switcher shows — leave
it out and readers see the raw code (`en`, `tr`) instead of a name they
recognise.

<Note>
  Right-to-left layout is on the roadmap. Pages in an RTL language serve
  correctly today; the reading direction doesn't flip yet.
</Note>

### Products

```json
{
  "products": [
    { "product": "Cloud", "default": true, "description": "Managed hosting" },
    { "product": "Enterprise", "description": "Self-hosted" }
  ]
}
```

Products render a switcher near the logo (when shipped); path prefix `/<slug>/...` routes to the product's own nav tree.

### Content layout

For `versions` / `languages` / `products`, the platform expects tenants to organise their MDX under matching path prefixes in the repo. Example for a v3 / v2 / v1 setup:

```
your-repo/                    # the docs base
├── introduction.mdx          # default (v3)
├── guides/
│   └── authentication.mdx    # default (v3)
├── v2/
│   ├── introduction.mdx
│   └── guides/
│       └── authentication.mdx
└── v1/
    ├── introduction.mdx
    └── guides/
        └── authentication.mdx
```

## Per-tab anchors + dropdowns

Tabs can carry their own `anchors` and `dropdowns` — they render above the tab's group list when that tab is active:

```json
{
  "tab": "Guides",
  "icon": "book",
  "anchors": [
    { "anchor": "Status page", "icon": "activity", "href": "https://status.example.com" }
  ],
  "groups": [
    { "group": "Getting Started", "pages": ["guides/intro"] }
  ]
}
```

Root-level anchors still render when no tab is active (flat navigation mode). In tabbed mode the sidebar uses the current tab's own anchors only.

## Global nav

Use `global` for chrome that must survive product / version / language switches — a status-page anchor that's visible everywhere, a changelog dropdown that's the same across versions, etc.

```json
{
  "global": {
    "anchors": [
      { "anchor": "Status", "icon": "activity", "href": "https://status.example.com" }
    ],
    "dropdowns": [
      {
        "dropdown": "Changelog",
        "icon": "history",
        "pages": ["changelog/2026-q1", "changelog/2025-q4"]
      }
    ]
  }
}
```

Global anchors always render first in the sidebar; scope-specific anchors follow below.

## Tab menus (rich dropdowns)

A tab with `menus` becomes a click-to-open dropdown showing rich items (title + description + icon) — think Mintlify's "mega menu" pattern.

```json
{
  "tab": "Products",
  "icon": "grid-2x2",
  "menus": [
    {
      "item": "Analytics",
      "description": "Real-time dashboards and event tracking.",
      "icon": "bar-chart",
      "pages": ["analytics/overview"]
    },
    {
      "item": "Webhooks",
      "description": "Stream events to your infrastructure.",
      "icon": "zap",
      "tag": "BETA",
      "pages": ["webhooks/overview"]
    },
    {
      "item": "Changelog",
      "description": "What shipped this quarter.",
      "icon": "history",
      "href": "https://example.com/changelog"
    }
  ]
}
```

Click a menu item → navigates to its `href` or first child page. The sidebar then reflects the destination's navigation, same as clicking a regular tab.

Each menu item supports: `item` (title, required), `description`, `icon`, `iconType`, `tag`, `hidden`, `href`, `pages`, `groups`.

---

# PDF export
Source: https://docs.nookdocs.com/configuration/pdf-export

Export the full docs site as a single PDF — for legal archive, compliance, or offline distribution. Enterprise tier.

Some teams need their entire docs site as a single PDF — legal archive, compliance audit, offline distribution, customer onboarding packets. NookDocs ships a PDF export endpoint that traverses the full navigation tree, renders every page, and merges them into one styled document.

## Endpoint

```
GET https://api.nookdocs.com/v1/projects/<project_id>/export/pdf
Authorization: Bearer <api_key_or_jwt>
```

Returns a streamed `application/pdf` response. The full export of a 500-page site takes 30-90 seconds; smaller sites are faster.

## What the PDF contains

- Branded cover page (your logo + site name)
- Auto-generated table of contents
- Every page in navigation order
- Internal links converted to PDF bookmarks
- Code blocks with syntax highlighting preserved
- Custom MDX components rendered to print-friendly equivalents

## Plan availability

| Plan | PDF export |
|---|:-:|
| Free | — |
| Pro | — |
| Team | — |
| Enterprise | ✅ |

## Status

The endpoint exists and is plan-gated today; the PDF generation pipeline (puppeteer page traversal + TOC merge + branded cover) ships in the Enterprise security release. Today's response is `501 not_yet_implemented` with a roadmap pointer.

This way you can wire your integration code now (CI job, S3 archive, customer-facing download button) against a stable URL — when generation goes live nothing on your side changes.

## For LLMs

If you're an AI agent helping a user wire up PDF export, here's the canonical recipe:

**1. Endpoint and auth:**

```
GET https://api.nookdocs.com/v1/projects/<project_id>/export/pdf
Authorization: Bearer <jwt_or_api_key>
```

**2. Status codes:**

- `200` — `Content-Type: application/pdf`, stream the body to a file
- `402 plan_required` — caller's plan does not include PDF export (Free / Pro / Team)
- `501 not_yet_implemented` — generation pipeline not yet shipped (current state)
- `404` — project not found or caller not a member

**3. Recommended integration pattern:**

```ts
async function exportDocsPdf(projectId: string, apiKey: string): Promise<Buffer> {
  const res = await fetch(
    `https://api.nookdocs.com/v1/projects/${projectId}/export/pdf`,
    { headers: { Authorization: `Bearer ${apiKey}` } },
  );
  if (!res.ok) throw new Error(`PDF export failed: ${res.status}`);
  return Buffer.from(await res.arrayBuffer());
}
```

**Common mistakes:**

- Don't poll the endpoint waiting for generation — it's a single synchronous call. The response either streams the PDF or returns an error.
- 30-90 second response time for a 500-page site is normal. Set client timeout ≥120s.
- The endpoint serves only published pages; drafts and private (frontmatter `private: true`) pages are filtered out.
- For repeated exports, cache the result on your side keyed by the latest deployment SHA — the platform doesn't cache yet.

---

# Custom RBAC roles
Source: https://docs.nookdocs.com/configuration/rbac

Define your own roles with explicit permission grants. Enterprise tier.

The built-in `owner / editor / viewer` roles cover most teams. Enterprise customers often need finer-grained roles — e.g. a "Support Editor" who can edit docs but never touch billing, or a "Compliance Reviewer" who can read everything (including audit log) but write nothing.

**Custom RBAC** lets you define those roles with an explicit permission matrix and assign them to org members.

## Where to manage

Project → **Settings → Roles**. Click **New role**, give it a name, tick the permissions you want, save. Existing members continue using their built-in role until you reassign them.

## Permission vocabulary

Stable strings — never invent new ones, the platform ignores unknown values:

| Permission | Grants |
|---|---|
| `project.read` | Read project + pages + analytics |
| `project.write` | Edit pages, commit config |
| `project.delete` | Delete the project |
| `settings.write` | Change project settings (domain, branding, access, etc.) |
| `billing.read` | View subscription + usage |
| `billing.write` | Change plan, manage billing |
| `members.invite` | Invite new members |
| `members.remove` | Remove members |
| `access.manage` | Set access mode + rotate password |
| `webhook.manage` | Create / edit / delete webhooks |
| `api_key.manage` | Create / revoke API keys |
| `audit.read` | View the audit log |

## Plan availability

| Plan | Custom roles |
|---|:-:|
| Free | — |
| Pro | — |
| Team | — |
| Enterprise | ✅ |

Lower tiers continue using the built-in `owner / editor / viewer` set.

## Notes

- Custom role assignment overlays the built-in role. When a member has a custom role assigned, that role's permissions win.
- The legacy `owner` role is preserved on every org so billing + plan changes always have someone authorised.
- Permission strings are stable — don't tie code to label changes; tie it to the slug.

## For LLMs

If you're an AI agent designing a custom role for a customer, here's the canonical recipe:

**1. Map the user's intent to permission slugs:**

| User says | Recommend permissions |
|---|---|
| "They edit docs but never touch billing" | `project.read`, `project.write`, `settings.write` |
| "Support team — read-only access" | `project.read`, `audit.read` |
| "Compliance reviewer" | `project.read`, `audit.read`, `members.invite` |
| "Contractor — single project, write only" | `project.read`, `project.write` |

**2. Always include `project.read`** — without it the user can't see the project to write to it.

**3. Don't grant `project.delete` casually** — it's irreversible. Only on roles where the user explicitly says "they need to delete projects."

**4. Billing permissions are sensitive:**

- `billing.read` — viewing usage + invoices is fine for most managers
- `billing.write` — changing plan + cancelling subscription. Restrict to founder + finance lead.

**Common mistakes:**

- Don't propose roles with no permissions — they're functionally useless and cause confusion in the member list.
- Don't suggest `members.remove` without `members.invite` — usually the same person needs both.
- Roles are org-scoped, not project-scoped. A role you create applies across every project in the org.

---

# Schema reference
Source: https://docs.nookdocs.com/configuration/schema-reference

Every field in nookdocs.config.json — auto-generated from public/schema.json. The LLM's single-paste reference for synthesising a valid NookDocs config.

<Note>
  This page is **auto-generated from [`public/schema.json`](https://nookdocs.com/schema.json)**. Whenever the schema changes, `npm run build:schema-reference` regenerates it. Do not edit by hand — your changes will be overwritten on the next build.
</Note>

`nookdocs.config.json` lives at the root of your docs repo and controls everything: branding, navigation, themes, API settings, AI features, integrations. Add `"$schema": "https://nookdocs.com/schema.json"` at the top of your config for IDE autocomplete + inline validation.

```json
{
  "$schema": "https://nookdocs.com/schema.json",
  "name": "Acme Docs",
  "theme": "cedar"
}
```

## Top-level keys at a glance

| Key | Type | Required | Summary |
|---|---|---|---|
| `name` | string | ✓ | Project display name (shown in tab title, OG metadata, etc.). |
| `theme` | enum (10 values) |  | Built-in theme slug. Affects shell layout + CSS tokens. Legacy aliases still resolve but a |
| `contentRoot` | string |  | Repo folder containing MDX files. Must end with '/'. |
| `appearance` | object |  | Default color scheme behavior. |
| `colors` | object |  | Brand colors + logo. |
| `background` | object |  | Page background colors or CSS gradients. |
| `typography` | object |  | Font family overrides. |
| `navbar` | object |  | Top navigation bar configuration. |
| `legal` | object |  | Legal block — copyright + privacy/terms/cookie links rendered in the site footer. |
| `footer` | object |  | Footer layout + social links. |
| `seo` | object |  | SEO defaults applied to all pages. Per-page frontmatter overrides these. |
| `geo` | object |  | GEO / AEO — generative & answer engine optimization. JSON-LD structured data, AI-crawler c |
| `customCss` | string |  | Per-tenant custom CSS. Appended to the docs site head and cascades over every theme + typo |
| `branding` | object |  | White-labeling controls. Setting branding.poweredBy: false requires the Team plan or highe |
| `advanced` | object |  | Niche behaviors that don't fit elsewhere. |
| `navigation` | array | object |  | Site navigation hierarchy. Either a flat array (V1) or a structured object (V2). |
| `api` | object |  | OpenAPI / API reference settings. |
| `brand` | object |  | Pluggable brand asset system (logos, OG images, favicons, manifest). |
| `versions` | object[] |  | Phase 3+ version switcher. Each entry defines a docs version; the navbar shows a dropdown  |
| `languages` | object[] |  | Phase 3+ language switcher. Each entry defines a locale; the navbar shows a dropdown to sw |
| `products` | object[] |  | Phase 3+ multi-product switcher. Renders a dropdown near the logo to switch between produc |
| `global` | object |  | Phase 3+ global chrome that persists across product / version / language switches. |
| `redirects` | object[] |  | URL redirects applied at the docs page layer. Tenants add entries to map old paths to new  |
| `interaction` | object |  | Navigation interaction toggles. Affects how group/tab clicks behave. |
| `ai` | object |  | AI features (assistant, future agent). |
| `feedback` | object |  | Per-page 'Was this page helpful?' widget at the bottom of every docs page. Default: enable |
| `analytics` | object |  | First-party analytics beacon + dashboard. Records views, searches, feedback, and assistant |
| `contextual` | object |  | Configures the contextual menu shown next to page titles (Copy page, Open in ChatGPT, etc. |
| `sidebar` | object |  | Sidebar appearance overrides. Every key defaults to 'auto', meaning the theme decides — se |
| `codeBlockStyle` | enum (4 values) |  | How fenced code blocks are framed. 'card' is a bordered block with a header strip; 'inset' |
| `layout` | object |  | Where the navigation chrome sits. Each theme picks its own arrangement; these depart from  |
| `viewSwitcherStyle` | 'auto' / 'dropdown' / 'tabs' |  | How the page-level View switcher is drawn. 'dropdown' (the default) states the current cho |
| `banner` | object |  | Site-wide announcement banner rendered above the navbar. |
| `search` | object |  | Search UI options. |
| `integrations` | object |  | Third-party analytics / chat integrations. Each provider takes its own small config object |
| `icons` | object |  | Icon rendering options. |
| `metadata` | object |  | Arbitrary key→value metadata attached to the site (exposed to templates and exports). |

---

## name

Project display name (shown in tab title, OG metadata, etc.).

<ParamField path="name" type="string" required>
  Project display name (shown in tab title, OG metadata, etc.).
</ParamField>

---

## theme

Built-in theme slug. Affects shell layout + CSS tokens. Legacy aliases still resolve but are deprecated — maple→larch, classic→cedar, modern→ember, minimal→sage; write the canonical slug.

**Deep dive:** [/configuration/theme](/configuration/theme)

<ParamField path="theme" type="'cedar' | 'obsidian' | 'birch' | 'oak' | 'cypress' | 'ember' | 'larch' | 'sage' | 'slate' | 'terminal'" default="larch">
  Built-in theme slug. Affects shell layout + CSS tokens. Legacy aliases still resolve but are deprecated — maple→larch, classic→cedar, modern→ember, minimal→sage; write the canonical slug.
</ParamField>

---

## contentRoot

Repo folder containing MDX files. Must end with '/'.

**Deep dive:** [/configuration/content-root](/configuration/content-root)

<ParamField path="contentRoot" type="string" default="docs/">
  Repo folder containing MDX files. Must end with '/'.
</ParamField>

---

## appearance

Default color scheme behavior.

**Deep dive:** [/configuration/site-settings#appearance](/configuration/site-settings#appearance)

<ParamField path="appearance.default" type="'light' | 'dark' | 'system'" default="system">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="appearance.strict" type="boolean" default="false">
  When true, hide the theme toggle (force a single mode).
</ParamField>

---

## colors

Brand colors + logo.

**Deep dive:** [/configuration/brand](/configuration/brand)

<ParamField path="colors.primary" type="string">
  Primary accent color (hex). Used for buttons, links, focus rings.
</ParamField>
<ParamField path="colors.light" type="string">
  Primary color in light mode.
</ParamField>
<ParamField path="colors.dark" type="string">
  Primary color in dark mode.
</ParamField>
### colors.logo

Logo images. A root-relative path is served from your repo's public/ folder; an absolute URL is used as given (e.g. a CDN).

<ParamField path="colors.logo.light" type="string">
  Light-mode logo — a path under public/ ("/logo/light.svg") or an absolute URL.
</ParamField>
<ParamField path="colors.logo.dark" type="string">
  Dark-mode logo — a path under public/ ("/logo/dark.svg") or an absolute URL.
</ParamField>
<ParamField path="colors.logo.href" type="string">
  Click target for the logo. Root-relative paths resolve against your docs base, so "/" returns to the docs home even on a subpath. Default: "/".
</ParamField>

---

## background

Page background colors or CSS gradients.

**Deep dive:** [/configuration/site-settings](/configuration/site-settings)

<ParamField path="background.light" type="string">
  Light mode background. Solid hex or any CSS gradient.
</ParamField>
<ParamField path="background.dark" type="string">
  Dark mode background.
</ParamField>

---

## typography

Font family overrides.

**Deep dive:** [/configuration/site-settings#typography](/configuration/site-settings#typography)

<ParamField path="typography.fontFamily" type="string">
  Default sans-serif font family for body text.
</ParamField>
<ParamField path="typography.headingFont" type="string">
  Override font for h1-h4 (defaults to fontFamily).
</ParamField>
<ParamField path="typography.bodyFont" type="string">
  Override font for paragraph body (defaults to fontFamily).
</ParamField>

---

## navbar

Top navigation bar configuration.

**Deep dive:** [/configuration/site-settings#navbar](/configuration/site-settings#navbar)

### navbar.links[]

External or internal links shown in the navbar.

<ParamField path="navbar.links[].label" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="navbar.links[].href" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

### navbar.primaryCta

Highlighted call-to-action button (e.g. 'Sign up', 'Get started').

<ParamField path="navbar.primaryCta.label" type="string" required>
  Button text, e.g. 'Dashboard', 'Sign up'.
</ParamField>
<ParamField path="navbar.primaryCta.href" type="string" required>
  Where it goes. Absolute URL for an external app, or a docs path.
</ParamField>
<ParamField path="navbar.primaryCta.style" type="'solid' | 'outline' | 'ghost'" default="solid">
  Shape. 'solid' = filled pill in the theme accent (default). 'outline' = accent border, transparent fill. 'ghost' = text only.
</ParamField>
<ParamField path="navbar.primaryCta.color" type="string">
  Fill/border colour. Any CSS colour. Omit to follow the theme's accent — override only when the CTA carries a different brand colour than the docs theme.
</ParamField>
<ParamField path="navbar.primaryCta.textColor" type="string">
  Label colour on a solid button. Omit to follow the theme's accent foreground.
</ParamField>
<ParamField path="navbar.primaryCta.external" type="boolean">
  Open in a new tab. Defaults to true for http(s) targets, false for docs paths.
</ParamField>

### navbar.controls

Where the navbar's controls sit and in what order. Each placement overrides the theme, which otherwise decides all of them together — so you can keep the language switcher in the header while moving the appearance toggle to the sidebar.

<ParamField path="navbar.controls.appearance" type="'auto' | 'header' | 'sidebar'" default="auto">
  Light/dark toggle. Where this control sits. 'auto' follows the theme's own preference.
</ParamField>
<ParamField path="navbar.controls.language" type="'auto' | 'header' | 'sidebar'" default="auto">
  Language switcher. Where this control sits. 'auto' follows the theme's own preference.
</ParamField>
<ParamField path="navbar.controls.version" type="'auto' | 'header' | 'sidebar'" default="auto">
  Version switcher. Where this control sits. 'auto' follows the theme's own preference. The sidebar slot only exists on themes whose footer renders controls; elsewhere the control won't render at all.
</ParamField>
<ParamField path="navbar.controls.product" type="'auto' | 'header' | 'sidebar'" default="auto">
  Product switcher. Where this control sits. 'auto' follows the theme's own preference. The sidebar slot only exists on themes whose footer renders controls; elsewhere the control won't render at all.
</ParamField>
<ParamField path="navbar.controls.assistant" type="'auto' | 'header' | 'sidebar'" default="auto">
  The 'Ask AI' button (only when ai.assistant.trigger resolves to 'button'). 'sidebar' gives it a full-width block in the rail; 'header' puts it in the top bar beside the CTA. 'auto' follows the theme.
</ParamField>
<ParamField path="navbar.controls.order" type="('appearance' | 'language' | 'version' | 'product' | 'assistant')[]">
  Left-to-right order of the controls that end up in the header. Names you leave out keep their default position after the ones listed.
</ParamField>

---

## legal

Legal block — copyright + privacy/terms/cookie links rendered in the site footer.

<ParamField path="legal.copyright" type="string">
  Copyright line. The token \{year\} expands to the current year. Example: '© \{year\} Acme, Inc.'
</ParamField>
<ParamField path="legal.privacyUrl" type="string">
  Privacy policy URL — rendered as a footer legal link.
</ParamField>
<ParamField path="legal.termsUrl" type="string">
  Terms of service URL.
</ParamField>
<ParamField path="legal.cookieUrl" type="string">
  Cookie policy URL.
</ParamField>
### legal.links[]

Extra legal links (imprint, accessibility statement, etc.).

<ParamField path="legal.links[].label" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="legal.links[].href" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

---

## footer

Footer layout + social links.

**Deep dive:** [/configuration/site-settings#footer](/configuration/site-settings#footer)

<ParamField path="footer.style" type="'none' | 'page' | 'columns'" default="none">
  'none' hides the footer. 'page' renders a single social-icon + copyright row beneath the page content. 'columns' renders a multi-column link grid with the social row below.
</ParamField>
<ParamField path="footer.logo" type="boolean">
  Show the docs' own logo (colors.logo) in the footer. Reuses the navbar logo — no separate path.
</ParamField>
### footer.social

Social profile URLs, rendered as brand icons in the page footer. Each key is a platform slug; the value is the profile/page URL.

<ParamField path="footer.social.github" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.x" type="string">
  X / Twitter profile URL
</ParamField>
<ParamField path="footer.social.linkedin" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.discord" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.youtube" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.facebook" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.website" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.slack" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.instagram" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.hackernews" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.medium" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.telegram" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.bluesky" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.threads" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.reddit" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.social.podcast" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

### footer.links[]

Column definitions for the 'columns' footer style. Each column has a title and an array of { label, href } links.

<ParamField path="footer.links[].title" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="footer.links[].items" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

<ParamField path="footer.width" type="'reading' | 'content' | 'full'">
  How wide the footer's surface runs — independent of footer.style, so it applies to page and columns footers alike. 'reading' (the default) aligns it with the reading column — the same narrow width as the page text and the 'Was this helpful?' feedback block. 'content' widens it to the outer content column (article + TOC width). 'full' spans the whole viewport and the sidebar stops at the footer's top rule. Omit to follow the active theme, then the 'reading' default.
</ParamField>

---

## seo

SEO defaults applied to all pages. Per-page frontmatter overrides these.

**Deep dive:** [/configuration/site-settings#seo](/configuration/site-settings#seo)

<ParamField path="seo.title" type="string">
  Default site title. Page titles render as '\{page\} | \{title\}'.
</ParamField>
<ParamField path="seo.description" type="string">
  Default meta description when a page has none.
</ParamField>
<ParamField path="seo.keywords" type="string[]">
  Default meta keywords for the site. Per-page frontmatter 'keywords' overrides.
</ParamField>
<ParamField path="seo.author" type="string">
  Default content author — emitted as &lt;meta name="author"&gt;.
</ParamField>
<ParamField path="seo.ogImage" type="string">
  Default Open Graph / social preview image URL.
</ParamField>
<ParamField path="seo.favicon" type="string">
  Favicon URL (path under your repo's public/ folder).
</ParamField>
<ParamField path="seo.indexing" type="'default' | 'noindex'" default="default">
  Set to 'noindex' to hide entire site from search engines.
</ParamField>
<ParamField path="seo.metatags" type="object">
  Free-form &lt;meta&gt; tag map, keyed by meta-name (e.g. 'twitter:site'). Appended to every page.
</ParamField>

---

## geo

GEO / AEO — generative & answer engine optimization. JSON-LD structured data, AI-crawler control, and citation signals for AI Overviews / Perplexity / ChatGPT.

<ParamField path="geo.structuredData" type="boolean" default="true">
  Emit JSON-LD (TechArticle, BreadcrumbList, Organization, WebSite) on every page.
</ParamField>
<ParamField path="geo.faqSchema" type="boolean" default="true">
  Emit FAQPage JSON-LD from a page's frontmatter `faq: [\{ q, a \}]`.
</ParamField>
### geo.organization

Publisher entity used in the JSON-LD graph.

<ParamField path="geo.organization.name" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="geo.organization.logo" type="string">
  Logo URL (absolute or repo-relative).
</ParamField>
<ParamField path="geo.organization.sameAs" type="string[]">
  Profile URLs identifying the same entity (X, GitHub, LinkedIn, Wikipedia…).
</ParamField>

<ParamField path="geo.aiCrawlers" type="any">
  AI crawler access in robots.txt. 'allow' (default) or 'block' all AI bots, or a per-bot map keyed by user-agent (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, CCBot, …).
</ParamField>
### geo.llmsTxt

Extra context lines for the auto-generated /llms.txt.

<ParamField path="geo.llmsTxt.intro" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="geo.llmsTxt.contact" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

<ParamField path="geo.topics" type="string[]">
  Primary topics/entities the site covers — surfaced as JSON-LD `about`.
</ParamField>
<ParamField path="geo.audience" type="string">
  Target audience, e.g. 'developers'.
</ParamField>
<ParamField path="geo.license" type="string">
  Content reuse / citation license, e.g. 'CC-BY-4.0'.
</ParamField>

---

## customCss

Per-tenant custom CSS. Appended to the docs site head and cascades over every theme + typography rule. Pro+ feature — Free tier saves are rejected server-side.

<ParamField path="customCss" type="string">
  Per-tenant custom CSS. Appended to the docs site head and cascades over every theme + typography rule. Pro+ feature — Free tier saves are rejected server-side.
</ParamField>

---

## branding

White-labeling controls. Setting branding.poweredBy: false requires the Team plan or higher.

<ParamField path="branding.poweredBy" type="boolean" default="true">
  Show the "Powered by NookDocs" attribution in the page footer. Default true. Set to false to hide it (Team+ only).
</ParamField>

---

## advanced

Niche behaviors that don't fit elsewhere.

**Deep dive:** [/configuration/site-settings#advanced](/configuration/site-settings#advanced)

### advanced.notFound

Custom 404 page configuration.

<ParamField path="advanced.notFound.active" type="boolean" default="false">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="advanced.notFound.title" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="advanced.notFound.description" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

<ParamField path="advanced.drilldownNavigation" type="boolean" default="false">
  Deprecated — use `interaction.drilldown` instead. Read only when `interaction.drilldown` is absent, so setting both means this one does nothing. Note the defaults differ: this defaulted to false, `interaction.drilldown` defaults to true.
</ParamField>
<ParamField path="advanced.showTimestamp" type="boolean" default="true">
  Show 'Last updated' timestamp at the bottom of each page.
</ParamField>

---

## navigation

Site navigation hierarchy. Either a flat array (V1) or a structured object (V2).

**Deep dive:** [/configuration/navigation](/configuration/navigation)

<ParamField path="navigation" type="any">
  Site navigation hierarchy. Either a flat array (V1) or a structured object (V2).
</ParamField>

---

## api

OpenAPI / API reference settings.

**Deep dive:** [/configuration/api](/configuration/api)

<ParamField path="api.baseUrl" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="api.openapi" type="string">
  Path to OpenAPI spec (relative to repo root) OR full URL.
</ParamField>
<ParamField path="api.asyncapi" type="string">
  Path or URL to AsyncAPI spec (planned).
</ParamField>
<ParamField path="api.playground" type="any" default="interactive">
  Try-It playground. `"interactive"` (or `true`) runs live requests; `"simple"` shows the form without sending; `"none"` (or `false`) hides it.
</ParamField>
### api.auth

Default auth scheme for the playground.

<ParamField path="api.auth.name" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="api.auth.type" type="'bearer' | 'basic' | 'apiKey' | 'oauth2'">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

---

## brand

Pluggable brand asset system (logos, OG images, favicons, manifest).

**Deep dive:** [/configuration/brand](/configuration/brand)

---

## versions

Phase 3+ version switcher. Each entry defines a docs version; the navbar shows a dropdown to switch between them. Exactly one entry may have `default: true`.

**Deep dive:** [/content/versioning](/content/versioning)

<ParamField path="versions[].version" type="string" required>
  Version label, e.g. 'v2', '2024-10'.
</ParamField>
<ParamField path="versions[].default" type="boolean">
  Mark as the default version (latest).
</ParamField>
<ParamField path="versions[].tag" type="string">
  Badge like 'Latest' or 'Deprecated'.
</ParamField>
<ParamField path="versions[].tabs" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="versions[].groups" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="versions[].pages" type="any[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="versions[].label" type="string">
  Display name shown in the switcher. Falls back to the code/name itself when omitted — set it to show "English" instead of "en".
</ParamField>
<ParamField path="versions[].slug" type="string">
  URL segment for this entry. Defaults to a slug of the label.
</ParamField>
<ParamField path="versions[].hidden" type="boolean">
  Keep the entry out of the switcher while its pages stay reachable.
</ParamField>
<ParamField path="versions[].status" type="'stable' | 'beta' | 'deprecated' | 'preview'">
  Status badge shown beside the entry.
</ParamField>

---

## languages

Phase 3+ language switcher. Each entry defines a locale; the navbar shows a dropdown to switch between them. Exactly one entry may have `default: true`.

**Deep dive:** [/content/localization](/content/localization)

<ParamField path="languages[].language" type="string" required>
  ISO 639-1 code (en, tr, de, es, fr, ja, zh, ar, etc.).
</ParamField>
<ParamField path="languages[].default" type="boolean">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="languages[].navbar" type="object">
  Top navigation bar configuration.
</ParamField>
<ParamField path="languages[].footer" type="object">
  Footer layout + social links.
</ParamField>
<ParamField path="languages[].tabs" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="languages[].groups" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="languages[].pages" type="any[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="languages[].label" type="string">
  Display name shown in the switcher. Falls back to the code/name itself when omitted — set it to show "English" instead of "en".
</ParamField>
<ParamField path="languages[].slug" type="string">
  URL segment for this entry. Defaults to a slug of the label.
</ParamField>
<ParamField path="languages[].hidden" type="boolean">
  Keep the entry out of the switcher while its pages stay reachable.
</ParamField>
<ParamField path="languages[].tag" type="string">
  Small badge shown beside the entry (e.g. NEW, BETA).
</ParamField>
<ParamField path="languages[].status" type="'stable' | 'beta' | 'deprecated' | 'preview'">
  Status badge shown beside the entry.
</ParamField>

---

## products

Phase 3+ multi-product switcher. Renders a dropdown near the logo to switch between products.

**Deep dive:** [/content/multi-product](/content/multi-product)

<ParamField path="products[].product" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="products[].icon" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="products[].description" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="products[].href" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="products[].tabs" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="products[].groups" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="products[].pages" type="any[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="products[].label" type="string">
  Display name shown in the switcher. Falls back to the code/name itself when omitted — set it to show "English" instead of "en".
</ParamField>
<ParamField path="products[].slug" type="string">
  URL segment for this entry. Defaults to a slug of the label.
</ParamField>
<ParamField path="products[].hidden" type="boolean">
  Keep the entry out of the switcher while its pages stay reachable.
</ParamField>
<ParamField path="products[].tag" type="string">
  Small badge shown beside the entry (e.g. NEW, BETA).
</ParamField>
<ParamField path="products[].status" type="'stable' | 'beta' | 'deprecated' | 'preview'">
  Status badge shown beside the entry.
</ParamField>

---

## global

Phase 3+ global chrome that persists across product / version / language switches.

**Deep dive:** [/configuration/navigation#global-chrome](/configuration/navigation#global-chrome)

### global.anchors[]

<ParamField path="global.anchors[].anchor" type="string" required>
  Label shown in the sidebar.
</ParamField>
<ParamField path="global.anchors[].icon" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.anchors[].iconType" type="'regular' | 'solid' | 'light' | 'thin' | 'sharp-solid' | 'duotone' | 'brands'">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.anchors[].tag" type="string">
  Badge text like 'NEW'.
</ParamField>
<ParamField path="global.anchors[].hidden" type="boolean">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.anchors[].href" type="string">
  Where the anchor goes. Absolute URL for an external link, or a root-relative path like "/changelog" for one of your own pages. Mutually exclusive with pages/groups.
</ParamField>
<ParamField path="global.anchors[].target" type="'_self' | '_blank'">
  Link target. Defaults to _blank for external URLs.
</ParamField>
<ParamField path="global.anchors[].expanded" type="boolean" default="false">
  Initial open state when the anchor has children.
</ParamField>
<ParamField path="global.anchors[].pages" type="any[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.anchors[].groups" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

### global.dropdowns[]

<ParamField path="global.dropdowns[].dropdown" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.dropdowns[].icon" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.dropdowns[].iconType" type="'regular' | 'solid' | 'light' | 'thin' | 'sharp-solid' | 'duotone' | 'brands'">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.dropdowns[].tag" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.dropdowns[].hidden" type="boolean">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.dropdowns[].description" type="string">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.dropdowns[].expanded" type="boolean" default="false">
  Initial open state. Persists in localStorage once the user toggles.
</ParamField>
<ParamField path="global.dropdowns[].pages" type="any[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.dropdowns[].groups" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

### global.notFound

<ParamField path="global.notFound.pages" type="any[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="global.notFound.groups" type="object[]">
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

---

## redirects

URL redirects applied at the docs page layer. Tenants add entries to map old paths to new ones during migrations or rename flows.

**Deep dive:** [/configuration/site-settings#redirects](/configuration/site-settings#redirects)

<ParamField path="redirects[].source" type="string" required>
  Source path. Trailing '/*' enables prefix matching; the matched tail is preserved when the destination also ends in '/*'.
</ParamField>
<ParamField path="redirects[].destination" type="string" required>
  Destination path or absolute URL.
</ParamField>
<ParamField path="redirects[].permanent" type="boolean" default="false">
  When true, returns HTTP 308 (permanent). Otherwise 307 (temporary). Search engines respect 308 and transfer ranking signals to the new URL.
</ParamField>

---

## interaction

Navigation interaction toggles. Affects how group/tab clicks behave.

**Deep dive:** [/configuration/site-settings#interaction](/configuration/site-settings#interaction)

<ParamField path="interaction.drilldown" type="boolean" default="true">
  Controls Group.root click behaviour. When true (default), clicking a group label with `root` set navigates to that page. When false, clicking only toggles expand/collapse.
</ParamField>

---

## ai

AI features (assistant, future agent).

**Deep dive:** [/configuration/ai-assistant](/configuration/ai-assistant)

### ai.assistant

On-site AI chat widget for your docs — answers from your content.

<ParamField path="ai.assistant.enabled" type="boolean" default="false">
  Show the assistant on every docs page. Default false (opt-in).
</ParamField>
<ParamField path="ai.assistant.trigger" type="'button' | 'bar' | 'input'">
  How readers open the assistant. 'button' = a button in the header (after search). 'bar' = a floating pill centered at the bottom of the content. 'input' = a docked input pill in the bottom-right. All open the same conversation drawer. Omit to follow the active theme's own preference (themes that express none fall back to 'button').
</ParamField>
<ParamField path="ai.assistant.label" type="string" default="Ask AI">
  Text shown on the trigger (button label / input placeholder) and as the drawer title. Default 'Ask AI'. Override to match your brand voice (e.g. 'Ask Acme', 'Docs AI').
</ParamField>
<ParamField path="ai.assistant.provider" type="'openai' | 'anthropic' | 'openrouter'">
  AI provider for `model` — only used with Bring-Your-Own-Key. Set it to the provider whose API key you added under AI models (BYOK): `openai`, `anthropic`, or your own `openrouter` account. Without a BYOK key, the assistant uses the AI included in your plan and this field is ignored.
</ParamField>
<ParamField path="ai.assistant.model" type="string">
  Model identifier for the chosen `provider` (e.g. 'gpt-4o' for openai, 'claude-3-5-sonnet-latest' for anthropic, 'anthropic/claude-3.5-sonnet' for openrouter). Only honored when a matching BYOK key is set.
</ParamField>
<ParamField path="ai.assistant.systemPrompt" type="string">
  Override the default system prompt. Use this to constrain tone, persona, or scope.
</ParamField>

---

## feedback

Per-page 'Was this page helpful?' widget at the bottom of every docs page. Default: enabled with Mintlify-style reason options.

**Deep dive:** [/configuration/feedback](/configuration/feedback)

<ParamField path="feedback.enabled" type="boolean" default="true">
  Toggle the widget per tenant.
</ParamField>
<ParamField path="feedback.prompt" type="string">
  Override the top prompt. Default: 'Was this page helpful?'.
</ParamField>
### feedback.positiveReasons[]

Radio options shown after Yes. Falls back to a sensible default set when omitted.

<ParamField path="feedback.positiveReasons[].id" type="string" required>
  Stable key written to page_feedback.reason.
</ParamField>
<ParamField path="feedback.positiveReasons[].label" type="string" required>
  Shown in the radio list.
</ParamField>

### feedback.negativeReasons[]

Radio options shown after No.

<ParamField path="feedback.negativeReasons[].id" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>
<ParamField path="feedback.negativeReasons[].label" type="string" required>
  *No description yet — see the [deep-dive page](#top-level-keys-at-a-glance) for context.*
</ParamField>

### feedback.github

GitHub issue automation for negative feedback.

<ParamField path="feedback.github.autoIssue" type="boolean" default="false">
  Open a GitHub issue when a thumbs-down includes a comment.
</ParamField>
<ParamField path="feedback.github.labels" type="string[]">
  Labels attached to auto-opened issues.

  Default: `["docs-feedback"]`.
</ParamField>

---

## analytics

First-party analytics beacon + dashboard. Records views, searches, feedback, and assistant usage into the platform's own tables. Independent of integrations.* (GA4/PostHog/Plausible/...).

**Deep dive:** [/configuration/analytics](/configuration/analytics)

<ParamField path="analytics.enabled" type="boolean" default="true">
  Enable the beacon. Turn off to disable all first-party analytics capture for this tenant.
</ParamField>

---

## contextual

Configures the contextual menu shown next to page titles (Copy page, Open in ChatGPT, etc.).

**Deep dive:** [/configuration/contextual](/configuration/contextual)

<ParamField path="contextual.enabled" type="('content' | 'ai-platforms' | 'mcp' | 'custom')[]">
  Built-in sections to show. Omit to show all. Unknown values are ignored.
</ParamField>
<ParamField path="contextual.display" type="'header' | 'toc'" default="header">
  Where to render the menu. 'toc' placement is queued for a follow-up release.
</ParamField>
### contextual.options[]

Tenant-defined custom menu items. Each appears in the 'Custom' section of the dropdown.

<ParamField path="contextual.options[].title" type="string" required>
  Menu item label.
</ParamField>
<ParamField path="contextual.options[].description" type="string">
  Subtitle shown under the title.
</ParamField>
<ParamField path="contextual.options[].icon" type="string">
  Lucide icon name or absolute image URL.
</ParamField>
<ParamField path="contextual.options[].href" type="string" required>
  Target URL. Supports template variables resolved at click time: $page (full URL), $path (pathname), $title (page title), $mdx (URL-encoded MDX source).
</ParamField>

<ParamField path="contextual.platforms" type="('chatgpt' | 'claude' | 'perplexity' | 'aistudio' | 'grok' | 'windsurf')[]">
  Which AI platforms appear in the 'AI platforms' section. Omit and ChatGPT and Claude are shown — a menu listing seven destinations makes the reader read a list instead of clicking the one they wanted. Name the ones you want to offer to change that. Ignored when 'enabled' leaves 'ai-platforms' out.
</ParamField>

---

## sidebar

Sidebar appearance overrides. Every key defaults to 'auto', meaning the theme decides — set one only when you want to depart from the theme you picked.

<ParamField path="sidebar.activeStyle" type="'auto' | 'bg-tint' | 'text-only' | 'text-tint' | 'caret'" default="auto">
  How the current page is marked. 'bg-tint' fills a pill behind it; 'text-only' draws a rail down every row with an accent bar on the active one; 'text-tint' colours the label and paints nothing else; 'caret' puts a chevron in the margin beside the active page and draws no rail. 'auto' follows the theme.
</ParamField>
<ParamField path="sidebar.showIcons" type="'auto' | 'true' | 'false'" default="auto">
  Show per-page icons in the sidebar. 'auto' follows the theme.
</ParamField>
<ParamField path="sidebar.scrollbar" type="'auto' | 'always' | 'hover'" default="auto">
  Whether the sidebar scrollbar is always visible or appears on hover. 'auto' follows the theme. Touch devices never show one either way.
</ParamField>
<ParamField path="sidebar.groupLabelStyle" type="'auto' | 'normal' | 'uppercase' | 'uppercase-mono'" default="auto">
  Casing and weight of group headings. 'auto' follows the theme.
</ParamField>
<ParamField path="sidebar.collapsibleGroups" type="'auto' | 'true' | 'false'" default="auto">
  Whether sidebar groups get a chevron toggle. 'auto' follows the theme.
</ParamField>
<ParamField path="sidebar.defaultGroupState" type="'auto' | 'expanded' | 'collapsed'" default="auto">
  How collapsible groups start: 'expanded' opens all of them, 'collapsed' opens only the group holding the current page. Ignored when groups aren't collapsible. Per-group 'expanded' in navigation still wins.
</ParamField>

---

## codeBlockStyle

How fenced code blocks are framed. 'card' is a bordered block with a header strip; 'inset' drops the border for a raised surface with the code recessed in a darker well; 'terminal' keeps sharp corners and a prompt marker before the language. 'auto' follows the theme.

<ParamField path="codeBlockStyle" type="'auto' | 'card' | 'inset' | 'terminal'" default="auto">
  How fenced code blocks are framed. 'card' is a bordered block with a header strip; 'inset' drops the border for a raised surface with the code recessed in a darker well; 'terminal' keeps sharp corners and a prompt marker before the language. 'auto' follows the theme.
</ParamField>

---

## layout

Where the navigation chrome sits. Each theme picks its own arrangement; these depart from it without leaving the theme. 'auto' (or omitting a key) keeps the theme's choice.

<ParamField path="layout.shell" type="'auto' | 'header-sidebar' | 'sidebar-first' | 'header-only'" default="auto">
  Which shell frames the page. 'header-sidebar' is a header bar above a sidebar, 'sidebar-first' drops the header so the rail owns the full height, 'header-only' has no rail. The largest of these overrides — it swaps the whole frame.
</ParamField>
<ParamField path="layout.tabPosition" type="'auto' | 'header' | 'sidebar-list' | 'sidebar-dropdown'" default="auto">
  Where navigation tabs render — across the header, or down the sidebar as a list or a dropdown.
</ParamField>
<ParamField path="layout.headerRows" type="'auto' | '0' | '1' | '2'" default="auto">
  Header rows. '0' drops the header bar entirely, '1' keeps tabs on the logo row, '2' gives them their own strip beneath it.
</ParamField>
<ParamField path="layout.tabStyle" type="'auto' | 'underline' | 'pill' | 'text' | 'text-right'" default="auto">
  How header tabs are drawn.
</ParamField>
<ParamField path="layout.tabAlign" type="'auto' | 'start' | 'center' | 'end'" default="auto">
  Horizontal placement of single-row tabs. Ignored when headerRows is 2.
</ParamField>

---

## viewSwitcherStyle

How the page-level View switcher is drawn. 'dropdown' (the default) states the current choice in one line and stays one control however many variants a page offers; 'tabs' spreads them in a row, which reads well for two or three and wraps past that.

<ParamField path="viewSwitcherStyle" type="'auto' | 'dropdown' | 'tabs'" default="auto">
  How the page-level View switcher is drawn. 'dropdown' (the default) states the current choice in one line and stays one control however many variants a page offers; 'tabs' spreads them in a row, which reads well for two or three and wraps past that.
</ParamField>

---

## banner

Site-wide announcement banner rendered above the navbar.

<ParamField path="banner.content" type="string" required>
  Banner text (inline Markdown supported).
</ParamField>
<ParamField path="banner.dismissible" type="boolean">
  Let readers dismiss the banner (remembered per browser).
</ParamField>
<ParamField path="banner.variant" type="'info' | 'warning' | 'primary'">
  Visual tone. Default: info.
</ParamField>

---

## search

Search UI options.

<ParamField path="search.prompt" type="string">
  Placeholder text shown in the search input.
</ParamField>

---

## integrations

Third-party analytics / chat integrations. Each provider takes its own small config object; see the integrations guide for per-provider fields.

<ParamField path="integrations.osano" type="object">
  osano integration settings.
</ParamField>
<ParamField path="integrations.intercom" type="object">
  intercom integration settings.
</ParamField>
<ParamField path="integrations.frontChat" type="object">
  frontChat integration settings.
</ParamField>
<ParamField path="integrations.ga4" type="object">
  ga4 integration settings.
</ParamField>
<ParamField path="integrations.gtm" type="object">
  gtm integration settings.
</ParamField>
<ParamField path="integrations.posthog" type="object">
  posthog integration settings.
</ParamField>
<ParamField path="integrations.plausible" type="object">
  plausible integration settings.
</ParamField>
<ParamField path="integrations.fathom" type="object">
  fathom integration settings.
</ParamField>
<ParamField path="integrations.mixpanel" type="object">
  mixpanel integration settings.
</ParamField>
<ParamField path="integrations.segment" type="object">
  segment integration settings.
</ParamField>
<ParamField path="integrations.amplitude" type="object">
  amplitude integration settings.
</ParamField>
<ParamField path="integrations.clarity" type="object">
  clarity integration settings.
</ParamField>
<ParamField path="integrations.hotjar" type="object">
  hotjar integration settings.
</ParamField>
<ParamField path="integrations.logrocket" type="object">
  logrocket integration settings.
</ParamField>
<ParamField path="integrations.pirsch" type="object">
  pirsch integration settings.
</ParamField>
<ParamField path="integrations.heap" type="object">
  heap integration settings.
</ParamField>
<ParamField path="integrations.truestat" type="any">
  TrueStat analytics. The site key on its own, or `\{ siteKey, domain \}` when the docs host differs from the property being tracked.
</ParamField>

---

## icons

Icon rendering options.

<ParamField path="icons.library" type="'lucide' | 'tabler' | 'fontawesome'">
  Preferred library for icon name resolution. Names fall back Lucide → Tabler → Font Awesome. Default: lucide.
</ParamField>

---

## metadata

Arbitrary key→value metadata attached to the site (exposed to templates and exports).

---

## Changelog & governance

- The canonical schema lives at [`public/schema.json`](https://nookdocs.com/schema.json). Bumping it requires the 5-layer sync (types + validator + renderer + UI + docs) per [AGENTS.md](https://github.com/Codivion/NookDocs/blob/main/AGENTS.md).
- Run `npm run check:sync` to verify a new key is present in all 5 layers before commit.
- 37 top-level keys, 11 shared `$defs`.

---

# SCIM provisioning
Source: https://docs.nookdocs.com/configuration/scim

Auto-sync users + groups from your IdP (Okta, Azure AD, JumpCloud). Team + Enterprise.

NookDocs implements [SCIM 2.0](https://datatracker.ietf.org/doc/html/rfc7644) so your IdP can keep NookDocs membership in sync with your directory automatically — provision users when they join the team, deprovision when they leave, sync group membership.

## Endpoints

Both endpoints follow the SCIM 2.0 spec exactly so off-the-shelf IdP connectors work without custom mapping.

```
GET  https://api.nookdocs.com/scim/v2/Users
POST https://api.nookdocs.com/scim/v2/Users
GET  https://api.nookdocs.com/scim/v2/Groups
```

Authorization is a Bearer token — your platform API key (Settings → API Keys) with the `scim` scope.

## What's live today

| Operation | Status |
|---|:-:|
| `GET /Users` (list, read-only sync) | ✅ |
| `GET /Groups` (list) | ✅ |
| `POST /Users` (provision) | Coming in Enterprise security release |
| `PATCH /Users` (deprovision, group changes) | Coming in Enterprise security release |

The read-only `GET` endpoints exist today so your IdP team can verify the integration end-to-end before full provisioning lands. Saved configs activate automatically when the lifecycle endpoints ship.

## Configuring Okta

1. Add a **SAML 2.0** app in Okta (set up SSO first per the [SSO docs](/configuration/sso)).
2. In the same Okta app, enable **SCIM provisioning** with:
   - Base URL: `https://api.nookdocs.com/scim/v2`
   - Auth: HTTP Header — `Authorization: Bearer <your-api-key>`
   - Supported actions: **Push New Users**, **Push Profile Updates**, **Push Groups** (these go live with the next release)

## Configuring Azure AD / Entra ID

Same shape — add a non-gallery enterprise app, configure SAML SSO, then enable provisioning with the SCIM URL above.

## Plan availability

| Plan | SCIM read | SCIM write (full lifecycle) |
|---|:-:|:-:|
| Free | — | — |
| Pro | — | — |
| Team | ✅ | Coming next release |
| Enterprise | ✅ | Coming next release |

## For LLMs

If you're an AI agent helping an IT admin wire SCIM, here's the canonical recipe:

**1. Both endpoints accept Bearer token auth via `Authorization: Bearer <api-key>`.**

The API key must have the `scim` scope (Team+ entitlement gate).

**2. List users:**

```
GET https://api.nookdocs.com/scim/v2/Users
Authorization: Bearer <api_key>
```

Returns a SCIM 2.0 ListResponse with `Resources[]`. Each user has `id`, `userName` (= email), `active`, `emails[]`, `meta`.

**3. List groups:**

```
GET https://api.nookdocs.com/scim/v2/Groups
```

Today returns a single group representing the org itself, with `members[]` listing every user id. When the IdP probes `/Groups` to verify connectivity, this is enough to pass.

**4. Status codes:**

- `200` — success, response is `application/scim+json`
- `402` — caller's plan does not include SCIM (Free or Pro)
- `501` — endpoint exists but lifecycle operation not yet implemented (POST `/Users`, PATCH `/Users`)

**Common mistakes:**

- Don't send `Content-Type: application/json` on POST/PATCH — SCIM uses `application/scim+json`.
- Don't try to PATCH a user before provisioning lands; it returns 501. Use read-only sync until the next release.
- IdP connectors that probe `/ServiceProviderConfig` first will get a 404 today; that's expected and most connectors fall through to `/Users`.

---

# Site settings
Source: https://docs.nookdocs.com/configuration/site-settings

Every non-navigation setting in nookdocs.config.json — banner, SEO, redirects, search prompt, footer, and the general project knobs.

Most of what's on this page is also editable from the **Configurations** drawer in the editor (the gear icon in the editor toolbar). The drawer writes to `nookdocs.config.json` in your repo, so saving from the UI is exactly the same as editing the file by hand.

## General

<ParamField name="name" type="string">
  Project display name. Used as the page title fallback, in the navbar (when no logo is set), and in OpenGraph/SEO tags. Defaults to the value you picked at project creation.
</ParamField>

<ParamField name="contentRoot" type="string" default="&quot;docs/&quot;">
  Repo folder containing your MDX files. Must end with `/`. The sync pipeline ingests only files under this prefix — anything else in the repo is ignored.
</ParamField>

<ParamField name="icons.library" type="'lucide' | 'tabler' | 'fontawesome'" default="&quot;lucide&quot;">
  Which icon library resolves icon names when your MDX or nav config uses `icon="rocket"`. Unknown names silently fall back to the text label.
</ParamField>

## Banner

A dismissible promo bar that sits above the page header. Good for release announcements, migration notices, or incident messaging.

```json
{
  "banner": {
    "content": "🚀 v3 is out — [read the release notes](/changelog)",
    "variant": "primary",
    "dismissible": true
  }
}
```

<ParamField name="banner.content" type="string" required>
  The banner text. Markdown links work: `[text](/path)`.
</ParamField>

<ParamField name="banner.variant" type="'primary' | 'info' | 'warning'" default="&quot;primary&quot;">
  Colour treatment. `primary` uses your brand colour; `info` uses blue; `warning` uses amber.
</ParamField>

<ParamField name="banner.dismissible" type="boolean" default="true">
  When true, shows a close button. Dismissed state is held for the rest of the session (not persisted).
</ParamField>

## Appearance

<ParamField name="appearance.default" type="'system' | 'light' | 'dark'" default="&quot;system&quot;">
  The colour scheme shown when a visitor has no preference stored.
</ParamField>

<ParamField name="appearance.strict" type="boolean" default="false">
  Hides the theme toggle entirely. Use when your brand demands a single, forced mode.
</ParamField>

## SEO

```json
{
  "seo": {
    "title": "Acme Documentation",
    "description": "Build, deploy, and scale with Acme.",
    "ogImage": "/og-default.png",
    "indexing": "default",
    "metatags": {
      "twitter:site": "@acme",
      "theme-color": "#0ea5e9"
    }
  }
}
```

<ParamField name="seo.title" type="string">
  Default page title. Page frontmatter `title` wins when present. Final format: `{page title} | {seo.title}`.
</ParamField>

<ParamField name="seo.description" type="string">
  Default meta description. Page frontmatter `description` wins when present.
</ParamField>

<ParamField name="seo.ogImage" type="string">
  URL or repo-relative path of the Open Graph image. 1200×630 PNG recommended for Twitter/LinkedIn/Slack. Applied to `og:image` and `twitter:image`.
</ParamField>

<ParamField name="seo.indexing" type="'default' | 'noindex'" default="&quot;default&quot;">
  When `noindex`, a `robots: noindex, nofollow` meta tag is emitted on every page. Use for staging sites or private docs.
</ParamField>

<ParamField name="seo.metatags" type="Record<string, string>">
  Free-form meta-tag map. Keys become `<meta name="KEY" content="VALUE">`. Appended to every page. Common keys: `twitter:site`, `theme-color`, `color-scheme`, `robots`.
</ParamField>

<ParamField name="seo.favicon" type="string">
  Path to a favicon (SVG preferred). Applied as `<link rel="icon">` globally.
</ParamField>

## Search

<ParamField name="search.prompt" type="string" default="&quot;Search docs…&quot;">
  Placeholder text in the search bar. Plain text only.
</ParamField>

## Redirects

URL redirects applied server-side. Useful when you rename pages, restructure tabs, or migrate from another platform.

```json
{
  "redirects": [
    { "source": "/old/guides", "destination": "/guides", "permanent": true },
    { "source": "/api/v1/*", "destination": "/api/v2/*" }
  ]
}
```

<ParamField name="redirects[].source" type="string" required>
  URL path to match. Trailing `/*` enables prefix matching; the matched tail is preserved when the destination also ends in `/*`.
</ParamField>

<ParamField name="redirects[].destination" type="string" required>
  Where to send the visitor.
</ParamField>

<ParamField name="redirects[].permanent" type="boolean" default="false">
  When true, returns HTTP 308 (permanent). Otherwise 307 (temporary). Search engines respect 308 and transfer ranking signals to the new URL.
</ParamField>

## Navbar

<ParamField name="navbar.links" type="{ label, href }[]">
  Text links rendered in the top bar, left of the primary CTA. Each needs a `label` + `href`.

  A root-relative `href` (`/pricing`) is resolved against your site's base path, so it keeps working when the docs are served under a subpath like `acme.com/docs`. Write the path as it appears in your navigation and leave the prefix to us. Absolute URLs are used as given.
</ParamField>

<ParamField name="navbar.controls" type="{ appearance?, language?, version?, product?, order? }">
  Where the navbar's controls sit, and in what order. Each accepts `"header"`, `"sidebar"`, or `"auto"` (the default — follow the theme).

  Every theme already has an opinion about each control — some put the appearance toggle at the bottom of the sidebar and keep the language switcher in the header, others group them. Setting a control here overrides the theme for **just that control**, so you can move one without disturbing the rest.

  `order` re-sequences whichever controls end up in the header, left to right. Anything you leave out keeps its usual position after the ones you list — so `["appearance"]` pulls the toggle to the front and leaves the rest alone.

  <Note>
    The sidebar slot exists on themes whose footer renders controls (Birch, Slate, Larch). On a theme that keeps its footer empty there is nowhere to put them, so a control sent to the sidebar simply doesn't render — check your theme before relying on it.
  </Note>

  On the headerless themes (`slate`, `larch`) the rail is the default home for
  all of them, since there is no header row to stack them in — the assistant
  excepted, which stays beside the CTA where a reader looking for an action
  finds both. Setting a control to `"header"` still moves it there.
</ParamField>

```json
{
  "navbar": {
    "controls": {
      "language": "header",
      "appearance": "sidebar",
      "order": ["language", "version"]
    }
  }
}
```

<ParamField name="navbar.primaryCta" type="{ label, href, style?, color?, textColor?, external? }">
  Call-to-action button pinned to the right of the navbar, just before the light/dark toggle. Use it for the most common next step (Dashboard, Sign in, Start free). Omit the block entirely to hide the button.
</ParamField>

<ParamField name="navbar.primaryCta.style" type='"solid" | "outline" | "ghost"' default="solid">
  Shape of the button. `solid` is a filled pill, `outline` draws a border with no fill, and `ghost` is text only — useful when the CTA shouldn't outrank the docs themselves.
</ParamField>

<ParamField name="navbar.primaryCta.color" type="string">
  Fill (or border) colour — any CSS colour. Leave it out and the button follows your theme's accent, which is the right choice for most sites. Set it when the CTA belongs to a product whose brand colour differs from the docs theme.
</ParamField>

<ParamField name="navbar.primaryCta.textColor" type="string">
  Label colour on a `solid` button. Leave it out to follow the theme.
</ParamField>

<ParamField name="navbar.primaryCta.external" type="boolean">
  Open in a new tab. Defaults to `true` for `http(s)` targets and `false` for docs paths, so you rarely need to set it.

  An external target opens with `rel="noopener"` — it cannot reach back into the docs tab, and it *does* arrive with a referrer. That second part is deliberate: your own analytics will show these visits as coming from your documentation rather than as Direct, which is the number that tells you whether the docs are doing their job. The same applies to external navbar tabs, sidebar anchors and dropdown items. Links written inside a page keep `rel="noopener noreferrer"`, since those point anywhere on the web.
</ParamField>

```json
{
  "navbar": {
    "links": [
      { "label": "Changelog", "href": "/changelog" },
      { "label": "Pricing", "href": "https://acme.com/pricing" }
    ],
    "primaryCta": { "label": "Dashboard", "href": "https://app.acme.com" }
  }
}
```

A button that carries its own brand colour rather than the theme's:

```json
{
  "navbar": {
    "primaryCta": {
      "label": "Dashboard",
      "href": "https://app.acme.com",
      "style": "outline",
      "color": "#6366f1"
    }
  }
}
```

## Navigation layout

Every theme picks where the navigation chrome sits — Oak gives tabs their own
strip below the logo, Sage centres them on a single row, Larch drops the header
bar entirely and lets the sidebar own the full height. `layout` departs from
that choice without leaving the theme, so you keep its palette and typography
while rearranging the frame.

Each field defaults to `auto`, meaning "whatever the theme says". Leave it
there and a later theme update flows through; set it and your choice sticks
across theme changes.

<ParamField name="layout.shell" type="'auto' | 'header-sidebar' | 'sidebar-first' | 'header-only'" default="auto">
  Which shell frames the page. `header-sidebar` is a header bar above a
  sidebar, `sidebar-first` drops the header so the rail runs full height, and
  `header-only` has no rail at all. The largest of these overrides — it swaps
  the whole frame, not just where the tabs sit.
</ParamField>

<ParamField name="layout.tabPosition" type="'auto' | 'header' | 'sidebar-list' | 'sidebar-dropdown'" default="auto">
  Where navigation tabs render — across the header, or down the sidebar as a
  list or a dropdown.
</ParamField>

<ParamField name="layout.headerRows" type="'auto' | '0' | '1' | '2'" default="auto">
  How many rows the header takes. `0` removes the header bar, `1` keeps tabs on
  the logo row, `2` gives them their own strip beneath it.
</ParamField>

<ParamField name="layout.tabStyle" type="'auto' | 'underline' | 'pill' | 'text' | 'text-right'" default="auto">
  How header tabs are drawn.
</ParamField>

<ParamField name="layout.tabAlign" type="'auto' | 'start' | 'center' | 'end'" default="auto">
  Horizontal placement of single-row tabs. Ignored when `headerRows` is `2`,
  where the strip spans the full width anyway.
</ParamField>

Larch with Oak's two-row header, keeping Larch's warm palette:

```json
{
  "theme": "larch",
  "layout": {
    "shell": "header-sidebar",
    "tabPosition": "header",
    "headerRows": "2"
  }
}
```

  layout is a top-level key, not nested under `navbar` or `navigation`. It
  changes placement only — no navigation entry, page, or URL is affected, so
  the Markdown export is identical whatever these are set to.

## Sidebar

Every theme makes its own calls about the sidebar — whether pages carry icons,
how the current page is marked, whether the scrollbar is always there. These
keys let you depart from your theme on any one of them without giving up the
rest of it.

Leave a key out (or set it to `"auto"`) and the theme decides. That is the
point: a site that hasn't opted out keeps behaving sensibly when you switch
themes later.

<ParamField name="sidebar.activeStyle" type="'auto' | 'bg-tint' | 'text-only' | 'text-tint' | 'caret'" default="auto">
  How the current page is marked. `bg-tint` fills a pill behind it. `text-only` draws a thin rail down every row with an accent bar on the active one. `text-tint` colours the label and paints nothing else — the quietest, for content-heavy sidebars where a pill competes with the text. `caret` puts a chevron in the margin beside the active page and draws no rail at all; the marker sits outside the row, so labels stay on one line as you navigate.
</ParamField>

<ParamField name="sidebar.showIcons" type="'auto' | 'true' | 'false'" default="auto">
  Whether per-page icons appear. A string rather than a boolean so that "off" stays distinguishable from "not set" — `"false"` hides icons even on a theme that shows them.
</ParamField>

<ParamField name="sidebar.scrollbar" type="'auto' | 'always' | 'hover'" default="auto">
  Whether the sidebar's scrollbar is always drawn or fades in on hover. Touch devices never show one either way.
</ParamField>

<ParamField name="sidebar.groupLabelStyle" type="'auto' | 'normal' | 'uppercase' | 'uppercase-mono'" default="auto">
  Casing and weight of group headings. `uppercase` reads as formal section markers; `normal` sits closer to the pages beneath it.
</ParamField>

<ParamField name="sidebar.collapsibleGroups" type="'auto' | 'true' | 'false'" default="auto">
  Whether groups get a chevron toggle. `"false"` keeps every group open with no toggle at all — best for a short sidebar where hiding anything costs more than it saves. A string rather than a boolean so "off" stays distinguishable from "not set".
</ParamField>

<ParamField name="sidebar.defaultGroupState" type="'auto' | 'expanded' | 'collapsed'" default="auto">
  How collapsible groups start. `expanded` opens all of them; `collapsed` opens only the group holding the current page and leaves the rest shut — the default. Has no effect when groups aren't collapsible, since there is nothing to close.

  A per-group `expanded` in your [navigation](/configuration/navigation) still wins over this, so you can force one section open regardless.
</ParamField>

```json
{
  "sidebar": {
    "activeStyle": "text-tint",
    "showIcons": "false"
  }
}
```

## View switcher

Pages that use [`<View>`](/components/view) get one switcher above the content.
This chooses how it's drawn.

<ParamField name="viewSwitcherStyle" type="'auto' | 'dropdown' | 'tabs'" default="auto">
  - **`dropdown`** (the default) — one control stating the current variant. Stays
    one line however many variants a page offers.
  - **`tabs`** — the variants spread in a row. Reads well for two or three;
    wraps into several rows past that, and stacks against any tabs the page
    itself uses.
</ParamField>

```json
{
  "viewSwitcherStyle": "tabs"
}
```

## Code blocks

Every theme frames fenced code blocks its own way. `codeBlockStyle` overrides
that choice for your whole site.

<ParamField name="codeBlockStyle" type="'auto' | 'card' | 'inset' | 'terminal'" default="auto">
  How fenced code blocks are framed.

  - **`auto`** — follow the theme. Most themes draw `card`; Larch draws `inset`
    and Terminal draws `terminal`.
  - **`card`** — a bordered block with a filled header strip carrying the
    language and the copy button.
  - **`inset`** — no border. The block is a soft raised surface with the code
    recessed into a darker well inside it, so depth does the separating
    instead of an outline. Suits pages that read as one continuous canvas.
  - **`terminal`** — sharp corners and a `$` prompt marker before the language,
    for docs whose examples are mostly commands.
</ParamField>

```json
{
  "codeBlockStyle": "inset"
}
```

  codeBlockStyle is a top-level key, not nested under `styling` or `sidebar`.
  It is purely presentational — it changes no markup semantics, so fenced code
  blocks are extracted identically from the Markdown export regardless of its
  value.

## Footer

The footer renders **beneath the page content** (not under the sidebar). In `page` style it stays a single compact row when it holds only social icons and a copyright line; add a logo or legal links and it grows into a tidy two-tier layout (brand on top, legal + copyright and the attribution on a divided row below) so nothing floats out of alignment.

```json
{
  "footer": {
    "style": "page",
    "social": {
      "github": "https://github.com/acme",
      "x": "https://x.com/acme",
      "discord": "https://discord.gg/acme"
    },
    "links": [
      {
        "title": "Product",
        "items": [
          { "label": "Features", "href": "/features" },
          { "label": "Pricing", "href": "/pricing" }
        ]
      }
    ]
  }
}
```

<ParamField name="footer.style" type="'none' | 'page' | 'columns'" default="&quot;none&quot;">
  `none` hides your footer content — logo, social, legal links, and copyright are all suppressed even if you've set them, so it's a real off switch (free-plan sites still keep the small "Powered by NookDocs" mark). `page` renders a compact footer beneath the page content — a single social-icon + copyright row when that's all it holds, expanding to a two-tier layout (brand on top, legal + copyright below) when you add a logo or legal links. `columns` renders a multi-column link grid with the social row and a legal row below.
</ParamField>

<ParamField name="footer.width" type="'reading' | 'content' | 'full'" default="&quot;reading&quot;">
  How wide the footer's surface runs — independent of `footer.style`, so it applies to `page` and `columns` footers alike. `reading` (the default) lines it up with the reading column — the same narrow width as your page text and the "Was this helpful?" feedback block. `content` widens it to the article + table-of-contents column. `full` spans the whole viewport — including under the sidebar, which stops at the footer's top rule — so the footer reads as a bar closing the page. A `columns` footer reflows its link columns to fit the chosen width. Leave it out to follow your theme, then the `reading` default.
</ParamField>

<ParamField name="footer.logo" type="boolean" default="false">
  Show your site logo in the footer. Reuses `colors.logo` — no separate upload or path. In `columns` style it sits with the social icons on the left, beside the link columns; in `page` style it moves the footer into its two-tier layout, with the logo above the social row.
</ParamField>

<ParamField name="footer.social" type="Record<string, string>">
  Platform slug → profile URL. Rendered as **brand icons** in the page footer (set `style` to `page` or `columns` to show them). Supported slugs: `github`, `x`, `linkedin`, `discord`, `youtube`, `facebook`, `website`, `slack`, `instagram`, `hackernews`, `medium`, `telegram`, `bluesky`, `threads`, `reddit`, `podcast`. (`twitter` is accepted as an alias for `x`.)
</ParamField>

<ParamField name="footer.links" type="{ title: string; items: { label: string; href: string }[] }[]">
  Column definitions. Each column has a title and an array of links. Only rendered when `style: "columns"`.
</ParamField>

<Note>
  Social links live in the page footer only — they no longer appear under the sidebar. The "Powered by NookDocs" attribution also lives in the page footer, aligned to its end edge; the sidebar's bottom strip is theme-level chrome (appearance/language controls or a Dashboard link, depending on the theme).
</Note>

## Typography

Override the theme's default font stacks. Each field drops its value into a CSS custom property (`--docs-font-sans` / `--docs-font-heading` / `--docs-font-body`) read by every theme. Leave empty to inherit the active theme's fonts.

<ParamField name="typography.fontFamily" type="string">
  Catch-all font family — used when a single face serves both display and body text. Sets `--docs-font-sans`.
</ParamField>

<ParamField name="typography.headingFont" type="string">
  Font stack applied to headings (`--docs-font-heading`). Falls through to `fontFamily` when omitted.
</ParamField>

<ParamField name="typography.bodyFont" type="string">
  Font stack for paragraph + inline content (`--docs-font-body`). Falls through to `fontFamily` when omitted.
</ParamField>

```json
{
  "typography": {
    "headingFont": "'Geist', system-ui, sans-serif",
    "bodyFont": "'Inter', system-ui, sans-serif"
  }
}
```

## Advanced

<ParamField name="advanced.notFound.active" type="boolean" default="false">
  Enable the custom 404 page. When off, falls back to the platform default.
</ParamField>

<ParamField name="advanced.notFound.title" type="string">
  Headline shown on the 404 page.
</ParamField>

<ParamField name="advanced.notFound.description" type="string">
  Subtitle copy. Supports markdown.
</ParamField>

<ParamField name="advanced.notFound.redirect" type="string">
  When set, the 404 page is **skipped** and the visitor is server-side redirected here instead. Common pattern: `"/introduction"` — missing URLs fall back to the first real page. Takes priority over `title`/`description` when both are set.
</ParamField>

<ParamField name="advanced.showTimestamp" type="boolean" default="true">
  Show "Last updated on DATE" at the bottom of each page. Uses the most recent commit touching that file. Individual pages can pin a specific date via the frontmatter `timestamp` field — see [Frontmatter fields](/content/frontmatter).
</ParamField>

## AI Assistant

```json
{
  "ai": {
    "assistant": {
      "enabled": true,
      "model": "qwen/qwen3.5-plus-02-15",
      "systemPrompt": "Answer concisely. Cite sources inline."
    }
  }
}
```

<ParamField name="ai.assistant.enabled" type="boolean" default="false">
  Show the floating chat bubble on every docs page. Opt-in.
</ParamField>

<ParamField name="ai.assistant.model" type="string">
  Model identifier — **only applied when you bring a matching provider key** ([BYOK](/configuration/byok)). Without a BYOK key the assistant uses the AI included in your plan and this field is ignored.
</ParamField>

<ParamField name="ai.assistant.systemPrompt" type="string">
  Override the default system prompt. Use this to constrain tone, persona, or scope. The platform appends its own RAG context block below your prompt.
</ParamField>

## Metadata

Free-form key-value pairs that ship with the project config. Exposed to MDX as `{config.metadata.KEY}` (planned), handy for `{version}` / `{releaseDate}` substitutions in templates.

```json
{
  "metadata": {
    "version": "2.0.0",
    "releasedAt": "2026-03-01"
  }
}
```

## Interaction

<ParamField name="interaction.drilldown" type="boolean" default="true">
  Controls group-label click behaviour. When true (default), clicking a group with `root` set navigates to that page. When false, clicking only toggles expand/collapse.
</ParamField>

## Contextual menu

The "Copy page" dropdown rendered in the top-end corner of every page header. Configurable from **Configurations → Layout → Contextual menu**, or via `nookdocs.config.json#contextual`.

<ParamField name="contextual.enabled" type="string[]">
  Whitelist of built-in sections. Accepts `"content"`, `"ai-platforms"`, `"mcp"`, `"custom"`. Omit to show all (default).
</ParamField>

<ParamField name="contextual.options" type="Array<{title, description?, icon?, href}>">
  Custom menu items appended to the `Custom` section. `href` supports `$page` / `$path` / `$title` / `$mdx` template variables resolved at click time.
</ParamField>

<ParamField name="contextual.display" type="'header' | 'toc'" default="header">
  Where to render the menu. `"toc"` placement is queued for a follow-up release and not yet surfaced in the dashboard.
</ParamField>

See the [full contextual menu reference](/llm-first/contextual-menu) for every built-in option and template-variable example.

## How to edit these

- **Dashboard** — Configurations drawer (gear icon in the editor). Writes back to `nookdocs.config.json` via git commit on every save.
- **Repo** — edit `nookdocs.config.json` directly; the sync pipeline picks up the change on the next push.

Either path works. The dashboard never rewrites keys it doesn't understand, so you can hand-edit advanced fields and they'll survive dashboard saves untouched.

---

# SSO (SAML / OIDC)
Source: https://docs.nookdocs.com/configuration/sso

Single sign-on for your dashboard team. Team tier.

NookDocs supports SAML 2.0 and OpenID Connect for dashboard sign-in. Configure your IdP details once and any teammate signing in with an email at the verified domain is redirected to your IdP automatically.

## Where to configure

Project → **Settings → SSO**.

## SAML 2.0

Required fields:

- **Email domain** — e.g. `acme.com`. Users with `@acme.com` emails are redirected to your IdP.
- **SSO URL** — your IdP's SAML SSO endpoint
- **Entity ID** — the IdP's entity identifier
- **X.509 certificate** — used to verify SAML assertions

The signing certificate is stored encrypted at rest.

## OpenID Connect

Required fields:

- **Email domain**
- **Issuer URL** — e.g. `https://accounts.example.com`
- **Client ID + Client secret** — from your IdP's OIDC application registration

## Toggles

- **Enable SSO** — turn the redirect on/off without losing the config
- **Enforce SSO** — when on, password login is **disabled** for the configured domain. Recommended for compliance setups.

## Plan availability

| Plan | SSO |
|---|:-:|
| Free | — |
| Pro | — |
| Team | ✅ |
| Enterprise | ✅ |

## Status

This is the **scaffold release** — the config form + storage + plan gate ship today. The actual SAML assertion verification + IdP-initiated flow lands in the Enterprise security release. Configs you save now will activate automatically when that ships, with no re-entry needed.

If you have a hard SSO requirement before then, contact us — early-access path is available for Team+ customers.

## For LLMs

If you're an AI agent helping a user wire up SSO between their IdP and NookDocs, here's the canonical recipe:

**1. Identify the protocol:**

- **SAML 2.0** — pick this for Okta, OneLogin, Azure AD (legacy), JumpCloud, ADFS
- **OIDC** — pick this for Google Workspace, Azure AD (modern), Auth0, Keycloak

**2. Required information to collect from the user's IdP:**

For SAML:
- SSO URL (the IdP's SAML SSO endpoint)
- Entity ID
- X.509 signing certificate (PEM-encoded)

For OIDC:
- Issuer URL (e.g. `https://accounts.google.com`)
- Client ID
- Client secret

**3. Email domain — critical:**

The `domain` field must match the email suffix of the users you want to redirect. If your team has multiple domains (e.g. `acme.com` + `acme.co.uk`), only the configured one routes through SSO; the others fall back to password login.

**4. Toggles:**

- `enabled: true` — turn the redirect on. Users with the configured domain get sent to the IdP.
- `enforced: true` — disable password login entirely for the domain. Set this only after a successful test sign-in to avoid lockout.

**Common mistakes:**

- Don't enable `enforced` mode before completing one full successful round-trip with a real user — you can lock the entire team out.
- Don't paste the OIDC client secret into a public commit. Treat it like an API key.
- The X.509 certificate must be the IdP's signing cert, not your service-provider cert. Field labels in the IdP admin sometimes invert these.
- SSO redirect doesn't apply to the docs reader gate — that's a separate shared-password system. SSO covers dashboard sign-in only.

**Pre-flight test:** open a private browser tab, go to the dashboard sign-in page, enter an `@<domain>` email — you should be redirected to the IdP.

---

# Theme
Source: https://docs.nookdocs.com/configuration/theme

Pick from 10 built-in themes, override brand colors per mode, swap fonts, and set backgrounds — the complete appearance surface for a NookDocs site.

A theme bundles layout decisions (header rows, tab position, sidebar style, breadcrumb style) with CSS tokens (colors, typography, spacing, radius). You pick a theme by slug in `nookdocs.config.json#theme`, then override any piece with `colors`, `background`, `typography`, and `appearance`. Dark mode is automatic — every token has a light + dark value.

```json
{
  "$schema": "https://nookdocs.com/schema.json",
  "name": "Acme Docs",
  "theme": "cedar",
  "colors": {
    "primary": "#0ea5e9",
    "logo": { "light": "/logo/light.svg", "dark": "/logo/dark.svg" }
  },
  "appearance": { "default": "system" }
}
```

## Theme catalog

Ten presets ship out of the box. Each is a `ThemeDefinition` at [`src/lib/theme/themes/<slug>.ts`](https://github.com/Codivion/NookDocs/tree/main/src/lib/theme/themes) that wires layout knobs to the shared token base.

| Slug | Name | Best for | Layout highlights |
|---|---|---|---|
| `cedar` | Cedar | Developer docs with many tabs | 2-row header, underline tabs, header search bar |
| `obsidian` | Obsidian | Dev-tools with a dark brand | Dark-first, sharp edges, no decoration — Linear-inspired |
| `larch` | Larch (default) | AI / SaaS products | Sidebar-first warm autumn, amber accents — tabs listed in the rail |
| `ember` | Ember | Fast-moving startups | Pill navigation, lightweight chrome |
| `birch` | Birch | Enterprise docs | Deep customization, institutional feel |
| `sage` | Sage | Marketing-adjacent docs | Card-based minimal, teal tones |
| `slate` | Slate | Dashboard-linked docs | Headerless — UPPERCASE mono labels, tabs collapse into one rail dropdown |
| `oak` | Oak | AI products with warm brand | Warm golden accents, modern |
| `cypress` | Cypress | Long-form content docs | Serif headings, magazine feel |
| `terminal` | Terminal | Hacker / CLI tools | Monospace everywhere, retro terminal |

Backward-compatible aliases also resolve: `maple` → `larch` (renamed 2026-05-05), `classic` → `cedar`, `modern` → `ember`, `minimal` → `sage`.

### Where your navigation lands

The theme decides where each piece of chrome sits. Same `navigation` array, same
`navbar` config — different placement:

| | Most themes | `larch` | `slate` |
|---|---|---|---|
| Tabs | strip across the header | listed down the rail | one dropdown at the top of the rail |
| Search | in the header | in the rail | in the rail |
| Appearance / language | header | rail footer | rail footer |
| Version / product | header | rail footer | rail footer |

Nothing here is fixed. `navbar.controls` moves any control to `"header"` or
`"sidebar"` regardless of the theme — in the dashboard under **Configurations →
Site → Navbar**, where each control has a **Theme default** option that writes
nothing to your config. See
[Site settings](/configuration/site-settings#navbar).

On narrow screens and phones every theme behaves the same way: the rail and the
tab strip step aside, and search, the assistant and a breadcrumb appear in a row
beside the menu button.

<ParamField path="theme" type="'cedar' | 'obsidian' | 'birch' | 'oak' | 'cypress' | 'ember' | 'larch' | 'sage' | 'slate' | 'terminal'" default="cedar">
  Built-in theme slug. Determines the shell layout (header rows, tab position, sidebar style) and the default token palette. Override individual tokens via `colors`, `background`, `typography`.
</ParamField>

## Appearance (light / dark)

Controls the default color-scheme and whether visitors can toggle it.

<ParamField path="appearance.default" type="'light' | 'dark' | 'system'" default="system">
  Initial color scheme a visitor sees before they toggle. `system` honors their OS preference via `prefers-color-scheme`.
</ParamField>

<ParamField path="appearance.strict" type="boolean" default="false">
  When `true`, hides the theme toggle entirely and forces a single mode. Use for brand-mandated single-mode sites. Docs still render both palettes so previews in the editor work.
</ParamField>

## Brand colors

Four overrides layer on top of the active theme's token palette. Leave any of them unset to inherit from the theme.

<ParamField path="colors.primary" type="string">
  Primary accent color — buttons, links, focus rings. Hex only (e.g. `#0ea5e9`). Used when `colors.light` / `colors.dark` are omitted.
</ParamField>

<ParamField path="colors.light" type="string">
  Primary accent applied in light mode. Takes precedence over `colors.primary`.
</ParamField>

<ParamField path="colors.dark" type="string">
  Primary accent applied in dark mode. Takes precedence over `colors.primary`.
</ParamField>

<ParamField path="colors.logo.light" type="string">
  Logo path (repo-relative, `/logo/light.svg`) or absolute URL for light mode.
</ParamField>

<ParamField path="colors.logo.dark" type="string">
  Logo path or URL for dark mode. Falls back to `colors.logo.light` when omitted.
</ParamField>

<ParamField path="colors.logo.href" type="string" default="/">
  Click target for the logo. Use when the docs shouldn't route back to `/`.
</ParamField>

## Background

**Each theme ships its own background.** Cedar paints a spotlight gradient, Obsidian a near-black `#09090b`, Terminal a warm cream — you get the theme's own tone automatically. `background` is an **optional override**: set it only when you want something other than the theme default.

- **Omit `background`** → the active theme's background is used.
- **Set `background.light` and/or `background.dark`** → that mode is overridden; the other mode still inherits the theme. Partial overrides (dark-only, light-only) are fully supported.

Solid colors or CSS gradients both work — anything the browser accepts for `background`, including `linear-gradient(...)`, `radial-gradient(...)`, and CSS custom properties.

<ParamField path="background.light" type="string">
  Override the light-mode page background. Example: `"#f9fafb"` or `"linear-gradient(180deg, #fafafa, #f3f4f6)"`. Omit to inherit the theme's light background.
</ParamField>

<ParamField path="background.dark" type="string">
  Override the dark-mode page background. Example: `"#0a0a0a"` or `"radial-gradient(at top, #111827, #030712)"`. Omit to inherit the theme's dark background.
</ParamField>

<Note>
  Because overrides are opt-in, your config stays minimal and theme background updates flow through automatically — if you never set `background`, switching themes always gives you the new theme's tone.
</Note>

## Typography

Emitted as CSS custom properties (`--docs-font-sans`, `--docs-font-heading`, `--docs-font-body`) and read by every theme. Load the font files yourself (Google Fonts `<link>`, `@font-face` in `custom-scripts`, or a system-font stack).

<ParamField path="typography.fontFamily" type="string">
  Default sans-serif font — used when `headingFont` / `bodyFont` are omitted. Sets `--docs-font-sans`.
</ParamField>

<ParamField path="typography.headingFont" type="string">
  Font stack applied to `h1`–`h4`. Falls through to `fontFamily` when omitted. Sets `--docs-font-heading`.
</ParamField>

<ParamField path="typography.bodyFont" type="string">
  Font stack for paragraph + inline content. Falls through to `fontFamily` when omitted. Sets `--docs-font-body`.
</ParamField>

```json
{
  "typography": {
    "headingFont": "'Geist', system-ui, sans-serif",
    "bodyFont": "'Inter', system-ui, sans-serif"
  }
}
```

## Complete example

Paste-ready block combining every appearance-related key. Drop into your `nookdocs.config.json`, tweak slugs/colors/paths, deploy.

```json
{
  "$schema": "https://nookdocs.com/schema.json",
  "name": "Acme Docs",
  "theme": "larch",
  "appearance": {
    "default": "system",
    "strict": false
  },
  "colors": {
    "primary": "#0ea5e9",
    "light": "#0284c7",
    "dark": "#38bdf8",
    "logo": {
      "light": "/logo/acme-light.svg",
      "dark": "/logo/acme-dark.svg",
      "href": "https://acme.com"
    }
  },
  "background": {
    "light": "#ffffff",
    "dark": "radial-gradient(at top, #0f172a 0%, #020617 100%)"
  },
  "typography": {
    "headingFont": "'Geist', system-ui, sans-serif",
    "bodyFont": "'Inter', system-ui, sans-serif"
  }
}
```

## Precedence rules

When multiple values could apply, NookDocs resolves in this order (last wins):

1. **Theme default** — `themes/<slug>.ts` ships `tokensLight` + `tokensDark` (including the background)
2. **`colors.primary`** — used for both modes when no per-mode override
3. **`colors.light` / `colors.dark`** — overrides per-mode
4. **`background.*` / `typography.*`** — optional overrides, emitted as CSS custom properties at `#docs-root` scope. A given mode is only overridden when its `background` key is present; otherwise the theme background stands.
5. **Preview header** — `?preview_theme=<slug>` (editor only) swaps the active theme definition at render time

This means `colors.dark` always wins over `colors.primary` in dark mode, and any per-tenant override always wins over the theme defaults — but an absent `background` key means "use the theme," not "use white/black."

<Note>
  **Preview shows the theme, not your site.** `?preview_theme=` deliberately
  skips your `colors` and `background` overrides so you can see each theme as it
  was designed — otherwise every theme would render with the same overridden
  background and they would look identical.

  So if you have set `background`, preview and your live site will differ. That
  is expected: preview answers "what does this theme look like," your live site
  answers "what does my site look like." Remove the override (or use **Reset to
  theme** in the dashboard) if you want your site to follow whichever theme you
  pick.
</Note>

## Editing from the dashboard

**Configurations → Site** surfaces every field above. When you pick a theme, the accent and background fields preview that theme's own colors; they're only written to `nookdocs.config.json` if you edit them, and each field has a **Reset to theme** action to drop the override and fall back to the theme default. A field showing **Theme default** is following the theme and will keep following it through future theme switches — so you can try several themes and see each one's real palette, then pin only the colors you actually want to differ. The dashboard writes back to `nookdocs.config.json` in your repo on save (git commit via the GitHub App), so dashboard edits and hand-edits stay in sync. Run `npm run check:sync` before committing schema additions — see [schema reference](/configuration/schema-reference) for the validator rules.

## Related

- [Schema reference](/configuration/schema-reference) — auto-generated field-by-field reference for every `nookdocs.config.json` key
- [Brand](/configuration/brand) — favicon, OG image, manifest, PWA assets beyond logos
- [Custom domain](/deploy/custom-domain) — DNS, SSL, and canonical URL setup
- [Site settings](/configuration/site-settings) — banner, SEO, redirects, footer, navbar

---

# White labeling
Source: https://docs.nookdocs.com/configuration/white-labeling

Hide "Powered by NookDocs" attribution from your docs. Team tier toggle.

NookDocs ships every docs site with a small **"Powered by NookDocs"** attribution in the page footer, aligned to the right. The default is the same on every plan: **on**. Team and Enterprise tiers can flip it off via a toggle in **Settings → Branding**.

## How it works

White labeling is **opt-in** — upgrading to Team alone does **not** silently hide the attribution. You explicitly turn it off when you want to. This way your docs site never changes appearance unexpectedly when you change plans.

| Action | Effect |
|---|---|
| Upgrade to Team | Toggle unlocks (was greyed out on Free/Pro) |
| Toggle off in Settings → Branding | "Powered by NookDocs" disappears from the page footer |
| Toggle back on | Attribution reappears on the next request |
| Downgrade to Free/Pro while toggle is off | Toggle becomes read-only; the attribution comes back automatically because the plan no longer grants the entitlement |

## The config field

Settings → Branding writes a single field into `nookdocs.config.json`:

```json
{
  "branding": {
    "poweredBy": false
  }
}
```

- Field omitted (or `true`) → attribution shown (default)
- Field `false` + Team+ plan → attribution hidden

You can also set this directly in the file if you prefer git-driven config — same plan gate applies on commit (the config save endpoint returns 402 if a Free/Pro tenant tries to set it to `false`).

## Where to manage

Project → **Settings → Branding** → toggle "Show 'Powered by NookDocs' in the footer".

- **Free / Pro:** toggle disabled with a Team plan badge + UpgradePrompt below
- **Team / Enterprise:** toggle enabled, save commits to `nookdocs.config.json` via the existing config-commit flow

## Plan availability

| Plan | Default state | Can toggle off? |
|---|:-:|:-:|
| Free | shown | No |
| Pro | shown | No |
| Team | shown | ✅ |
| Enterprise | shown | ✅ |

## What still renders

Your `footer.social` links, legal links and copyright line are unaffected by `branding.poweredBy`. Only the literal "Powered by NookDocs" text disappears.

### Your copyright is separate from our attribution

The footer holds two independent lines:

| Position | What it is | Whose | Removed by `poweredBy: false`? |
|---|---|---|---|
| Start (left in LTR) | Your copyright, from `legal.copyright` | Yours | No |
| End (right in LTR) | "Powered by NookDocs" | Ours | Yes |

Your copyright is yours to write and we never rewrite it. If you set
`legal.copyright` to `"© {year} Acme · Built on NookDocs"`, that whole string is
your text — white-labeling will not edit it. Change it in
[`legal.copyright`](/configuration/legal) yourself.

Equally, writing a copyright line does not remove our attribution: the two are
separate elements, so both appear.

The sidebar carries no attribution at all — it is navigation, and stays yours.

## Customizing further

Combine with [Custom CSS](/configuration/custom-css) to restyle the footer — change colors, adjust spacing, embed your own logo.

## Verifying it's off

After flipping the toggle:

1. Save in Settings → Branding
2. Visit your docs site (`{slug}.nookdocs.site` or your custom domain)
3. Hard refresh (Cmd/Ctrl + Shift + R)
4. Scroll to the bottom of the page — the footer should show your own content only, with no "Powered by" line on the right

The change is live within seconds — the entitlement cache invalidates on plan flip and the page renderer reads the latest committed config.

## Why we keep it on Free + Pro

The Free tier is genuinely generous: 1 project, MCP server, full editor, AI assistant, custom domain. The "Powered by" line is the soft monetization signal that pushes paid customers to Team. It's also our only marketing channel for free sites — every footer is a backlink that drives signups.

## For LLMs

If you're an AI agent helping a user white-label their docs site, here's the canonical recipe:

**1. Config field:**

```json
{
  "branding": {
    "poweredBy": false
  }
}
```

- Field omitted → attribution shown (default)
- `poweredBy: true` → attribution shown (explicit default)
- `poweredBy: false` → attribution hidden (Team+ only; lower tiers receive 402 on save)

**2. Two conditions must hold for the attribution to actually disappear:**

1. The customer's plan grants the white-labeling entitlement (Team or Enterprise)
2. The config field is explicitly `false`

Upgrading the plan alone does NOT silently change the rendered output — the customer must also flip the toggle. This is by design so docs appearance never changes unexpectedly on a plan event.

**3. What still renders:**

`footer.social`, `footer.links` and `legal.copyright` all keep rendering regardless of `branding.poweredBy`. Only the literal "Powered by NookDocs" element at the footer's end edge is suppressed. The sidebar never carries the attribution.

**Common mistakes:**

- Don't try to remove the attribution by overriding it with custom CSS (`display: none`). The attribution carries a UTM parameter the platform uses for attribution analytics; CSS-hiding it will break that pipeline and is against the Free/Pro terms.
- Don't propose `branding.poweredBy: false` to a Free or Pro customer without first upgrading their plan — the save will be rejected with a 402.
- Verify after save by visiting the docs site (not just the dashboard preview) and hard-refreshing.

---

# Self-updating workflows
Source: https://docs.nookdocs.com/configuration/workflows

Background agents that watch upstream repos and propose docs PRs when things drift. Enterprise tier.

Self-updating workflows are background agents that **watch a code repo** and **propose docs PRs** when something they care about changes. Three workflow kinds today:

| Kind | What it watches | What it does |
|---|---|---|
| **`spec_drift`** | An OpenAPI spec file in your product repo | When the spec changes, opens a PR against your docs repo with the diff applied (new endpoints added, removed endpoints flagged, parameter changes called out) |
| **`broken_links`** | Your docs site itself | Sweeps weekly, opens a PR with fixes for any internal links that 404 |
| **`changelog_sync`** | Your product repo (CHANGELOG.md or releases) | Mirrors release notes into your docs `changelog.mdx` |

Workflows are **opt-in per project**. Each project can have many.

## Where to manage

Project → **Settings → Workflows**.

Click **Add workflow**, pick a kind, point it at the upstream source (repo + path + branch), choose whether to open a PR or just stamp a notification, and save. The PR-branch prefix defaults to `nookdocs/auto-` so you can route them to the right reviewers.

## Plan availability

| Plan | Workflows |
|---|:-:|
| Free | — |
| Pro | — |
| Team | — |
| Enterprise | ✅ |

## Status

Workflows are **configured today** — the panel saves your config and the plan gate enforces correctly. The **background runner** that watches the upstream repo and opens the PR ships in the Enterprise security release. Saved configs activate automatically; no re-entry needed.

If you have a hard requirement before then, contact us — early-access path is available for Enterprise customers.

## For LLMs

If you're an AI agent helping a user configure a workflow, here's the canonical recipe:

**1. Pick the right kind:**

- `spec_drift` — only useful when the customer publishes an OpenAPI spec from a product repo separate from the docs repo
- `broken_links` — universally applicable; recommend this first for any docs site with >50 pages
- `changelog_sync` — useful when the customer ships through GitHub Releases and wants release notes mirrored without manual copy-paste

**2. Required fields per kind:**

| Kind | watch_repo | watch_path | watch_branch |
|---|:-:|:-:|:-:|
| spec_drift | required (`owner/name`) | required (path to openapi.yaml) | required (default `main`) |
| broken_links | not used | not used | not used |
| changelog_sync | required | optional (CHANGELOG.md by default) | required |

**3. PR semantics:**

- `open_pr: true` — workflow creates a branch named `<pr_branch_prefix><timestamp>` and opens a PR. Reviewer merges = update lands.
- `open_pr: false` — workflow only fires the audit event + telemetry; no commit is made.

**Common mistakes:**

- Don't enable on Day 1 without a reviewer assigned — `spec_drift` can produce noisy diffs early on. Pause until reviewers are ready.
- Don't watch the SAME repo as the docs project; that creates a feedback loop (docs PR triggers workflow triggers docs PR).
- Workflows are tenant-scoped: one workflow per project, not shared across projects in the same org.

---

# Changelogs
Source: https://docs.nookdocs.com/content/changelogs

Publish product updates with date-based entries, tag badges, an auto-generated RSS feed, and a one-click subscribe button. One MDX page + one frontmatter flag, no new infra.

A changelog page is a regular docs page with a series of `<Update>` components, one per release. NookDocs renders each as a timelined entry (date + coloured label + version + tags + content), exposes the whole page as an RSS 2.0 feed at `<page-url>/rss.xml`, and — when `rss: true` is set in frontmatter — shows a **RSS** button in the page header so readers can subscribe with one click.

## Quick start

Create `docs/changelog.mdx`:

````mdx
---
title: Changelog
description: Product updates and release notes.
rss: true
---

<Update date="2026-04-19" label="Feature" version="1.2.0" tags={["API","AI"]}>
  ## New
  - Schema-reference page auto-generated from `public/schema.json`
  - RSS feeds for any page containing `<Update>` components

  ## Fixes
  - Navigation crash when nested groups were placed inside `pages` array
</Update>

<Update date="2026-04-15" label="Fix" version="1.1.3" tags={["API"]}>
  Fixed rate-limit header parsing on custom-domain tenants.
</Update>
````

Add to your nav in `nookdocs.config.json`:

```json
{
  "navigation": [
    {
      "tab": "Changelog",
      "groups": [
        { "group": "Releases", "pages": ["docs/changelog"] }
      ]
    }
  ]
}
```

Deploy. The page renders as a timeline. The RSS button appears in the header. `https://docs.yoursite.com/changelog/rss.xml` serves a valid RSS 2.0 feed.

## The `<Update>` component

Each entry is one `<Update>` block. Props:

<ParamField path="date" type="string (ISO 8601)">
  Entry date. Used for sorting, feed `pubDate`, and the human-readable date above the entry.
</ParamField>

<ParamField path="label" type="string">
  Short category label rendered as a coloured badge. Known values get smart colours: `Feature` → green, `Fix` → blue, `Breaking` → red, `Improvement` → primary, `Security` → amber. Any other value falls through to a neutral badge.
</ParamField>

<ParamField path="version" type="string">
  Optional version number (e.g. `1.2.0`). Rendered next to the label.
</ParamField>

<ParamField path="description" type="string">
  One-line summary. Used as the RSS item description when the Update has no `rss` override.
</ParamField>

<ParamField path="tags" type="string[]">
  Array of tag strings, each rendered as a neutral badge.
</ParamField>

<ParamField path="rss" type="string">
  Optional plain-text override for the RSS feed description. Use when the Update body contains components / code / HTML that don't serialise cleanly to RSS. When omitted the feed strips fenced code + JSX and truncates the body to 600 chars.
</ParamField>

### Example with every prop

```mdx
<Update
  date="2026-04-19"
  label="Feature"
  version="1.2.0"
  description="RSS feeds + tag filter UI + rss frontmatter button"
  tags={["API","AI","DX"]}
  rss="Shipped RSS feed generation for every page with Update components."
>
  ### What's new
  - `/<any-page>/rss.xml` returns a valid RSS 2.0 feed
  - `rss: true` in frontmatter shows a subscribe button in the page header
  - Optional `rss="..."` prop on each Update overrides the feed description

  ### Gotcha
  Tag filter UI is cosmetic only today — tags render as badges but don't gate display. Filtering lands in a follow-up.
</Update>
```

## RSS feed

### Endpoint

Every docs page has an RSS variant at `<page-url>/rss.xml`:

```text
https://docs.acme.com/changelog/rss.xml
https://docs.acme.com/api-updates/rss.xml
https://docs.acme.com/whatever/rss.xml
```

Pages without `<Update>` components produce an empty-channel feed — not a 404 — so subscribers don't panic when a page gets cleared temporarily.

### Format

Standards-compliant RSS 2.0. Each `<item>` has:

- `<title>` — the Update's `label`
- `<link>` — absolute URL to the entry anchor (`<page>#<slug>`)
- `<guid>` — same as `link`, `isPermaLink="true"`
- `<pubDate>` — from `date` prop (RFC 822 / UTC), or a descending synthesised sequence when `date` is missing
- `<description>` — plaintext from `rss` prop → `description` prop → body (stripped of JSX + code fences, 600-char cap)

### Subscribing

Any RSS reader works: [Feedly](https://feedly.com), [NetNewsWire](https://netnewswire.com), [Inoreader](https://inoreader.com). For team-level notifications:

- **Slack** — `/feed subscribe https://docs.acme.com/changelog/rss.xml` in any channel
- **Discord** — bots like [Readybot](https://readybot.io) or [RSS.app](https://rss.app/en/bots/rssfeeds-discord-bot)
- **Email** — Zapier's RSS-to-Email integration

### The `rss: true` button

Adding `rss: true` to page frontmatter renders an **RSS** button in the page header next to **Copy page**:

```mdx
---
title: Changelog
rss: true
---
```

Click subscribes the reader's default RSS handler to the feed. Without `rss: true`, the feed still exists — readers just have to know the URL.

## When to use `tags`

Tags render as neutral badges alongside the coloured label. They're searchable by readers (Cmd+F) but don't drive any filtering UI today — that's a cosmetic-only ship.

Useful tag categories:

- **Surface** — `API`, `Dashboard`, `CLI`, `Docs`
- **Audience** — `Pro`, `Enterprise`, `Public beta`
- **Domain** — `Auth`, `Billing`, `Search`, `Analytics`

## Labels we colour

| Label | Badge colour | When to use |
|---|---|---|
| `Feature` | success (green) | New functionality |
| `Fix` | info (blue) | Bug fix |
| `Improvement` | primary | Enhancement to existing behaviour |
| `Breaking` | danger (red) | API break, forced migration |
| `Security` | warning (amber) | Security patch, CVE |

Any other label string renders as a neutral badge — use custom labels when the standard five don't fit.

## Nav placement

Changelogs sit best as their own top-level **tab** in the `docs.json` nav — readers click "Changelog" at the top of the docs and land on a single chronological page. Example:

```json
{
  "navigation": [
    {
      "tab": "Documentation",
      "groups": [ ... your main docs ... ]
    },
    {
      "tab": "Changelog",
      "groups": [
        { "group": "Releases", "pages": ["docs/changelog"] }
      ]
    }
  ]
}
```

Alternatively fold it into an existing group (e.g. "Resources" or "About") — the feature doesn't require tab placement.

## Limitations

- **No tag filter UI.** Tags render as badges today; a filter component that toggles entries by tag lands in a follow-up. Cosmetic pages look fine without it.
- **No auto-TOC from `<Update label>`.** The right-column TOC lists `h2` / `h3` headings, not Update labels. Write `## Your date` headings inside each Update body to get TOC entries.
- **No `rssEntries` prop.** The feed includes every `<Update>` on the page — no way to exclude one. Delete unwanted entries from the page.
- **No per-entry `authorName` / `authorEmail`.** Feed items use the channel-level metadata only.

## Related

- [`<Update>` component](/components/update) — rendering reference + examples
- [Schema reference](/configuration/schema-reference) — `nookdocs.config.json` full field listing
- [Markdown export](/optimize/markdown-export) — `/page.md` companion for LLM crawlers
- [SEO](/optimize/seo) — sitemap / robots / canonical URLs

---

# Frontmatter
Source: https://docs.nookdocs.com/content/frontmatter

Every field the platform reads from the YAML block at the top of your MDX files.

Every MDX page carries a YAML frontmatter block between two `---` markers at the top. The platform reads these fields for the page title, navigation, SEO, and a handful of per-page overrides.

```mdx
---
title: Authentication
description: How to authenticate API requests.
icon: lock
tag: NEW
---

Page body starts here.
```

## Core fields

<ParamField name="title" type="string">
  Page title. Used as the `<h1>` (unless the MDX body starts with its own `#` heading), the `<title>` meta tag, and the sidebar label when the page appears in navigation. Required in practice — pages without a title fall back to the filename.
</ParamField>

<Note>
  Above the title the page shows the section it belongs to — `Getting Started`
  over `Introduction`, say. It comes from the group the page sits in under
  [navigation](/configuration/navigation), not from frontmatter, so there is
  nothing to set: move a page to another group and the label follows. Pages
  that aren't listed in navigation show no section label rather than a guess.
</Note>

<ParamField name="sidebarTitle" type="string">
  Short label for the sidebar, used instead of `title` there. The page keeps its full heading; only the navigation gets the shorter form.

  Worth setting when a title runs past the rail's width — roughly 23 characters at the default 288px, and fewer on a monospace theme like Terminal. A label that doesn't fit is truncated with an ellipsis and its full text stays available on hover, but a short label reads better than either.

  ```yaml
  title: Data Processing Agreement (DPA)
  sidebarTitle: DPA
  ```
</ParamField>

<ParamField name="description" type="string">
  One-line description. Rendered under the title in the rendered page, used as the meta description, shown in search results, and passed to AI retrieval as part of the snippet context.
</ParamField>

<ParamField name="icon" type="string">
  Icon name (Lucide default, or Tabler/FontAwesome depending on `config.icons.library`). Shown in the sidebar next to the page label and — when the page is a `root` of a group with `directory` — inside the generated directory cards.
</ParamField>

<ParamField name="tag" type="string">
  Badge text shown next to the page label in the sidebar (e.g. `NEW`, `BETA`, `DEPRECATED`). Truncates at 8 characters.
</ParamField>

<ParamField name="hidden" type="boolean" default="false">
  When `true`, the page is hidden from the sidebar but still accessible by URL. Handy for drafts you want to share via link without advertising.
</ParamField>

## SEO overrides

<ParamField name="ogImage" type="string">
  Open Graph image URL for this page specifically. Overrides `config.seo.ogImage`. 1200×630 PNG recommended for social preview fidelity.
</ParamField>

<ParamField name="noindex" type="boolean">
  When `true`, emits `<meta name="robots" content="noindex, nofollow">`. Use for private sections, draft pages, or any URL you want out of search engines without removing the content.
</ParamField>

## Timestamp override

<ParamField name="timestamp" type="string (ISO 8601)">
  Override the "Last updated" date shown at the bottom of the page.

  Precedence (highest first):
  1. `config.advanced.showTimestamp: false` → renders nothing, regardless of frontmatter.
  2. Frontmatter `timestamp` (this field).
  3. DB `updated_at` — the git commit mtime from the sync pipeline.

  Useful when the git mtime is noisy (bot commits, bulk renames, formatter churn) and you want to pin a meaningful date. Accepts any ISO 8601 form:

  ```mdx
  ---
  title: Authentication
  timestamp: "2026-04-18"
  ---
  ```

  Or with time:

  ```mdx
  ---
  timestamp: "2026-04-18T12:00:00Z"
  ---
  ```
</ParamField>

## API reference pages

Used by pages that auto-generate from an OpenAPI spec:

<ParamField name="openapi" type="string">
  Points at a specific operation in the spec. Format: `"<METHOD> <path>"` — e.g. `"GET /users/{id}"`. The platform generates the ParamField + ResponseField tables, RequestExample + ResponseExample code samples, and endpoint metadata automatically.
</ParamField>

<ParamField name="mode" type="'default' | 'wide' | 'custom'">
  Layout mode. `default` renders the standard 3-column docs layout. `wide` removes the right-side TOC column (useful for landing pages). `custom` strips both columns and the prose style, giving you a blank canvas — for hero / changelog / custom layouts.
</ParamField>

## Authoring tips

- **Put the most-visited fields at the top.** `title` then `description` then `icon` — makes diffs readable when you bulk-edit pages.
- **Quote strings with colons or special chars.** YAML parses `title: GET /users` as an object; wrap in quotes: `title: "GET /users"`.
- **Prefer `icon` over inline `<Icon>` components in h1.** Frontmatter icon renders consistently in every surface (sidebar, directory cards, AI context); an inline `<Icon>` only renders in the page body.

## Things the platform ignores

Frontmatter is a free-form YAML dict — put whatever you want in it. Fields the platform doesn't read are passed through unchanged (the sync pipeline writes them to `pages.frontmatter` JSONB) and available for future features or custom MDX templates.

Common custom fields teams add:
- `author: "Jane Doe"` — rendered via a custom `<Byline>` component
- `reviewedOn: "2026-01-15"` — shown alongside the timestamp for policy / compliance pages
- `estimatedReadingTime: "5 min"` — shown in the hero

None of these are required — they're YOUR fields for YOUR templates.

---

# Localization (i18n)
Source: https://docs.nookdocs.com/content/localization

Serve docs in multiple languages — folder layout, locale switcher, RTL, and translation workflow.

NookDocs treats languages the same way it treats versions: a top-level switcher in the navbar, URL-prefix routing (`/fr/...`, `/ar/...`), and side-by-side folders in the repo. Your default locale has no prefix; other locales live under folders named after their ISO code.

## Declare languages

In Configurations → Languages (or direct `nookdocs.config.json`):

```json
{
  "languages": [
    { "language": "en", "default": true, "label": "English" },
    { "language": "fr", "label": "Français" },
    { "language": "es", "label": "Español" },
    { "language": "de", "label": "Deutsch" },
    { "language": "ja", "label": "日本語" },
    { "language": "ar", "label": "العربية" },
    { "language": "zh-CN", "label": "简体中文" }
  ]
}
```

<ParamField name="language" type="string" required>
  ISO 639-1 code (en, es, de, fr, ja, ar, zh…) or BCP 47 tag (zh-CN, pt-BR, en-GB). Used as both the discriminator and the default URL slug.
</ParamField>

<ParamField name="label" type="string">
  Display name in the switcher. Write native names (`Français`, `日本語`, `العربية`) rather than English translations.
</ParamField>

<ParamField name="default" type="boolean">
  Exactly one language must be the default. Its URLs serve at `/` (no prefix). Others route to `/<language>/...`.
</ParamField>

<ParamField name="dir" type="'ltr' | 'rtl'">
  Explicit text direction. Auto-inferred from the code — `ar`, `he`, `fa`, `ur` default to `rtl`, everything else to `ltr`. Set explicitly for edge cases.
</ParamField>

## Repo layout

```
your-repo/                        # the docs base
├── nookdocs.config.json
├── introduction.mdx              ← English (default)
├── quickstart.mdx
├── guides/
│   └── authentication.mdx
├── fr/                           ← French, URL prefix /fr
│   ├── introduction.mdx
│   ├── quickstart.mdx
│   └── guides/
│       └── authentication.mdx
└── ar/                           ← Arabic, URL prefix /ar
    ├── introduction.mdx
    └── guides/
        └── authentication.mdx
```

Each locale folder mirrors the structure of the default. You don't need every page translated — untranslated pages simply 404 in that locale, or you can link them back to the English version via a Banner at the top.

## Pages that don't need translating

Some pages are meant to be language-neutral — API reference pages generated from OpenAPI, code samples, changelogs. Keep them ONLY in the default locale and skip them from the translated trees. They'll 404 under `/fr/...` but that's expected; you can soft-redirect via the `redirects` config:

```json
{
  "redirects": [
    { "source": "/fr/api/*", "destination": "/api/*" },
    { "source": "/ar/api/*", "destination": "/api/*" }
  ]
}
```

This way `/fr/api/authentication` gracefully falls back to `/api/authentication` (always the default-locale spec) regardless of active locale.

## Frontmatter stays the same

The MDX frontmatter schema is identical across locales. Only the content body changes:

```mdx docs/guides/authentication.mdx (English)
---
title: Authentication
description: How to authenticate API requests.
icon: lock
---

Every API request needs a Bearer token...
```

```mdx docs/fr/guides/authentication.mdx (French)
---
title: Authentification
description: Comment authentifier les requêtes API.
icon: lock
---

Chaque requête API nécessite un jeton Bearer...
```

The `icon`, `tag`, `hidden`, and other meta fields stay in English (they're internal keys). Only user-visible copy gets translated.

## RTL support

Languages flagged as `dir: "rtl"` (either explicitly or via auto-inference from `ar`, `he`, `fa`, `ur`) render with:

- `dir="rtl"` on the root HTML element.
- Sidebar on the **right**, content on the **left**.
- `ps-4` / `pe-4` / `start-0` / `end-0` CSS logical properties resolve correctly (our components use logical properties throughout — no layout breakage).
- Code blocks and tables stay LTR (technically correct for code / data).

Test your RTL layout by visiting the locale's URL in the browser. Take a screenshot; nothing should visually misalign.

## Translation workflow

We don't ship a built-in translation manager. The recommended workflow for small teams:

<Steps>
  <Step title="Translate in-repo with PRs">
    Open a branch per locale (`l10n/tr`, `l10n/ar`). Translator works against it; you review + merge. Simple, version-controlled, free.
  </Step>
  <Step title="Use Crowdin / Lokalise for larger teams">
    Both tools have GitHub integration that opens PRs from translation memory. Point them at `docs/<locale>/**/*.mdx` and they'll keep translations in sync with source changes.
  </Step>
  <Step title="Machine-translated fallback">
    Copy `docs/` → `docs/fr/` and run each file through a translation API as a draft. Mark pages with a Banner ("Machine-translated — help us improve") and invite community edits.
  </Step>
</Steps>

## Per-language chrome

Config supports per-language navbar / footer / banner overrides (planned but not yet wired up):

```json
{
  "languages": [
    {
      "language": "fr",
      "label": "Français",
      "navbar": {
        "links": [
          { "label": "Tarifs", "href": "https://example.com/fr/tarifs" }
        ]
      },
      "footer": {
        "social": { "twitter": "https://twitter.com/example_fr" }
      }
    }
  ]
}
```

For now, the top-level navbar / footer / banner apply to every locale. Per-locale overrides ship when this item lands in the roadmap.

## Navigation per language

Same caveat as [versioning](/content/versioning#navigation-per-version) — the current renderer uses the top-level `navigation` config for every locale. Per-language nav tree scoping is queued.

Until then, the sidebar labels stay in the default language. This is surprisingly OK in practice because:
- Group / tab labels tend to be English-ish anyway ("Guides", "API Reference")
- Page titles in the sidebar come from each MDX file's frontmatter — so translated pages DO show translated titles

If mixed-language sidebars bother you, the workaround is to write every group / tab label in the default language, and let frontmatter carry translated titles.

## The AI Assistant and i18n

The chat widget already handles multilingual queries — a non-English question triggers a translation hop so retrieval still works against English-indexed content, and the final answer comes back in the user's language. See [AI Assistant](/configuration/site-settings#ai-assistant).

Retrieval is not yet scoped by active locale (v2 follow-up). A user on `/fr/...` asking a question in French may get results from the English tree; the answer still comes in French.

---

# Multi-product docs
Source: https://docs.nookdocs.com/content/multi-product

Host docs for multiple products on one site — Cloud / Enterprise / Self-hosted, each with its own nav and content.

Teams with multiple products often face a choice: run N separate docs sites (one subdomain per product, painful to maintain, no shared chrome), or cram everything into a single navigation tree (confusing for readers who care about only one product).

NookDocs gives you a third option: **one site, N product switchers**. A dropdown next to the logo lets readers pick their product; the sidebar, URL prefix, and (future) chrome overrides update accordingly.

## Declare products

In Configurations → Products (or direct `nookdocs.config.json`):

```json
{
  "products": [
    { "product": "Cloud", "default": true, "description": "Managed hosting" },
    { "product": "Enterprise", "description": "Self-hosted", "tag": "Beta", "status": "beta" }
  ]
}
```

<ParamField name="product" type="string" required>
  Product name. Used as both the switcher label and the default URL slug.
</ParamField>

<ParamField name="description" type="string">
  One-line description shown below the product name in the switcher dropdown. Helps readers pick the right one.
</ParamField>

<ParamField name="default" type="boolean">
  The product loaded when a reader lands on `/` without a product prefix. At most one default.
</ParamField>

<ParamField name="slug" type="string">
  URL prefix override. Defaults to the slugified product name (e.g. "Cloud Connect" → `cloud-connect`).
</ParamField>

## Repo layout

```
your-repo/                        # the docs base
├── nookdocs.config.json
├── introduction.mdx              ← Cloud (default), no prefix
├── quickstart.mdx
├── api/
│   └── overview.mdx
└── enterprise/                   ← Enterprise, URL prefix /enterprise
    ├── introduction.mdx
    ├── installation.mdx
    └── admin/
        └── sso.mdx
```

Readers land on `/` → see Cloud docs. They pick "Enterprise" from the switcher → URL becomes `/enterprise/` → Enterprise tree loads. Same pattern for every product.

## When to use products vs versions vs tabs

<CardGroup cols={3}>
  <Card title="Products" icon="package">
    **Different audiences.** Each product has its own concepts, onboarding, and audience. Cloud users and Enterprise users rarely read the same pages.
  </Card>
  <Card title="Versions" icon="git-branch">
    **Same product, multiple generations.** v1 / v2 / v3 readers are mostly the same people who happen to be locked onto different releases.
  </Card>
  <Card title="Tabs" icon="folder-tree">
    **Same product, different tasks.** Guides / API Reference / Changelog — everyone reads all tabs, they just organize information.
  </Card>
</CardGroup>

Combining them:

- **Products × versions**: Cloud v1 / v2 / v3 AND Enterprise v1 / v2. Nest `versions[]` inside each `product`. Per-product versions ship as part of the Phase 3+ follow-up (see [Navigation schema](/configuration/navigation)).
- **Products × languages**: Cloud in en / tr AND Enterprise in en / tr. Nest `languages[]` inside each product (planned).

## Shared vs product-specific chrome

Elements that look the same across products (logo, brand colors, theme) are defined at the top level of the config and apply everywhere. Product-specific chrome lives on the product entry:

```json
{
  "products": [
    {
      "product": "Cloud",
      "default": true,
      "navbar": {
        "links": [{ "label": "Pricing", "href": "https://example.com/cloud/pricing" }]
      },
      "colors": {
        "primary": "#3b82f6"
      }
    },
    {
      "product": "Enterprise",
      "navbar": {
        "links": [{ "label": "Contact sales", "href": "mailto:sales@example.com" }]
      },
      "colors": {
        "primary": "#8b5cf6"
      }
    }
  ]
}
```

<Note>
  Per-product navbar / colors / footer / banner are in the schema today but the renderer uses the top-level config for every product. Per-product chrome wiring ships in a follow-up sprint.
</Note>

## Shared chrome: `global`

When something must appear on every product (status page anchor, global changelog, corporate privacy link), use the top-level `global` config instead of duplicating it:

```json
{
  "global": {
    "anchors": [
      { "anchor": "Status", "icon": "activity", "href": "https://status.example.com" }
    ],
    "dropdowns": [
      {
        "dropdown": "Changelog",
        "icon": "history",
        "pages": ["docs/changelog/2026-q1"]
      }
    ]
  }
}
```

`global.anchors` + `global.dropdowns` render at the top of every sidebar, regardless of active product. The Configurations → Global nav section lets you edit anchors from the dashboard; dropdowns require direct `nookdocs.config.json` edit.

## Onboarding a reader to the right product

Link pages across products using absolute paths:

```mdx
For self-hosted docs, see [Enterprise → Installation](/enterprise/installation).
```

When a reader lands from an ad or blog post, they'll arrive on a specific product's page; the switcher shows them which one. This is usually enough context — but for marketing landing pages you may want to add a Banner that surfaces the product switcher:

```mdx
<Banner variant="info">
  Reading Cloud docs. Looking for self-hosted? [Switch to Enterprise](/enterprise/).
</Banner>
```

## Migration: single-product → multi-product

<Steps>
  <Step title="Wrap existing content into a default product">
    Your existing `docs/` stays where it is. Add a default product entry: `{ "product": "Your Product", "default": true }`. Nothing changes visually because the default product has no URL prefix.
  </Step>
  <Step title="Add the second product's folder">
    `docs/enterprise/` (or whatever slug you pick). Drop at least an `introduction.mdx` so the switcher has somewhere to route.
  </Step>
  <Step title="Add the second product entry">
    `{ "product": "Enterprise", "description": "Self-hosted" }` in `products[]`. Save config, wait for sync, the switcher appears in the navbar.
  </Step>
  <Step title="Cross-link where useful">
    Banners on product-specific pages that point readers to the other product when relevant. "This feature is Cloud-only. For Enterprise, see Self-hosted SSO."
  </Step>
</Steps>

No existing URLs break — the default product's content still serves at `/`. Non-default product URLs gain the prefix and start resolving only after you add the folder + config entry.

## Search and AI Assistant

Search (Postgres FTS) indexes every page regardless of product. A Cloud reader searching "SSO" will see both Cloud SSO and Enterprise SSO results. Per-product search scoping ships when the full routing layer lands.

The AI Assistant has the same caveat — it retrieves from the full docs tree. For clean-separation customers, disable the widget on one product and leave it on the other via `ai.assistant.enabled` per scope (planned).

---

# Personalized content
Source: https://docs.nookdocs.com/content/personalization

Show different content to different viewers. Audience split via `<Visibility for="humans | agents">` ships today; authenticated user-group personalization is on the roadmap.

Personalization means the same docs page renders differently depending on who's viewing it. NookDocs ships one real split today — browser readers vs LLM agents — plus a roadmap for authenticated user-group personalization once the auth layer lands.

<Banner variant="warning">
  **Shipping status today.** `<Visibility for="humans | agents">` works right now (audience split between browser readers and LLM crawlers). Authenticated user-group personalization (`public: false`, `authGroups: [...]`) is **roadmap** — schema support is scaffolded but runtime enforcement isn't wired.
</Banner>

## Audience split — `<Visibility>`

The real feature shipping today. Wrap any block with `

  <Note>
    If you're an LLM reading this page, the full MDX source is
    available at `/content/personalization.md`. Use that for context.
  </Note>

```

- **Browsers** render `for="humans"` blocks normally, hide `for="agents"` blocks entirely.
- **Markdown exports** (`.md` URLs, llms-full.txt, copy-for-llms) do the inverse — agent blocks included, human blocks stripped.

### When to use audience split

<CardGroup cols={2}>
  <Card title="Human-only UX cues" icon="mouse-pointer-2">
    Instructions that reference UI state — "click the button", "look at the sidebar", "watch the cursor". Agents read raw text, so these instructions confuse them.
  </Card>
  <Card title="Agent-only context" icon="bot">
    Meta-instructions for LLMs — "this page's schema reference lives at ...", "when generating code, use the `<Steps>` component not plain ordered lists". Hide from browsers; surface to agents.
  </Card>
  <Card title="Legal boilerplate" icon="scroll">
    Some compliance text only matters for humans (cookie banners, accessibility disclosures). Ship it to browsers, strip from LLM context.
  </Card>
  <Card title="Debugging directives" icon="bug">
    "If your answer doesn't compile, retry with the component spec at /llm-first/component-spec.md" — guidance agents should see, but clutter for human readers.
  </Card>
</CardGroup>

See the [Visibility component](/components/visibility) for the API reference.

## User-group personalization (roadmap)

The schema already accepts two personalization fields. They're **not** enforced at runtime yet — setting them today has no effect.

### `public: boolean` (page-level)

Whether a page is publicly accessible. Default `true`. When `false`, the page becomes visible only to authenticated users with an allowed role. Ships when the auth layer lands.

### `authGroups: string[]` (group + page level)

List of group slugs a viewer must belong to. Ships with the auth layer.

```json
{
  "navigation": [
    {
      "group": "Admin",
      "public": false,
      "authGroups": ["admin", "devrel"],
      "pages": ["docs/admin/rotate-keys"]
    }
  ]
}
```

When the auth layer ships, only viewers whose JWT / session carries a matching group slug see this nav group.

### What the roadmap covers

<Steps>
  <Step title="Viewer identification">
    Tenants configure an upstream auth provider (Clerk / Auth0 / custom JWT). The docs shell reads the session cookie and extracts the viewer's group memberships.
  </Step>
  <Step title="Nav-level gating">
    Groups / tabs / pages with `public: false` disappear from the sidebar for viewers lacking the right `authGroups` entry. Direct navigation returns 404.
  </Step>
  <Step title="Page-level gating">
    Individual pages with frontmatter `public: false` + `authGroups: [...]` check viewer context at render. Same 404-on-miss behaviour.
  </Step>
  <Step title="Per-block gating (long-term)">
    `<Visibility for="group:enterprise">` inside an MDX page to show/hide sections by tier. Long-term — the nav/page-level gating lands first.
  </Step>
</Steps>

Track progress at [github.com/Codivion/NookDocs/issues](https://github.com/Codivion/NookDocs/issues?q=personalization).

## Related patterns that already ship

### `hidden: true` — remove from sidebar + search + SEO

Hide a page from discovery (sidebar, search, sitemap, llms.txt) while keeping the URL accessible. Public to anyone who has the URL; invisible to anyone who doesn't.

```mdx
---
title: Internal API
hidden: true
---
```

Useful for gated flows ("only people who get this URL from our CS team see this page") or deprecated-but-still-reachable pages. Not personalization — no viewer check — but covers some of the same use cases.

See hidden pages when that lands, or the `hidden` field in the [schema reference](/configuration/schema-reference).

### `seo.indexing: "noindex"` — hide entire site from search

Site-wide version of the same idea. `noindex` emits `robots: noindex, nofollow` on every page. Staging sites, private docs, early-access beta docs.

See [SEO](/optimize/seo).

### `Visibility` for audience, not viewer

The name suggests "show/hide" which is what personalization does too, but `<Visibility>` splits by AUDIENCE (browser vs LLM) not VIEWER (user group). Don't confuse the two.

## Limitations

- **No viewer-aware gating today.** `public` / `authGroups` fields are accepted by the schema but not enforced. Adding them to config has no effect until the auth layer lands.
- **No cookie / geo / AB conditionals.** Content doesn't branch by IP, user-agent, or session state.
- **`<Visibility>` is boolean, not multi-audience.** `for="humans"` or `for="agents"` — no `for="enterprise+pro"` tiers yet.

## Related

- [Visibility component](/components/visibility) — audience-split API reference
- [Markdown export](/optimize/markdown-export) — how agent blocks flow to LLMs
- [Schema reference](/configuration/schema-reference) — `authGroups` and `public` field listings
- [Reusable snippets](/content/reusable-snippets) — a different kind of content reuse (dedupe vs gate)

---

# Redirects
Source: https://docs.nookdocs.com/content/redirects

Map old URLs to new ones with wildcards, permanent or temporary HTTP status codes, and tail preservation — all config-driven, zero code.

Redirects keep inbound links alive after you rename a page, reshuffle navigation, or migrate from another platform. NookDocs applies them at the docs-page layer before any lookup — if an incoming URL matches a redirect entry, the reader gets a 307 / 308 response pointing to the new URL.

All config-driven via `nookdocs.config.json#redirects`. No filesystem, no middleware, no rebuild.

## Quick start

```json
{
  "redirects": [
    { "source": "/old/guides", "destination": "/guides", "permanent": true }
  ]
}
```

Deploy. Every hit to `/old/guides` → `308 Permanent Redirect` → `/guides`.

## How matching works

<Steps>
  <Step title="Exact match first">
    The incoming path is compared against each entry's `source` verbatim. First match wins.
  </Step>
  <Step title="Wildcard prefix match">
    When `source` ends with `/*`, the entry matches any path starting with the prefix. Example: `/old/*` matches `/old/foo`, `/old/a/b/c`, `/old`.
  </Step>
  <Step title="Tail preservation">
    When BOTH `source` and `destination` end with `/*`, the matched tail is preserved in the destination. `/blog/*` → `/articles/*` applied to `/blog/2024/hello` produces `/articles/2024/hello`.
  </Step>
  <Step title="HTTP status">
    `permanent: true` returns **308 Moved Permanently**. `permanent: false` (default) returns **307 Temporary Redirect**. Use 308 for permanent moves so search engines transfer ranking signals.
  </Step>
</Steps>

## Config reference

<ParamField path="redirects[].source" type="string" required>
  URL path to match. Must start with `/`. Trailing `/*` enables prefix matching.
</ParamField>

<ParamField path="redirects[].destination" type="string" required>
  Where to send the visitor. Can be a path on your docs (`/new/path`) or an absolute URL (`https://old.example.com/page`). When both source and destination end with `/*`, the matched tail appends.
</ParamField>

<ParamField path="redirects[].permanent" type="boolean" default="false">
  HTTP status: `true` → 308 (permanent, SEO signals transfer), `false` → 307 (temporary, no signal transfer). Default `false` for safety — bump to `true` once you're confident the old URL shouldn't come back.
</ParamField>

## Common patterns

### Single page rename

```json
{
  "redirects": [
    {
      "source": "/old-slug",
      "destination": "/new-slug",
      "permanent": true
    }
  ]
}
```

### Folder flatten / deepen

```json
{
  "redirects": [
    { "source": "/guides/advanced", "destination": "/advanced-guides" },
    { "source": "/v1/api", "destination": "/api-reference" }
  ]
}
```

### Wildcard sub-tree move

```json
{
  "redirects": [
    {
      "source": "/blog/*",
      "destination": "/articles/*",
      "permanent": true
    }
  ]
}
```

`/blog/hello` → `/articles/hello`, `/blog/a/b` → `/articles/a/b`, `/blog` → `/articles`.

### Wildcard to single destination

Omit `/*` on the destination to redirect an entire prefix to one page:

```json
{
  "redirects": [
    {
      "source": "/old/*",
      "destination": "/migration-notice",
      "permanent": false
    }
  ]
}
```

`/old/anything/here` → `/migration-notice`.

### Redirect to an external URL

```json
{
  "redirects": [
    {
      "source": "/support",
      "destination": "https://help.acme.com",
      "permanent": false
    }
  ]
}
```

### Platform migration bulk entries

When migrating from Mintlify / Docusaurus / GitBook, the old platform's URL structure is usually different. Add an entry per old path so inbound search-engine hits don't 404:

```json
{
  "redirects": [
    { "source": "/essentials/markdown", "destination": "/content/format-text", "permanent": true },
    { "source": "/essentials/code", "destination": "/content/format-code", "permanent": true },
    { "source": "/essentials/images", "destination": "/content/images-embeds", "permanent": true },
    { "source": "/quickstart/*", "destination": "/quickstart", "permanent": true }
  ]
}
```

The [migrate-from-mintlify](/cli/migrate-from-mintlify) CLI generates these automatically for you.

## Edit from the dashboard

**Configurations → SEO → Redirects** exposes a form-backed editor — no JSON hand-editing required. Each row has source / destination / permanent toggle. The panel writes back to `nookdocs.config.json` via a git commit on save, so dashboard edits and hand-edits stay in sync.

## Order matters

Redirects are evaluated top-to-bottom. The first match wins. Order specific rules before generic ones:

```json
{
  "redirects": [
    { "source": "/old/premium", "destination": "/pricing" },
    { "source": "/old/*", "destination": "/archive" }
  ]
}
```

If you flipped the order, `/old/premium` would match `/old/*` first and land on `/archive` — not what you want.

## Limitations

- **No regex matching.** Only exact and trailing-wildcard (`/*`) patterns. For complex rewriting logic you need a reverse proxy in front of your domain.
- **No status-code override.** 307 / 308 only. No 301, 302, 303, 410 options.
- **No request header / cookie conditions.** Redirects are path-only. Conditional redirects (e.g. by geo or auth state) need middleware.
- **No query-string matching.** `?foo=bar` doesn't participate in matching, but query strings pass through: hitting `/old?x=1` with a redirect to `/new` sends you to `/new?x=1` (query preserved).

## Related

- [Schema reference — redirects](/configuration/schema-reference#redirects) — auto-generated field listing
- [Site settings](/configuration/site-settings) — banner, SEO, footer, navbar configuration
- [Migrating from Mintlify](/cli/migrate-from-mintlify) — auto-generated redirect entries during CLI migration
- [Custom domain](/deploy/custom-domain) — canonical URL + multi-domain handling

---

# Reusable snippets
Source: https://docs.nookdocs.com/content/reusable-snippets

Share boilerplate across pages. Inline-children authoring works today; repo-wide `/snippets/*.mdx` resolution with template variables ships in Phase 4.

Reusable snippets let you author a piece of content once and include it in many pages — API auth intros, common warnings, shared error tables, consistent callouts. Without this, you copy-paste and drift the moment you update one and forget the others.

<Banner variant="warning">
  **Shipping status today.** Inline-children authoring via `<Snippet>` works right now. Repo-wide `/snippets/*.mdx` file resolution + template variables (`vars` prop) are **Phase 4 roadmap** — see [Phase 4 status](#phase-4-roadmap) below.
</Banner>

## What works today

Write `<Snippet>` call sites in your MDX. Pass the content as children. The component renders whatever you pass, unchanged.

````mdx
<Snippet>
  Add your API key to the `Authorization` header:

  ```bash
  curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/v1/users
  ```
</Snippet>
````

Renders exactly like the children would if they were inline — no reuse benefit, but the call sites are **forward-compatible**. When Phase 4 ships, you swap inline children for `<Snippet file="...">` without rewriting anything.

## The target API (Phase 4)

### File-based snippets

Author once at `_snippets/<name>.mdx`, include anywhere:

```mdx
<Snippet file="_snippets/authentication.mdx" />
```

````mdx
<!-- docs/_snippets/authentication.mdx -->
Add your API key to the `Authorization` header:

```bash
curl -H "Authorization: Bearer YOUR_KEY" https://api.example.com/v1/users
```
````

At sync time the pipeline walks `_snippets/` (under `contentRoot`), stores each file's body, and inlines it wherever `file="..."` resolves to an existing snippet.

### Template variables

Parameterise snippets per call site:

```mdx
<Snippet
  file="_snippets/install.mdx"
  vars={{ tool: "docker", version: "4.2" }}
/>
```

````mdx
<!-- docs/_snippets/install.mdx -->
Install {{tool}} version {{version}}:

```bash
{{tool}} install --version {{version}}
```
````

`{{variable}}` placeholders resolve at render time with values from the `vars` prop. Missing values render as an empty string with a warning in the build log.

## When to use snippets (once available)

<CardGroup cols={2}>
  <Card title="Auth intros" icon="key">
    Every API reference page opens with the same auth paragraph. Write it once; include in all.
  </Card>
  <Card title="Compliance warnings" icon="shield-alert">
    GDPR / HIPAA / SOC 2 notices that must appear on specific page types. Snippet = one update site.
  </Card>
  <Card title="Install / setup blocks" icon="download">
    Same package-manager tabs across quickstart, concepts, recipes. Parameterise with `vars` to swap package names.
  </Card>
  <Card title="Shared tables" icon="table">
    Error code tables, rate-limit tables, feature-tier matrices. Centralise so the source of truth lives in one file.
  </Card>
</CardGroup>

## Phase 4 roadmap

Full file-based resolution ships alongside the OpenAPI parser and assistant upgrades in Phase 4. The pipeline work is:

<Steps>
  <Step title="Sync extracts snippets">
    Walk `<contentRoot>/_snippets/` during webhook sync. Store each file's body + hash in a new `snippets` Postgres table keyed by `(project_id, path)`.
  </Step>
  <Step title="Renderer resolves at render time">
    When MDX renderer encounters `<Snippet file="...">`, it looks up the row and inlines the body. Missing file → render with a warning banner instead of crashing.
  </Step>
  <Step title="Template variable substitution">
    Parse `{{name}}` placeholders in snippet body, substitute from `vars` prop. Missing variable → empty string + build warning.
  </Step>
  <Step title="Dashboard snippet manager">
    Editor gets a side-panel view of every snippet + usage count (how many pages include it), so writers can audit before deleting.
  </Step>
</Steps>

Track the actual ship at [github.com/Codivion/NookDocs/issues](https://github.com/Codivion/NookDocs/issues?q=snippet) or follow the changelog.

## Escape hatches until Phase 4

- **Inline children** — shown above. No reuse, but forward-compatible call sites.
- **Hand-copy + grep** — author your snippet content once in a local `.md` note, grep its usages across `docs/` when it changes. Crude but keeps drift bounded.
- **Import at edit time** — the dashboard editor lets you search across all pages; copy-paste during editing keeps a mental cross-reference.

## Related

- [Snippet component](/components/snippet) — the component reference (stub behaviour)
- [Format text](/guides/content-types) — raw Markdown in pages
- [Format code](/features/code-blocks) — code-block-specific reuse patterns
- [Visibility](/components/visibility) — audience-split authoring (different reuse story — splits content by viewer type)

---

# Static assets
Source: https://docs.nookdocs.com/content/static-assets

Host images, videos, fonts, and downloads in your repo's public/ folder — or reference any external URL. Both work everywhere an asset path is accepted.

Two ways to use a file in your docs. Pick per asset — they mix freely on the same page:

<CardGroup cols={2}>
  <Card title="Repo public/ folder" icon="folder-open">
    Commit the file next to your docs. Versioned with your content, no third-party dependency, served from your docs domain.
  </Card>
  <Card title="External URL" icon="link">
    Reference any `https://` URL — your CDN, S3 bucket, or an existing asset host. Nothing to commit.
  </Card>
</CardGroup>

## Repo `public/` folder

Put files in a `public/` folder next to your content root and reference them with a root-relative path:

```text
your-repo/
├── docs/              ← your MDX content
├── public/            ← static assets live here
│   ├── logo/
│   │   ├── light.svg
│   │   └── dark.svg
│   └── images/
│       ├── setup-flow.mp4
│       └── dashboard.png
└── nookdocs.config.json
```

```mdx Referencing assets
<Image src="/images/dashboard.png" alt="Dashboard overview" />
<Video src="/images/setup-flow.mp4" poster="/images/setup-flow-poster.png" loop />
[Download the SDK reference](/files/sdk-reference.pdf)
```

Your logo and favicon in `nookdocs.config.json` resolve from the same folder.

<Note>
  In a monorepo where your docs live under a subdirectory (content root `docs`), the `public/` folder sits **inside** that subdirectory: `docs/public/…`. The URL paths in MDX stay the same.
</Note>

  Assets in the repo's public/ folder (at the configured content root) are served from the docs site root: `public/images/x.png` → `https://docs.example.com/images/x.png`. They are fetched from the connected GitHub repo at request time (current branch) and cached for 5 minutes — a push updates assets without a deploy. External `https://` URLs are passed through untouched. Supported extensions include svg, png, jpg/jpeg, webp, gif, ico, avif, pdf, mp4, webm, woff/woff2, ttf, otf, css, js, json, txt, md, yaml.

### How serving works

- Assets are read from your **connected GitHub repo at request time** and cached for 5 minutes — pushing a new file makes it available immediately, no rebuild needed.
- Served from your docs domain (`docs.example.com/images/…`), so there are no cross-origin issues.
- Files up to **100 MB** are supported, but keep web assets small — videos under ~2.5 MB, images under ~500 KB. Large files slow the first uncached request.

### Supported file types

Images (`svg` `png` `jpg` `webp` `gif` `ico` `avif`), media (`mp4` `webm`), documents (`pdf` `txt` `md` `json` `yaml`), fonts (`woff` `woff2` `ttf` `otf`), and code (`css` `js`).

## External URLs

Anywhere an asset path is accepted, a full URL works too:

```mdx External URLs
<Image src="https://cdn.acme.com/screenshots/dashboard.png" alt="Dashboard" />
<Video src="https://assets.acme.com/demos/onboarding.mp4" loop />
```

Use external URLs when the asset already lives on your CDN, is shared across multiple sites, or is too large to belong in a git repo.

<Warning>
  External assets load from a different origin — if your docs readers are behind a strict corporate proxy or the third-party host goes down, those assets break while repo-hosted ones keep working. For anything load-bearing (logo, key diagrams), prefer the repo `public/` folder.
</Warning>

## Choosing between them

| | Repo `public/` | External URL |
|---|---|---|
| Versioned with docs content | ✓ — rolls back with git | ✗ |
| Survives third-party outages | ✓ | ✗ |
| Good for very large files (>100 MB) | ✗ | ✓ |
| Needs a commit to update | ✓ | ✗ — swap at the source |
| Same-origin (no CORS concerns) | ✓ | depends on host |

---

# Versioning
Source: https://docs.nookdocs.com/content/versioning

How to organize v1 / v2 / v3 content in your repo, route readers between versions, and retire deprecated APIs.

Docs sites for long-lived products eventually need to version themselves. NookDocs versioning is **URL-prefix based** — your default version serves at `/`, other versions at `/<slug>/...` — and content lives side-by-side in the same repo under folders that match the slugs.

## Two questions, one answer

<CardGroup cols={2}>
  <Card title="How do readers switch?" icon="arrow-left-right">
    A dropdown in the navbar shows every non-hidden version. Click → the URL changes to that version's prefix. Active version is inferred from the URL on every page load.
  </Card>
  <Card title="Where does the content live?" icon="folder">
    Alongside your existing docs, under folders named after each version's slug. The default version has no folder prefix — it's the root of your docs tree.
  </Card>
</CardGroup>

## Declare versions

Open Configurations → Versions in the dashboard (or edit `nookdocs.config.json` directly):

```json
{
  "versions": [
    { "version": "v3", "default": true, "tag": "Latest", "status": "stable" },
    { "version": "v2", "status": "stable" },
    { "version": "v1", "tag": "Deprecated", "status": "deprecated" }
  ]
}
```

<Warning>
  Exactly one version may carry `default: true`. Validation rejects configs with zero or multiple defaults.
</Warning>

Each entry's **URL slug** is the version label lowercased (override with `slug: "..."` if you want something custom). The default version's URL has NO prefix — it serves at `/`. Non-default versions serve at `/<slug>/...`.

## Repo layout

This is the layout for the config above:

```
your-repo/                        # the docs base
├── nookdocs.config.json
├── introduction.mdx              ← v3 (default), no prefix
├── quickstart.mdx
├── guides/
│   └── authentication.mdx
├── v2/                           ← v2, URL prefix /v2
│   ├── introduction.mdx
│   ├── quickstart.mdx
│   └── guides/
│       └── authentication.mdx
└── v1/                           ← v1, URL prefix /v1
    ├── introduction.mdx
    └── guides/
        └── authentication.mdx
```

URLs resolve like this:

| URL | Reads from |
|---|---|
| `/` | `introduction.mdx` (v3) |
| `/guides/authentication` | `guides/authentication.mdx` (v3) |
| `/v2/` | `v2/introduction.mdx` |
| `/v2/guides/authentication` | `v2/guides/authentication.mdx` |
| `/v1/` | `v1/introduction.mdx` |

The sync pipeline treats `v2/` as a peer of the base content — same MDX rules, same component allowlist, same frontmatter fields. There's no "v2 mode" to toggle.

## Navigation per version

<Warning>
  **The current version of NookDocs** renders the top-level `navigation` config for every version's sidebar. Per-version navigation trees (so the v2 sidebar can differ from v3) is queued for a follow-up sprint — see the [Navigation V2 roadmap](/configuration/navigation).
</Warning>

For now, your navigation is shared across versions. Pages that only exist in one version simply 404 on the others — use `hidden: true` in frontmatter to drop a page from the sidebar without removing the file.

## Writing tips

### Add a new version

<Steps>
  <Step title="Snapshot the current docs">
    Copy the base content into a `v2/` folder at the base. The old version's content is frozen; new work continues at the base.
  </Step>
  <Step title="Mark the old version in config">
    Add `{ "version": "v2", "status": "stable" }` to `versions[]` — alongside the existing default entry.
  </Step>
  <Step title="Commit + push">
    The sync pipeline ingests the new folder. Visitors at `/v2/...` see the snapshot immediately.
  </Step>
</Steps>

### Deprecate an old version

Edit the version's entry to add a red tag and a deprecation banner on the version's pages:

```json
{
  "version": "v1",
  "tag": "Deprecated",
  "status": "deprecated"
}
```

Status `deprecated` colours the badge red in the navbar dropdown. For a visible warning on every v1 page, add a frontmatter banner to the `v1/*.mdx` files or use a [Banner](/components/banner) component at the top of each doc.

### Retire a version

Three options depending on how clean you want the break:

1. **Hide from the switcher**: set `hidden: true` on the entry. URLs still resolve, but the dropdown doesn't show v1. Good for "read-only legacy, don't surface it."
2. **Redirect to the latest**: add a `redirects` entry for `/v1/*` → `/*`. The old URLs bounce to the current version.
3. **Delete**: remove the `v1/` folder and the versions[] entry. Returns 404 on `/v1/...` URLs. Add a 404 redirect (see [Redirects](/configuration/site-settings#redirects)) if you want a softer landing.

## OpenAPI per version

API docs usually track their own version independently. Your `api.openapi` can point at different specs per version by putting the spec file next to each version's content:

```
your-repo/                   # the docs base
├── openapi.json             ← v3 spec (default)
├── v2/
│   └── openapi.json         ← v2 spec
└── v1/
    └── openapi.json         ← v1 spec
```

And reference them in the version-scoped navigation (once per-version nav ships). Until then, use a single top-level `api.openapi` that points at the latest, and surface legacy specs as direct download links inside the deprecated version's docs.

## AI Assistant + versioning

The chat widget's RAG retrieval (via Postgres FTS) indexes every page in the project, including version-prefixed ones. A user asking "how do I authenticate" will get results from whichever version matches best — not necessarily the active one.

Two mitigations:

1. **Pre-pend the active version to queries** (planned) — the widget will detect `/v2/` in the URL and scope retrieval to `docs/v2/*`.
2. **Disable the widget on deprecated versions**: `hidden: true` on the version entry + `config.ai.assistant.enabled: false` if the version is hosted separately.

---

# AWS Route 53 + CloudFront
Source: https://docs.nookdocs.com/deploy/aws-cloudfront

Host your NookDocs site at yourdomain.com/docs with a CloudFront behavior + function.

On AWS, a **CloudFront distribution** for `acme.com` routes the `/docs*` path to
a NookDocs origin, and a **CloudFront Function** tags requests with the headers
we need. See [Host at a subpath](/deploy/subpath) for the overall model.

  Subpath hosting lives in the customer's CloudFront config — there is no NookDocs API. Add the project origin (`<slug>.nookdocs.site`, HTTPS only, empty origin path so `/docs` is kept), a behavior on path pattern `/docs*`, and a viewer-request CloudFront Function that sets two request headers: `x-nookdocs-host` (the public host) and `x-nookdocs-base-path` (e.g. `/docs`). NookDocs then prefixes every link, asset, and canonical with that base path. Use an Origin request policy that forwards host + headers (AllViewer) and CachingDisabled or a low TTL so edits appear quickly.

## 1. Add the NookDocs origin

In your CloudFront distribution → **Origins → Create origin**:

| Field | Value |
|---|---|
| Origin domain | `acme.nookdocs.site` (your project subdomain) |
| Protocol | HTTPS only |
| Origin path | *(leave empty — the `/docs` path is kept)* |

## 2. Add a behavior for `/docs*`

**Behaviors → Create behavior**:

| Field | Value |
|---|---|
| Path pattern | `/docs*` |
| Origin | the NookDocs origin above |
| Viewer protocol policy | Redirect HTTP to HTTPS |
| Allowed methods | GET, HEAD (+ OPTIONS) |
| Cache policy | CachingDisabled (or a short TTL) |
| Origin request policy | AllViewer (forward host + headers) |

This makes CloudFront send `acme.com/docs/*` to NookDocs while everything else
keeps hitting your default origin.

## 3. Tag requests with a CloudFront Function

**Functions → Create function** (viewer request), attach it to the `/docs*`
behavior:

```js
function handler(event) {
  var request = event.request;
  request.headers["x-nookdocs-host"] = { value: "acme.com" };
  request.headers["x-nookdocs-base-path"] = { value: "/docs" };
  return request;
}
```

## 4. Route 53

Point `acme.com` (A/AAAA alias) at the CloudFront distribution as usual. No
record points at NookDocs directly — CloudFront fronts everything.

## Verify

```bash
curl -sI https://acme.com/docs | grep -i content-type
curl -s  https://acme.com/docs/llms.txt | head -1
```

## Notes

- Use **CachingDisabled** (or low TTL) on the `/docs*` behavior so doc edits
  appear quickly; NookDocs already sends sensible cache headers.
- Sending a CSP via CloudFront response headers? See [CSP](/deploy/csp).

---

# Cloudflare Workers
Source: https://docs.nookdocs.com/deploy/cloudflare

Host your NookDocs site at yourdomain.com/docs with a Cloudflare Worker reverse proxy.

If `acme.com` is on Cloudflare, a small **Worker** forwards `/docs/*` to your
NookDocs origin. See [Host at a subpath](/deploy/subpath) for the overall model.

  Subpath hosting is configured entirely in the customer's Cloudflare Worker — there is no NookDocs API for it. The Worker matches `/docs` and `/docs/*`, rewrites the request to the project origin (`<slug>.nookdocs.site`), and sets two request headers: `X-Nookdocs-Host` (the public host, e.g. `acme.com`) and `X-Nookdocs-Base-Path` (e.g. `/docs`). NookDocs then prefixes every emitted link, asset, and canonical URL with that base path. Use `redirect: "manual"` in the `fetch` call so NookDocs trailing-slash and config redirects reach the visitor intact.

## 1. Create the Worker

In the Cloudflare dashboard → **Workers & Pages → Create → Worker**, paste this
(replace the origin with your project's subdomain and adjust the path):

```js
export default {
  async fetch(request) {
    const url = new URL(request.url);
    // Only proxy the docs subpath; everything else hits your own origin.
    if (url.pathname === "/docs" || url.pathname.startsWith("/docs/")) {
      const target = new URL(request.url);
      target.hostname = "acme.nookdocs.site";
      target.protocol = "https:";
      target.port = "";
      const headers = new Headers(request.headers);
      headers.set("X-Nookdocs-Host", "acme.com");
      headers.set("X-Nookdocs-Base-Path", "/docs");
      headers.set("Host", "acme.nookdocs.site");
      return fetch(target, {
        method: request.method,
        headers,
        body: request.body,
        redirect: "manual",
      });
    }
    return fetch(request);
  },
};
```

## 2. Add a route

Workers → your worker → **Settings → Domains & Routes → Add route**:

```
Route:  acme.com/docs*
Zone:   acme.com
```

The `*` is important — it matches `/docs` and everything beneath it.

## 3. Verify

```bash
curl -sI https://acme.com/docs | grep -i content-type   # text/html from NookDocs
curl -s  https://acme.com/docs/llms.txt | head -1        # # Your Project
```

Internal links, assets, and canonical tags all resolve under `acme.com/docs`.

## Notes

- **Other paths are untouched** — `return fetch(request)` passes everything
  outside `/docs/*` straight to your own origin.
- **Redirects** use `redirect: "manual"` so NookDocs redirects (trailing-slash,
  config `redirects`) reach the visitor intact.
- If you send a CSP from your site, see [CSP configuration](/deploy/csp).

---

# CSP configuration
Source: https://docs.nookdocs.com/deploy/csp

Content-Security-Policy directives to allow your NookDocs site when it's served from your own domain.

If your site sends a strict **Content-Security-Policy** header, it also applies
to the docs served at `acme.com/docs` (same origin, via your
[reverse proxy](/deploy/subpath)). A too-tight policy blanks the page, drops
styles, or breaks the AI assistant. Allow the directives below.

  This CSP is set by the customer's own edge (Cloudflare Transform Rule/Worker, Vercel `headers`, or a CloudFront Response Headers Policy) — there is no NookDocs API for it. NookDocs requires `script-src 'unsafe-inline'` (framework hydration + inline JSON-LD; a per-request nonce works instead), `style-src 'unsafe-inline'` (theme tokens are inline `--docs-*` style attributes — nonces do NOT cover these, so `'unsafe-inline'` here is unavoidable), `img-src 'self' data: https:`, `font-src 'self' data:`, and `connect-src 'self' https://*.nookdocs.site` for the AI assistant and search. Add `frame-src` hosts only for videos/iframes you actually embed.

<Note>
  No CSP on your domain? Nothing to do — skip this page. This only matters when
  you're already sending a `Content-Security-Policy` and now host docs under it.
</Note>

## Recommended directives

```
default-src 'self';
script-src 'self' 'unsafe-inline';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https:;
font-src 'self' data:;
connect-src 'self' https://*.nookdocs.site;
frame-src 'self' https://www.youtube.com https://player.vimeo.com;
```

| Directive | Why NookDocs needs it |
|---|---|
| `script-src 'unsafe-inline'` | Framework hydration + inline JSON-LD. Use a nonce instead if you can mint one per request. |
| `style-src 'unsafe-inline'` | Theme tokens (`--docs-*`) are applied as inline styles. |
| `img-src data: https:` | Logos/favicons (data: + your assets) and any external images in your content. |
| `font-src 'self' data:` | Bundled + embedded fonts. |
| `connect-src https://*.nookdocs.site` | The AI assistant + search call back to the platform. Drop if you don't use the assistant. |
| `frame-src ...` | Only if you embed videos/iframes via `<Video>` / `<Embed>`. Add the hosts you actually use. |

## Tightening with a nonce

`'unsafe-inline'` for scripts is the simple path. If your platform injects a
per-request nonce, prefer:

```
script-src 'self' 'nonce-{REQUEST_NONCE}';
```

and drop `'unsafe-inline'` from `script-src`. Styles still need `'unsafe-inline'`
(theme tokens are inline style attributes, which nonces don't cover).

## Where to set it

- **Cloudflare** — a Transform Rule or a `response.headers` set in the
  [Worker](/deploy/cloudflare).
- **Vercel** — `headers` in `vercel.json` or `next.config.js`.
- **CloudFront** — a Response Headers Policy on the `/docs*` behavior.

After changing the policy, hard-reload and check the browser console for
blocked-resource warnings.

---

# Custom domain
Source: https://docs.nookdocs.com/deploy/custom-domain

Point docs.yourcompany.com at your project via CNAME or ALIAS, survive DNS propagation, get Let's Encrypt SSL in seconds, and avoid the common Cloudflare + Vercel gotchas.

Every project ships on a free `{slug}.nookdocs.site` subdomain. Adding a custom domain is a 3-step flow: type the hostname in the dashboard, copy the DNS record, wait for verification. SSL provisions automatically. This page covers every edge case we've hit: apex domains, CAA records, Cloudflare proxy mode, multi-domain setups, and canonical URL handling for SEO.

  Subdomains attach with one CNAME to `cname.nookdocs.site`; apex domains use ALIAS/ANAME/flattening (or A record `76.76.21.21` as a fallback) since apex CNAMEs are invalid. Verification polls DNS for up to 60 seconds, then Let's Encrypt SSL provisions automatically — no manual cert step. If a CAA record exists it MUST include `0 issue "letsencrypt.org"` or issuance fails silently. With Cloudflare, keep the proxy off (grey cloud / DNS only) and set SSL/TLS to Full (strict); a proxied record or Flexible mode breaks tenant resolution and TLS. One domain attaches to one project; the Primary domain drives the `<link rel="canonical">`, overridable via `seo.metatags.canonical` in `nookdocs.config.json`.

## Why use a custom domain

<CardGroup cols={3}>
  <Card title="Brand consistency" icon="sparkles">
    `docs.acme.com` reads as part of your product; `acme-docs.nookdocs.site` reads as a third-party tool.
  </Card>
  <Card title="SEO authority" icon="search">
    Backlinks accrue to your apex domain, not ours. Custom domains compound your organic search.
  </Card>
  <Card title="User trust" icon="shield-check">
    Users are trained to verify the domain bar. A branded host is one fewer phishing signal.
  </Card>
</CardGroup>

## Pick the host shape

Two shapes work out of the box. Pick based on where your docs live in your information architecture.

<CardGroup cols={2}>
  <Card title="Subdomain — docs.acme.com" icon="globe">
    A subdomain of your apex. Add a CNAME record, we verify it, SSL provisions automatically. 90% of setups look like this.
  </Card>
  <Card title="Subpath — acme.com/docs" icon="folder-tree">
    Hosts your docs as a path prefix of your marketing site. Requires a reverse proxy rule in front of your site. Advanced — see [subdomain](/deploy/subdomain) for the split.
  </Card>
</CardGroup>

## Add via the dashboard

<Steps>
  <Step title="Open Settings → Custom domains">
    Scroll to **Custom domains**. Empty when you've only been using the default subdomain; otherwise you'll see existing domains with verification state.
  </Step>

  <Step title="Enter your hostname">
    Type `docs.acme.com` (or whatever you own) and hit **Add**. Each project can carry multiple custom domains simultaneously — e.g. `docs.acme.com` + `docs.acme.dev` + a regional `help.acme.eu` — each with its own verification state. Mark one as **Primary** (see [canonical URLs](#canonical-urls-for-seo) below) and the rest stay aliased.
  </Step>

  <Step title="Copy the DNS record we show you">
    You'll see something like:

    ```text
    Type  : CNAME
    Host  : docs
    Value : cname.nookdocs.site
    TTL   : 3600 (or Auto)
    ```

    Copy the **Value** field — that's what your DNS provider needs.
  </Step>

  <Step title="Add the record at your DNS provider">
    Open Cloudflare / Route 53 / DNSimple / GoDaddy / Google Domains / Namecheap and paste the CNAME record as shown. Save.
  </Step>

  <Step title="Wait for verification">
    Our checker polls DNS every 5 seconds for up to 60 seconds. When it catches the propagated record, the domain flips from **Pending** to **Active** and SSL provisioning kicks off.
  </Step>
</Steps>

## DNS record reference

### CNAME — the default case

```dns
docs.acme.com.    IN    CNAME    cname.nookdocs.site.
```

CNAMEs are the simplest case — your provider routes `docs.acme.com` through us, and everything (TLS, headers, caching) flows end-to-end.

<Warning>
  Don't create an A record *as well*. CNAME + A on the same hostname is invalid per RFC 1034 and most providers reject it.
</Warning>

### CAA — required when you have one

If your domain already has a CAA record, it **must** allow Let's Encrypt. Otherwise our cert issuance fails silently.

```dns
acme.com.    IN    CAA    0 issue "letsencrypt.org"
```

Check your current CAA:

```bash
dig acme.com CAA +short
# → 0 issue "digicert.com"   ← blocks Let's Encrypt
# → no output                  ← no CAA, any issuer allowed ✓
```

If you see an existing `issue` entry, add Let's Encrypt alongside it:

```dns
acme.com.    IN    CAA    0 issue "digicert.com"
acme.com.    IN    CAA    0 issue "letsencrypt.org"
```

## Apex domain (`acme.com`)

Apex domains — the bare root without any subdomain — can't use CNAMEs per the DNS spec. Three options, from best to worst:

### ALIAS / ANAME / flattening (recommended)

Modern providers (Cloudflare, DNSimple, Route 53) offer a CNAME-like record at the apex that resolves to the target's current IPs on every query.

<CodeGroup>
```dns Cloudflare
acme.com.    CNAME    cname.nookdocs.site.    ; proxy: OFF
```

```dns Route 53
acme.com.    ALIAS    cname.nookdocs.site.    ; alias record, no TTL
```

```dns DNSimple
acme.com.    ALIAS    cname.nookdocs.site.
```
</CodeGroup>

<Warning>
  **Cloudflare users — keep the proxy off.** The orange cloud (proxied mode) breaks the SSL handshake by terminating TLS at Cloudflare. Set the record to "DNS only" (grey cloud) so traffic flows end-to-end.
</Warning>

### A record fallback

If your provider doesn't support ALIAS, fall back to A records pointing at our published IPs:

```dns
acme.com.    IN    A    76.76.21.21
```

Downsides: IPs can change (90 days notice), and single-A means no multi-region failover. Prefer ALIAS when available.

### Subdomain redirect

Dodge the problem entirely — keep your apex as your marketing site, and run docs on a subdomain:

```
acme.com         → www.acme.com (marketing)
docs.acme.com    → NookDocs (this guide)
```

## SSL

SSL certificates auto-provision via Let's Encrypt (issued through Vercel's edge) the moment verification succeeds.

- **First issuance** — usually under 30 seconds after the DNS record goes green.
- **Renewal** — automatic, ~30 days before expiry.
- **Issuer** — Let's Encrypt R3.
- **Reserved path** — `/.well-known/acme-challenge/*` is reserved for the challenge handshake; don't configure your docs to write content to that path.

## Multiple domains per project

Add more than one custom domain to the same project — e.g. regional domains or migration scenarios where both old and new domains need to serve during a cutover.

```text
docs.acme.com         primary    ✓ active
docs.acme.dev                    ✓ active
help.acme.eu                     ✓ active
acme.nookdocs.site    default    ✓ active
```

All active domains serve the same content. The **primary** domain drives canonical URLs — see below.

## Canonical URLs for SEO

When you have multiple domains serving the same docs, search engines need one canonical URL per page to avoid duplicate-content penalties. NookDocs picks the canonical automatically in this priority order:

1. The domain marked **Primary** in Settings → Custom domains
2. The first verified custom domain in the list
3. The default `{slug}.nookdocs.site` subdomain

Every rendered page ships `<link rel="canonical" href="https://{canonical-host}/{path}">` so Google/Bing know which URL to index. Override site-wide via `nookdocs.config.json`:

```json
{
  "seo": {
    "metatags": {
      "canonical": "https://docs.acme.com"
    }
  }
}
```

See [SEO](/optimize/seo) for the full indexing + sitemap + robots story.

## Cloudflare-specific gotchas

<AccordionGroup>
  <Accordion title="SSL/TLS encryption mode">
    In Cloudflare dashboard → **SSL/TLS → Overview**, set encryption mode to **Full (strict)**. `Flexible` terminates TLS at Cloudflare and re-connects to us over HTTP — we reject HTTP, so the site hangs on a redirect loop. `Full` works but is less secure; `Full (strict)` is correct.
  </Accordion>
  <Accordion title="Always Use HTTPS">
    Turn on **Rules → Always Use HTTPS**. Prevents mixed-content warnings when readers land on `http://docs.acme.com`.
  </Accordion>
  <Accordion title="Proxy mode">
    Keep the orange cloud **off** (DNS only) for the NookDocs CNAME. Proxying prevents our edge from seeing the real hostname, which breaks tenant resolution. If you need Cloudflare's WAF or caching, put it at a different level of your stack.
  </Accordion>
</AccordionGroup>

## Vercel verification (if your DNS is managed on Vercel)

Vercel-hosted DNS adds a TXT record during verification. If you manage your DNS on Vercel (most users don't — this is an edge case), you'll see a prompt asking you to add:

```dns
_vercel.acme.com.    IN    TXT    "vc-domain-verify=docs.acme.com,abc123..."
```

Paste into Vercel's DNS panel. We detect the record, verification completes, the TXT record can stay (harmless) or be removed.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Verification stuck on Pending for >2 minutes">
    DNS propagation sometimes takes longer. Check with `dig docs.acme.com CNAME +short` — if the result doesn't show `cname.nookdocs.site`, your record hasn't propagated. Wait 5 minutes, re-check. Cloudflare's proxied mode also hides the CNAME from `dig` — disable the orange cloud to see the raw record.
  </Accordion>

  <Accordion title="SSL error after verification">
    A CAA record that doesn't include `letsencrypt.org` blocks cert issuance. Check with `dig acme.com CAA +short`, add `0 issue "letsencrypt.org"` if missing, re-trigger provisioning from the dashboard.
  </Accordion>

  <Accordion title="'This domain is already claimed' error">
    Each custom domain can only attach to one NookDocs project at a time. If you previously used it with another project, detach it there first. Migrating from another vendor? Confirm their DNS is fully removed before re-pointing to us.
  </Accordion>

  <Accordion title="Cloudflare: TOO_MANY_REDIRECTS">
    Your SSL mode is **Flexible**. Switch to **Full (strict)** (dashboard → SSL/TLS → Overview). Flexible terminates TLS at Cloudflare and connects to us over HTTP, which we reject; the result is an HTTPS→HTTP→HTTPS loop.
  </Accordion>

  <Accordion title="SSL error: NET::ERR_CERT_DATE_INVALID after switching primary domain">
    Browser cached the old certificate. Hard-refresh (Cmd+Shift+R / Ctrl+Shift+R) or clear the site's HSTS state in chrome://net-internals/#hsts.
  </Accordion>

  <Accordion title="Docs load but assets 404 / paths broken">
    Check `nookdocs.config.json#contentRoot` — if your repo stores MDX under `docs/` make sure the value ends with a slash (`"contentRoot": "docs/"`). The sync pipeline ignores anything outside `contentRoot`.
  </Accordion>
</AccordionGroup>

## Related

- [Subdomain vs subpath](/deploy/subdomain) — `docs.acme.com` vs `acme.com/docs` trade-offs
- [SEO](/optimize/seo) — canonical URLs + sitemap + robots behaviour
- [Site settings](/configuration/site-settings) — `seo.metatags` for canonical override
- [Custom domain (config reference)](/configuration/schema-reference#seo) — field-by-field config reference

---

# Monorepo
Source: https://docs.nookdocs.com/deploy/monorepo

Keep your docs in a subfolder of a larger repository. Point NookDocs at the directory that holds nookdocs.config.json and everything resolves under it.

If your docs don't live at the root of their repository — for example a monorepo where the app, packages, and docs share one repo — tell NookDocs which subfolder holds your docs project.

  The monorepo base path is a project setting, NOT a key in `nookdocs.config.json` — NookDocs needs it to locate the config file itself. Set it to the folder that contains `nookdocs.config.json` (e.g. `docs` or `apps/docs`, no leading/trailing slash) when connecting the repo or later under Settings → Git → Monorepo. Only that subtree is synced and ingested; the rest of the repo (app code, packages) is never read. Paths inside the config (`contentRoot`, `api.openapi`) stay relative to this base, page URLs strip the base (and `contentRoot`), and repo-meta files (`README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `LICENSE`, `CHANGELOG.md`) at the base are never published as docs pages.

## How it works

NookDocs treats one directory as your **docs base**: the folder that contains `nookdocs.config.json`. Everything resolves relative to it:

- `nookdocs.config.json` — at the base
- your content — under the base (flat, or under `contentRoot`)
- `api.openapi` — relative to the base

So a repo like this just works:

```
my-monorepo/
├─ apps/
│  └─ web/            ← your app
├─ packages/
└─ docs/              ← docs base (point NookDocs here)
   ├─ nookdocs.config.json
   ├─ openapi.json
   ├─ index.mdx
   └─ guides/...
```

## Set it up

When you **connect the repository**, pick the repo and flip **Set up as monorepo**, then enter the path to the folder that contains `nookdocs.config.json` (e.g. `docs` or `apps/docs`, no leading/trailing slash). You can also change it later under **Settings → Git → Monorepo**.

### Only your docs folder is read

NookDocs syncs (and the editor's Files tab shows) **only the base path** — the rest of the repo is never ingested. So pointing us at `docs/` in a repo that also holds your app keeps the app code out of NookDocs entirely.

<Note>
  GitHub Apps grant access at the repository level (you choose which repos during install), so the base path is how NookDocs narrows that down to just your docs subtree. It's a project setting, not a key inside `nookdocs.config.json` — we need it to *find* the config. Paths inside the config (`contentRoot`, `api.openapi`) stay relative to the base.
</Note>

## Content layout

Inside the base, content can be **flat** (Markdown files directly under the base, like the starter template) or nested under a `contentRoot` folder. Page URLs are the file path with the base (and `contentRoot`, if set) stripped — so moving a docs project into a monorepo subfolder doesn't change any URLs.

Repo-meta files at the base (`README.md`, `CONTRIBUTING.md`, `AGENTS.md`, `LICENSE`, `CHANGELOG.md`) are never ingested as docs pages.

---

# Publishing & drafts
Source: https://docs.nookdocs.com/deploy/publishing

Keep a site private while you work on it, preview it, then publish when it's ready. A draft site is invisible to the public until you press Publish.

Every NookDocs project has a **published** state. Your site **goes live automatically on its first successful deploy** — push your docs (or edit in the browser) and once the first deploy finishes, `{slug}.nookdocs.site` is public. No extra publish step for a normal launch.

You stay in control after that: **Unpublish** anytime to take the site offline (it returns to "Site not found"), then **Publish** again when you're ready. Once you've unpublished, later deploys won't silently re-publish — your choice sticks.

  A project's public tenant site is gated by a `published` flag, separate from deploy status. It is set to true automatically on the first successful deploy (last_deploy_at was previously null); subsequent deploys never change it, so an explicit Unpublish is preserved. While unpublished (draft), the public site — every page plus `sitemap.xml`, `llms.txt`, `llms-full.txt`, `robots.txt`, `.md` raw exports and RSS — responds as if the subdomain didn't exist ("Site not found"). Search engines and AI crawlers therefore index nothing while unpublished. Toggled by the project owner from the dashboard; there is no config-file key for it.

## Draft vs. live

| | Draft | Published |
|---|---|---|
| Public visits `{slug}.nookdocs.site` | Sees **"Site not found"** | Sees your docs |
| Appears in search / AI crawlers | No | Yes |
| `sitemap.xml`, `llms.txt`, `robots.txt` | Not served | Served |
| You can edit & deploy | Yes | Yes |
| You can preview it | Yes (private preview) | Yes (it's just live) |

A draft is **indistinguishable from a nonexistent site** to anyone without a preview link — there's no "coming soon" page that reveals the site exists.

<Info>
  Publish state is separate from **deploy status**. A project can be deployed and building fine, yet still be a draft. And it's separate from **password protection** ([access control](/configuration/access-control) if configured) — that gates an *already-public* site behind a password; a draft isn't public at all.
</Info>

## Preview a draft

While a site is a draft, open **Preview draft** from the project overview (or **Settings → General → Visibility**). It opens your site in a new tab and starts a **private preview session** that only works in your browser — the public still sees "Site not found".

## Publish (after unpublishing)

The first deploy publishes for you. You only press **Publish** to bring a site back after you've unpublished it: on the project overview or **Settings → General → Visibility**, press **Publish** — the badge flips to **Live** and `{slug}.nookdocs.site` is public again. (Publishing needs at least one successful deploy; if the button is disabled, deploy first.)

## Unpublish

Need to take the site offline? Press **Unpublish** on the overview or **Settings → General → Visibility**. The public site immediately returns "Site not found" again — your content and deploys are untouched, they're just no longer served publicly. Later deploys won't re-publish it; press **Publish** when you're ready.

## Related

- [Custom domains](/deploy/custom-domain) — the publish gate applies to custom domains too.
- [Access control](/configuration/access-control) — password-protect an already-published site.

---

# Subdomain
Source: https://docs.nookdocs.com/deploy/subdomain

Every project gets a free subdomain under nookdocs.site — here's what you can pick, how to rename it, and what's reserved.

## Default subdomain

Every project gets a free subdomain at `<slug>.nookdocs.site` the moment it's created. The slug is whatever you pick on the new-project screen — so a project with slug `acme-docs` is live at `https://acme-docs.nookdocs.site`.

SSL is auto-provisioned; there's nothing to configure.

  The subdomain is assigned automatically from the project slug at `<slug>.nookdocs.site`; there is no DNS record or API call to deploy it. Slugs must be 3–32 chars, lowercase letters/digits/hyphens, start and end alphanumeric, no consecutive hyphens, and not match a reserved name (`api`, `app`, `www`, `docs`, `admin`, `status`, etc.). Renaming preserves the old subdomain as a 301 redirect for exactly 90 days, after which it is released for reuse. For a customer-owned hostname use a CNAME (Custom domain); the subpath option uses a customer-controlled reverse proxy, not DNS.

## Constraints

<Warning>
  Slugs are immutable-looking but actually rename-able. See [Renaming](#renaming) below.
</Warning>

| Rule | Example |
|---|---|
| 3–32 characters | `a` (too short), `acme-docs-for-the-entire-enterprise-and-more` (too long) |
| Lowercase letters, digits, and hyphens only | `acme-docs` ✅, `Acme_Docs` ❌ |
| Must start and end with a letter or digit | `-acme` ❌, `acme-` ❌ |
| No consecutive hyphens | `acme--docs` ❌ |
| Not a [reserved subdomain](#reserved-subdomains) | `api` ❌, `www` ❌ |

Validation runs both in the create form and on the server — we reject anything that slips through the client check.

## Renaming

Yes, you can change your slug after you've shipped.

<Note>
  The 90-day redirect window is a hard deadline. After that, the old subdomain becomes eligible for someone else to claim.
</Note>

## Reserved subdomains

Some subdomains are permanently reserved for platform infrastructure and can never be claimed by a project:

| Reserved | Used for |
|---|---|
| `api` | Public REST API (`api.nookdocs.com`) |
| `app` | Dashboard (`app.nookdocs.com`) |
| `www`, `nookdocs`, `nookdocs` | Marketing site |
| `admin`, `dashboard`, `account` | Reserved for future auth flows |
| `docs` | `docs.nookdocs.com` (NookDocs' own docs) |
| `status`, `health`, `monitor` | Reserved for status pages |
| `mail`, `email`, `smtp`, `imap` | Reserved for email infrastructure |

If you need a slug that's currently reserved, open a support ticket — we may be able to release it case-by-case.

## Ready to use your own domain?

See [Custom domain](/deploy/custom-domain) for attaching `docs.yourcompany.com`.

---

# Host at a subpath
Source: https://docs.nookdocs.com/deploy/subpath

Serve your docs at yourdomain.com/docs instead of a subdomain — keep your marketing site and docs on one domain via a reverse proxy.

By default a custom domain is a **subdomain** (`docs.acme.com`) pointed at us
with a CNAME. **Subpath hosting** instead serves your docs under a path of your
existing site — `acme.com/docs` — with your own infrastructure in front. Great
when you want docs and marketing under one domain for SEO and brand.

  Subpath hosting has no NookDocs API and touches no DNS on our side; the customer runs a reverse proxy they control (Cloudflare Worker, Vercel middleware, or AWS CloudFront) that forwards the docs path to the project's `<slug>.nookdocs.site` origin. The proxy MUST send two headers: `X-Nookdocs-Host` (the canonical apex, e.g. `acme.com`, used for canonical/sitemap/OG) and `X-Nookdocs-Base-Path` (the path prefix, e.g. `/docs`, stripped for routing and re-prefixed on every emitted URL). The path is kept on the forwarded request; NookDocs strips it for routing and re-prefixes navigation, assets, `sitemap.xml`, `llms.txt`, JSON-LD, and canonical tags. Repo, content, and config are unchanged — subpath is purely a serving choice; contrast with subdomain (single CNAME, platform-provisioned cert).

## How it works

You keep `acme.com` on your own platform and add a small **reverse proxy** that
forwards just the docs path to NookDocs:

```
Visitor → acme.com/docs/guide
        → your proxy (Cloudflare / Vercel / CloudFront)
        → acme.nookdocs.site/docs/guide   (+ two headers)
        → NookDocs renders, prefixing every link/asset/canonical with /docs
```

The proxy tags each forwarded request with two headers we read:

| Header | Value | Purpose |
|---|---|---|
| `X-Nookdocs-Host` | `acme.com` | Your canonical domain — used for `<link rel="canonical">`, sitemap, OG. |
| `X-Nookdocs-Base-Path` | `/docs` | The subpath — stripped for routing, re-prefixed on every emitted URL. |

Everything the site emits — navigation, prev/next, breadcrumbs, the logo, page
images, `sitemap.xml`, `llms.txt`, JSON-LD, canonical tags — is automatically
prefixed with your subpath, so links stay inside `acme.com/docs`.

## Set it up

<Steps>
  <Step title="Enable subpath on the domain">
    In **Settings → Domains**, flip **Host at /docs**, enter your apex
    (`acme.com`) and the path (`/docs`), and add it. No CNAME or certificate on
    our side — your proxy fronts it.
  </Step>
  <Step title="Add the reverse proxy">
    Copy the snippet for your platform and deploy it on your domain. Per-provider
    guides:
    - [Cloudflare Workers](/deploy/cloudflare)
    - [Vercel](/deploy/vercel)
    - [AWS Route 53 + CloudFront](/deploy/aws-cloudfront)
  </Step>
  <Step title="Check the headers (CSP)">
    If your site sends a Content-Security-Policy, make sure it doesn't block the
    docs assets — see [CSP configuration](/deploy/csp).
  </Step>
</Steps>

<Note>
  The project's origin is always `<your-subdomain>.nookdocs.site`. The proxy
  forwards to it and keeps the `/docs` path; we strip it for routing and
  re-prefix it on output. Your repo, content, and config are unchanged — subpath
  is purely a serving choice.
</Note>

## Subpath vs subdomain

<CardGroup cols={2}>
  <Card title="Subdomain — docs.acme.com" icon="globe">
    One CNAME to `cname.nookdocs.site`, we provision the certificate. Simplest;
    no proxy to maintain.
  </Card>
  <Card title="Subpath — acme.com/docs" icon="route">
    Docs + marketing share one domain (better for brand + SEO consolidation).
    You run a small reverse proxy; we never touch your DNS.
  </Card>
</CardGroup>

---

# Vercel
Source: https://docs.nookdocs.com/deploy/vercel

Host your NookDocs site at yourdomain.com/docs with Vercel middleware.

If `acme.com` is a Next.js app on Vercel, a `middleware.ts` rewrite forwards
`/docs/*` to your NookDocs origin. See [Host at a subpath](/deploy/subpath) for
the overall model.

  This is configured in the customer's own Next.js `middleware.ts` — there is no NookDocs API for subpath hosting. Use `NextResponse.rewrite(url, { request: { headers } })`, not `vercel.json`/`next.config.js` `rewrites`, because only middleware can attach request headers. Rewrite to the project origin (`<slug>.nookdocs.site`) and set `X-Nookdocs-Host` (public host) and `X-Nookdocs-Base-Path` (e.g. `/docs`); NookDocs prefixes every link, asset, and canonical with that base path. Scope it with `export const config = { matcher: "/docs/:path*" }` so the rest of the app is untouched.

## middleware.ts

Add this to your Next.js app (replace origin/domain/path):

```ts
// middleware.ts
import { NextResponse } from "next/server";

export const config = { matcher: "/docs/:path*" };

export function middleware(request: Request) {
  const url = new URL(request.url);
  url.hostname = "acme.nookdocs.site";
  url.protocol = "https:";
  url.port = "";
  const headers = new Headers(request.headers);
  headers.set("X-Nookdocs-Host", "acme.com");
  headers.set("X-Nookdocs-Base-Path", "/docs");
  return NextResponse.rewrite(url, { request: { headers } });
}
```

## Why middleware, not `rewrites`

`vercel.json` / `next.config.js` rewrites can forward the path but **can't set
request headers**, and we need `X-Nookdocs-Host` + `X-Nookdocs-Base-Path`.
Middleware's `NextResponse.rewrite(url, { request: { headers } })` does both —
it proxies to the external origin *and* attaches the headers.

## Verify

```bash
curl -sI https://acme.com/docs | grep -i content-type
curl -s  https://acme.com/docs/llms.txt | head -1
```

## Notes

- The `matcher` scopes the middleware to `/docs/*` only — the rest of your app
  is untouched.
- Not a Next.js app? Use [Cloudflare Workers](/deploy/cloudflare) or
  [AWS CloudFront](/deploy/aws-cloudfront) in front of any stack.
- Sending a CSP? See [CSP configuration](/deploy/csp).

---

# Configurations panel
Source: https://docs.nookdocs.com/editor/configurations-panel

The editor's slide-out for site-wide settings — theme, colors, navbar, SEO, AI — organised in five tabs, saving straight to nookdocs.config.json in your repo.

Everything a site can configure lives in [`nookdocs.config.json`](/configuration/config-file).
The Configurations panel is that file as a UI: it reads the current config,
gives every key a control, and saves by committing the updated JSON back to
your repository — the same [save path](/editor/save-and-publish) as a page
edit, so the config in Git stays the source of truth.

<Note>
  Config and panel are twins by design: anything the JSON accepts has a
  control here, and saving from the panel preserves keys you set by hand in
  the file. You never lose a setting for having edited it "the other way".
</Note>

## The five tabs

| Tab | What lives there |
|---|---|
| **Site** | Name, theme, appearance defaults, brand colors, logo, favicons, social card, background |
| **Layout** | Shell and layout options, sidebar behaviour, code-block style, content settings |
| **Navigation** | Navbar links, the primary CTA button, footer columns and social links |
| **SEO** | Title and description, keywords, indexing, GEO/structured-data switches |
| **AI & Advanced** | The AI assistant, feedback widget, contextual "Copy page" menu, analytics, redirects, advanced flags |

Each control loads its value from the config on open — a key you never set
shows the default it falls back to, so the panel doubles as a reference for
what the site is actually doing.

## How saving works

<Steps>
  <Step title="Edit any number of controls">
    Changes stage locally in the panel; nothing touches the site yet.
  </Step>
  <Step title="Save commits the config">
    The panel rebuilds `nookdocs.config.json` — your untouched keys included —
    and commits it to the repo. On a plan that gates a setting (for example
    removing the "Powered by" attribution needs Team+), the save tells you
    instead of silently dropping the change.
  </Step>
  <Step title="Sync applies it">
    The push comes back through the [sync pipeline](/github/sync-pipeline) and
    the live site picks up the new config — theme, colors, navigation and all.
  </Step>
</Steps>

## Panel or JSON — both, freely

Some teams live in the panel; some keep the config in code review like any
other file. Mixing works because both paths write the same file:

- Set up the basics in the panel, then fine-tune rarely-used keys in JSON with
  [`$schema` autocomplete](/configuration/config-file).
- Hand-write the config and use the panel to preview what a theme or color
  change looks like before committing to it.
- Let an agent edit the JSON over [MCP](/integrations/mcp) — it can validate
  the file with `validate_config` before the commit, and the panel reflects
  the result on next open.

<Tip>
  The panel shows a live preview of theme and color choices before you save —
  cheaper than a commit-and-look loop when you're picking between two darks.
</Tip>

---

# Dashboard navigation
Source: https://docs.nookdocs.com/editor/dashboard-navigation

How the sidebar, project switcher, header, and per-project nav are organized. Includes the theme selector and the avatar menu.

The dashboard is split into three regions: a **left sidebar** (project switcher + navigation), a **top header** (theme + account), and the **main content area**.

  This page describes the dashboard chrome — a browser-only UI with no API. The left sidebar holds a project switcher plus nav items that swap between global (Projects, Settings, Billing) and per-project (Overview, Analytics, Feedback, Settings) depending on whether you are inside a `/projects/[id]` route. Switching projects keeps you on the same subroute. The top header (right-aligned, above the main content, not the sidebar) holds a three-way System/Light/Dark theme toggle and an avatar account menu; the theme controls only the dashboard UI, persists in `localStorage` as `nookdocs-app-theme`, and is separate from a tenant site's `appearance.default`. Below 768px the header collapses into a top bar and the sidebar becomes a hamburger overlay.

## Sidebar

The sidebar is fixed to the left edge on desktop and collapsible to an icon rail via the **Collapse** button at the bottom. On mobile it slides in from the left via the hamburger menu.

### Project switcher (top)

Right below the NookDocs logo is the **project switcher**. It shows:

- The **active project** — when you're inside a project route (editor, settings, analytics, connect), its name and subdomain appear here.
- A **list of all your projects** — click the switcher to reveal; picking another project hops you straight to the same subroute (e.g. switching from Project A's editor lands you on Project B's editor, not its overview).
- **Create project** and **View all projects** — sticky footer actions inside the dropdown.

Outside a project route (on `/projects`, `/settings`, `/billing`), the switcher label reads **Select project**.

### Nav items

The nav swaps between two states depending on where you are:

**Global (outside a project)**

- **Projects** — the list of all docs projects in your workspace
- **Settings** — workspace-level settings
- **Billing** — plan + invoices

**Per-project (inside `/projects/[id]`)**

- **Overview** — project dashboard
- **Analytics** — first-party analytics (views, visitors, searches, feedback, AI-vs-human split). See [Analytics](/configuration/analytics).
- **Feedback** — per-page "Was this helpful?" triage backlog. See [Feedback](/configuration/feedback#triage-dashboard).
- **Settings** — project-level settings

Below both states there's always a **Documentation** external link and a **Log out** button at the bottom.

## Header

The desktop header sits above the main content area, not above the sidebar. It's right-aligned and holds two things:

### Theme toggle

Three-way selector: **System** / **Light** / **Dark**. Controls the dashboard UI theme only — tenant docs sites have their own `appearance.default` setting in [site-settings](/configuration/site-settings#appearance).

Selection persists in `localStorage` under `nookdocs-app-theme` and applies a `data-app-theme` attribute to the document root. System mode follows your OS preference.

### Avatar menu

Click the avatar circle (the first letter of your name) to open the account menu:

- **Name + email** — a compact identity header
- **Documentation** — opens `docs.nookdocs.com` in a new tab
- **Contact support** — opens a mailto link to the support inbox
- **Log out** — signs you out of the dashboard

The theme selector intentionally lives **outside** this menu — it's a one-click target at the far right of the header, not three clicks deep.

## Mobile

Below the `md` breakpoint (768px), the desktop header collapses into a thin top bar with only the NookDocs wordmark and a hamburger button. Opening the hamburger slides the full sidebar in as an overlay. Theme + avatar actions are reachable from inside that sidebar drawer on mobile.

## Why this layout

The previous design stacked user info and theme selector into a single sidebar dropdown, which made two common actions (switching projects, changing theme) fight for the same slot. The new split promotes project navigation to the sidebar's top and account actions to the header's right — each high-frequency action gets its own dedicated target.

---

# Navigation tab
Source: https://docs.nookdocs.com/editor/navigation-tab

Build your sidebar from the editor — right-click to add pages, groups, anchors, and dropdowns.

The Navigation tab (left sidebar of the editor) shows your site's navigation tree exactly as readers see it — tabs at the top, groups under each tab, pages inside each group. Everything in this tree is driven by `nookdocs.config.json#navigation`; the editor is just a visual layer on top of that.

  This is a browser-only visual editor over `nookdocs.config.json#navigation` — there is no navigation API; every action writes back to that file. Right-click a tree node to add pages, groups, anchors, or dropdowns, or to open a per-entry Settings slide-out; available actions depend on the node type. Anchors and dropdowns are root-level only (new ones append to the end of the navigation array); per-tab anchors/dropdowns are configured via repeaters in a tab's Settings. To produce the same result directly, edit `nookdocs.config.json#navigation`. Drag a node onto a sibling to reorder within the same parent; cross-parent moves are JSON-only for now.

## Right-click context menu

Right-clicking any node in the tree opens a context menu. The available actions depend on what you clicked:

### On a tab, group, anchor, or dropdown

- **Add a page** — create a new MDX file in the repo and link it here
- **Add a group** — create a nested group inside the current entry
- **Add an anchor** — append a new [Anchor](/configuration/navigation#anchors-and-dropdowns-phase-3) to the root navigation. The anchor starts as `{ anchor: "New anchor", href: "" }` — click it then right-click → Settings to fill in the label, icon, and href.
- **Add a dropdown** — append a new [Dropdown](/configuration/navigation#anchors-and-dropdowns-phase-3) to the root navigation. Starts as `{ dropdown: "New dropdown", pages: [] }` — configure via Settings.
- **Add existing file** — link an MDX file that already exists in the repo but wasn't in the nav
- **Settings** — open the per-entry settings slide-out (see below)
- **Convert to group / tab** — swap between the two top-level shapes
- **Duplicate** — clone the entry (useful for versioned docs setups)
- **Delete** — remove from navigation (prompts whether to also delete the underlying MDX)

### On a page

- **Settings** — open the page settings slide-out (frontmatter editor)
- **Convert to group** — promote a single page into a group container
- **Duplicate** — clone the MDX file under a new path
- **Delete** — remove the page from both nav and repo

## Settings panel

Right-click → Settings opens a slide-out on the right. Fields depend on the entry type:

### Shared fields (every entry type)

- **Title** — display label (`tab` / `group` / `anchor` / `dropdown` key in config)
- **Icon** — Lucide icon name (searchable picker)
- **Tag** — toggle on, then type the badge text (NEW / BETA / 2.0 — truncates at 8 chars). Off removes the badge.
- **Hidden** — toggle to remove from the sidebar without deleting

### Group-only

- **Root page** — path to the page that loads when the group label is clicked (requires `interaction.drilldown: true` in config)
- **Directory** — auto-render children on the root page as an `accordion` or `card` grid
- **Expanded** — `auto` / `open` / `closed` — overrides the default "expand if contains active page"
- **OpenAPI spec** — per-group override for the API reference generator

### Anchor-only

- **Description** — subtitle shown under the anchor label
- **Link (href)** — external URL; mutually exclusive with children
- **Expanded** — toggle state for anchors that have pages / groups

### Dropdown-only

- **Description** — subtitle shown in the rich dropdown header
- **Expanded** — persists in reader's localStorage once toggled

### Tab-only

- **Icon** — shown left of the tab label
- **Link (href)** — turn the tab into an external link (skips the sidebar)
- **OpenAPI spec** — per-tab override
- **Per-tab anchors** — repeater for anchors scoped to this tab's sidebar. Each row has a label, icon, and optional `href`. Leave `href` empty to create a section header with no target. Anchors that already have nested `pages` / `groups` children (hand-edited in `nookdocs.config.json`) show a hint and their `href` field locks — remove them from the repeater or edit the file directly to change children.
- **Per-tab dropdowns** — repeater for collapsible dropdowns at the top of this tab's sidebar. Each row has a label, icon, and optional description. Existing nested children are preserved across saves; add pages to a dropdown via the tree's right-click → Add a page.

## Drag-to-reorder

Drag a tree node onto a sibling to reorder it. Reordering works **within the same parent** — you can resequence pages inside a group, or groups inside a tab.

<Note>
  Moving an entry **across** parents (e.g. dragging a page from one group into another) isn't supported yet — for cross-parent moves, edit `nookdocs.config.json` directly.
</Note>

## Keyboard

- **Right-click** — context menu (only way to reach anchor/dropdown creation today)
- **Enter** (on a selected page) — opens the MDX in Monaco
- **Esc** — close the Settings panel or context menu

## Working with Phase 3+ entries

Anchors and dropdowns are root-level by design — they always sit above the group list at the top of the sidebar. Creating them from the context menu appends to the end of the navigation array; drag them in JSON if you want a different order.

Per-tab anchors and dropdowns have their own repeaters in a tab's Settings panel — see the [Tab-only](#tab-only) section above. Nested children inside an anchor / dropdown (if you added `pages` or `groups` by hand) survive every dashboard save, so the sub-editor and manual JSON edits coexist cleanly.

---

# Editor overview
Source: https://docs.nookdocs.com/editor/overview

A tour of the web editor — three regions, two sidebar tabs, and the slide-out panel for page or site settings.

The editor is a browser-only dashboard surface for editing MDX in a connected repo; there is no editor API. It has three regions: a left sidebar (a Navigation tab mirroring `nookdocs.config.json#navigation`, and a Files tab showing the raw repo tree), a center Monaco editor, and a context-aware right panel (Page Settings when a page is selected, site-wide Configurations when the toolbar gear is clicked). Save rolls all unsaved MDX, frontmatter, and config changes into one commit signed `nookdocs-bot[bot]`, which the sync pipeline replays to update the live site. The branch selector appears only for self-hosted repos with more than one branch; managed repos are single-branch. Editor permissions derive from the underlying repo's GitHub permissions — there is no separate editor RBAC.

## What the editor does

The in-app editor lets you edit MDX in your connected repo through a familiar Monaco surface (the engine behind VS Code). A sidebar on the left lists your pages and files, and a slide-out panel on the right handles settings — either for the current page or for the whole site.

Save writes a commit to your repo. The webhook replays through our sync pipeline and your site updates within seconds.

## Three regions

<CardGroup cols={3}>
  <Card title="Left sidebar" icon="sidebar">
    Navigation tree (mirrors `nookdocs.config.json#navigation`) and Files tree (raw repo layout). Right-click on any row for actions.
  </Card>
  <Card title="Center — Monaco" icon="code">
    Full Monaco editor with MDX syntax highlighting, multi-cursor, find/replace, and autosave to a draft buffer until you click Save.
  </Card>
  <Card title="Right panel" icon="settings">
    Page Settings for the currently-open page, or Site Configurations for project-wide options. Click outside to dismiss.
  </Card>
</CardGroup>

The dashboard's own sidebar starts collapsed here — the editor already asks for
three columns, and a fourth leaves little room for the document. Expand it with
the toggle and the editor remembers; your dashboard sidebar keeps its own
setting either way.

Right-clicking a row and choosing **Settings** selects that row as well as
opening its panel, so the highlight always matches what the panel is editing.

### Left: Navigation tab vs Files tab

The Navigation tab shows pages grouped exactly the way your site's sidebar renders them — tabs, groups, and pages in the order declared in `nookdocs.config.json#navigation`. Pages referenced in your repo but not in the nav show up under an automatic **Other** group at the bottom.

The Files tab shows the raw repo tree — every file, every folder. Use this when you need to work with files your nav doesn't surface (images under `public/`, templates, snippets).

### Center: Monaco

The Monaco instance is configured for MDX: syntax highlighting for Markdown + JSX, bracket matching, multi-cursor editing (<Kbd>⌘D</Kbd>), and find/replace (<Kbd>⌘F</Kbd>). Unsaved edits live in-memory only until Save fires a commit.

### Right: Page Settings vs Configurations

The right panel is context-aware:

- Click a **page** in the navigation tree → **Page Settings** slides in (frontmatter, icon, tag, hidden, redirects).
- Click the **gear icon** in the top toolbar → **Configurations** slides in (site identity, colors, navbar, footer, AI Assistant, advanced toggles).
- Click outside the panel or hit <Kbd>Esc</Kbd> → panel closes without saving.

## Top toolbar

<Frame caption="The editor toolbar sits above the three regions.">
  Branch selector · Save button (shows pending-change count) · Configurations gear
</Frame>

### Branch selector

Only visible for [self-hosted repos](/github/self-hosted-repo) with more than one branch. Pick the branch you want to edit — the navigation tree, file tree, and editor all re-resolve against that branch. For [managed repos](/github/managed-repo) the selector is hidden (single-branch operation is enforced).

### Save

The Save button counts unsaved changes across all panels — MDX edits, frontmatter updates, and configuration tweaks all roll into one commit. The commit message is auto-generated (`[nookdocs] update <files>`), signed as `nookdocs-bot[bot]`.

### Configurations gear

Toggles the right-side Configurations panel for project-wide settings.

## When the panel changes

| You do | Panel shows |
|---|---|
| Click a page in Navigation or Files | Page Settings for that page |
| Right-click a page → **Settings** | Same as above |
| Click the gear icon in the toolbar | Configurations (site-wide) |
| Click outside the panel | Panel closes, unsaved field values stay in the form |
| Hit <Kbd>Esc</Kbd> | Same as click-outside |

## Permissions inside the editor

<Warning>
  Editor permissions are derived from the GitHub permissions on the underlying repo. We do not have a separate editor-level RBAC.
</Warning>

- **Viewers** (no repo write access) — read-only. Can open any page and see Monaco, but Save is disabled and the context menu's destructive actions (delete, rename, move) are hidden.
- **Editors** (repo write access) — can save directly to branches that are NOT protected. Hitting Save on a protected branch (`main` with branch protection rules) falls through to the PR-creation flow (planned).
- **Owners** (repo admin) — everything editors can do, plus project-level deletion (in Settings, not the editor).

## Where to go next

<CardGroup cols={2}>
  <Card title="Save and publish" href="/editor/save-and-publish" icon="upload">
    How Save turns clicks into commits, and what happens on protected branches.
  </Card>
  <Card title="Navigation tab" href="/editor/navigation-tab" icon="list">
    Build your sidebar by drag-dropping pages and groups.
  </Card>
  <Card title="Configurations panel" href="/editor/configurations-panel" icon="sliders">
    The slide-out for site-wide settings — colors, navbar, AI, and more.
  </Card>
  <Card title="Page settings" href="/editor/page-settings" icon="file-pen">
    Per-page frontmatter without touching raw YAML.
  </Card>
</CardGroup>

---

# Page settings
Source: https://docs.nookdocs.com/editor/page-settings

Per-page frontmatter as a form — title, slug, icon, tags, visibility, layout mode — without touching raw YAML.

Every page's behaviour is controlled by its [frontmatter](/content/frontmatter).
Page settings is that frontmatter as a form: open it on any page in the editor
and each field maps to a frontmatter key, saved back into the page's own
`.mdx` file — so what you set here is exactly what a teammate sees at the top
of the file in Git.

## The fields

| Field | Frontmatter key | What it does |
|---|---|---|
| **Title** | `title` | The page heading, browser tab and search result title |
| **Slug** | — | The page's URL path |
| **External URL** | `href` | Makes the nav entry an outbound link instead of a page |
| **Description** | `description` | Subtitle under the title, meta description, and what search snippets quote |
| **Icon** | `icon` | Sidebar icon — a [Lucide name](/components/icon) like `rocket` |
| **Sidebar title** | `sidebarTitle` | Shorter label for the sidebar when the real title runs long |
| **OG Image URL** | `og:image` | Social-share card image; auto-generated when empty |
| **Tag** | `tag` | Small badge next to the sidebar entry — "New", "Beta" |
| **Hidden** | `hidden` | Keeps the page out of the sidebar while its URL still resolves |
| **Keywords** | `keywords` | Extra search terms the page should match |
| **Mode** | `mode` | [Layout mode](/guides/custom-layouts) — `default`, `center`, `wide`, `custom` |

<Note>
  The form writes ordinary frontmatter, nothing panel-specific. A page
  configured here can be edited as YAML tomorrow — by a person or by an agent
  over [MCP](/integrations/mcp) — and the panel will show whatever the file
  says.
</Note>

## Slug changes are moves

Changing the slug moves the page: the old file is deleted and the content is
committed under the new path — two commits, both visible in your Git history.
Links elsewhere in your docs that
pointed at the old path don't update themselves — add a
[redirect](/content/redirects) for the old URL, and if you author over MCP,
`validate_mdx` will flag any internal link left pointing at the old path.

## Hidden vs private

Two switches, different jobs:

- **Hidden** (`hidden: true`) — out of the sidebar, still reachable by URL and
  still served to search engines and agents. Use for pages you link to
  directly.
- **Private** (`private: true`, set in frontmatter) — access-controlled: gone
  from search, listings, [LLM exports and MCP](/integrations/mcp) alike. Use
  for pages that genuinely aren't public.

---

# Save and publish
Source: https://docs.nookdocs.com/editor/save-and-publish

Saving records a pending change; publishing commits it to Git and updates the live site. What each one does, and what happens when a protected branch says no.

Saving and publishing are two different things.

**Save** records your work as a pending change. Nothing reaches your Git
repository and nothing on your live site moves. You can leave the page, come
back, and the pending version is what you see.

**Publish** commits every pending change on the branch, pushes it, and the
same sync pipeline that handles a `git push` from your terminal takes it from
there. Repo first, always — the file in Git remains the source of truth, and
publishing is how the editor writes to it.

The **Publish** button appears only when something is pending, and it carries
the count: `Publish 3` means three pages are about to go live.

Creating a page, deleting one, renaming one and duplicating one are all
pending changes too — the count covers everything about your content that has
not gone live.

<Note>
  Pending changes are shared with your team, not private to your browser. A
  teammate opening the same project sees them, and either of you can publish
  them.
</Note>

<Warning>
  **Navigation and configuration are the exception.** Reordering the sidebar,
  adding a group, or changing a setting in the Configurations panel commits
  straight away. `nookdocs.config.json` is one shared file rather than one file
  per page, so staging it would mean two people's edits overwriting each other
  at publish time. Content is staged; structure is live.
</Warning>

## What Publish actually does

<Steps>
  <Step title="Each pending change becomes a commit">
    The page's MDX — or `nookdocs.config.json`, if you changed it from the
    Configurations panel — is committed to the repository the project syncs
    from. On a [managed repo](/github/managed-repo) the commit lands in
    `nookdocs-projects/<your-slug>`; on a [self-hosted repo](/github/self-hosted-repo)
    it is written through the NookDocs GitHub App installation, so it shows up
    in your history like any other commit.

    A pending change is cleared only after its own commit lands. If one file
    fails, the rest stay pending rather than being lost, and the editor names
    the ones that did not go through.
  </Step>
  <Step title="The push event comes back to us">
    GitHub notifies NookDocs about the new commit — the same webhook that
    fires when anyone on your team pushes from a terminal. The editor does not
    write to the database directly; it waits for its own commit to round-trip.
  </Step>
  <Step title="Sync runs, the site updates">
    The [sync pipeline](/github/sync-pipeline) re-reads the changed files and
    updates the live site. For a single page this is typically a few
    seconds; you can watch it land under **Deployments**.
  </Step>
</Steps>

<Note>
  Because Publish makes real commits, everything Git gives you applies: each
  change has an author and a timestamp, it shows in `git log` and `git blame`,
  and reverting it is `git revert` — from your terminal or from GitHub's UI.
</Note>

## Where the file goes

The editor writes the page to its path under your content root. A page served
at `/guides/webhooks` becomes `guides/webhooks.mdx` at the repo root by
default, or under the folder named by [`contentRoot`](/configuration/content-root)
when your config sets one. Monorepo base paths are honored the same way.

## Protected branches

Publishing targets the branch your project syncs from, and pending changes
are tracked per branch — work saved on one branch does not appear on another.

If that branch has protection rules that block direct pushes (required pull requests, required
status checks), GitHub rejects the commit and the editor surfaces the error —
NookDocs does not bypass protection and does not open a pull request on your
behalf.

Two ways to work with protection:

- **Sync from an unprotected branch** — point the project at a `docs` branch
  without required reviews and protect `main` as strictly as you like.
- **Allow the app to push** — GitHub branch protection can grant specific
  apps bypass permission if your team prefers reviews for humans only.

## When publishing fails

<AccordionGroup>
  <Accordion title="&quot;Self-hosted project is missing GitHub App installation&quot;">
    The project points at your own repo but the NookDocs GitHub App is no
    longer installed on it — usually after the app was uninstalled or the repo
    was transferred. Reinstall from [GitHub accounts](/github/accounts) and
    publishing works again. Your pending changes are untouched by the failure.
  </Accordion>
  <Accordion title="GitHub App lacks Contents permission">
    The app's installation needs **Repository permissions → Contents: Read and
    write**. If the permission was narrowed after install, GitHub keeps the
    old grant until you re-accept — the error message links the settings page
    where the pending prompt waits.
  </Accordion>
  <Accordion title="The commit landed but the site didn't change">
    The commit and sync both ran, but the file may not be inside the content
    root, or the page isn't listed in `navigation`. Check the deploy log under
    **Deployments** — a sync that found nothing to do says so.
  </Accordion>
</AccordionGroup>

---

# Code Blocks
Source: https://docs.nookdocs.com/features/code-blocks

Syntax highlighting, line numbers, highlighting, focus, word wrap, expandable sections, and copy buttons on every fenced code block.

## What you get for free

Any fenced code block in your MDX gets three things automatically — no imports, no wrapper components, no config.

<CardGroup cols={3}>
  <Card title="Syntax highlighting" icon="palette" href="#theme-integration">
    Theme-aware colors via Prism, scoped to each tenant's `--docs-*` tokens.
  </Card>
  <Card title="Copy button" icon="copy" href="#copy-button-behavior">
    Hover-revealed copy button in the top-end corner. Success state for 1.8 seconds.
  </Card>
  <Card title="Language badge" icon="tag" href="#title-filename">
    Small monospace label in the top-start corner showing the language name.
  </Card>
</CardGroup>

## Writing code blocks

Standard markdown fences with a language tag. The language tag drives both the syntax highlighter and the badge.

````mdx
```typescript
export function greet(name: string): string {
  return `Hello, ${name}!`;
}
```
````

Produces:

```typescript
export function greet(name: string): string {
  return `Hello, ${name}!`;
}
```

## Supported languages

The Prism grammar set is loaded client-side on docs sites. Current set:

<CardGroup cols={3}>
  <Card title="Shell">bash</Card>
  <Card title="Data">json, yaml</Card>
  <Card title="Web">typescript, tsx, jsx, css</Card>
  <Card title="Systems">go, rust, java</Card>
  <Card title="Scripting">python</Card>
  <Card title="Other">sql, markdown</Card>
</CardGroup>

<Tip>
  Need another language? Open an issue on GitHub — Prism has grammars for most popular languages and adding one is a single import line.
</Tip>

## Grouping multiple languages

Use `<CodeGroup>` to show the same code in different languages with tabs. See the [CodeGroup component](/components/code-group) docs.

## Theme integration

Syntax colors are not hard-coded. Prism token classes (`.token.keyword`, `.token.string`, etc.) are mapped to `--docs-*` CSS variables in `prose-docs`, so the highlighting:

- Automatically adapts to the reader's light/dark theme choice
- Uses your tenant primary color for keywords
- Uses your configured success/warning colors for strings and numbers
- Stays subtle (Linear-style muted hues, not a "christmas tree" explosion)

## Line numbers

Add `lines` after the language tag to show line numbers in the gutter.

````mdx Syntax
```typescript lines
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```
````

Result:

```typescript lines
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```

## Highlighting lines

Use `highlight={lines}` to visually emphasize specific lines. Accepts single numbers and ranges.

````mdx Syntax
```typescript highlight={1,4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```
````

Result:

```typescript highlight={1,4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```

Highlighted lines get a tinted background with a left border accent using your theme's primary color.

## Focusing lines

Use `focus={lines}` to draw attention to specific lines while dimming the rest. On hover, dimmed lines become more readable.

````mdx Syntax
```typescript focus={4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```
````

Result:

```typescript focus={4-6}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data } = await supabase.from("pages").select("*");
```

## Word wrapping

Add `wrap` to enable word wrapping for lines that exceed the code block width.

````mdx Syntax
```bash wrap
curl -X POST https://api.example.com/v1/documents/create -H "Authorization: Bearer sk-1234567890abcdef" -H "Content-Type: application/json" -d '{"title": "Getting Started", "content": "This is a very long line."}'
```
````

Result:

```bash wrap
curl -X POST https://api.example.com/v1/documents/create -H "Authorization: Bearer sk-1234567890abcdef" -H "Content-Type: application/json" -d '{"title": "Getting Started", "content": "This is a very long line that would normally overflow the code block horizontally."}'
```

## Expandable code

Add `expandable` to collapse long code blocks (more than 15 lines). A "Show more" button appears at the bottom.

````mdx Syntax
```python expandable
import os
from pathlib import Path

def process(directory):
    results = []
    ...
```
````

Result:

```python expandable
import os
import json
from pathlib import Path

def process_documents(directory: str) -> list[dict]:
    """Walk a directory and process all markdown files."""
    results = []
    base = Path(directory)

    for path in sorted(base.rglob("*.md")):
        with open(path) as f:
            content = f.read()

        meta = extract_frontmatter(content)
        body = strip_frontmatter(content)

        results.append({
            "path": str(path.relative_to(base)),
            "title": meta.get("title", path.stem),
            "content": body,
            "word_count": len(body.split()),
        })

    return results
```

## Combining options

Meta options can be combined freely. The order does not matter.

````mdx Syntax
```typescript lines highlight={3-5}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);
```
````

Result:

```typescript lines highlight={3-5}
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);
```

## Title / filename

Any text in the meta string that is not a recognized option becomes the code block's header title. This is how filenames work.

````mdx Syntax
```typescript src/lib/db.ts
export const db = createClient(url, key);
```
````

Result:

```typescript src/lib/db.ts
export const db = createClient(url, key);
```

## Copy button behavior

The copy button sits in the top-end corner of every code block. It is hidden until the reader hovers over the block (or focuses it via keyboard), then reveals. Clicking copies the raw code (without the language tag or badge) to the system clipboard via the Clipboard API. On success the icon swaps to a checkmark for ~2 seconds.

<Note>
  The button relies on `navigator.clipboard.writeText`, which requires HTTPS or `localhost`. If the Clipboard API is blocked by the browser (very rare), the button silently fails — the code still renders normally.
</Note>

---

# Copy for LLMs
Source: https://docs.nookdocs.com/features/copy-for-llms

One-click copy of any page as LLM-ready context, plus deep links to ChatGPT and Claude.

## The Copy Page dropdown

Every docs page has a **Copy page** split button in the top-end corner of the page header. The primary button copies the raw Markdown; the chevron opens a dropdown with five options.

<Steps>
  <Step title="Copy page as Markdown">
    Plain MDX source. Useful when you want to quote the page verbatim.
  </Step>
  <Step title="Copy as Markdown for LLMs">
    The same source prefixed with a component reference header. Paste this into any LLM and it instantly understands the NookDocs component library — no fine-tuning, no prompt engineering.
  </Step>
  <Step title="Copy page URL">
    The canonical https URL of the page, ready to paste into a chat, PR, or issue tracker.
  </Step>
  <Step title="Open in ChatGPT">
    Deep-links to a new ChatGPT conversation with the page URL and source pre-filled as the first message.
  </Step>
  <Step title="Open in Claude">
    Same idea via `claude.ai/new` — a new Claude conversation with the page context loaded.
  </Step>
</Steps>

## What "for LLMs" actually adds

The **Copy as Markdown for LLMs** option wraps the raw source with a machine-readable header:

```markdown
# Page Title
> Page description

Source: https://docs.nookdocs.com/features/copy-for-llms

This page is written in MDX for the NookDocs documentation platform.
It uses a fixed set of components from the NookDocs component library:

- <Callout type="note|info|tip|warning|danger">
- <Card title icon href> / <CardGroup cols>
- <CodeGroup> with titled code fences
- <Steps> with nested <Step title>
- <Tabs> / <TabsList> / <TabsTrigger> / <TabsContent>
- <Accordion> / <AccordionItem> / <AccordionTrigger> / <AccordionContent>
- <Frame caption> for screenshots
- <ParamField name type required> for API request params
- <ResponseField name type> for API response fields

When editing or extending this page, keep the component API the same
and do not import anything — only these components are allowed.

---

{original source body}
```

## Why this matters

Most docs platforms expect you to author content by hand. NookDocs assumes you will often hand the page off to an LLM — to summarize it, to extend it, to generate a companion page, to translate it, to debug it. That handoff only works if the LLM understands the component language of the target platform.

<Info>
  This is NookDocs' core bet: **the fastest path to great documentation is an LLM that already speaks your docs dialect**. The Copy for LLMs option is the lightweight version of that. The full version ships in Phase 3 as an MCP server, CLI, and published ChatGPT/Claude Projects — but a single copy click with a context-rich header already unblocks the common case.
</Info>

## Example workflow

1. Reader opens `docs.yoursite.com/api/authentication`
2. Clicks the chevron next to "Copy page"
3. Picks **"Copy as Markdown for LLMs"**
4. Pastes into Claude with the prompt *"Extend this page with a section on OAuth flows, using the same component set"*
5. Claude writes new `<Steps>`, `<CodeGroup>`, and `<Callout>` blocks that drop straight back into the MDX file

No system prompt. No fine-tuning. The header is the entire context the LLM needs.

## Coming in Phase 3

The Copy Page dropdown is designed to grow. Phase 3 adds:

- **Install MCP server** — `npx nookdocs-mcp install --client cursor` for deeper LLM integration
- **Connect to Cursor** — one-click MCP server connection in Cursor's IDE
- **Connect to VS Code** — same for VS Code with the Claude Code extension
- **Open in Perplexity** — deep link for research-mode search

The existing five options stay the same — Phase 3 is additive.

---

# Reading Experience
Source: https://docs.nookdocs.com/features/reading-experience

Breadcrumb, Table of Contents, and prev/next navigation come wired in for every docs page.

## What readers get automatically

Every rendered page ships with four reading-experience primitives that the platform wires in from your MDX source and `nookdocs.config.json` — you don't configure them per page.

<CardGroup cols={2}>
  <Card title="Breadcrumb / section eyebrow" icon="chevron-right">
    The parent group (or tab + group, in tabbed mode) renders as a muted link above the h1.
  </Card>
  <Card title="On this page" icon="list">
    Every h2 and h3 in your MDX body appears in a sticky right-column TOC with scroll-spy highlighting.
  </Card>
  <Card title="Prev / next cards" icon="arrow-right">
    Paired navigation cards at the end of each page use the flattened navigation order.
  </Card>
  <Card title="Last updated" icon="clock">
    A subtle timestamp under the footer shows when the page was last synced from your GitHub repo.
  </Card>
</CardGroup>

## Breadcrumb

The breadcrumb reads from the `navigation` field in your `nookdocs.config.json`. The platform walks all groups to find which one contains the current page, then renders:

- **Single item** (flat mode or tabbed mode with one-level nesting): a primary-colored "eyebrow" label above the h1, like `Documentation`
- **Multiple items** (nested groups or explicit tab + group): a classic chevron-separated trail, like `Documentation › Getting Started`

No extra config. If the page is in the `Getting Started` group under the `Documentation` tab, the breadcrumb renders itself.

## Table of Contents

The right-column "On this page" list is generated by parsing your MDX source and extracting every h2 and h3 heading. Clicking a heading scrolls to it; the active heading highlights automatically as the reader scrolls using `IntersectionObserver`.

<Tip>
  h1 is reserved for the page title (from frontmatter). The TOC never includes it. h4 and deeper headings are also skipped to keep the list scannable.
</Tip>

Heading IDs are auto-generated from the text:

```mdx
## API Reference → #api-reference
## Create a project → #create-a-project
```

You can override the slug with `{#custom-id}` syntax if you need stable anchors:

```mdx
## Create a project {#new-project}
```

### Permalinks

Hovering an h2 or h3 reveals a link icon in the margin beside it. Clicking it
copies that section's full URL to the clipboard and updates the address bar, so
readers can share a specific section rather than the whole page.

<Tip>
  Only headings you write as markdown `##` / `###` get an id and appear in the
  TOC. Headings that components render — a `<Card>` title, an `<ApiEndpoint>`
  section label — are part of that component's design, not landmarks in your
  page, so they stay out of both.
</Tip>

A `<Card>` pointing at a section on the same page (`href="#pricing"`) also shows
the permalink icon beside its title, since it names a section the same way a
heading does. Cards linking to another page don't — the whole card is already a
link there.

## Prev / next navigation

Below the last paragraph of every page, readers see two cards linking to the previous and next pages in the flattened navigation sequence.

<Note>
  In tabbed mode, prev/next stay **within the current tab**. The Next button on the last Documentation page does not jump to the first Components page — each tab is a self-contained reading sequence.
</Note>

## Last updated

The timestamp is read from the `pages.updated_at` column, which is set every time the Trigger.dev sync job writes the page. In practice, this is the timestamp of the most recent `git push` that touched the file.

## Writing for the reading experience

The primitives above just work, but a few authoring habits make them work *better*:

1. **Lead with an h2.** The first paragraph of your body is not an h1 — that is the `title` in frontmatter. The body should start with a section heading so the TOC has entries from the first scroll.
2. **Keep h2 and h3 scannable.** Think of them as the table of contents entries, because they are.
3. **Name your navigation groups like human sections.** "Getting Started" works; "gs-v2-final" does not — the group name becomes the breadcrumb.
4. **Order your nav entries thoughtfully.** Prev/next walks the list in order, so bad ordering becomes bad reading flow.

---

# Search
Source: https://docs.nookdocs.com/features/search

Full-text search across your docs site with a keyboard-first modal.

## How it works

Search runs directly against Postgres — there is no external Algolia or Meilisearch instance to manage, and no indexing step after deploy. Every time a page is synced from your GitHub repo, a stored `tsvector` column is regenerated automatically with weighted content:

| Weight | Field | Description |
|--------|-------|-------------|
| **A** (highest) | `frontmatter.title` | Matches against the page title rank first |
| **B** | `frontmatter.description` | Near-first hit boost for description matches |
| **C** | URL path | Keyword-in-URL matches |
| **D** (lowest) | page body | Full-text fallback |

When a reader submits a query, the platform calls `websearch_to_tsquery` — the same query parser Postgres uses for Google-style searches. That means your users can write:

```
"custom domain"          exact phrase
authentication OR oauth  either term
components -accordion    exclude a term
```

## Keyboard shortcuts

<CardGroup cols={2}>
  <Card title="Open search" icon="search">
    **⌘K** on macOS, **Ctrl+K** on Windows/Linux, or `/` from any page
  </Card>
  <Card title="Navigate" icon="arrow-down">
    **↑** and **↓** to move through results
  </Card>
  <Card title="Open result" icon="arrow-right">
    **↵** Enter to navigate to the highlighted result
  </Card>
  <Card title="Close" icon="x">
    **Esc** to dismiss the modal and return to the page
  </Card>
</CardGroup>

## Result ranking

Results are ordered by `ts_rank`, which scores matches based on frequency, term weight, and proximity. Short snippets with `<mark>` highlighting appear under each result so readers can confirm relevance before clicking.

<Tip>
  If a reader searches for a term and gets zero results, that usually signals a content gap. In Phase 7 you will see these queries in your analytics dashboard — a great input for the next pages to write.
</Tip>

## What to write for better search

The weighted ranking rewards well-structured pages. You don't need to do anything special — just follow good documentation habits:

1. **Write a clear `title`** in frontmatter. It carries the highest rank weight.
2. **Add a `description`** of 1–2 sentences explaining the page. Boosts near-first hits.
3. **Use descriptive URL paths**. `/configuration/custom-domain` ranks better than `/config/cd`.
4. **Lead with the keyword.** The first 200 characters matter most for snippet extraction.

## Semantic search (coming in Phase 5)

Keyword search is Phase 1. In Phase 5 the same modal will gain a sparkle toggle for **AI mode** — hybrid keyword + vector search powered by `pgvector` embeddings and reciprocal rank fusion. Readers will be able to ask natural-language questions and get results that match intent, not just keywords.

<Note>
  No action needed on your side. When Phase 5 ships, your existing docs will be embedded automatically and the AI toggle appears in the modal. Your ⌘K habits transfer 1:1.
</Note>

---

# Theme Toggle
Source: https://docs.nookdocs.com/features/theme-toggle

Visitors choose between light, dark, and system themes — persisted per docs site.

## How it works

The toggle lives in the top-right of the navbar (and next to the hamburger menu on mobile). Clicking it cycles through:

<Steps>
  <Step title="Light">
    Forces the light palette regardless of OS preference.
  </Step>
  <Step title="Dark">
    Forces the dark palette.
  </Step>
  <Step title="System">
    Follows the visitor's `prefers-color-scheme` setting and updates live if they switch their OS theme.
  </Step>
</Steps>

## Persistence per site

The visitor's choice is saved in `localStorage` scoped to the current hostname. That means:

- A visitor's preference on `docs.stripe-like-company.com` does not bleed into `docs.other-customer.com` — each tenant has its own isolated preference.
- Same user visiting the NookDocs dashboard at `app.nookdocs.com` has a separate preference there (the dashboard uses its own token namespace `data-app-theme`).

## Default theme

Set the first-paint default in your [`nookdocs.config.json`](/configuration/config-file):

```json
{
  "appearance": {
    "default": "dark"
  }
}
```

Valid values: `"light"`, `"dark"`, `"system"` (default).

The configured default is what new visitors see on their very first page load, before they touch the toggle. Once they pick, their choice persists across visits via `localStorage`.

## Custom colors per theme

Both themes share the same design tokens but resolve to different values. You can override them in your config:

```json
{
  "colors": {
    "primary": "#3B82F6"
  }
}
```

Primary color applies to both light and dark variants. In Phase 2 you will be able to specify separate light/dark values for every token (primary, accent, background, border) directly from the dashboard theme editor.

<Note>
  The toggle never overrides your brand colors — it only switches the background and foreground palette. Your primary/accent colors stay consistent.
</Note>

---

# GitHub accounts
Source: https://docs.nookdocs.com/github/accounts

How NookDocs connects to GitHub — account authorization, the App installation, and per-project repo connections — and how to manage them from Settings → Integrations.

NookDocs talks to GitHub through **two account-level grants** plus a
**per-project repo connection**. Understanding the three layers makes
connecting, disconnecting, and troubleshooting predictable.

  Adding, managing, and removing a GitHub account are browser-only actions performed under Settings → Integrations — there is no NookDocs API endpoint for them. The OAuth authorization and the GitHub App installation both live at the account level (user or org); only the repo binding is per-project. Removing an account uninstalls the App, which disconnects every project on that account and purges their synced docs, but never modifies repos on GitHub. GitHub-side changes (uninstall, repo removal, rename, reinstall) are reconciled automatically via webhooks — the dashboard does not need manual repair.

## The three layers

<CardGroup cols={3}>
  <Card title="Authorization (OAuth)" icon="key">
    Identifies *you* and lets NookDocs act on your behalf — create repos,
    add/remove repos from the App. Account-wide, granted once. Not per-repo.
  </Card>
  <Card title="App installation" icon="plug">
    Grants the NookDocs GitHub App access to specific repos on an account.
    **One installation per account, shared by every project** on that account.
    Not per-project.
  </Card>
  <Card title="Project connection" icon="git-branch">
    The only per-project piece: which **repo** (and branch, and monorepo
    subfolder) a project syncs from. The installation is resolved from the repo.
  </Card>
</CardGroup>

<Note>
  Both the authorization and the installation live at the **account** level
  (your personal account or an org). Two projects can connect different repos
  on the same account and share one installation. The *project* only ever owns
  a repo binding.
</Note>

## Settings → Integrations

The **Integrations** tab in your global Settings lists every GitHub account
you've connected:

| Column | Meaning |
|---|---|
| Account | The GitHub user or org the App is installed on |
| Type | `User` or `Org` |
| Authorized | Whether we hold a valid OAuth token (lets us create repos / manage access on your behalf) |
| Projects | How many of your projects sync from this account |

## Disconnect a project vs. remove an account

Two different scopes — pick the one that matches your intent:

<CardGroup cols={2}>
  <Card title="Disconnect one project" icon="unlink">
    **Settings → Git → Disconnect** on a project. Unlinks just that repo and
    removes its synced docs. The App stays installed for your other projects.
  </Card>
  <Card title="Remove the whole account" icon="trash">
    **Settings → Integrations → Remove**. Uninstalls the App from the account,
    disconnecting **every** project on it at once.
  </Card>
</CardGroup>

## What happens automatically

NookDocs reconciles GitHub-side changes via webhooks — you don't have to keep
the dashboard in sync by hand:

- **Uninstall the App** (on GitHub) → every project on it is disconnected and
  purged.
- **Remove a repo** from the App's access → projects bound to that repo are
  disconnected and purged.
- **Delete or rename a repo** → bound projects are updated/cleaned accordingly.
- **Reinstall the App** → a reinstall mints a new installation id; NookDocs
  resolves the live installation per repo, so connections keep working without
  manual repair.

<Warning>
  Removing an account or uninstalling the App removes our **access** and our
  **synced copy** of the docs — never anything in your repository. Reconnect
  any time to pull everything back in.
</Warning>

## Next

<CardGroup cols={2}>
  <Card title="Self-hosted repo" href="/github/self-hosted-repo" icon="github">
    Connect your own repo, pick a branch, and disconnect when needed.
  </Card>
  <Card title="Monorepo" href="/deploy/monorepo" icon="folder-tree">
    Point a project at a docs subfolder of a larger repo.
  </Card>
</CardGroup>

---

# Managed repo
Source: https://docs.nookdocs.com/github/managed-repo

Zero-Git onboarding — we create the repo, install the GitHub App, and seed it with a starter template. You just write.

A managed repo is chosen during project creation by picking "Let NookDocs host the repo for you" — a browser action, with no API to provision one. NookDocs creates a private repo at `github.com/nookdocs-projects/<your-slug>`, seeds it with a flat starter (`nookdocs.config.json`, `introduction.mdx`, `quickstart.mdx`, `logo/light.svg`, `logo/dark.svg` — content at the base, no `docs/` subfolder), and syncs it to a live site. You can still clone, branch, and PR via local Git; the editor enforces single-branch `main`. Two reversible migrations exist, both via Settings → Git: "Migrate to your GitHub" moves to a self-hosted repo you own (the managed repo is archived, not deleted), and the self-hosted "Host on NookDocs" button brings a project back onto managed hosting.

## What you get

When you pick **"Let NookDocs host the repo for you"** during project creation, we provision a private GitHub repo on your behalf and connect it to your project in a single click. No Git, no SSH keys, no GitHub App install dance.

<CardGroup cols={3}>
  <Card title="Zero Git knowledge" icon="sparkles">
    The editor commits feel like a CMS. You never see a branch, a merge, or a rebase unless you want to.
  </Card>
  <Card title="Pre-installed app" icon="plug">
    Our GitHub App is already on the hosting org, so sync works the instant the repo exists — no OAuth page, no permission review.
  </Card>
  <Card title="Seeded starter" icon="rocket">
    The new repo ships with `nookdocs.config.json`, a working navigation, and a welcome page — all flat at the base. You're viewing rendered docs within 10 seconds of project creation.
  </Card>
</CardGroup>

## How it works

1. On **project create**, we provision a private repo at `github.com/nookdocs-projects/<your-slug>`.
2. We seed it with (a flat layout — content sits at the base, no `docs/` subfolder):
   - `nookdocs.config.json` — starter config that matches the project name + theme you picked.
   - `introduction.mdx` — a welcome page.
   - `quickstart.mdx` — a starter quickstart.
   - `logo/light.svg` + `logo/dark.svg` — placeholder logos.
3. We install our GitHub App (it's already on the `nookdocs-projects` org, so this is a no-op under the hood).
4. A webhook fires, the sync pipeline runs, and `<your-slug>.nookdocs.site` goes live.

<Frame caption="End-to-end project creation to live site typically takes 10–30 seconds.">
  New project → managed repo → webhook → sync pipeline → live site
</Frame>

## What you can still do

Managed doesn't mean locked. You have the same Git superpowers a self-hosted repo gives you — you just don't *need* them.

- **Clone locally** — `git clone git@github.com:nookdocs-projects/<your-slug>.git`. Edit, commit, push. The sync pipeline runs the same way.
- **Open pull requests** — commit to a branch, open a PR, merge when ready. The editor's branch selector stays single-branch by default, but local Git works fully.
- **Add collaborators** — we mirror your NookDocs org members to the managed repo automatically. Adding a teammate in Settings → Members grants them repo access.

## Limitations

<Warning>
  You don't own the repo — we do. If that's a blocker, use a [self-hosted repo](/github/self-hosted-repo) instead.
</Warning>

- **Repo ownership**: the repo lives under `nookdocs-projects`, not your GitHub org. For most customers this is invisible, but if your company requires docs repos under your own org, self-host.
- **No third-party GitHub Apps** — we don't let other apps install on the managed org. If you rely on a CI check or Linear/Slack integration that runs via GitHub App, you'll need self-hosted.
- **Deletion is permanent** — when you delete a project, we delete the repo and its history. Export first if you want a copy.

## Migrating off

You're not locked in. In **Settings → Git**, the managed repository card has a **Migrate to your GitHub** button that moves the project to a repo you own — instantly, no support ticket and no waiting.

<Note>
  Changed your mind later? You can come back the other way — **Host on NookDocs** on a self-hosted project's Git settings brings it back onto managed hosting. See [self-hosted repo → Switch to managed hosting](/github/self-hosted-repo#switch-to-managed-hosting).
</Note>

## Branch creation

The editor's branch selector is hidden for managed repos — we enforce single-branch (`main`) operation to keep the Zero-Git promise honest. If you need branches, either:

- Use Git locally (`git checkout -b feature/xyz; git push`), then open a PR.
- [Migrate to your own repo](#migrating-off), where the editor exposes full branch support.

## Deletion

Deleting a project deletes its managed repo. We prompt you twice — once to confirm the project delete, once to confirm the repo delete — and require you to type the project slug to proceed. There's no undo.

## Next

<CardGroup cols={2}>
  <Card title="Self-hosted repo" href="/github/self-hosted-repo" icon="github">
    For teams that want repo ownership in their own GitHub org.
  </Card>
  <Card title="Editor overview" href="/editor/overview" icon="edit">
    How to actually use the editor you just connected.
  </Card>
</CardGroup>

---

# Self-hosted repo
Source: https://docs.nookdocs.com/github/self-hosted-repo

Connect your own GitHub repo — install the GitHub App, pick a branch, and start shipping.

Connecting a self-hosted repo is a one-time browser action started from Projects → New ("Connect your own GitHub repo"), which lands on the project's connect page — there is no API endpoint for it. It authorizes the NookDocs GitHub App on the chosen account/repos (narrow, selected-repos install is recommended over "All repositories"), then you select a repository; selecting one reveals its options, including a monorepo toggle that takes the docs folder path. Add `nookdocs.config.json` at that docs base (repo root, or the monorepo subfolder). After that, every `git push` deploys automatically. Editor saves commit as `nookdocs-bot[bot]`, touch only files under `docs/`/`nookdocs.config.json`, and never modify code, CI, or package files (enforced server-side). Disconnecting (Settings → Git → Disconnect) revokes this repo from the App, stops syncing, and purges the synced copy, but never modifies your repo; it requires a "selected repositories" install — under "All repositories" you remove the repo yourself on GitHub.

## When to choose self-hosted

<CardGroup cols={3}>
  <Card title="You already have a repo" icon="copy">
    Existing docs repo, existing collaborators, existing CI — self-hosted keeps all of that.
  </Card>
  <Card title="Full ownership" icon="shield-check">
    Repo lives in your GitHub org. You own everything — history, branches, protection rules, and the ability to leave us without a data export.
  </Card>
  <Card title="Monorepo" icon="folder-tree">
    Docs live under `apps/docs/` or similar alongside code. Self-hosted lets you configure a subpath root.
  </Card>
</CardGroup>

If none of those apply, [managed repos](/github/managed-repo) save you the GitHub App install and a few minutes of config.

## Setup

<Steps>
  <Step title="Choose your own repo in Projects → New">
    Pick **"Connect your own GitHub repo"** on the new-project screen. Creating the project takes you straight to the repo picker.
  </Step>
  <Step title="Install the NookDocs GitHub App">
    Pick the organization (or your personal account) and the specific repositories you want to expose. **Narrow selection is strongly recommended** — install on just the docs repo, not "All repositories."
  </Step>
  <Step title="Pick the repo">
    Select an account, then a repository from the list. Selecting one reveals the rest of the options — including **Set up as monorepo**, which asks for the folder your docs live in (`docs`, `apps/docs`) and limits everything we read to that path. An empty repo is also offered the starter template.

    The branch is the repository's default. Change it later in Settings → Git if your team publishes from `staging` or a docs-specific branch.
  </Step>
  <Step title="Add `nookdocs.config.json` to the docs base directory">
    Create a minimal config at the docs base (the repo root for a single repo, or your monorepo subfolder):

    ```json
    {
      "$schema": "https://nookdocs.com/schema.json",
      "name": "Your Project",
      "navigation": [
        {
          "group": "Get started",
          "pages": ["introduction", "quickstart"]
        }
      ]
    }
    ```
  </Step>
  <Step title="Add your content files">
    By default content sits **flat** at the docs base, next to the config. Add two `.mdx` files matching the nav entries above (set `contentRoot` if you'd rather nest them in a subfolder):

    ```mdx introduction.mdx
    ---
    title: Introduction
    description: Welcome to our documentation.
    ---

    Hello world.
    ```
  </Step>
  <Step title="Push and watch it deploy">
    `git push`. The webhook fires, sync runs, your site goes live at `<slug>.nookdocs.site` within seconds.
  </Step>
</Steps>

## Resyncing everything

Each push syncs only the files that push changed, which keeps deploys fast. If
your site looks out of date — say a setting was wrong while you were pushing, so
those changes never landed — a later push won't fix it on its own: it only
carries its own files, and the untouched ones stay as they were.

**Settings → Git → Resync all pages** re-reads every page from the repo and
rewrites them. Your repo is the source of truth, so nothing is lost; anything
saved in the editor but never committed is replaced by the committed version.

## Recommended folder layout

Content sits flat at the docs base by default — no `docs/` wrapper:

```
your-repo/                   # the docs base (repo root, or a monorepo subfolder)
├── nookdocs.config.json     # required, at the docs base
├── introduction.mdx
├── quickstart.mdx
├── guides/
│   ├── authentication.mdx
│   └── webhooks.mdx
├── api/
│   └── overview.mdx
├── logo/                    # referenced from config.colors.logo
│   ├── light.svg
│   └── dark.svg
├── images/                  # inline in MDX as ![alt](/images/foo.png)
│   └── architecture.png
├── openapi.json             # optional, referenced from config.api.openapi
└── .nookignore              # optional, files to exclude from sync
```

Prefer to nest your content in a subfolder? Set `contentRoot: "docs/"` in `nookdocs.config.json`. See [Content root](/configuration/content-root).

## Branch strategy

Most teams run a single branch (`main`) and treat every commit as a deploy. A few patterns for larger teams:

<AccordionGroup>
  <Accordion title="Single branch, PR-based review">
    Team opens PRs against `main`. Merges deploy instantly. Simplest and recommended for docs-only repos.
  </Accordion>

  <Accordion title="Staging branch + separate NookDocs project">
    Create a second NookDocs project pointing at the `staging` branch of the same repo, with a subdomain like `docs-staging`. Merges from `staging` → `main` promote to production. Per-branch preview deployments ship in a future release.
  </Accordion>

  <Accordion title="Protected main">
    Branch protection on `main` is fully supported. The editor's Save button falls through to a PR-creation flow (planned) when the selected branch is protected. Until PR-creation ships, configure the editor's branch selector to point at an unprotected development branch.
  </Accordion>
</AccordionGroup>

## What we write to your repo

Every editor save lands as a Git commit signed as `nookdocs-bot[bot]`. Commit messages follow a predictable format so `git log` stays readable:

```text
[nookdocs] update docs/guides/authentication.mdx
[nookdocs] rename docs/old-name.mdx → docs/new-name.mdx
[nookdocs] delete docs/deprecated.mdx
[nookdocs] update nookdocs.config.json
```

All commits touch files under `docs/` or `nookdocs.config.json` by default. Nothing else.

## What we never write

<Warning>
  We never modify code, CI configs, or infrastructure files. These rules are enforced server-side, not just a policy.
</Warning>

- **Code directories**: `src/`, `app/`, `packages/`, `lib/`, `apps/` (except the configured docs subpath in monorepos) — untouched.
- **CI configs**: `.github/`, `.gitlab-ci.yml`, `Dockerfile`, `.circleci/` — untouched.
- **Node / package files**: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` — untouched.
- **Files matching `.nookignore`**: see [.nookignore reference](/configuration/content-root).

If the editor would need to touch something in this list (e.g., your docs are inside a monorepo path you haven't declared), Save fails loudly rather than silently committing.

## Switch to managed hosting

Changed your mind? You can move a self-hosted project onto [NookDocs managed hosting](/github/managed-repo) at any time — the reverse of the managed → self-hosted migration.

In **Settings → Git**, the connected repository card has a **Host on NookDocs** button. It:

<Note>
  After switching, edits sync from NookDocs rather than your repo. You can move back to your own repo anytime via **Migrate to your GitHub** on the managed repository card — see [managed repos → Migrating off](/github/managed-repo#migrating-off).
</Note>

## Disconnecting a repository

In **Settings → Git**, the connected repository card has a **Disconnect** button. Disconnecting:

- **Removes the repo from our GitHub access** — we revoke this repo from the NookDocs App installation, so we genuinely lose access to it (not just a setting on our side). GitHub then notifies us via webhook to finish the cleanup.
- **Stops syncing** — pushes to the repo no longer trigger deploys.
- **Removes the docs we pulled from it** — the pages, file tree, parsed OpenAPI specs, and AI search index we synced are deleted, so your site stops serving content from a repo you've unlinked.
- **Leaves your repo untouched** — we only drop our *access* and our *synced copy*. Your code, history, and files on GitHub are never modified. Reconnect any time to pull everything back in fresh.
- **Keeps the project** — its name, subdomain, theme, custom domains, and analytics history all stay. Only the repo link and synced content are cleared.

<Note>
  Revoking access automatically needs the GitHub authorization you granted at connect time and only works when the App was installed on **selected repositories**. If the App is installed on **all repositories**, GitHub can't remove a single repo via API — we unlink and purge on our side, and you remove the repo (or the whole App) yourself under **GitHub → Settings → Applications**. We tell you when this is the case.
</Note>

<Note>
  The same cleanup runs automatically if you uninstall the App, remove this repo from the App's access list on GitHub, or delete the repo: we detect it via webhook, unlink the project, and purge the synced docs. We never keep serving content — or holding access to — a repo you've disconnected.
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Install the GitHub App" href="/github/accounts" icon="plug">
    Full walkthrough of the App install + permission scopes.
  </Card>
  <Card title="Monorepo support" href="/deploy/monorepo" icon="folder-tree">
    Hosting docs in a subpath of a larger repo.
  </Card>
  <Card title="Sync pipeline" href="/github/sync-pipeline" icon="refresh-cw">
    What happens between `git push` and your site going live.
  </Card>
  <Card title=".nookignore" href="/configuration/content-root" icon="file-x">
    Exclude files from sync — READMEs, drafts, internal notes.
  </Card>
</CardGroup>

---

# Sync pipeline
Source: https://docs.nookdocs.com/github/sync-pipeline

What happens between git push and your site going live — step by step, including incremental syncs, .nookignore, and how to read a deploy that did nothing.

Every deploy starts the same way: a push lands on the branch your project
syncs from, GitHub notifies NookDocs, and a sync run works through the commit.
This page walks the run in order — useful when a deploy didn't do what you
expected and you want to know which step decided that.

## The steps, in order

<Steps>
  <Step title="A deployment opens">
    The push event creates a deployment record — that's the "building" row you
    see under **Deployments**, tied to the commit SHA it is processing.
  </Step>
  <Step title="Find the config">
    The sync lists the repository tree and locates `nookdocs.config.json`. In
    a monorepo the folder containing the config becomes the base — everything
    else resolves relative to it, which is how
    [subtree setups](/deploy/monorepo) work without extra configuration.
  </Step>
  <Step title="Config first, content second">
    The config is fetched, [validated](/configuration/config-file) and stored
    before any page is read — it decides the
    [`contentRoot`](/configuration/content-root) the rest of the run filters
    by. Validation never rejects a deploy: errors and ignored-key warnings go
    to the deploy log, and the site keeps serving the last good config for
    anything broken.
  </Step>
  <Step title="Apply .nookignore">
    Patterns in a [`.nookignore`](/configuration/content-root) file exclude
    matching paths from sync — gitignore syntax, relative to the base.
  </Step>
  <Step title="Filter to content">
    Only Markdown/MDX inside the content root becomes pages. Repo noise —
    `README.md` at the root, `AGENTS.md`, planning folders — never turns into
    a docs page by accident.
  </Step>
  <Step title="Incremental or full">
    A normal push syncs **only the files that changed in it** — added and
    modified pages are re-fetched, removed pages are deleted, everything else
    is untouched. The first sync of a project, and a manual **Resync**, scan
    everything.
  </Step>
  <Step title="Pages upsert">
    Each changed file's frontmatter is parsed and the page row updated — this
    is the moment a page's `Updated` date changes, search indexes the new
    text, and the URL starts serving the new content.
  </Step>
  <Step title="OpenAPI, when it changed">
    If the config names an [`api.openapi`](/configuration/api) spec and this
    push touched it, the spec is re-fetched and re-parsed — that's what feeds
    the generated API reference and the playground. Untouched specs are left
    alone.
  </Step>
  <Step title="The deployment closes">
    The record flips to ready with counts of what happened. The log keeps the
    per-file detail.
  </Step>
</Steps>

## Reading a surprising deploy

<AccordionGroup>
  <Accordion title="Deploy succeeded but the page didn't change">
    The file probably isn't inside the content root, or matched a
    `.nookignore` pattern — the deploy log lists every file the run
    considered. If the page synced but isn't in the sidebar, it's missing
    from `navigation`.
  </Accordion>
  <Accordion title="A full scan found zero files">
    That's reported as an error rather than an empty site — it almost always
    means `contentRoot` points at a folder that doesn't exist at the base.
    The log names the prefix it searched.
  </Accordion>
  <Accordion title="Config errors in the log, site still up">
    By design: a config that fails validation is logged, not applied
    destructively. Fix the reported keys and push again — or catch it before
    pushing with [`validate_config` over MCP](/integrations/mcp).
  </Accordion>
</AccordionGroup>

<Note>
  The pipeline is the same for [managed](/github/managed-repo) and
  [self-hosted](/github/self-hosted-repo) repos, and the same whether the
  commit came from `git push`, the [editor's Save](/editor/save-and-publish),
  or an agent. One write path, one set of rules.
</Note>

---

# Guides
Source: https://docs.nookdocs.com/guides

Principles, frameworks, and workflows for writing docs that humans read AND AI agents consume. Not the feature reference — the thinking behind it.

The rest of the NookDocs docs describe **how** features work. This section describes **why** you'd author content a particular way and **what** patterns tend to win. Think of it as the opinion that backs the tools.

## The LLM-first bet

Every guide here is written under one assumption: **docs are read by humans AND by AI agents, and those two audiences share most of the page but disagree on edges**. Humans want UI cues and reassurance; agents want component spec links and canonical URLs. NookDocs ships the [Visibility component](/llm-first/human-vs-agent) so you can target both from one MDX source — but that's the mechanism. The guides here cover the editorial strategy.

## Writing

<CardGroup cols={2}>
  <Card title="Writing for LLMs" icon="bot" href="/guides/writing-for-llms">
    Our unique angle. How LLMs actually read docs — skim patterns, chunk boundaries, token economics, citation mechanics — and how to author pages that degrade well under agent consumption.
  </Card>
  <Card title="GEO — AI search optimization" icon="sparkles" href="/guides/geo">
    Generative Engine Optimization. ChatGPT, Perplexity, Gemini, Google AI Overviews. What ranks in the answer box. Why it's different from classic SEO. Seven GEO patterns that work.
  </Card>
  <Card title="Style and tone" icon="pen-line" href="/guides/style-and-tone">
    Second person, active voice, heading intent, the technical-writing fundamentals that still rank in 2026. The Microsoft / Google style guides distilled to one page.
  </Card>
  <Card title="Content types" icon="layers" href="/guides/content-types">
    The Diátaxis framework — tutorials vs how-to guides vs reference vs explanation. Why most docs fail by mixing types, and how to split when you catch yourself mixing.
  </Card>
  <Card title="Understand your audience" icon="users" href="/guides/understand-your-audience">
    Three human personas (evaluators / implementers / operators) plus the fourth, LLM agents. How to find out who actually reads your docs, what they're trying to do, and how to ship content that matches.
  </Card>
</CardGroup>

## Publishing

<CardGroup cols={2}>
  <Card title="SEO for docs" icon="search" href="/guides/seo">
    On-page SEO playbook for technical documentation — title + meta + headings + links + sitemap + schema.org. The reliable foundation, sibling to the GEO guide.
  </Card>
  <Card title="Accessibility" icon="accessibility" href="/guides/accessibility">
    WCAG 2.2 AA patterns specific to docs — keyboard nav, screen readers, colour contrast, alt text, focus management. Cheap on day one, expensive to retrofit.
  </Card>
  <Card title="Media" icon="image" href="/guides/media">
    Screenshots, diagrams, videos, embeds — what to capture, how to annotate, how to size, how to write alt text that serves both humans and LLMs.
  </Card>
  <Card title="Linking" icon="link" href="/guides/linking">
    Internal clusters build authority. Descriptive anchor text. Orphan audits. External link hygiene. The linking playbook.
  </Card>
  <Card title="Navigation IA" icon="map" href="/guides/navigation">
    Information architecture principles behind the sidebar — group granularity, tab vs group choice, nested subgroups, drill-down vs expand-all. The *thinking* behind the config reference.
  </Card>
</CardGroup>

## Maintaining

<CardGroup cols={2}>
  <Card title="Improving docs" icon="trending-up" href="/guides/improving-docs">
    Metrics-driven iteration. Five specific signals (zero-result searches, bounce rate, support ticket URLs, thumbs-down comments, time-to-first-success), a weekly review rhythm, quarterly audits, what NOT to measure.
  </Card>
  <Card title="Maintenance" icon="wrench" href="/guides/maintenance">
    Keeping docs fresh as the product ships. What rots + how fast, five staleness signals, quarterly freshness audit, screenshot discipline, deprecation process, retirement decision tree.
  </Card>
  <Card title="Migration playbooks" icon="arrow-right-left" href="/guides/migration-playbooks">
    Moving docs from Mintlify / ReadMe / GitBook / Docusaurus to NookDocs. Three-phase strategy, redirect maps, Search Console continuity, rollback plans, complete cutover checklist.
  </Card>
</CardGroup>

## AI tools

Rules files + prompt patterns for the three agent surfaces docs writers use most.

<CardGroup cols={3}>
  <Card title="Claude Code" icon="terminal" href="/guides/claude-code">
    Anthropic's CLI agent. AGENTS.md template + prompt patterns for audit-and-rewrite, scaffold-from-sibling, long-session hygiene.
  </Card>
  <Card title="Cursor" icon="mouse-pointer-click" href="/guides/cursor">
    VS Code fork. `.cursor/rules/` template + tab-complete + Cmd+K + Composer patterns for NookDocs MDX.
  </Card>
  <Card title="Windsurf" icon="wind" href="/guides/windsurf">
    Cascade-driven multi-file editor. `.windsurf/rules/` template. GUI-first, good for non-dev writers.
  </Card>
</CardGroup>

## Use cases

Larger playbooks for specific docs-site shapes.

<CardGroup cols={2}>
  <Card title="Developer documentation" icon="code" href="/guides/developer-documentation">
    End-to-end recipe for API + SDK + CLI docs. The seven sections every dev docs site needs, page budget per section, day-1 + first-quarter + second-quarter work plans.
  </Card>
  <Card title="Help center" icon="life-buoy" href="/guides/help-center">
    Support-style docs for end-users. Voice tuning for non-technical readers, FAQ patterns, troubleshooting trees, ticket-deflection loops.
  </Card>
  <Card title="Knowledge base" icon="book-marked" href="/guides/knowledge-base">
    Internal-only docs for your own team. Runbooks, ADRs, postmortems, onboarding flows. Separate tenant vs unified tenant architectures.
  </Card>
  <Card title="Internationalization" icon="languages" href="/guides/internationalization">
    Multi-language docs without burning the translation budget. Priority order, RTL considerations, professional vs hybrid vs machine translation, honest cost breakdown.
  </Card>
  <Card title="Headless + custom frontend" icon="layout-template" href="/guides/custom-frontend">
    When to render docs outside the default shell — in-product panels, mobile apps, marketing sites. API surface, SSR vs client-only, migration-back patterns.
  </Card>
</CardGroup>

## Advanced

Niche guides for teams that have outgrown the defaults.

<CardGroup cols={2}>
  <Card title="Git concepts for writers" icon="git-branch" href="/guides/git-concepts">
    Minimum viable Git for non-dev writers. Commits, branches, PRs, merge conflicts — no terminal jargon, just the mental model.
  </Card>
  <Card title="Branches for docs workflows" icon="git-branch-plus" href="/guides/branches">
    When to branch vs commit-to-main, naming conventions, reviewer patterns, merge strategies, PR template. Lighter discipline than engineering branching.
  </Card>
  <Card title="Configure automerge" icon="git-merge" href="/guides/configure-automerge">
    Safe auto-merge setup for docs PRs. GitHub's auto-merge + required CI + CODEOWNERS. Reduce review friction on low-risk changes.
  </Card>
  <Card title="Migrating from custom MDX" icon="package-2" href="/guides/migrating-from-mdx">
    You already use MDX — Next.js, Astro, Docusaurus, Contentlayer, hand-rolled. The path to NookDocs without losing content, URLs, or tooling you like.
  </Card>
  <Card title="Custom page layouts" icon="layout-dashboard" href="/guides/custom-layouts">
    `mode: center / wide / custom` for per-page layout variation. Narrow narratives, wide reference tables, custom-mode landing pages. Lighter touch than headless.
  </Card>
</CardGroup>

## Roadmap

Additional per-source migration guides (Docusaurus, GitBook, ReadMe, MkDocs) + team-scaling playbooks (growing a docs team from one writer to five, organisational governance at 1000+ pages) ship in subsequent waves.

## How to use this section

<Steps>
  <Step title="Skim the titles">
    Each guide declares a specific angle. If the title doesn't match a question you've asked recently, skip.
  </Step>
  <Step title="Read start-to-finish">
    These aren't reference docs — pages are narrative. Jumping to the middle loses the framing.
  </Step>
  <Step title="Link back, not forward">
    Every guide ends with cross-links to the feature pages it justifies. Use the guides as the "why" and the feature pages as the "how."
  </Step>
</Steps>

## Contributing a guide

See something missing? Open an issue at [github.com/Codivion/NookDocs/issues](https://github.com/Codivion/NookDocs/issues) with a title + outline. The best guides come from real experience — if you've written docs for 5+ years, we want your opinion.

## Related

- [Human vs agent content](/llm-first/human-vs-agent) — the canonical reference for the dual-audience model these guides assume
- [Component library](/components/callout) — the primitives the guides reference
- [Schema reference](/configuration/schema-reference) — configuration surface
- [Changelog](/changelog) — what shipped recently on the platform itself

---

# Accessibility
Source: https://docs.nookdocs.com/guides/accessibility

WCAG for docs — keyboard navigation, screen readers, colour contrast, alt text, focus management. The accessibility patterns that make docs usable for everyone AND easier for LLMs to parse.

Docs are the part of your product most likely to be read by someone who can't see the screen, can't use a mouse, or has a cognitive load budget you don't know about. WCAG 2.2 AA is the baseline every docs site should clear. Most of it is cheap to get right on day one and expensive to retrofit later.

This guide covers the accessibility patterns specific to docs. For the WCAG 2.2 AA full reference, see [the W3C spec](https://www.w3.org/TR/WCAG22/).

## The big four

<CardGroup cols={2}>
  <Card title="Keyboard navigation" icon="keyboard">
    Every interactive thing reachable + operable with Tab / Shift+Tab / Enter / Space. No keyboard trap. Focus outline always visible.
  </Card>
  <Card title="Screen reader compatibility" icon="ear">
    Structured headings, descriptive link text, alt text on images, ARIA labels on icon-only buttons. The page makes sense narrated aloud.
  </Card>
  <Card title="Colour + contrast" icon="palette">
    4.5:1 contrast for body text, 3:1 for large text + UI. Never rely on colour alone to convey meaning (icons + text labels).
  </Card>
  <Card title="Reading order + language" icon="list-ordered">
    DOM order matches visual order. `<html lang="en">` set. Plain language, expanded acronyms on first use, no jargon without definition.
  </Card>
</CardGroup>

## What NookDocs ships accessibility-wise

Out-of-the-box behaviours every tenant gets:

- **Skip-to-main-content link** at the top of every page. Hidden until focused; press Tab once to jump past the nav.
- **Semantic HTML** — `<main>`, `<nav>`, `<article>`, `<header>`, `<footer>` wherever appropriate. Screen readers use these as landmarks.
- **Focus outlines** always visible (CSS `outline` not overridden to `none`).
- **`<html lang="...">`** from the tenant's [language config](/content/localization) or default `en`.
- **Theme tokens for contrast** — every theme's light + dark palette hits WCAG AA minimum on body text.
- **Descriptive page titles** — `<title>` per page so screen-reader users hear where they are.

What's on you as the author:

- Writing alt text for images you add.
- Keeping heading hierarchy clean (see [style and tone](/guides/style-and-tone)).
- Not overriding link colours to match paragraph colour.
- Not inventing custom interactive components that lack keyboard handlers.

## Keyboard navigation

Every interactive element must be reachable with the keyboard:

<Steps>
  <Step title="Tab order follows visual order">
    DOM order = visual order = keyboard order. If a sidebar visually comes before the main content, it should come first in the DOM. NookDocs layouts enforce this.
  </Step>
  <Step title="Every interactive element has a visible focus indicator">
    A blue outline, a background shift, a ring — whatever your theme uses, it must be visible against both light and dark backgrounds. Don't `outline: none` without replacing with `:focus-visible { box-shadow: ... }`.
  </Step>
  <Step title="Enter and Space activate buttons">
    `<button>` elements handle both natively. Custom components built with `<div onClick>` don't — avoid them, or add `onKeyDown` + `role="button"` + `tabindex="0"`.
  </Step>
  <Step title="Escape closes overlays">
    Search modal, contextual menu, mobile drawer — all dismissable with Escape. NookDocs's built-in components already handle this.
  </Step>
</Steps>

Test: unplug your mouse, navigate every page by keyboard. If you can't reach something, can't see where focus is, or get stuck — fix it.

## Screen reader compatibility

Screen readers (VoiceOver, JAWS, NVDA) narrate the page aloud. They rely on structure, not visuals.

### Headings as landmarks

Screen reader users navigate by heading — press `H` in JAWS/NVDA to jump heading by heading. Clean hierarchy matters more than for sighted readers:

- One `H1` per page (the page title).
- Don't skip levels (no `H4` directly after `H1`).
- Use headings for structural sections, not for visual sizing.

### Alt text for images

Every `<Frame>` / `<Image>` needs an `alt` attribute. Rules:

- **Describe the content relevant to the surrounding text.** For a screenshot of a dashboard showing analytics: `alt="Analytics dashboard showing 1200 daily page views and a search bar at the top"`.
- **Decorative images get `alt=""`** (empty, not missing). Screen readers skip over them.
- **Don't repeat surrounding text.** If the caption says "Analytics dashboard with page views", the alt text can be shorter: `alt="Dashboard UI"`.
- **Avoid "image of" / "picture of"** — the screen reader already announces "image".

```mdx
<Frame caption="The Custom Domains panel after adding docs.acme.com">
  ![Dashboard panel listing docs.acme.com as verified with a green check](/images/custom-domain-verified.png)
</Frame>
```

### Descriptive link text

Screen reader users pull up a list of all links with `Insert+F7`. If every link says "click here" or "read more", the list is useless.

```markdown
❌ To add a custom domain, [click here](/deploy/custom-domain).
✅ Add a custom domain in the [deploy guide](/deploy/custom-domain).
✅ For DNS record specifics, see [custom domain setup](/deploy/custom-domain).
```

### ARIA labels on icon-only buttons

Buttons that render only an icon (no text) need `aria-label`:

```mdx
<button aria-label="Close search">
  <XIcon />
</button>
```

NookDocs's built-in interactive components handle this — the danger is when you build custom widgets. Always add an aria-label if there's no visible text.

### Code blocks

Fenced code blocks render with `role="region"` and `aria-label="Code example"` (implicit from the `<pre><code>` elements). Screen readers announce the language when the fence has one: `​```bash` announces "bash code example".

Multi-block `<CodeGroup>` tabs have proper ARIA — screen reader users hear "tab 1 of 3, cURL" and can arrow between tabs.

## Colour + contrast

### Text contrast thresholds

WCAG 2.2 AA minimums:

| Text size | Minimum contrast |
|---|---|
| Body text (< 18pt) | **4.5:1** against background |
| Large text (≥ 18pt or ≥ 14pt bold) | **3:1** |
| UI components (buttons, focus outline, borders of interactive things) | **3:1** |

Tools:

- Browser DevTools → Inspect an element → "Contrast" in the Colours panel. Works in Chrome + Firefox + Safari.
- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) — paste hex values.
- [Stark](https://www.getstark.co) — Figma / browser plugin, real-time checks.

Every NookDocs theme ships palettes that meet WCAG AA on `--docs-fg` against `--docs-bg`. When overriding via `colors.primary` / `background.*`, test the combination before shipping.

### Never rely on colour alone

Red/green distinctions fail for ~8% of men. Always pair colour with an icon or label:

```mdx
❌ Colour-only
<Badge variant="success">Active</Badge>
<Badge variant="danger">Failed</Badge>

✅ Colour + icon
<Badge variant="success"><CheckIcon /> Active</Badge>
<Badge variant="danger"><XIcon /> Failed</Badge>
```

The text label alone usually suffices; icons reinforce for scanning.

### Dark mode

Auto-adaptive by default via `prefers-color-scheme`. Manual toggle via the theme button in the header. The `<Visibility>` component's agent/human split doesn't interact with dark mode — both variants render through both palettes.

Don't override `--docs-fg-dark` / `--docs-fg-muted-dark` without re-testing contrast.

## Reading order + language

### Reading order

DOM order = what screen readers narrate. If your CSS re-orders elements visually (flexbox `order`, grid areas, absolute positioning), screen reader users hear the original DOM order, not the visual one.

NookDocs layouts keep DOM == visual. When writing MDX, structure top-to-bottom in the order you want it read.

### Language attribute

`<html lang="en">` set on every page automatically from tenant [language config](/content/localization). Multi-language tenants use the language's slug. Critical for:

- Screen reader pronunciation (reads English text with English phonemes)
- Automatic translation tools
- Search engine indexing

If a specific word or phrase is in a different language, wrap it:

```mdx
The Japanese word <span lang="ja">ドキュメント</span> means "document".
```

### Plain language

Technical writing can be precise without being jargon-dense. Every acronym defined on first use. Every domain-specific term linked to a glossary entry or explained in-line.

Flesch-Kincaid reading-ease score of 60+ is a good target for docs — roughly 8th-grade reading level. Tools:

- [Hemingway Editor](https://hemingwayapp.com) — pasteable
- VS Code extension `tammersaleh.write-good` — inline
- Your LLM of choice — "score this passage for reading ease"

## Motion + animation

WCAG 2.3 AAA: respect `prefers-reduced-motion`. Users with vestibular disorders can literally be nauseated by decorative parallax.

NookDocs's built-in components honour the preference — Framer Motion animations respect `prefers-reduced-motion: reduce`. When adding custom motion:

```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

Good default: turn motion OFF when the user asks, turn it on when they don't.

## Forms + inputs

(Less relevant for docs, but feedback widgets + search inputs apply.)

- Every `<input>` has a `<label for="...">` or `aria-label`.
- Required fields marked with `aria-required="true"` + visible indicator (asterisk, the word "required").
- Error messages have `role="alert"` or `aria-live="polite"` so screen readers announce them.
- Don't validate on every keystroke — only on blur or submit. Frustrating announcements.

## Testing protocol

Weekly, on a representative page:

<Steps>
  <Step title="Lighthouse accessibility audit">
    Chrome DevTools → Lighthouse → Accessibility category. Target: 95+. Covers 30-40% of WCAG via automated checks.
  </Step>
  <Step title="Keyboard-only navigation">
    Unplug your mouse. Navigate the page. Can you reach every link, button, toggle? Is focus always visible?
  </Step>
  <Step title="Screen reader spot-check">
    macOS: Cmd+F5 to enable VoiceOver, read the page. Windows: NVDA (free) or JAWS. Listen for 2 minutes. Does the page make sense narrated?
  </Step>
  <Step title="Contrast check">
    DevTools → Inspect any text → Contrast ratio. Target: 4.5:1 body, 3:1 UI.
  </Step>
  <Step title="prefers-reduced-motion">
    macOS: System Preferences → Accessibility → Display → Reduce motion. Visit the page. Animations should be ~0ms.
  </Step>
</Steps>

## Common accessibility mistakes

<AccordionGroup>
  <Accordion title="Missing alt text on screenshots">
    The most common miss. Writers paste screenshots without alt. Agents can't see the image either — so accessibility + LLM-readiness have the same fix.
  </Accordion>
  <Accordion title="Outline: none without :focus-visible replacement">
    Designer removes the default browser outline because it clashes with the visual. Keyboard users now can't tell where they are. Either keep the default or replace with `:focus-visible` styles.
  </Accordion>
  <Accordion title="Placeholder text as label">
    `<input placeholder="Search...">` without a `<label>`. Placeholder disappears on focus; screen readers announce placeholder inconsistently. Always use a label.
  </Accordion>
  <Accordion title="Colour-only error states">
    Red border on invalid field. Users with red-green colour blindness see no difference. Add an error icon + message text.
  </Accordion>
  <Accordion title="Skip link that doesn't work">
    The "skip to main content" link is there but anchors to an ID that doesn't exist. Test by pressing Tab on page load + pressing Enter.
  </Accordion>
  <Accordion title="ARIA abuse">
    `role="button"` on `<div>`s when `<button>` would just work. `aria-label` that contradicts the visible text. `aria-hidden="true"` on interactive elements. If the native element works, use it. ARIA is a last resort.
  </Accordion>
</AccordionGroup>

## Related

- [Style and tone](/guides/style-and-tone) — plain language conventions, foundations
- [Media guide](/guides/media) — alt text patterns + image-specific a11y
- [WCAG 2.2 AA reference](https://www.w3.org/TR/WCAG22/) — the standard itself
- [WebAIM](https://webaim.org) — practical accessibility resources + testing tools
- [SEO for docs](/guides/seo) — sibling guide covering on-page signals

---

# Branches for docs workflows
Source: https://docs.nookdocs.com/guides/branches

When to branch vs commit-to-main, how to name branches, reviewer patterns, merge strategies. The branching conventions that actually fit how docs teams work.

Most engineering branching strategies (Gitflow, GitHub Flow, Trunk-Based) were designed for code that breaks the build if you merge it half-done. Docs rarely do that — a half-written page is still a page, just an incomplete one. That means docs teams can use a lighter branching model than code teams.

This guide covers the branching conventions that actually fit docs work.

## The simplest model — direct to main

For most docs commits, there's no reason to branch. Typo fixes, broken-link fixes, adding a paragraph, updating a link — all go straight to `main` via the dashboard editor or a direct commit.

```text
main ─┬─── small edit ─┬─── typo fix ─┬─── paragraph add ─┬─── (live)
      │               │              │                   │
      └── every commit deploys within 30-60s
```

**Use direct-to-main when:**
- The change is under 20 minutes of work.
- You're confident the change is correct.
- No coordination with teammates needed.
- The page isn't load-bearing for a launch or compliance moment.

This covers ~80% of docs commits for most teams.

## When to branch

Branch when:

<CardGroup cols={2}>
  <Card title="Multi-day rewrites" icon="clock">
    Rewriting a 1000-word concept page across three days. Users shouldn't see the half-done state. Branch + merge when complete.
  </Card>
  <Card title="Coordinated with a product launch" icon="rocket">
    Docs for a feature shipping next Tuesday. Page must be live at the launch hour, not before. Work on a branch; merge at launch time.
  </Card>
  <Card title="Needs review before going live" icon="eye">
    Legal disclaimer wording. Security disclosure. Pricing page. Anything where wrong wording is worse than no wording. Branch + PR review.
  </Card>
  <Card title="Experimental restructuring" icon="shuffle">
    Testing a new IA: moving 20 pages into a different section. If it doesn't work, you want to throw it away cleanly. Branch makes abandoning easy.
  </Card>
</CardGroup>

## Branch naming

Simple patterns that scale:

| Prefix | Use for | Example |
|---|---|---|
| `docs/<topic>` | Most docs work | `docs/webhook-guide`, `docs/rewrite-concepts` |
| `feature/<name>` | Docs for a new product feature | `feature/team-invites-docs` |
| `fix/<issue>` | Fixing a specific bug or broken content | `fix/custom-domain-caa-record` |
| `launch/<name>` | Launch-coordinated content | `launch/q2-pricing-update` |
| `experiment/<topic>` | Throwaway experiments | `experiment/tutorial-split-test` |

Keep names short (under 40 chars), hyphenated, descriptive. `docs/webhooks` beats `updating-the-webhook-documentation-page-with-new-fields`.

## Who commits to what

A convention that scales past 5 people:

- **Writers** branch for anything over 20 minutes. Commit directly for small fixes.
- **Engineers** branch whenever they touch docs as part of a code change — the same PR that ships the feature ships its doc.
- **Contractors / external reviewers** always branch. Gives the internal team a chance to review before going live.

For a 2-3 person team, these distinctions often collapse — everyone branches for medium changes, everyone ships small ones direct.

## Merge strategies

GitHub offers three merge button options. Docs teams usually want:

| Strategy | What it does | When to use |
|---|---|---|
| **Squash and merge** | Combines all your branch commits into one on `main` | Default for most docs PRs. Keeps `main` history clean. |
| **Rebase and merge** | Replays your commits onto `main` as-is | When your commits tell a useful story each on their own (rare for docs). |
| **Create a merge commit** | Explicit merge commit showing the branch joined | Large feature branches with extensive history worth preserving. |

**Recommended default:** Squash and merge. For docs, the commit history matters less than for code; a clean `main` history is easier to read.

## Reviewer patterns

Docs PRs are lighter to review than code PRs. Reviewer focus:

<Steps>
  <Step title="Does it match the house style?">
    Voice, tone, heading format, component usage. See [style and tone](/guides/style-and-tone).
  </Step>
  <Step title="Does it render cleanly?">
    Preview the branch in the dashboard (if supported) or pull down locally. MDX parse errors should be caught by CI but eyeball for visual issues.
  </Step>
  <Step title="Are claims accurate?">
    Does the feature actually work the way the page describes? For reference docs, verify against code. For tutorials, run the tutorial end-to-end.
  </Step>
  <Step title="Cross-links present?">
    Every new page should link to + from 3-5 related pages. See [linking](/guides/linking).
  </Step>
  <Step title="Nav updated?">
    New pages need to be added to `nookdocs.config.json#navigation` to appear in the sidebar.
  </Step>
</Steps>

Target review time: 10-20 minutes for a single-page change. If review is taking longer than that, the PR is too big — ask the author to split.

## PR template for docs changes

GitHub supports `.github/PULL_REQUEST_TEMPLATE.md`. For docs repos:

```markdown .github/PULL_REQUEST_TEMPLATE.md
## Summary

(What does this PR change?)

## Motivation

(Why? Related ticket or feature launch?)

## Checklist

- [ ] Page parses cleanly (no MDX errors)
- [ ] Added to `nookdocs.config.json#navigation` if new
- [ ] Cross-linked to + from 3-5 related pages
- [ ] Frontmatter has title + description + icon
- [ ] Follows house style (voice, headings, ParamField usage)
- [ ] If a screenshot changed: alt text updated
- [ ] If documenting a breaking change: changelog entry added

## Screenshots

(If visual changes — before/after)
```

Triggers the right review discipline without slowing anyone down.

## Protection rules

For teams where docs quality matters enough to enforce mechanically, configure GitHub branch protection on `main`:

<CardGroup cols={2}>
  <Card title="Require PR reviews" icon="user-check">
    "Require approvals: 1" means every change needs a second pair of eyes. Overkill for small teams; mandatory for teams over ~10 people.
  </Card>
  <Card title="Require status checks" icon="check-circle">
    MDX parse check + check-sync + build must pass before merge. Catches errors the reviewer missed.
  </Card>
  <Card title="Require branches to be up-to-date" icon="arrow-up">
    Prevents "my branch is 3 weeks behind main" merges. Forces pulling in latest changes first.
  </Card>
  <Card title="Restrict who can push to main" icon="lock">
    Prevents accidental force-pushes or direct commits that skip review. Keep a small admin list.
  </Card>
</CardGroup>

For 1-2 person teams: skip protection rules. Friction outweighs benefits.

## Branch lifetime

Short branches reduce merge pain:

- **Hours-to-days** — most docs branches.
- **Up to 1 week** — bigger rewrites. Pull from `main` daily to stay current.
- **Over 1 week** — probably scope bloat. Ship in pieces rather than batching.

Branches that live 3+ weeks accumulate enough drift from `main` that merging becomes a multi-conflict archaeology project. Prevention beats cure.

## Draft PRs

GitHub's "Draft PR" feature lets you open a PR that explicitly ISN'T ready for review. Useful for:

- **Long in-progress work** where you want CI to run continuously.
- **Soliciting early feedback** on structure before investing in polish.
- **Coordinating with an engineer** on a page + code change happening in parallel.

Open as draft, work, convert to "Ready for review" when done. Reviewers know not to spend review cycles on a draft.

## Common branch-workflow mistakes

<AccordionGroup>
  <Accordion title="Branching for every tiny change">
    "Let me fix this typo" → branch, commit, PR, review, merge, delete branch = 10 minutes for a 30-second fix. Direct-to-main for small changes.
  </Accordion>
  <Accordion title="Long-running 'docs overhaul' branches">
    Two months of rewriting. Branch is now 3000 commits behind main. Merge is hell. Ship in pieces weekly; rebase onto main before each push.
  </Accordion>
  <Accordion title="Forgetting to update nav in the PR">
    New page written + merged. Nav config still points at the old structure. Page exists but nobody can find it. PR template checklist catches this.
  </Accordion>
  <Accordion title="Not deleting merged branches">
    After 6 months of PR merges, your branch list is 200 stale entries. Enable GitHub's "Automatically delete head branches" setting in repo settings.
  </Accordion>
  <Accordion title="Branch names that don't explain the change">
    `docs/update`, `docs/fix`, `docs/changes`. A year later nobody knows what was in that branch. Descriptive names survive org churn.
  </Accordion>
</AccordionGroup>

## Related

- [Git concepts](/guides/git-concepts) — prerequisite primer
- [Configure automerge](/guides/configure-automerge) — automate the merge step for low-risk PRs
- [Maintenance](/guides/maintenance) — how branch discipline feeds into freshness audits
- [Style and tone](/guides/style-and-tone) — the reviewer's checklist

---

# Writing docs with Claude Code
Source: https://docs.nookdocs.com/guides/claude-code

Paste-ready AGENTS.md + prompt patterns that turn Claude Code (Anthropic's CLI agent) into a NookDocs-fluent writing partner. Edit MDX, scaffold new pages, audit for drift — without re-teaching the component library every session.

[Claude Code](https://claude.com/claude-code) is Anthropic's CLI agent — runs in your terminal, reads + edits files in your repo, understands long-form project context. It's a natural fit for docs work because docs are text-heavy, MDX is structured enough that an agent can reason about it, and every edit is a diff the writer can review before committing.

This page gives you a paste-ready `AGENTS.md` + prompt patterns that turn Claude Code into a NookDocs-fluent writing partner. Same bet as NookDocs's core thesis: **LLMs get good at docs when you teach them the component language once, not every session**.

## Install + first run

```bash
# Install
npm install -g @anthropic-ai/claude-code

# First run (from your docs repo root)
cd ~/projects/acme-docs
claude

# Claude Code reads AGENTS.md if present + uses it as system context
```

Claude Code auto-discovers `AGENTS.md` / `CLAUDE.md` in the project root. That file becomes the implicit system prompt for every session. Which means: put the NookDocs component rules there, and you never re-paste them.

## The AGENTS.md template

Drop this at the root of your docs repo. Claude Code picks it up automatically.

````markdown AGENTS.md for NookDocs repos
# Project context

This is a NookDocs-based documentation repo. Pages are MDX files
under `docs/`. The config lives at `nookdocs.config.json` (schema:
https://nookdocs.com/schema.json).

## Component library (ALWAYS use, NEVER import)

NookDocs provides a fixed set of components available in every MDX
file. Don't `import` them — they're globally resolved by the
renderer. The full machine-readable spec is at:

  https://nookdocs.com/nookdocs-components.llm.md

Cheat sheet (use these verbatim, don't invent new components):

- Text + structure: `<Callout type="note|info|tip|warning|danger">`,
  `<Note>`, `<Tip>`, `<Warning>`, `<Info>`, `<Danger>`, `<Check>`
- Cards + grids: `<Card title icon href>`, `<CardGroup cols>`,
  `<Tile>`, `<Tiles cols>`, `<HeroCard>`, `<LinkCard>`
- Code: `<CodeGroup>` (wraps multiple fenced code blocks),
  `<CodeBlock>`, `<RequestExample>`, `<ResponseExample>`,
  `<TerminalBlock>`
- Tabs + accordions: `<Tabs>` + `<TabsList>` + `<TabsTrigger>` +
  `<TabsContent>`, `<Accordion>` + `<AccordionGroup>` +
  `<AccordionItem>`
- Steps: `<Steps>` + `<Step title="...">`
- Media: `<Frame caption="...">` (wrap images), `<Image>`, `<Video>`,
  `<Embed>`, `<Mermaid>`
- API fields: `<ParamField path="..." type="..." required default="">`,
  `<ResponseField name="..." type="...">`, `<ApiMethod>`
- Misc: `<Badge>`, `<Banner>`, `<Pill>`, `<Tag>`, `<Kbd>`, `<Icon>`,
  `<Snippet>`, `<Update>`, `<Tooltip>`, `<View>`, `<Visibility>`

## Authoring rules

- Second person, active voice, imperative for instructions.
- Every page has `title` + `description` + `icon` in frontmatter.
- One H1 per page (from the frontmatter title — don't write `# ` in
  the body).
- Use `<ParamField>` for config keys + API request params — always
  with `type` + `required` when applicable + `default` when a default
  exists.
- Code examples in fenced blocks with a language: `​```typescript`,
  `​```bash`, `​```json`, etc.
- Multi-language examples go in `<CodeGroup>`.
- Verb-first H2 headings for how-to sections ("Configure X", not
  "Configuration of X").
- Never write decorative introductions ("In this guide we will...").
  Lead with the answer.
- Cross-link to related pages at the bottom of every page in a
  `## Related` section.

## Audience split (for LLM-friendly content)

Use `<Visibility for="humans">` to wrap UI references, screenshots,
reassurance paragraphs — content that serves browser readers only.

Use `<Visibility for="agents">` to wrap meta-instructions, canonical
URL hints, forbidden-pattern callouts — content for LLMs reading the
page via `/<slug>.md` or `/llms-full.txt`.

## Verification commands

After editing any MDX file:

```bash
# Parse-check (prevents MDX syntax errors on deploy)
node --input-type=module -e "
  import { mdxParse } from 'safe-mdx/parse';
  import { readFileSync } from 'fs';
  mdxParse(readFileSync('docs/PATH.mdx','utf-8'));
" && echo 'parse OK'

# Cross-layer drift (if editing nookdocs.config.json schema keys)
npm run check:sync

# TypeScript
npx tsc --noEmit
```

## When asked to add a new page

1. Pick a path under `docs/` that matches an existing nav section
   (see `nookdocs.config.json#navigation`).
2. Write the MDX file with frontmatter (`title`, `description`,
   `icon`).
3. Add the page to `nookdocs.config.json#navigation` in the right group.
4. Run the parse check.
5. Run `npm run check:sync` if the page documents a config schema key.

## When asked to rewrite a page

1. Read the page in full before editing.
2. Preserve URL-stable section anchors (don't rename H2s that other
   pages link to unless given permission).
3. Apply the authoring rules above.
4. Run the parse check on the result.
````

Commit this as `AGENTS.md` at the repo root. Next Claude Code session uses it automatically — no re-paste, no reminder prompts.

## Prompt patterns that work

Two patterns produce consistently good output with Claude Code once the AGENTS.md is in place.

### Pattern 1: "Audit this page against the guides"

```text
Read docs/guides/style-and-tone.mdx and docs/guides/writing-for-llms.mdx
as reference. Then audit docs/features/search.mdx against those guidelines.
Give me a bulleted list of specific problems — line numbers + what to fix
— not abstract critique.
```

Produces targeted rewrites. Claude reads the rubric, then the target, returns a changelog not a rewrite. Review + selectively apply.

### Pattern 2: "Scaffold a new page like an existing sibling"

```text
Add a new page docs/configuration/webhooks.mdx. Use docs/configuration/
feedback.mdx as the structural template — same frontmatter shape, same
section order, same ParamField usage. Content covers the webhook
delivery configuration: retry policy, signature verification, payload
schema. Commit it + add to nookdocs.config.json nav under Configuration.
```

Gives Claude a known-good shape to imitate. Results land closer to your house style than a cold-start prompt.

### Pattern 3: "Migrate from my current platform"

When your docs come from another tool, tell Claude what the source is — it can detect and convert the structure.

```text
This repo is a Mintlify docs site (docs.json + .mdx files). Convert it to
NookDocs: run `npx nookdocs migrate . -o ../nookdocs-out`, then move the
output into this repo. Resolve the migrate report's "Manual review needed"
items, and make sure every page is wired into the navigation array.
```

For a source the CLI doesn't convert yet (Docusaurus, GitBook, hand-rolled), Claude can do it by hand — and it can read the source platform's own machine-readable index to learn the page tree:

```text
These are Docusaurus docs (docusaurus.config.js + docs/**). There's no CLI
converter yet, so convert by hand into the flat NookDocs layout: one .mdx per
page at the repo root, map sidebars.js into the navigation array, rewrite
:::note / :::tip admonitions to <Note> / <Tip>, and move static/ to public/.
If the old site is live, read its /llms.txt to confirm the full page list.
```

The key instruction: **NookDocs content is flat at the repo root** (`contentRoot: "/"`), most Mintlify/MDX components keep the same tag name (only `<Latex>`→`<Math>` and `<Tree>`→`<FileTree>` are renamed), and **no page ships without a `navigation` entry**. See [Migrating from Mintlify](/cli/migrate-from-mintlify) and [Migration playbooks](/guides/migration-playbooks).

## Workflow — docs as pair programming

<Steps>
  <Step title="Branch">
    `git checkout -b docs/webhooks`. Keep Claude's edits on a branch until you've reviewed.
  </Step>
  <Step title="State the outcome">
    "I need a webhooks config page that covers delivery, retry, and signature verification. Target ~200 lines. Use ParamField for every config key + include one complete JSON example."
  </Step>
  <Step title="Let Claude draft">
    Claude proposes the file + nav edit + any schema changes. Review the diff.
  </Step>
  <Step title="Iterate on specifics">
    "The retry section is too long — condense the backoff table into one paragraph plus the table. Remove the 'Why webhooks?' introduction — straight into the config."
  </Step>
  <Step title="Verify">
    `npm run check:sync`, parse-check, `tsc --noEmit`. If any fail, Claude fixes then re-runs.
  </Step>
  <Step title="Commit + PR">
    Claude can compose the commit message. Review before pushing.
  </Step>
</Steps>

## Managing long sessions

Claude Code's context window is large (200K+ tokens) but finite. For long docs sessions:

- **Work one page at a time.** Don't ask Claude to "rewrite the entire section" — rewrite page by page so context stays focused.
- **Reference shared context by URL.** Instead of pasting the component spec into the prompt, reference the URL: `See https://nookdocs.com/nookdocs-components.llm.md for the component list`. Claude Code fetches when needed.
- **Use `/clear` between unrelated pages.** Starts a fresh session with just the AGENTS.md context. Prevents cross-contamination between tasks.

## What Claude Code does well

- **Precise MDX edits** — targeted changes to specific lines without disturbing surrounding content.
- **Frontmatter + nav sync** — updating `nookdocs.config.json` to match a new page location.
- **Cross-page consistency** — "check if all Configuration pages have the same section order" works reliably.
- **Running verification commands** — parse check + tsc + check-sync orchestration.
- **Commit message composition** — follows the project's commit style once it's seen 10+ past commits.

## What Claude Code doesn't do well (yet)

- **Screenshot + visual design decisions** — can't see the rendered output. Keep Claude away from "does this look good" questions; show the rendered page yourself.
- **Performance optimisation** — bundle size, Core Web Vitals. Not its wheelhouse.
- **Inventing product features** — if you ask Claude to document a feature that doesn't exist in the codebase, it'll invent plausible-looking nonsense. Verify every claim maps to real shipped behaviour.
- **Long-form tutorials from scratch** — better at editing than at first-draft 1000-word tutorials. Draft yourself; have Claude polish.

## Related

- [Writing for LLMs](/guides/writing-for-llms) — the broader theory
- [Cursor](/guides/cursor) — sibling guide for Cursor-based workflow
- [Windsurf](/guides/windsurf) — sibling guide for Windsurf
- [Component spec](/llm-first/component-spec) — machine-readable component reference
- [Schema reference](/configuration/schema-reference) — the `nookdocs.config.json` field reference
- [Human vs agent content](/llm-first/human-vs-agent) — the `<Visibility>` audience-split story

---

# Configure automerge
Source: https://docs.nookdocs.com/guides/configure-automerge

Safe, opinionated automerge setup for docs PRs — GitHub's auto-merge plus a minimum CI gate that catches bad MDX without blocking typo fixes. Reduce review friction on the 80% of changes that don't need human eyes.

Most docs PRs are low-risk: typo fixes, broken-link updates, minor additions. Requiring human review on every one creates friction — a writer opens a PR at 4pm, the reviewer isn't online until the next morning, the typo stays live for 18 hours. GitHub's `auto-merge` feature lets you flip this: the PR merges automatically once required CI checks pass, without waiting for an approving human.

This guide covers the safe defaults for docs-repo auto-merge.

## When auto-merge makes sense

<CardGroup cols={2}>
  <Card title="Typo + broken-link fixes" icon="check">
    Low-risk by definition. CI catches MDX parse errors. Reviewer adds no value vs 18h delay.
  </Card>
  <Card title="Generated content updates" icon="refresh-cw">
    Auto-generated files (schema-reference, integration pages, llms.txt). CI catches schema drift. Human review is rubber-stamping.
  </Card>
  <Card title="Dependabot bumps" icon="arrow-up-circle">
    Small dependency updates. CI catches regressions. Patch + minor version bumps auto-merge; major bumps go through review.
  </Card>
  <Card title="Low-churn reference docs" icon="book">
    A contributor fixes a value in a table. The table was auto-gen'd from code. No structural change. Safe auto-merge candidate.
  </Card>
</CardGroup>

## When NOT to auto-merge

<CardGroup cols={2}>
  <Card title="New pages" icon="file-plus">
    Structural change. Every new page should get a human look — voice, IA placement, cross-links all need judgement.
  </Card>
  <Card title="Rewrites of existing pages" icon="edit">
    Major revisions change the meaning. Need a second pair of eyes to verify accuracy.
  </Card>
  <Card title="Legal / security / billing content" icon="shield">
    Wrong wording here is expensive. Always human review.
  </Card>
  <Card title="Config schema changes" icon="settings">
    `public/schema.json` changes affect every tenant. Review carefully.
  </Card>
</CardGroup>

## The safe baseline setup

Three layers:

1. **GitHub's native auto-merge** — opt-in per PR. Requires all checks + reviews (if configured).
2. **Required CI checks** — catch mechanical failures before merge.
3. **CODEOWNERS** — high-sensitivity paths still require human review even with auto-merge.

## Step 1: enable auto-merge on the repo

GitHub repo settings → General → scroll to "Pull Requests" → check "Allow auto-merge".

Now PRs can opt in individually by clicking "Enable auto-merge" on the PR page.

## Step 2: required CI checks

In `.github/workflows/docs-ci.yml` (or equivalent), run checks that catch the classes of errors that shouldn't reach `main`:

```yaml .github/workflows/docs-ci.yml
name: Docs CI

on:
  pull_request:
    paths:
      - "docs/**"
      - "nookdocs.config.json"
      - "public/schema.json"
      - "src/components/docs/**"

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci

      # Parse every MDX file — catches syntax errors before deploy
      - name: MDX parse check
        run: |
          node --input-type=module -e "
            import { mdxParse } from 'safe-mdx/parse';
            import { readFileSync, readdirSync, statSync } from 'fs';
            import { join } from 'path';
            function walk(dir) {
              const out = [];
              for (const f of readdirSync(dir)) {
                const p = join(dir, f);
                if (statSync(p).isDirectory()) out.push(...walk(p));
                else if (p.endsWith('.mdx')) out.push(p);
              }
              return out;
            }
            let errors = 0;
            for (const f of walk('docs')) {
              try { mdxParse(readFileSync(f, 'utf-8')); }
              catch(e) { errors++; console.log(\`❌ \${f}:\${e.line}: \${e.message}\`); }
            }
            if (errors) process.exit(1);
            console.log('All MDX files parsed cleanly.');
          "

      # Cross-layer drift (types + validator + renderer + docs + UI)
      - name: Sync check
        run: npm run check:sync

      # TypeScript
      - name: Type check
        run: npx tsc --noEmit

      # JSON validity
      - name: Config JSON valid
        run: node -e "JSON.parse(require('fs').readFileSync('nookdocs.config.json','utf-8'))"

      # Broken links (internal + external)
      - name: Link check
        run: npx lychee --include-file-extensions=mdx docs/ || true
        # `|| true` keeps link-rot from blocking merges; flag it in the PR comment instead
```

Then in repo settings → Branches → `main` → Require status checks to pass, check "MDX parse check" + "Sync check" + "Type check" + "Config JSON valid".

## Step 3: CODEOWNERS for sensitive paths

`.github/CODEOWNERS` forces explicit review for paths you care about:

```text .github/CODEOWNERS
# Default: any docs change pings the docs team (shows in PR sidebar)
/docs/                       @yourorg/docs-team

# Legal / compliance — always require legal review
/docs/legal/                 @yourorg/legal-team
/docs/privacy/               @yourorg/legal-team
/docs/terms/                 @yourorg/legal-team

# Security — security team review
/docs/security/              @yourorg/security-team

# Schema changes — engineering review
/public/schema.json          @yourorg/engineering-team
/src/types/                  @yourorg/engineering-team

# Billing / pricing — product + finance review
/docs/pricing*               @yourorg/finance-team
/docs/billing/               @yourorg/finance-team
```

Pair with branch protection's "Require review from Code Owners" — now legal-team must review any `/docs/legal/` change, even if auto-merge is enabled.

## Step 4: enable auto-merge per PR

On each PR you'd like to auto-merge:

1. Open the PR.
2. Scroll to the merge panel at the bottom.
3. Click **Enable auto-merge**.
4. Pick merge strategy (squash-and-merge is the usual choice for docs).

Once required checks pass AND required reviews are satisfied, the PR merges automatically.

## Auto-merge patterns

### Pattern 1: auto-merge on approval

Writer opens PR. Reviewer approves. Auto-merge fires when CI completes. No "hit the button" friction.

**Workflow:**
1. Writer opens PR.
2. Writer clicks "Enable auto-merge" (or uses a PR template checkbox).
3. Reviewer approves.
4. CI completes.
5. PR merges automatically.

Saves the 1-3 minute "pinging reviewer to click merge" step.

### Pattern 2: auto-merge Dependabot PRs

Most Dependabot PRs are trivial (patch + minor bumps). Auto-merge these after CI passes:

```yaml .github/workflows/dependabot-automerge.yml
name: Dependabot auto-merge

on:
  pull_request_target:
    types: [opened, synchronize]

jobs:
  automerge:
    if: github.actor == 'dependabot[bot]'
    runs-on: ubuntu-latest
    steps:
      - name: Dependabot metadata
        id: metadata
        uses: dependabot/fetch-metadata@v2

      # Auto-merge only patch + minor version bumps
      - name: Auto-merge
        if: |
          steps.metadata.outputs.update-type == 'version-update:semver-patch' ||
          steps.metadata.outputs.update-type == 'version-update:semver-minor'
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

Major version bumps still require human review.

### Pattern 3: auto-generated content updates

Daily job regenerates integration pages / schema-reference / etc. Opens PR. Auto-merges if CI passes.

```yaml .github/workflows/regen-generated-pages.yml
name: Regenerate generated content

on:
  schedule:
    - cron: "0 5 * * *"  # daily 5am UTC
  workflow_dispatch:

jobs:
  regen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npm ci

      - name: Regenerate
        run: |
          npm run build:schema-reference
          npm run build:integration-pages

      - name: Open PR (auto-merge enabled)
        uses: peter-evans/create-pull-request@v6
        with:
          commit-message: "chore(generated): refresh auto-generated docs"
          branch: auto/regen-generated-pages
          title: "chore(generated): daily refresh"
          body: |
            Automated refresh of schema-reference + integration pages.
            Auto-merges on CI pass.
          labels: auto-merge
```

Pairs with a workflow that enables auto-merge on PRs with the `auto-merge` label.

## Safety net — what to do when automerge goes wrong

Inevitably, some bad content ships because auto-merge merged a PR that should have been flagged. Recovery playbook:

<Steps>
  <Step title="Identify the bad commit">
    `git log --oneline main | head -20` on the failing branch.
  </Step>
  <Step title="Revert">
    `git revert <commit-sha>` creates a new commit that undoes the bad one. Push to `main` — auto-deploys within 30 seconds.
  </Step>
  <Step title="Diagnose the gap">
    What check should have caught this? If parse check missed it, the check is insufficient. If the reviewer wasn't required, CODEOWNERS needs expanding.
  </Step>
  <Step title="Tighten the gate">
    Update CI / CODEOWNERS to catch this class of error next time. Commit the change.
  </Step>
  <Step title="Reset trust">
    If automerge caused real damage (legal / security / billing exposure), pause auto-merge for 1-2 weeks. Force human review on everything while the gap gets fixed.
  </Step>
</Steps>

## Common automerge mistakes

<AccordionGroup>
  <Accordion title="Enabling automerge without CI gates">
    "Auto-merge on CI pass" when the CI only checks that the build doesn't fail. MDX parse errors + factual errors + schema drift all slip through. Require parse check + sync check + type check minimum.
  </Accordion>
  <Accordion title="Not using CODEOWNERS">
    Legal text auto-merged because the reviewer wasn't required. Protect sensitive paths with CODEOWNERS + "Require review from code owners" in branch protection.
  </Accordion>
  <Accordion title="Dependabot auto-merge on major bumps">
    `@stripe/stripe-js@3 → @stripe/stripe-js@4` auto-merged because "Dependabot passes CI". Breaking changes slip through. Only auto-merge patch + minor.
  </Accordion>
  <Accordion title="No revert plan">
    Bad content lands. Writers panic. Nobody knows how to revert. Document the `git revert` recipe in your onboarding — every writer should know the muscle memory.
  </Accordion>
  <Accordion title="Auto-merging experimental branches">
    Draft PRs or experiment branches shouldn't auto-merge. Don't click the button on them. Draft PRs don't auto-merge by default; non-draft experiment branches need explicit discipline.
  </Accordion>
</AccordionGroup>

## Related

- [Git concepts](/guides/git-concepts) — foundations
- [Branches](/guides/branches) — when to branch vs direct-to-main
- [Maintenance](/guides/maintenance) — CI + auto-merge feed the freshness audit loop
- [Improving docs](/guides/improving-docs) — reduce review cycles without reducing quality

---

# Content types
Source: https://docs.nookdocs.com/guides/content-types

The Diátaxis framework — tutorials, how-to guides, reference, and explanations. Four distinct modes, four distinct voices, four distinct page shapes. The single highest-leverage framing decision in technical writing.

Most docs problems are **mode confusion** — a page trying to be a tutorial AND a reference AND an explanation all at once, serving none of those needs well. [Diátaxis](https://diataxis.fr) (by Daniele Procida) is the cleanest framework for fixing this. Four modes, defined by what the reader is doing AT THE MOMENT THEY READ:

<CardGroup cols={2}>
  <Card title="Tutorial" icon="graduation-cap">
    **Reader:** studying. Learning by doing, first-time exposure.
    **You:** teacher. Safe environment, controlled outcome, immediate feedback.
    **Success:** reader completes the tutorial feeling "I built something that worked."
  </Card>
  <Card title="How-to guide" icon="wrench">
    **Reader:** working. Already oriented, solving a specific problem.
    **You:** senior colleague at the next desk. Direct, goal-oriented.
    **Success:** reader finishes the task.
  </Card>
  <Card title="Reference" icon="book">
    **Reader:** looking up. Needs an exact answer.
    **You:** index. Exhaustive, flat, search-optimised.
    **Success:** reader finds the parameter / status code / schema they needed.
  </Card>
  <Card title="Explanation" icon="brain">
    **Reader:** understanding. Wants context, history, trade-offs.
    **You:** architect. Narrative, opinionated, comparative.
    **Success:** reader grasps WHY you designed it this way.
  </Card>
</CardGroup>

## The Diátaxis compass

The framework positions each mode on two axes:

```text
                 ACQUIRE                  APPLY
                (learning)               (doing)
        ┌─────────────────────┬────────────────────────┐
PRACTICAL│     TUTORIAL       │     HOW-TO GUIDE       │
(steps) │  teaches by doing  │  helps finish a task   │
        ├─────────────────────┼────────────────────────┤
THEORY  │    EXPLANATION     │     REFERENCE          │
(ideas) │ builds understanding│  describes the thing  │
        └─────────────────────┴────────────────────────┘
```

**Acquire vs apply:** is the reader learning or doing?
**Practical vs theory:** is the page about steps or about ideas?

Most docs pages should fit cleanly in ONE quadrant. Pages straddling two quadrants usually signal "this needs to be split".

## Diátaxis by voice

Same content, four different voices:

### Tutorial voice

```markdown
# Your first Acme integration

In this tutorial, we'll create an Acme account, install the SDK,
and send your first test payment. By the end, you'll have a working
integration you can iterate on.

## Before you start

You'll need Node.js 18+ and a terminal. If you've used any npm
package before, this will feel familiar.

## 1. Create an Acme account

Head to acme.com/signup. You can use your personal email — we'll
stay in sandbox mode the whole tutorial.

...
```

Key markers: first-person plural (`we'll`), encouraging tone (`you'll have...`), familiar pacing (`Before you start`), hand-holding (`If you've used...`).

### How-to voice

```markdown
# Add a custom domain

Add a CNAME record pointing to `cname.nookdocs.site`, add the domain
in Settings → Custom domains, wait for verification.

## DNS

```dns
docs.acme.com.  IN  CNAME  cname.nookdocs.site.
```

## Verify

Open Settings → Custom domains → Add. The check polls every 5 seconds
for 60 seconds. Green when the CNAME propagates.
```

Key markers: imperative (`Add`, `Open`), terse, no hand-holding, assumes reader knows the stack.

### Reference voice

```markdown
# Rate limit headers

Every API response includes three rate-limit headers.

| Header | Type | Semantics |
|---|---|---|
| `X-RateLimit-Limit` | integer | Requests allowed per window. |
| `X-RateLimit-Remaining` | integer | Requests remaining in current window. |
| `X-RateLimit-Reset` | integer (unix) | Timestamp when the window resets. |

Windows are fixed 60-second intervals aligned to UTC.
```

Key markers: no narrative, structured data (table), exhaustive, lookup-friendly.

### Explanation voice

```markdown
# Why we rate-limit per API key, not per IP

We debated this for weeks. Per-IP limits are industry standard —
they're what AWS, GitHub, and Stripe use. We went with per-API-key
because most of our customers deploy behind corporate NAT: one
shared IP for hundreds of developers. Per-IP rate-limiting would
have given a 100-engineer startup the same budget as a hobbyist.

Per-API-key has its own tradeoffs — an abusive key can exhaust its
budget and cascade-fail other services calling the same endpoint.
We accept that because...
```

Key markers: first-person plural (`we debated`), narrative arc, explicit tradeoffs, historical context.

## Common mistakes

### Mistake 1: tutorial-reference hybrid

The page starts as a tutorial ("let's create your first integration") then halfway through turns into exhaustive reference ("full list of all config options: …"). The reader was in learning mode and got dumped into look-up mode. Neither mode got served.

**Fix:** split. Tutorial keeps one happy path with just the fields you need; reference doc covers every field comprehensively.

### Mistake 2: how-to with theory

The page claims to be a how-to ("Add a custom domain") but half the prose explains why DNS propagation takes up to 48 hours and how Let's Encrypt works under the hood. The reader wanted to finish the task; you gave them a lecture.

**Fix:** one-sentence framing, then steps. If the theory matters, link to an explanation page. Don't inline.

### Mistake 3: reference with marketing

The API reference page starts with "Our powerful rate-limiting system protects your infrastructure while scaling effortlessly..." The reader scanning for the `X-RateLimit-Remaining` header has to scroll past 200 words of marketing.

**Fix:** reference is dispassionate. Marketing lives on the landing page.

### Mistake 4: explanation as FAQ

The page labeled "Rate limits explained" is actually 15 Q&A pairs. Not wrong, but the FAQ format fragments what could be a narrative with clear cause-and-effect. FAQs are great for common objections; explanation is better for "why we designed X the way we did".

**Fix:** pick one or the other. If it's genuinely 15 disconnected questions, FAQ is right. If there's a through-line, write the narrative.

## How to split a mixed page

If you have a single page trying to be all four modes (common in "Complete Guide to X" posts), split by quadrant:

<Steps>
  <Step title="Identify the reader's mode in each section">
    Go heading by heading. Mark each: T (tutorial), H (how-to), R (reference), E (explanation).
  </Step>
  <Step title="Group by mode">
    Collect all T sections into one page, all H sections into another, etc.
  </Step>
  <Step title="Redraw the URLs">
    One T page at `/tutorials/first-X`. Multiple H pages at `/how-to/add-X`, `/how-to/configure-Y`. Reference pages under `/api-reference/...` or `/configuration/...`. Explanation pages under `/concepts/...` or `/guides/explanations/...`.
  </Step>
  <Step title="Cross-link at the right points">
    Tutorial: "For the full list of config fields, see [Reference]." Reference: "Learning this for the first time? See [Tutorial]." Explanation: "For the how-to steps, see [How-to]."
  </Step>
</Steps>

## NookDocs's own application

Looking at this site's current pages through the Diátaxis lens:

| Section | Mode | Path pattern |
|---|---|---|
| [Quickstart](/quickstart) | Tutorial (somewhat) | `/quickstart` |
| [Migrate from Mintlify](/cli/migrate-from-mintlify) | How-to | `/cli/*` |
| [Add a custom domain](/deploy/custom-domain) | How-to | `/deploy/*` |
| [Schema reference](/configuration/schema-reference) | Reference | `/configuration/*` |
| [Component library](/components/callout) | Reference | `/components/*` |
| [Human vs agent content](/llm-first/human-vs-agent) | Explanation | `/llm-first/*` |
| [Writing for LLMs](/guides/writing-for-llms) | Explanation | `/guides/*` |
| [Guides](/guides) | Explanation (landing) | `/guides` |

The pattern lands cleanly: `/guides/` hosts explanations, `/cli/` + `/deploy/` host how-tos, `/configuration/` + `/components/` host references, tutorials live at top-level entry points like `/quickstart`.

## When to ignore Diátaxis

Diátaxis is a framework, not a law. Cases where a hybrid page works:

- **Very short features.** A 300-word page on a tiny feature can legitimately cover all four modes if each mode is ~75 words. Splitting would be overkill.
- **Changelog entries.** An `<Update>` entry is mode-agnostic by design — it announces what changed without pretending to be a tutorial.
- **Landing pages.** Index / overview pages intentionally mix modes because they're signposts, not destinations.

For anything 500+ words, apply the framework.

## Related

- [Diátaxis homepage](https://diataxis.fr) — the full framework, with cross-domain examples
- [Writing for LLMs](/guides/writing-for-llms) — LLM-specific authoring patterns that apply across all four modes
- [Style and tone](/guides/style-and-tone) — voice and register per mode
- [GEO — AI search optimization](/guides/geo) — why smaller, focused pages rank better in AI answers

---

# Writing docs with Cursor
Source: https://docs.nookdocs.com/guides/cursor

Paste-ready `.cursor/rules/` template + prompt patterns that make Cursor's built-in Chat + Composer fluent in the NookDocs component library. Ship docs edits with tab-complete confidence.

[Cursor](https://cursor.com) is a VS Code fork with first-class LLM editing. Unlike a separate CLI agent, Cursor edits happen inline — tab-completion suggests MDX blocks, Composer rewrites multi-file changes, Chat answers questions about the current file. The editor IS the agent.

This page gives you a Cursor rules file + prompt patterns specifically for NookDocs repos.

## Install + project setup

<Steps>
  <Step title="Install Cursor">
    Download from [cursor.com](https://cursor.com). Macs + Windows + Linux supported. Pricing starts free (Hobby) with Pro tiers for more LLM calls.
  </Step>
  <Step title="Open your docs repo">
    `File → Open Folder...` and point at your local clone.
  </Step>
  <Step title="Add Cursor rules">
    Create `.cursor/rules/nookdocs.mdc` at the repo root with the template below. Cursor picks up any `.mdc` file in `.cursor/rules/` as project-wide context.
  </Step>
  <Step title="Pick a default model">
    Cursor settings → Models. Claude Sonnet 4+ or GPT-4-class models produce the best MDX. Haiku / smaller models are faster but lose detail on component semantics.
  </Step>
</Steps>

## The `.cursor/rules/nookdocs.mdc` template

Cursor rules files use a YAML frontmatter + Markdown body. This file targets every `.mdx` file in the repo:

````markdown .cursor/rules/nookdocs.mdc
---
description: NookDocs component + authoring rules for MDX files.
globs:
  - "docs/**/*.mdx"
  - "nookdocs.config.json"
alwaysApply: false
---

# NookDocs repo rules

This is a NookDocs documentation repo. Pages live under `docs/`,
config at `nookdocs.config.json`.

## Component library (use verbatim, never import)

Full machine-readable spec:
https://nookdocs.com/nookdocs-components.llm.md

Allowed components:

- Text: `<Callout type>`, `<Note>`, `<Tip>`, `<Warning>`, `<Info>`,
  `<Danger>`, `<Check>`, `<Badge>`, `<Pill>`, `<Tag>`
- Cards: `<Card title icon href>`, `<CardGroup cols>`, `<Tile>`,
  `<Tiles cols>`, `<HeroCard>`, `<LinkCard>`
- Code: `<CodeGroup>`, `<CodeBlock>`, `<RequestExample>`,
  `<ResponseExample>`, `<TerminalBlock>`
- Navigation: `<Tabs>` + `<TabsList>` + `<TabsTrigger>` +
  `<TabsContent>`, `<Accordion>` + `<AccordionGroup>`
- Steps: `<Steps>` + `<Step title="...">`
- Media: `<Frame caption>`, `<Image>`, `<Video>`, `<Embed>`,
  `<Mermaid>`
- API: `<ParamField path type required default>`,
  `<ResponseField name type>`, `<ApiMethod>`
- Meta: `<Snippet>`, `<Update date label version tags>`,
  `<Visibility for="humans|agents">`

## Frontmatter contract

Every `.mdx` page starts with:

```mdx
---
title: Verb-first page title
description: 1-sentence specific pitch naming 3 concrete affordances.
icon: lucide-icon-name
---
```

Changelog pages also set `rss: true` to expose the RSS subscribe button.

## Authoring rules

- Second person, active voice, imperative for instructions.
- Lead with the answer (no intro paragraphs like "In this guide...").
- Verb-first H2 headings for how-to sections.
- `<ParamField>` for every config key + API param.
- Code examples always in fenced blocks with a language tag.
- Cross-link to 3-5 related pages at the bottom in a
  `## Related` section.
- Use `<Visibility for="agents">` for LLM-targeted directives.
- One H1 per page, sourced from frontmatter `title` — don't write
  `# ` in the body.

## Do NOT

- Invent components — if it's not in the list above, it doesn't
  render. Check the machine-readable spec URL.
- Import anything in MDX — no ES imports allowed.
- Write HTML — use the components instead.
- Use marketing adjectives (powerful, seamless, easily, simply,
  robust, scalable) — reference docs describe, they don't sell.
- Add "Changelog" entries without also updating nookdocs.config.json
  nav if the page is new.

## Parse verification

Before committing any MDX change:

```bash
node --input-type=module -e "
  import { mdxParse } from 'safe-mdx/parse';
  import { readFileSync } from 'fs';
  mdxParse(readFileSync('docs/PATH.mdx','utf-8'));
"
```

For config changes that touch schema keys:

```bash
npm run check:sync
```
````

Commit `.cursor/rules/nookdocs.mdc`. Cursor reads this automatically when you edit any matching file.

## Cursor workflows

### Workflow 1: Tab-complete MDX

With the rules file active, Cursor's tab-complete suggests NookDocs component blocks as you type:

- Type `<Par` → Cursor completes to `<ParamField path="" type="" required>...</ParamField>`.
- Type `<Step` → completes to `<Step title="">...</Step>`.
- Type `<Code` → completes to `<CodeGroup>...</CodeGroup>` with tab placeholders.

The completion is smart about context — inside a `<Steps>` it suggests `<Step>`, inside a `<Tabs>` it suggests `<TabsTrigger>` + `<TabsContent>`.

### Workflow 2: Cmd/Ctrl+K inline edit

Select a paragraph, press Cmd+K (macOS) or Ctrl+K (Win/Linux), describe the transform:

```text
Rewrite as second person active voice.
Replace the build-up with lead-with-answer structure.
Convert to a ParamField table.
Add an example below in a bash code block.
```

Cursor applies the edit inline. Review the diff before accepting.

### Workflow 3: Composer (Cmd+I) for multi-file changes

Open Composer (Cmd+I). Describe a broader task:

```text
Add a new configuration page at docs/configuration/webhooks.mdx
covering retry + signature verification + payload schema. Use
docs/configuration/feedback.mdx as the structural template. Add the
new page to nookdocs.config.json nav under Configuration (after
custom-domain). Include a ParamField for every config key. Use a
complete JSON example at the end.
```

Composer proposes changes across `docs/configuration/webhooks.mdx` + `nookdocs.config.json` in one shot. Review + accept.

### Workflow 4: Chat (Cmd+L) for questions

Chat panel answers questions about the current file or repo without editing:

- "What's the difference between `<ParamField>` and `<ResponseField>`?"
- "Which pages use `<Visibility for='agents'>` already?"
- "List every H2 in docs/features/ so I can audit for consistency."

Chat is read-only; Cursor doesn't edit files from Chat. Switch to Composer or Cmd+K when you want changes.

## Model selection

Which model behind the scenes matters:

| Model | Best for | Trade-off |
|---|---|---|
| Claude Sonnet 4+ | Structural edits, multi-file changes, nuanced prose | Slower, costs more |
| GPT-4-class | Speed + decent quality | Occasionally misses MDX syntax edge cases |
| Claude Haiku | Tab-complete, simple edits | Loses component semantics on longer contexts |
| Smaller OSS models (Cursor Small) | Privacy-preferring, free tier | Noticeable quality drop on MDX |

For docs-writing specifically, Claude Sonnet is the recommended default — it's best-in-class at preserving structure + voice.

## Custom commands (Cursor-specific)

Cursor supports custom commands — prompt templates you can trigger with `@`:

```text
.cursor/commands/new-page.md

Generate a new NookDocs docs page. Ask:
1. Section (deploy / configuration / api / features / guides)
2. Topic (single word / hyphenated)
3. Three ParamField candidates the page should cover

Then create docs/{section}/{topic}.mdx with:
- Frontmatter (title, description, icon)
- 1-2 paragraph intro leading with the answer
- Main H2 section per ParamField
- Complete JSON example at the end
- Related section with 3-5 cross-links

Also add to nookdocs.config.json navigation under the matching group.
```

Save in `.cursor/commands/`, trigger with `@new-page`. Fast way to scaffold consistently.

## What Cursor does well

- **Inline edits at the keystroke level.** Tab-complete + Cmd+K turn docs editing into typing-speed feedback loops.
- **Preserving surrounding context.** Cursor's edits respect existing structure without rewriting the whole file.
- **Multi-file refactors.** Composer handles "rename X across 20 pages" reliably.
- **Model-mediated Chat.** Answers questions without requiring an external tool switch.

## What Cursor doesn't do well

- **Long reasoning chains.** Agent-style "plan + execute" workflows are smoother in Claude Code or a dedicated agent tool. Cursor's strength is interactive, not autonomous.
- **Terminal-heavy workflows.** You can run commands in Cursor's integrated terminal, but orchestration is weaker than a CLI agent.
- **Verifying claims about product features.** Same as any LLM — Cursor will invent feature behaviour when it doesn't know. Verify against code.

## Related

- [Claude Code](/guides/claude-code) — CLI agent sibling guide
- [Windsurf](/guides/windsurf) — alternative editor-based agent
- [Writing for LLMs](/guides/writing-for-llms) — broader authoring theory
- [Component spec](/llm-first/component-spec) — the URL you share with the agent
- [Style and tone](/guides/style-and-tone) — the authoring rubric Cursor enforces

---

# Headless + custom frontend
Source: https://docs.nookdocs.com/guides/custom-frontend

When you outgrow the default docs shell — or want docs rendered inside your product UI, in a mobile app, or on a marketing site — point at NookDocs's APIs and render yourself. The architectural trade-offs and when NOT to do this.

NookDocs renders your MDX with a built-in shell — sidebar, header, search modal, theme system, footer. For 95% of tenants this is the right default. The other 5% need something the default shell doesn't provide: docs embedded in the product UI, docs rendered via a mobile app, docs as part of a larger marketing site with custom chrome, docs that feed into a third-party helpdesk tool.

This guide covers the headless pattern — fetching your docs via API, rendering with your own UI — when it makes sense, and when to push back against it.

## When to go headless

<CardGroup cols={2}>
  <Card title="In-product docs panel" icon="sidebar">
    You want docs to appear inside your product's dashboard as a slide-out panel, with your own chrome. Users never leave the product to get help.
  </Card>
  <Card title="Mobile app docs" icon="smartphone">
    Your product has a native iOS / Android app. Users need in-app documentation that matches the app's visual identity, not a web-shell-in-a-WebView.
  </Card>
  <Card title="Marketing-site integration" icon="globe">
    Docs are one section of a larger corporate site with its own nav + footer. You want the MDX content, not the docs shell.
  </Card>
  <Card title="Customised search / chat UX" icon="search">
    You want to build a domain-specific chat interface (e.g. an AI assistant that blends docs + your internal KB + real-time product state).
  </Card>
</CardGroup>

## When to NOT go headless

<CardGroup cols={2}>
  <Card title="You want a different theme" icon="palette">
    NookDocs ships 10 themes + full token-level customisation. Try [theme](/configuration/theme) before rebuilding from scratch.
  </Card>
  <Card title="You dislike the default header" icon="minus-square">
    Replace via config — logo, links, CTA, banner all tenant-configurable. See [site settings](/configuration/site-settings).
  </Card>
  <Card title="You want your brand colour" icon="droplet">
    `colors.primary` / `colors.light` / `colors.dark` cover it.
  </Card>
  <Card title="You want to add a GA pixel" icon="bar-chart">
    `integrations.ga4` exists. 16 analytics providers ship. See [integrations overview](/configuration/integrations).
  </Card>
</CardGroup>

Most "I need custom docs" asks turn out to be "I haven't explored the config". Exhaust config options before committing to headless work — the maintenance cost is real.

## The trade-offs

Going headless shifts responsibility:

| Concern | Default shell | Headless |
|---|---|---|
| **Rendering the MDX** | NookDocs | You — use `@mdx-js/react` or similar |
| **Component library** | NookDocs ships 47 components | You implement every component you use |
| **Search** | Built-in ⌘K | You build or integrate |
| **Theme tokens** | Automatic light/dark | You manage |
| **SEO meta + sitemap** | Auto-emitted | You emit |
| **`/llms.txt` + RSS** | Auto-generated | Optional — you integrate if needed |
| **Versioning + multi-language** | Built-in | You implement |
| **Analytics beacon** | Auto | Your tool chain |

You're not losing the content-management story (still author MDX, still edit in the dashboard, still auto-sync from Git) — you're losing the rendering-to-production pipeline. That's more work than it sounds.

## The API surface for headless

NookDocs exposes JSON + Markdown endpoints for programmatic consumption:

### Page content

```bash
# Raw MDX for one page (agent-filtered)
GET https://{tenant}.nookdocs.site/<page-path>.md

# Same page, JSON envelope with frontmatter + source
GET https://api.nookdocs.com/v1/projects/{projectId}/pages/<page-path>
```

### Search

```bash
POST https://api.nookdocs.com/v1/projects/{projectId}/pages/search
Content-Type: application/json

{
  "query": "custom domain",
  "limit": 10
}
```

Returns ranked results with snippet highlights. See [API reference](/api-reference/introduction) for the full shape.

### Navigation

```bash
# The parsed navigation tree (tabs + groups + pages)
GET https://api.nookdocs.com/v1/projects/{projectId}/config
```

Returns the `nookdocs.config.json` navigation as structured JSON. Your frontend renders a sidebar from this.

### AI assistant

```bash
POST https://{tenant}.nookdocs.site/api/v1/projects/{projectId}/assistant/ask
Content-Type: application/json

{
  "query": "How do I set up webhooks?",
  "history": [...]
}
```

Returns a streamed SSE response. Your frontend subscribes + renders incrementally. See [AI assistant](/configuration/ai-assistant).

### llms.txt + sitemap

Still auto-generated at the tenant URL. Useful even in headless mode for LLM crawlers that expect the standard endpoints:

```text
GET https://{tenant}.nookdocs.site/llms.txt
GET https://{tenant}.nookdocs.site/llms-full.txt
GET https://{tenant}.nookdocs.site/sitemap.xml
```

## A minimal headless React example

```tsx
// DocsPanel.tsx — in-product slide-out docs
import { useState, useEffect } from "react";
import { MDXRemote } from "next-mdx-remote/rsc";
import { serialize } from "next-mdx-remote/serialize";

async function fetchDoc(path: string) {
  const res = await fetch(
    `https://api.nookdocs.com/v1/projects/${PROJECT_ID}/pages/${path}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  const json = await res.json();
  return await serialize(json.source_mdx, { parseFrontmatter: true });
}

export function DocsPanel({ path }: { path: string }) {
  const [content, setContent] = useState<any>(null);

  useEffect(() => {
    fetchDoc(path).then(setContent);
  }, [path]);

  if (!content) return <div>Loading...</div>;

  return (
    <aside className="docs-panel">
      <MDXRemote
        source={content}
        components={{
          // Your component implementations
          Callout: YourCallout,
          Card: YourCard,
          ParamField: YourParamField,
          // ...47 more components to implement
        }}
      />
    </aside>
  );
}
```

The `components` prop is where the real work lives — you're implementing every NookDocs component in your own design system. Ship 1 at a time as pages need them.

## Component strategy

Three approaches, increasing effort:

<Steps>
  <Step title="1. Minimal set (ship fast)">
    Implement only the ~15 most-used components: `<Callout>`, `<Note>`, `<Warning>`, `<Info>`, `<Card>`, `<CardGroup>`, `<Steps>`, `<Step>`, `<Tabs>`, `<CodeGroup>`, `<ParamField>`, `<ResponseField>`, `<Frame>`, `<Accordion>`.

    Unknown components render as raw children (ugly but functional). Good for shipping an MVP.
  </Step>
  <Step title="2. Full set (parity)">
    Implement all 47 components to match NookDocs's built-in library. Expensive — 2-4 weeks of component work. Pays off if docs are central to your product.
  </Step>
  <Step title="3. Subset + redirect">
    Implement 15-20 core components. For pages that use fancy components (like `<ColorPalette>` or `<Mermaid>`), render a "View this page in full" link that opens the NookDocs-hosted version.
  </Step>
</Steps>

Most teams land at approach 2 or 3.

## SSR vs client-only

Headless docs work either as part of an SSR app (Next.js, Remix, Astro) OR a fully-client-rendered SPA:

- **SSR** — fetch at build time or per-request, serialize MDX, hydrate. Better SEO, faster first paint. Preferred for public-facing headless docs.
- **Client-only** — fetch on mount, serialize + render in the browser. Worse SEO (search engines see empty shell), faster iteration. OK for in-product panels where SEO doesn't matter.

For in-product docs (private, authenticated), client-only is usually fine — your users authenticate before seeing docs, so Google can't crawl anyway.

## Performance considerations

- **Don't fetch MDX on every render** — cache aggressively. Most docs pages don't change minute-to-minute.
- **Lazy-load heavy components** — `<Mermaid>` needs Mermaid.js; `<CodeGroup>` needs Prism. Lazy-load to keep initial bundle lean.
- **Stream where possible** — the assistant endpoint streams SSE; render tokens as they arrive, don't wait for completion.
- **Prefetch likely next pages** — docs readers tend to follow the "Next" footer link; prefetch on hover.

## When to reconsider

At some point, implementing + maintaining a headless docs pipeline becomes more work than learning to customise the default shell. Signs you should reconsider:

- You've built 20+ components and are still hitting edge cases.
- Every shipping change needs a coordinated update across MDX + your frontend + your search index.
- Users ask for features the default shell has (search modal, copy-for-LLMs, RSS, etc.).

Migration back to the default shell is usually straightforward — your MDX is portable, your config translates, your search index is already in NookDocs. The hard part is sunsetting your custom work without disruption.

## Hybrid pattern — partial headless

Compromise pattern: use the NookDocs default shell for `docs.acme.com` + embed specific pages in-product via the API:

```text
docs.acme.com            — full default shell (public docs)
app.acme.com/help-panel  — headless in-product docs (private)
```

Authoring + editing happens in one place. Rendering branches by audience. Less work than full headless; still covers the in-product use case.

## Common headless pitfalls

<AccordionGroup>
  <Accordion title="Starting with a full custom render before validating the need">
    Team commits to "we're going custom" at launch, builds for 2 months, ships. 6 months later realises they'd have been fine with default shell + theme tokens. Try defaults first.
  </Accordion>
  <Accordion title="Implementing components inconsistently with NookDocs defaults">
    Your `<Callout>` renders differently than the dashboard preview. Writers see their content rendered one way in editor, another in production. Confusing. Either match the defaults closely OR give writers a preview of YOUR renderer.
  </Accordion>
  <Accordion title="No search strategy">
    You built the MDX render but not the search. Users can't find anything. Either wire up a search endpoint + UI or link out to the NookDocs-hosted search for searches.
  </Accordion>
  <Accordion title="SEO afterthought">
    SSR not wired up properly; Googlebot sees empty pages. Months later no organic traffic. Get SSR working before shipping publicly.
  </Accordion>
  <Accordion title="Forgetting llms.txt + RSS + sitemap">
    Default shell emits these. You forgot. LLM discovery breaks, changelog readers lose the feed. Either proxy the NookDocs-hosted endpoints or re-emit yourself.
  </Accordion>
  <Accordion title="One person knows how it works">
    Custom docs pipeline built by one engineer. They leave. Nobody can maintain it. Documented or not. Either commit to formalising the maintenance OR fall back to default shell.
  </Accordion>
</AccordionGroup>

## Related

- [Theme](/configuration/theme) — full theme + token customisation before headless
- [Site settings](/configuration/site-settings) — banner / SEO / navbar / footer config
- [AI assistant config](/configuration/ai-assistant) — the streaming chat API
- [Markdown export](/optimize/markdown-export) — the `.md` URL pattern
- [llms.txt](/optimize/llms-txt) — LLM crawler index
- [Schema reference](/configuration/schema-reference) — full config surface

---

# Custom page layouts
Source: https://docs.nookdocs.com/guides/custom-layouts

Different pages want different layouts — wide content, centered narrative, dashboard-style splits, reference tables. NookDocs's layout system lets you pick per page without dropping into full-headless mode.

Default NookDocs pages have a predictable shape — sidebar on the left, article in the middle, table of contents on the right. That works for 80% of content. The other 20% wants something different: a wide Mermaid diagram that overflows the default content max-width, a single-column narrative without a distracting TOC, a landing page with edge-to-edge hero cards, a reference table that needs 100% of horizontal space.

This guide covers NookDocs's per-page layout customisation. Lighter touch than [going headless](/guides/custom-frontend); uses frontmatter + component patterns to adjust layout page-by-page.

## The built-in layout modes

NookDocs exposes layout as a frontmatter field. Set `mode` on any page to change its shape:

<ParamField path="mode" type="'default' | 'center' | 'wide' | 'custom'" default="default">
  How the page renders inside the shell.
  - `default` — standard three-column (sidebar / article / TOC).
  - `center` — article centered, no TOC, narrower max-width. Good for long-form narratives.
  - `wide` — article fills available width, no TOC. Good for wide tables, diagrams, dashboards.
  - `custom` — article and TOC both removed; you render your own chrome inside the `<Card>`/`<Tiles>` primitives.
</ParamField>

### When to use each

<CardGroup cols={2}>
  <Card title="default" icon="columns-3">
    **Use for:** reference docs, how-to guides, most content. TOC helps readers navigate long pages. Max-width keeps lines readable.
  </Card>
  <Card title="center" icon="align-center">
    **Use for:** long-form narratives, editorial pieces, "explanation" mode Diátaxis content. Removing TOC focuses attention on the prose.
  </Card>
  <Card title="wide" icon="stretch-horizontal">
    **Use for:** reference tables with many columns, Mermaid diagrams, dashboards, code comparisons. Full horizontal space.
  </Card>
  <Card title="custom" icon="layout-grid">
    **Use for:** landing pages, feature grids, hero sections. You control everything inside.
  </Card>
</CardGroup>

## Example: narrow narrative

```mdx
---
title: "Why we rate-limit per API key, not per IP"
description: Design decision with context + tradeoffs. Long-form explanation mode.
mode: center
---

We debated this decision for weeks. Per-IP limits are industry
standard — AWS, GitHub, Stripe all default to IP-based ...

(500 more words of narrative)
```

Rendered: no sidebar nav duplication, no TOC clutter. Reader scrolls linearly through the argument.

## Example: wide reference table

```mdx
---
title: HTTP status codes
description: Full list of response codes the API can return, with meanings, causes, and resolution steps.
mode: wide
---

| Code | Reason | HTTP status | Billing impact | Resolution |
|---|---|---|---|---|
| `invalid_api_key` | Missing Bearer prefix or revoked key | 401 | None | Regenerate key |
| `insufficient_credits` | Account balance below threshold | 402 | Block | Top up billing |
| `rate_limited` | Too many requests in 60s window | 429 | None | Back off + retry |
| `internal_server_error` | Unexpected server failure | 500 | Refund eligible | Contact support |
```

Wide layout gives every column breathing room. Default layout would wrap or truncate.

## Example: landing page

```mdx
---
title: "Acme Docs"
description: Developer documentation for the Acme platform.
mode: custom
---

<Tiles cols={3}>
  <Tile icon="rocket" href="/quickstart">
    ## Quickstart
    5-minute walkthrough to your first API call.
  </Tile>
  <Tile icon="code" href="/api-reference">
    ## API reference
    Every endpoint, every parameter, every response.
  </Tile>
  <Tile icon="sparkles" href="/ai-features">
    ## AI features
    Hosted LLM assistant, semantic search, agent-ready docs.
  </Tile>
</Tiles>

<HeroCard
  title="Ship your first integration today"
  description="Free sandbox account, real API keys, no credit card."
  cta="Sign up"
  href="https://acme.com/signup"
/>
```

Custom mode drops the article max-width + removes the TOC. You control visual composition via `<Tiles>`, `<HeroCard>`, `<CardGroup>`, `<Columns>`, etc.

## Layout beyond mode — the `<Columns>` primitive

For mid-article layouts (two-column inside an otherwise default page), use `<Columns>`:

```mdx
## Integration architecture

<Columns cols={2}>
  <div>
    Our API speaks REST + JSON. Authenticate with a Bearer token on
    every request. Rate limits per API key, not per IP.

    Responses stream back as Server-Sent Events for the assistant
    endpoint, standard JSON for everything else.
  </div>
  <div>
    <Frame caption="Request lifecycle from client to response">
      <Mermaid>
        sequenceDiagram
          Client->>API: POST /v1/payment
          API->>Stripe: Charge card
          Stripe-->>API: Success
          API-->>Client: 200 OK
      </Mermaid>
    </Frame>
  </div>
</Columns>

## Next steps
```

Mid-page columns work in any layout mode — use when one section benefits but most of the page is standard.

## The max-width system

NookDocs exposes content width as a theme token:

```css
--docs-content-max-width: 768px;       /* default mode article */
--docs-content-outer-max-width: 1280px; /* wide mode */
--docs-shell-max-width: 88rem;          /* whole shell (sidebar + article + TOC) */
```

These are CSS custom properties, not config keys — you set them through
[Custom CSS](/configuration/custom-css) to change every page in your site, or
via an inline `style` on a wrapper element to change one page:

```css
/* site-wide, in your custom CSS */
#docs-root {
  --docs-content-max-width: 860px;
}
```

Most tenants never touch these. They're escape hatches.

### Side rails

The article is flanked by two rails — the navigation sidebar on one side, the
"On this page" table of contents on the other. Both rails reserve the **same**
width, which is what keeps your article centred on the page:

```css
--docs-sidebar-width: 288px;  /* navigation sidebar */
--docs-rail-width: 288px;     /* gutter reserved on BOTH sides */
--docs-toc-width: 220px;      /* how wide the TOC itself draws */

--docs-sidebar-border: 1px solid var(--docs-border);   /* rule between sidebar and article */
--docs-sidebar-divider: 1px solid var(--docs-border);  /* rules inside the sidebar */
```

Set either to `none` for a sidebar that separates by whitespace alone. They are
independent — you can keep the outer rule and drop the internal ones, or the
reverse.

Two things worth knowing:

- `--docs-toc-width` is smaller than `--docs-rail-width`. The table of contents
  draws at its own width and sits against the inner edge of the rail; the
  leftover space stays empty. Change `--docs-toc-width` to make the TOC narrower
  or wider without moving your article.
- The rail is reserved **even on pages that have no table of contents**, so your
  article stays in exactly the same place as readers move between pages.

If you widen `--docs-sidebar-width`, set `--docs-rail-width` to match — otherwise
the article drifts off-centre by half the difference.

### Sidebar scrollbar

When your navigation is longer than the viewport the sidebar scrolls. How its
scrollbar behaves is part of the theme:

| Value | Behaviour |
|---|---|
| `always` | Visible whenever the nav overflows. The default. |
| `hover` | Fades in when the pointer enters the sidebar, out when it leaves. |
| `hidden` | Never drawn. The nav still scrolls by wheel, trackpad and keyboard. |

The gutter is reserved in every mode, so the nav never shifts sideways as the
scrollbar appears. Readers who have reduced motion enabled get the scrollbar
without the fade.

This one is chosen by the theme rather than by config — Ember uses `hover`,
every other theme uses `always`. Pick the behaviour you want by picking the
theme, or override it yourself with [Custom CSS](/configuration/custom-css):

```css
/* hide the sidebar scrollbar on any theme */
.docs-sidebar,
.docs-sidebar * {
  scrollbar-width: none;
}
.docs-sidebar::-webkit-scrollbar,
.docs-sidebar *::-webkit-scrollbar {
  display: none;
}
```

<Note>
API reference pages are the exception. Their right column holds request and
response code samples rather than a table of contents, so the rail widens to fit
them and the article narrows to compensate. This happens automatically — you
don't configure it, and it doesn't affect your other pages.
</Note>

## Reading-mode toggles

Some tenants want readers to toggle between "reading mode" (center / narrow) and "reference mode" (wide / tables visible). NookDocs doesn't ship this out of the box — tenants with this need use one of:

1. **Separate pages** — narrative version at `/page`, reference version at `/page/reference`. Linked from each other. Simpler than a toggle.
2. **`<Visibility>` audience split** — sort of works for agent/human but not for "simplified/detailed" human variants.
3. **[Custom frontend](/guides/custom-frontend)** — full layout control, highest cost.

## Combining layout + components

Layout mode sets the FRAME. Components set the CONTENT. They compose:

<CardGroup cols={2}>
  <Card title="wide + CodeGroup" icon="code">
    Wide mode lets wide code blocks breathe. Multi-language examples display all languages fully.
  </Card>
  <Card title="center + Steps" icon="list-ordered">
    Long tutorial walkthroughs feel natural in center mode — reader scrolls linearly through numbered steps.
  </Card>
  <Card title="default + Accordion" icon="chevron-down">
    Reference docs with occasional deep-dives — put the deep-dives in `<Accordion>` to keep the base page scannable.
  </Card>
  <Card title="custom + Tiles" icon="layout-grid">
    Landing pages use `<Tiles cols>` grids to display many entry points at once. Custom mode removes the article max-width that would otherwise constrain.
  </Card>
</CardGroup>

## Theme vs layout

Two different customisation axes:

| Axis | What it controls | Scope |
|---|---|---|
| **Theme** (`nookdocs.config.json#theme`) | Colours, fonts, spacing, radius, shadows | Site-wide, consistent across every page |
| **Layout** (page frontmatter `mode`) | Page structure — article width, TOC presence, shell chrome | Per-page, can vary wildly |

You can use `mode: wide` on a docs site with the `larch` theme (default) — layout + theme are orthogonal.

## Limitations

- **No custom React components per page.** You're working within the built-in component library. For truly custom rendering, see [custom frontend](/guides/custom-frontend).
- **`mode: custom` still uses the shell chrome** (header, sidebar, footer). To remove ALL chrome, you need a custom frontend.
- **No fine-grained TOC control.** Either TOC is there (default) or it's not (center / wide / custom). No "show only h2s, not h3s" toggle.
- **Max-width overrides are per-tenant, not per-page.** To tweak per-page widths you'd need inline CSS.

## Common layout mistakes

<AccordionGroup>
  <Accordion title="Using wide mode for normal prose">
    Wide mode has wide content area. Reading 200-character lines is fatigue-inducing. Only use wide for tables / diagrams / dashboards.
  </Accordion>
  <Accordion title="Using custom mode for regular pages">
    Custom removes the article max-width. Long prose without constraint stretches uncomfortably wide. Only use custom for grid-based landing pages.
  </Accordion>
  <Accordion title="Inconsistent layout modes across similar pages">
    Your quickstart uses `mode: center`, your concepts uses `mode: default`, your install page uses `mode: wide`. Readers notice the discontinuity. Pick one layout per content type.
  </Accordion>
  <Accordion title="Overriding max-width globally to fit one table">
    "This reference table doesn't fit, let me widen the site max-width." Now every page has too-wide lines. Use `mode: wide` on the one page instead.
  </Accordion>
  <Accordion title="Assuming custom mode means 'no restrictions'">
    Custom mode removes the article chrome; it doesn't disable components, typography, or theme tokens. You still render inside NookDocs's rendering pipeline.
  </Accordion>
</AccordionGroup>

## Related

- [Frontmatter reference](/content/frontmatter) — the `mode` field + other per-page controls
- [Theme](/configuration/theme) — site-wide appearance
- [Custom frontend](/guides/custom-frontend) — when layout modes aren't enough
- [Component library](/components/callout) — the building blocks every layout mode uses
- [Columns component](/components/columns) — mid-page two-column content
- [Tiles component](/components/tiles) — landing-page grid primitive

---

# Developer documentation
Source: https://docs.nookdocs.com/guides/developer-documentation

End-to-end recipe for API + SDK + CLI docs. The seven sections every developer-facing docs site needs, the order they should live in, and how to phase the work across two quarters without burning out the writer.

Developer documentation has a specific shape. The best-in-class sites — Stripe, Twilio, Linear, Vercel, Supabase — all follow roughly the same structure because it matches the way developers evaluate, adopt, and operate a platform. Missing any of the seven core sections loses you users at a specific stage of the funnel.

This is the end-to-end recipe. Apply it as a gap analysis against your current docs, a blueprint for a new one, or a prioritisation list.

## The seven sections every dev doc site needs

<CardGroup cols={2}>
  <Card title="1. Introduction / landing" icon="sparkles">
    **For:** evaluators in the first 30 seconds. **Answers:** "What is this? Who's it for?" One page, 150-300 words, with a `<CardGroup>` linking to the next four sections.
  </Card>
  <Card title="2. Quickstart" icon="rocket">
    **For:** implementers on first day. **Answers:** "How do I get a working integration in under 5 minutes?" One page, step-by-step, runnable end-to-end with real example values.
  </Card>
  <Card title="3. Concepts / architecture" icon="brain">
    **For:** engineers deciding whether to adopt. **Answers:** "How does this model its world?" 3-5 pages covering primary objects, request lifecycle, consistency guarantees, rate-limit philosophy.
  </Card>
  <Card title="4. How-to guides" icon="list-checks">
    **For:** implementers solving specific problems. **Answers:** "How do I X?" 10-30 task-focused pages covering common integration paths.
  </Card>
  <Card title="5. API reference" icon="book">
    **For:** operators in production. **Answers:** "What exact fields does endpoint X accept?" Auto-generated from OpenAPI. One page per operation + shared schema definitions.
  </Card>
  <Card title="6. SDK docs" icon="package">
    **For:** anyone not writing raw HTTP. **Answers:** "How do I use the TypeScript client?" One section per SDK with install, usage, type reference.
  </Card>
  <Card title="7. Changelog + migration" icon="history">
    **For:** operators at version bumps. **Answers:** "What changed? How do I upgrade?" Append-only timeline of releases + per-breaking-change migration guides.
  </Card>
</CardGroup>

## How each section maps to Diátaxis

| Section | Diátaxis mode | Voice |
|---|---|---|
| Introduction / landing | Explanation | Marketing-adjacent, first person plural |
| Quickstart | Tutorial | Encouraging, second person, first person plural framing |
| Concepts | Explanation | Narrative, opinionated, third person on objects |
| How-to guides | How-to | Imperative, second person, terse |
| API reference | Reference | Dispassionate, flat, lookup-optimised |
| SDK docs | Mix (reference + how-to) | Code-first, tabs for multi-language |
| Changelog | Meta | Dated, structured, neutral |

See [content types](/guides/content-types) for the framework.

## Section order in the sidebar

Top-to-bottom, matches reader journey:

```text
├── Get Started
│   ├── Introduction
│   ├── Quickstart
│   └── Concepts
├── Guides            (how-to section)
│   ├── Authenticate
│   ├── Handle webhooks
│   ├── Pagination
│   └── ...
├── API Reference     (separate tab — can be huge)
├── SDKs              (separate tab — one per language)
└── Resources
    ├── Changelog
    ├── Migration
    └── Status
```

Readers land on Introduction → Quickstart → (when stuck) Guides → (when operating) API Reference + SDKs → (at version bumps) Changelog. Mismatched order means readers can't find their next step.

## Page budget for each section

Rough sizing for a mid-sized dev platform:

| Section | Page count | Lines per page |
|---|---|---|
| Introduction + Concepts | 4-6 | 150-250 |
| Quickstart | 1-2 | 200-350 |
| How-to guides | 10-30 | 150-300 |
| API Reference | 50-200 (auto-gen) | (auto) |
| SDK docs | 3-5 per SDK | 100-250 |
| Changelog | 1 | Append-only timeline |
| Migration | 1 per breaking change | 200-500 |

Anything more is probably sprawl. Anything less is probably under-documented.

## Day 1 — minimum viable dev docs

Ship these 8 pages before launch:

<Steps>
  <Step title="Introduction">
    150 words. What the product does. Who it's for. `<CardGroup>` linking to Quickstart + Concepts.
  </Step>
  <Step title="Quickstart">
    Working end-to-end integration in under 5 minutes. Real API call with real response. Use a sandbox/test-mode key so readers can run without a production account.
  </Step>
  <Step title="Authentication">
    Bearer token? API key? OAuth? Be specific. Example curl + fetch + SDK for each supported method.
  </Step>
  <Step title="Core concepts (1 page)">
    The primary objects + how they relate. Diagram or table listing entity → purpose. Sequence diagram for the request lifecycle.
  </Step>
  <Step title="One end-to-end guide">
    The top use case your product solves. "Charge a card with Acme" or "Send your first notification" — the thing 80% of users want.
  </Step>
  <Step title="API Reference">
    Auto-generate from OpenAPI spec. Ship with at least 5 operations documented with request / response / error examples.
  </Step>
  <Step title="Errors">
    One page listing every error code with: code, HTTP status, what it means, how to fix. Operators search this by error message all the time.
  </Step>
  <Step title="Changelog (empty)">
    Start empty. First real release populates it. Having the page from day 1 signals the discipline.
  </Step>
</Steps>

8 pages is enough to launch. Ship. Iterate.

## First quarter — expand the core

After launch, add 10-20 more pages over ~3 months:

- **More concepts** — one per primary object (users, sessions, webhooks, subscriptions, whatever).
- **More how-tos** — one per top-10 support ticket theme. [Support tickets are the canonical priority list](/guides/improving-docs).
- **SDK docs per language** — TypeScript first (widest audience for most dev tools), then Python, then Go / Ruby / others by user demand.
- **Common-case tutorials** — a 30-minute "build X with Acme" tutorial for the top use case. Longer than a quickstart, more narrative, results in a working sample repo.

## Second quarter — depth and polish

By month 6:

- **Migration guides** for every breaking change shipped so far.
- **Webhooks deep dive** — signature verification, retries, payload schemas.
- **Rate limit docs** — actual numeric limits, headers returned, back-off strategy.
- **Error code exhaustive list** — every error code your API can return, grouped by category.
- **Data model reference** — object schemas beyond what the API reference covers.
- **Integration recipes** — "Using Acme with Next.js", "Using Acme with Django" — code-heavy tutorials.

## Dev docs patterns that rank

Three specific patterns that consistently rank well in Google + LLM answer boxes:

### Pattern 1: "Install in 30 seconds" hero

````mdx
## Install

<CodeGroup>
```bash npm
npm install @acme/sdk
```

```bash yarn
yarn add @acme/sdk
```

```bash pnpm
pnpm add @acme/sdk
```
</CodeGroup>

## Send your first request

```typescript
import Acme from "@acme/sdk";

const acme = new Acme({ apiKey: process.env.ACME_KEY });
const result = await acme.users.list();
console.log(result.data.length);
```
````

Above the fold: install, one API call, one log. Readers see they can be productive in 30 seconds before scrolling to the details.

### Pattern 2: Error as entry point

Create a page per HTTP error code your API returns. Developers Google error messages verbatim. The page should include the message, the cause, and the fix.

```mdx
---
title: "Error: invalid_api_key"
description: "401 response when the Authorization header is missing, malformed, or references a revoked key. Resolution steps below."
---

HTTP 401 returned when the `Authorization` header fails server-side
validation. Four common causes:

1. **Missing `Bearer` prefix**: The header must be
   `Authorization: Bearer sk_live_...`, not `Authorization: sk_live_...`.
2. **Revoked key**: Check the dashboard for key status. Rotate if
   revoked.
3. **Wrong environment**: `sk_test_...` keys only work against test-
   mode endpoints (`api-test.acme.com`), not production.
4. **Whitespace**: Trailing newline or space in the env var. Trim
   before using.
```

This page ranks for `"acme invalid_api_key"` and every variant. One page per error code = compound SEO wins over time.

### Pattern 3: "X in Y" recipe pages

```text
Using Acme with Next.js
Using Acme with Vercel Functions
Using Acme with Django
Using Acme with Laravel
Using Acme with Rails
```

Each page is a focused integration walkthrough. Developers search "acme next js tutorial" — your recipe page is the top hit. Compounds over time as you cover more frameworks.

## API reference discipline

The reference pages auto-generate from your OpenAPI spec. Quality comes from spec quality:

- **Every operation has a `description`**, not just a `summary`.
- **Every parameter has a `description`**, `type`, `required`, `default`.
- **Every response has at least one `example`** that looks like real data.
- **Every error status has its own `response` entry** with the `Error` schema.
- **`operationId`s are human-readable** — `listUsers`, `createPayment`, not `op_423`.

See [multiple responses](/openapi/multiple-responses), [complex types](/openapi/complex-types), and [SDK examples](/openapi/sdk-examples) for the MDX-component side. The OpenAPI spec discipline compounds into docs quality.

## SDK documentation strategy

For each supported SDK:

1. **Install page** — package manager tabs, version constraints, peer deps.
2. **Getting started** — mirrors the API quickstart but SDK-specific.
3. **Core patterns** — common usage patterns with idiomatic code.
4. **Type reference** — for typed languages (TS / Python Pydantic / Go), link to generated type docs or re-document in the site.
5. **Error handling** — SDK-specific exception hierarchy.

Don't write 5 pages per SDK if you have 8 SDKs — that's 40 pages for lower-priority languages. Typescript + Python full 5-page treatment, Go + Ruby + Java 2-page abbreviated, other SDKs 1-page install + link-to-github-readme.

## Migration guides — the underrated section

Most dev docs under-invest here. Every breaking change needs:

- **What changed** (bullet list of renames / removals / behaviour changes).
- **Why** (one paragraph — readers want to know if it affects them).
- **Timeline** (deprecation date, sunset date, hard removal date).
- **Step-by-step upgrade** with before / after code diffs.
- **Edge cases** (what if you're combining old X with new Y during migration).

Good migration guides reduce support load more than any other type of docs.

## The "what next" call-to-action

Every page should end with a specific next step. Not "Learn more about Acme" — a literal next page:

```mdx
## Related

- [Next: handle webhooks](/guides/webhooks)
- [Reference: API rate limits](/api/rate-limits)
- [Deep dive: why Acme uses per-key rate limits](/concepts/rate-limit-design)
```

Readers ALWAYS have a next step. Docs that end flat lose readers to bounce.

## Common developer-docs mistakes

<AccordionGroup>
  <Accordion title="Quickstart that isn't actually 5 minutes">
    Marketing-labeled "5-minute quickstart" that takes 45 minutes because it assumes ngrok, Stripe test setup, AWS deploy, and SDK install. Measure the actual time with a new developer. If it's over 10 minutes, split: first page hits 5-min, second page deploys to prod.
  </Accordion>
  <Accordion title="Concept pages that are marketing copy">
    "Our powerful webhooks system revolutionises how you..." — concepts pages should be precise technical explanations, not pitch. If a competitor replaced your product name in the page it should still be technically accurate.
  </Accordion>
  <Accordion title="Auto-generated API reference with no examples">
    OpenAPI-to-docs pipeline runs but the spec has no `example` values. Reference pages show schemas with zero concrete values. Developers struggle to construct a valid request. Populate `example` fields in the spec first.
  </Accordion>
  <Accordion title="No errors page">
    Developers Google error messages. If your docs don't have a page per error code, competitors' Stack Overflow answers rank. Write the page.
  </Accordion>
  <Accordion title="Unmaintained SDK docs">
    TypeScript SDK docs describe v1.x but the current npm package is v3.5. Readers follow outdated patterns, hit errors, lose faith. SDK docs must be updated in the same release as the SDK.
  </Accordion>
  <Accordion title="No changelog">
    "Latest changes" = blog posts on Medium from 2 years ago. Every dev docs site needs a proper `/changelog` with `<Update>` entries. See [changelog guide](/content/changelogs).
  </Accordion>
</AccordionGroup>

## Related

- [Content types](/guides/content-types) — Diátaxis framework for mode choices
- [Style and tone](/guides/style-and-tone) — voice rubric per section
- [Understand your audience](/guides/understand-your-audience) — evaluators / implementers / operators personas
- [SEO for docs](/guides/seo) — ranking signals for each section type
- [API reference overview](/openapi/overview) — auto-generation mechanics
- [Changelogs](/content/changelogs) — the `<Update>` component

---

# GEO — AI search optimization
Source: https://docs.nookdocs.com/guides/geo

Generative Engine Optimization. How to rank in ChatGPT, Perplexity, Google AI Overviews, and Bing Copilot answer boxes — the patterns that work, the ones that don't, and why it's different from classic SEO.

Classic SEO optimised for the ten blue links. **GEO** — Generative Engine Optimization — optimises for the one paragraph an LLM pastes above them. ChatGPT browse, Perplexity, Google AI Overviews, Bing Copilot all work the same way: query → retrieve top-N pages → synthesise a ~200-word answer → cite 3-5 sources. Ranking #1 in classic SEO doesn't mean you're the cited source in the AI answer.

This guide covers the patterns that get your page cited.

## Why GEO is different from SEO

<CardGroup cols={2}>
  <Card title="Classic SEO targets a query → click" icon="mouse-pointer">
    Title tag, meta description, headings, backlinks, word count. Success = reader clicks to your site. Page content after the click is secondary.
  </Card>
  <Card title="GEO targets a query → quote" icon="quote">
    Answer paragraphs, citation-worthy sentences, structured facts. Success = the LLM synthesiser pulls your exact sentence into its answer. The reader may never click — they got the answer.
  </Card>
  <Card title="Classic SEO rewards length" icon="ruler">
    Longer pages rank better in most niches. 1500+ words is table stakes.
  </Card>
  <Card title="GEO rewards density" icon="package">
    The best 3-sentence paragraph on the topic wins the citation. Long pages get their best chunks picked and the rest ignored.
  </Card>
</CardGroup>

## The seven patterns

### 1. Lead-with-the-answer

LLMs retrieve chunk-by-chunk. The first chunk that matches the query wins. Put the answer in the first paragraph, not after a build-up.

```markdown
❌ Build-up — LLM retrieves the intro paragraph, has nothing to cite

# Rate limits

Acme implements a rate-limiting system to protect our infrastructure
and ensure fair use for all customers. We continually monitor...

✅ Answer first — LLM retrieves the first paragraph, has the limit to cite

# Rate limits

Default limit: 100 requests per minute per API key. Enterprise plans
scale to 1000/min. Exceed the limit → HTTP 429 with `Retry-After` header.
```

### 2. Query-matching headings

The retrieval step matches query keywords to heading text. "How do I add a CAA record" searches for "CAA record" — make sure your heading says that exactly, not "DNS records" or "SSL preparation".

```markdown
❌ Vague                    ✅ Query-matching
## DNS                       ## CAA records
## Configuration             ## Environment variables
## More info                 ## Rate limit error codes (429)
## Getting started           ## Install the SDK via npm
```

One query per heading. Multiple-question headings ("DNS + SSL + CAA") confuse the matching.

### 3. Quotable fact sentences

LLMs pull sentences, not paragraphs. Write sentences the synthesiser can drop into an answer without editing.

- **Complete.** "Default limit: 100 req/min" beats "we set a reasonable limit."
- **Self-contained.** "Acme's API returns JSON." beats "It returns JSON." — pronouns don't survive chunking.
- **Imperative when instructive.** "Add the CAA record: `acme.com. IN CAA 0 issue letsencrypt.org`" beats "You might want to add a CAA record."

### 4. Structured data wins citations

LLMs prefer quoting structured content over prose. Given two equivalent pages, the one with a table gets cited.

<CardGroup cols={2}>
  <Card title="Tables" icon="table">
    Per-field semantics, numeric limits, pricing tiers, HTTP status codes. LLMs quote table rows intact.
  </Card>
  <Card title="Code blocks" icon="code">
    Commands, config snippets, curl examples. Round-trip cleanly through every LLM.
  </Card>
  <Card title="ParamField / ResponseField" icon="list-tree">
    API docs with explicit `type` / `required` / `default` cite cleanly. Loose prose descriptions ("you'll probably want to set...") don't.
  </Card>
  <Card title="Step-by-step lists" icon="list-ordered">
    Imperative numbered steps are the highest-citation format for how-to content. Paragraph walkthroughs lose.
  </Card>
</CardGroup>

### 5. Canonical URL + `<link rel="canonical">`

LLMs cite URLs. If your page lives at `https://docs.acme.com/api/custom-domain` but the canonical URL points to `https://acme-docs.vercel.app/api/custom-domain`, the LLM cites the Vercel URL — embarrassing and potentially broken on deploy.

NookDocs emits canonical tags automatically. When you add a [custom domain](/deploy/custom-domain) and mark it primary, every page's `<link rel="canonical">` updates. Verify once after adding a domain:

```bash
curl -sI https://docs.acme.com/any-page | grep -i canonical
# Link: <https://docs.acme.com/any-page>; rel="canonical"
```

### 6. First-paragraph definition

Glossary-style first paragraphs rank in answer boxes. LLMs synthesise "what is X?" questions by pulling the first definition they find.

```markdown
✅ First paragraph defines the term

# Rate limits

Acme enforces 100 requests per minute per API key by default, returning
HTTP 429 with a `Retry-After` header when exceeded. Enterprise customers
can request higher limits via support.
```

This one paragraph will cite for "what is Acme's rate limit", "how many req/min does Acme allow", "does Acme rate limit by API key", and "what HTTP status does Acme return for rate limit?".

### 7. Freshness signals

LLMs prefer fresh sources when synthesis uncertainty is high. Signals the retrieval step uses:

- **`<time>` tags + ISO dates** in visible prose ("Updated 2026-04-20")
- **NookDocs' Last Updated footer** — automatically emitted from the last git commit touching the file
- **Year in heading or subtitle** — "2026 API changes", "Q2 2026 updates"
- **Changelog pages** with recent `<Update date="...">` entries

Dates from 2+ years ago get deprioritised. Pages with no date at all get assumed-stale and deprioritised further.

## Where each AI engine gets its content

| Engine | How it fetches your page | GEO implication |
|---|---|---|
| **ChatGPT (browse)** | Bing search → top N → read HTML + render | Classic SEO signals matter for the initial retrieval. GEO structure matters for citation. |
| **Perplexity** | Own index + Bing. Checks `/llms.txt` when present. | `/llms.txt` presence is a real signal. NookDocs auto-generates. |
| **Claude.ai Projects** | User pastes URL. Claude fetches HTML + checks `/llms.txt` / `/<slug>.md`. | LLM-optimised endpoints win — ship both. |
| **Google AI Overviews** | Same index as Google search. Schema.org + featured-snippet patterns rank. | JSON-LD `TechArticle` / `BreadcrumbList` / `Organization` / `FAQPage` — **NookDocs emits these automatically** (tune via [GEO config](/configuration/geo)). |
| **Bing Copilot** | Bing index + content-type negotiation. | `Accept: text/markdown` returns raw MDX (roadmap on our side). `.md` URL suffix works today. |
| **Google Gemini / Bard** | Google index. Schema-driven. | Same as AI Overviews. |

Takeaway: emit rich HTML for classic search bots, AND emit `/llms.txt` + `/<page>.md` for AI crawlers. NookDocs does both automatically.

## What NookDocs emits automatically

Every page ships **JSON-LD structured data** — the format AI Overviews,
Perplexity, and Gemini parse to understand and cite a page:

- `TechArticle` — headline, description, dates, author, keywords, license
- `BreadcrumbList` — the page's place in your nav hierarchy
- `Organization` + `WebSite` — your publisher entity (name, logo, `sameAs`)
- `FAQPage` — from a page's frontmatter `faq` (see below)

Tune it with the [`geo` config block](/configuration/geo): set your
`organization.sameAs` profiles, primary `topics`, content `license`, and a
custom `/llms.txt` intro. You can also control which AI crawlers may access
your site (`geo.aiCrawlers`). Everything is on by default — a site with no
`geo` block still emits sensible structured data.

### FAQ schema

Add a `faq` array to any page's frontmatter and NookDocs emits a `FAQPage` —
the single most cited format in answer engines:

```yaml
---
title: Rate limits
faq:
  - q: What is the default rate limit?
    a: 100 requests per minute per API key.
  - q: What happens when I exceed it?
    a: The API returns HTTP 429 with a Retry-After header.
---
```

## Anti-patterns

<AccordionGroup>
  <Accordion title="Optimising for clicks over citations">
    Clickbait titles + withheld answers worked for classic SEO. GEO punishes this — if the LLM can't find the answer in your page, it cites someone who put the answer up front.
  </Accordion>
  <Accordion title="Single giant page per feature">
    10,000-word "Complete Guide to X" pages chunk into ~20 windows. Retrieval picks 1-2. Most of your page is dead weight and none of it's specific enough to cite. Split into focused 500-800 word pages.
  </Accordion>
  <Accordion title="Synonym sprawl">
    Calling the same thing "API key" in one paragraph, "credential" in the next, "token" in the third. LLMs match on exact terms; synonyms halve your chance of retrieval.
  </Accordion>
  <Accordion title="No dates, no version labels">
    An LLM doesn't know if "you'll see the new settings panel" is from 2022 or last week. Date every claim that could age.
  </Accordion>
  <Accordion title="Screenshots carrying key facts">
    "Click the button highlighted in red below." LLMs can't see the image. State the location in prose: "Click **Save** in the bottom-right of the dialog."
  </Accordion>
  <Accordion title="Paywalled or auth-gated reference content">
    LLMs can't read what they can't crawl. If you want the AI engines to help users with your product, reference content has to be public. Put tutorials behind auth; keep the reference open.
  </Accordion>
</AccordionGroup>

## Measuring GEO success

Classic SEO tracks impressions, clicks, rankings. GEO tracking is harder because AI engines don't expose impressions or ranks. Proxies that work:

1. **AI traffic referrer.** Check for `chat.openai.com`, `perplexity.ai`, `claude.ai`, `gemini.google.com` in your analytics referrer field. Not precise but signals "users are coming here from AI answers".
2. **Manual LLM spot-checks.** Weekly, ask the top 5-10 questions about your product in ChatGPT + Perplexity + Google AI. Note whether your docs are cited. Trend over time.
3. **Brand mention tracking.** Tools like Profound, Otterly, HubSpot AI Grader track "does the LLM mention your brand when answering relevant questions?". Early-stage, mostly heuristic.

Expect messy data. The discipline is about patterns (see the seven above), not dashboard-watching.

## Related

- [Writing for LLMs](/guides/writing-for-llms) — sibling guide, focused on the authoring mechanics
- [Style and tone](/guides/style-and-tone) — foundations
- [Content types](/guides/content-types) — Diátaxis helps you split mega-pages into focused ones
- [llms.txt](/optimize/llms-txt) — the auto-generated LLM crawler index
- [SEO](/optimize/seo) — classic search optimisation that complements GEO
- [Markdown export](/optimize/markdown-export) — the `/<page>.md` endpoint

---

# Git concepts for writers
Source: https://docs.nookdocs.com/guides/git-concepts

Minimum viable Git for docs writers who've never used it. Commits, branches, pull requests, merge conflicts — explained in prose, not jargon, with the specific NookDocs workflow baked in.

Docs on NookDocs are stored in a Git repository. Most writers use the dashboard editor + never see Git directly — changes save, the site updates, no CLI involved. But when you collaborate with engineers, review a pull request, or hit a merge conflict, understanding Git's model helps.

This guide is the minimum viable Git for writers. No terminal commands. No developer jargon. Just the mental model.

## The mental model

<CardGroup cols={2}>
  <Card title="Repository = a folder that remembers every change" icon="folder">
    The docs repo is a folder. Git remembers every version of every file in it — forever. You can always go back.
  </Card>
  <Card title="Commit = a snapshot of all the files, with a note" icon="camera">
    When you save, you take a "commit" — a frozen copy of every file at that moment, plus a short message explaining what changed.
  </Card>
  <Card title="Branch = a parallel timeline of changes" icon="git-branch">
    `main` is the timeline everyone sees on the live site. You work on a separate "branch" while editing so your changes don't go live until reviewed.
  </Card>
  <Card title="Pull request = 'please merge my branch into main'" icon="git-pull-request">
    When your changes are ready, you open a PR asking teammates to review + merge. The PR shows a diff (what you changed vs what's live).
  </Card>
</CardGroup>

## The three ways changes reach production

<Steps>
  <Step title="Via the dashboard editor (most writers)">
    Open the editor. Edit a page. Click **Save**. Behind the scenes, NookDocs commits your change to Git + pushes to the remote. The site updates in ~30 seconds. No branches, no reviews — direct to `main`.
    **When to use:** small edits, typos, adding a paragraph, no coordination needed.
  </Step>
  <Step title="Via a pull request (reviewed changes)">
    An engineer opens a branch. They edit files. They push. They open a PR asking for review. A reviewer checks, comments, approves. The PR merges to `main`. Site updates.
    **When to use:** bigger rewrites, structural changes, anything needing a second pair of eyes.
  </Step>
  <Step title="Via Git directly (engineer-heavy teams)">
    Clone the repo locally, edit in VS Code, commit, push. Same underlying flow as #2, just without the browser. Faster for power users.
    **When to use:** batch edits across 20+ files, or when the dashboard editor doesn't support the workflow.
  </Step>
</Steps>

Most docs sites use a mix — writers live in the dashboard, engineers use Git directly, PRs handle the coordination.

## Why branches matter

Without branches, every save goes live immediately. That's fine for a typo fix. Bad for a 3-day rewrite where the page would be half-broken during the work.

Branches let you:

- Work for days or weeks without affecting live docs.
- Get feedback from teammates BEFORE users see your changes.
- Abandon experiments without cleaning up live pages.
- Collaborate — two writers working on related pages can each have their own branch.

**Rule of thumb:** anything over 20 minutes of work wants a branch. Quick fixes can go straight to `main` via the dashboard.

## What a commit looks like

Every commit has three parts:

1. **A diff** — which lines in which files were added, removed, or changed.
2. **A message** — a short note from the author explaining the "why".
3. **Metadata** — who, when, from which parent commit.

Example commit message:

```text
docs(theme): expand theme.mdx from 29 to 177 lines

Added ParamField tables for every color / font / icon token, a
complete example JSON block, precedence rules, dashboard editing
notes. Covers Mintlify parity depth + adds the typography overrides
our multi-theme system supports.
```

Good commit messages have:

- **A summary line** (under 72 chars) — what changed.
- **A body** (optional) — why it changed or context for reviewers.

## What a merge conflict is

When two people edit the same lines of the same file and both try to merge, Git doesn't know which version wins. That's a merge conflict.

Example:

```text
Alice edits:
  "The feedback widget appears at the bottom of every page."

Bob edits the same line:
  "The feedback widget renders under the last article paragraph."
```

When Bob's branch tries to merge and Alice's change is already on `main`, Git marks the file:

```text
<<<<<<< (Alice's version)
The feedback widget appears at the bottom of every page.
=======
The feedback widget renders under the last article paragraph.
>>>>>>> (Bob's version)
```

Somebody (usually Bob, since he's merging last) has to pick which version stays — or write a third version combining both. After resolving, the merge completes.

Conflicts are normal. Don't panic. If one happens in your PR, ask the engineer who reviewed it for help the first few times.

## Git on NookDocs — the hosted flow

NookDocs is a "managed repo" platform — your docs live in a GitHub repository, either in our `nookdocs-projects` org (managed) or your own. The GitHub App syncs changes automatically:

<Steps>
  <Step title="You save in the dashboard">
    Dashboard editor commits to your repo via our GitHub App + pushes to `main`.
  </Step>
  <Step title="Webhook fires">
    GitHub sends a webhook to NookDocs saying "this repo got a new commit".
  </Step>
  <Step title="Sync job runs">
    Our Trigger.dev job fetches the new commit, parses MDX, updates the Postgres pages table.
  </Step>
  <Step title="Site updates">
    Within ~30 seconds of save, the public site serves the new content.
  </Step>
</Steps>

You can also push directly via Git (engineers) — the webhook fires the same way.

## Terms you'll see in the dashboard

- **Commit history** — list of all the changes to a page. Click any entry to see the diff.
- **Last updated** — the date of the most recent commit touching this page. Shown at the bottom of every docs page.
- **Branch selector** — which branch the editor is working on (usually `main`).
- **Deploy status** — did the most recent commit successfully sync to the DB? Green = yes, red = something broke.

## When things go wrong

### "My change isn't live"

1. Check the commit landed in the repo. Dashboard Git panel should show your recent change.
2. Check the deploy status on the project detail page. If red, a sync error happened — open the deployment detail + read the log.
3. Wait 30-60 seconds. Sync is async; small delay is normal.
4. Force refresh (Cmd+Shift+R) — your browser might be caching.

### "Someone reverted my change"

Not uncommon in team workflows. Check the Git history. If an engineer force-pushed or reverted, they should have left a commit message explaining why. Ask them directly.

### "I broke the build"

Parse errors (invalid MDX) block the site deploy. The failed deployment shows which file + what line. Open the file, fix the issue, save again. See [maintenance](/guides/maintenance) for common MDX issues.

## When to ask for help

- **First merge conflict** — always. Conflicts are learnable but easier with someone watching over your shoulder.
- **Reverting something you didn't mean to commit** — Git "reset"/"revert" commands are dangerous. Ask an engineer.
- **Your PR has 50 comments** — step back. Usually means there's a scope problem, not 50 specific fixes. Ask the reviewer for a higher-level call.

## What writers don't need to know (but might hear)

Vocabulary you'll encounter but can usually ignore:

- **Rebase** — re-ordering commits. Engineering-level Git surgery.
- **Cherry-pick** — copying specific commits. Niche.
- **Stash** — temporarily shelving uncommitted changes.
- **HEAD** — "where you are right now in the timeline".
- **Origin / remote** — the GitHub-hosted copy of the repo vs your local copy.

Engineers use these routinely. Writers usually don't need to — the dashboard editor abstracts them.

## Related

- [Branches for docs writers](/guides/branches) — deeper dive into branching strategies for docs teams
- [Configure automerge](/guides/configure-automerge) — reduce review friction on low-risk changes
- [Maintenance](/guides/maintenance) — Git's role in the freshness audit
- [Managed repo](/github/managed-repo) — NookDocs's hosted GitHub org model
- [Self-hosted repo](/github/self-hosted-repo) — wiring your own repo

---

# Help center
Source: https://docs.nookdocs.com/guides/help-center

Support-style docs for end-users, not developers. FAQ patterns, troubleshooting trees, and how to keep the content from duplicating your support team's inbox.

A help center is docs for **end-users** — people using your product, not building with your API. Support articles, FAQs, troubleshooting guides, billing questions. Different audience, different voice, different IA than developer docs.

Most help centers fail for one of two reasons: they duplicate support tickets (same question asked 30 times → not answered in docs) or they over-engineer the IA (10-level category trees nobody navigates). This guide covers the help-center patterns that work.

## Help center vs developer docs

| Axis | Developer docs | Help center |
|---|---|---|
| **Primary audience** | Engineers integrating or operating | End-users, admins, billing contacts |
| **Voice** | Imperative, dense, terse | Conversational, reassuring, patient |
| **Primary affordance** | API reference, code examples | Step-by-step walkthroughs, FAQ |
| **Search intent** | "How do I authenticate against the API?" | "Why am I getting charged?" |
| **Media ratio** | Low (code over screenshots) | High (screenshots, recordings) |
| **Maintenance cadence** | Per-release | Per support-ticket trend |

Mixing the two in one site confuses both audiences. Either separate tabs (NookDocs supports this) or separate subdomains (`docs.acme.com` vs `help.acme.com`).

## The four section pattern

Most help centers fit this shape:

<CardGroup cols={2}>
  <Card title="1. Getting started" icon="rocket">
    First-time user onboarding. "How to sign up", "How to invite your team", "How to set up billing". The 5-10 pages every new account reads.
  </Card>
  <Card title="2. Features / how-to" icon="list-checks">
    Feature-specific walkthroughs. One page per significant product feature. Lots of screenshots; end-users expect visual proof.
  </Card>
  <Card title="3. Troubleshooting + FAQ" icon="alert-circle">
    Common errors + fixes. FAQs from actual support tickets. This section usually has the most page-views-per-page of any help center.
  </Card>
  <Card title="4. Billing + account" icon="credit-card">
    Pricing, upgrades, cancellations, invoicing, refunds. Quarantine billing questions here — they get high traffic and deserve their own section.
  </Card>
</CardGroup>

Advanced help centers add:

- **Use cases / recipes** — "How teams use Acme for customer research".
- **Integrations** — non-developer-facing ("How to connect Acme to Slack").
- **Admin guides** — for org/team admins vs individual users.

## Voice tuned for non-technical users

Most technical-writing best practices still apply ([style and tone](/guides/style-and-tone)), with shifts:

- **More conversational.** First sentence often asks the reader's question back: "Wondering why you got charged twice? Here's what happened."
- **More reassuring.** "Don't worry" appears here where it'd be banned in dev docs. End-users frame problems emotionally.
- **More step-by-step hand-holding.** Where dev docs assume readers know terms, help docs define every term on first use.
- **Fewer links.** Dev docs can link densely because engineers parse links fast. End-users get overwhelmed. 3-5 links per page max.
- **More visual.** Screenshots of every non-trivial UI step, not just tricky ones.

### Before / after

```markdown
❌ Dev-doc voice in help center
Rotate your API key by POST-ing to /v1/api-keys with a valid
authenticated session. The response returns the new key; the old key
is revoked immediately.

✅ Help-center voice
Your API key is like a password for your Acme integrations. If it
might have been exposed (you shared it by accident, or you're
rotating it for security), here's how to generate a new one:

1. Open **Settings** → **API keys** in the dashboard.
2. Click **Rotate key** next to the key you want to replace.
3. Confirm. Your old key stops working immediately — be sure to
   update any integrations using it.
4. Copy the new key and store it somewhere safe (password manager is
   ideal).

If an integration breaks after rotating, it's likely still using
the old key. Check the integration's settings.
```

Same information, different register.

## FAQ pages that actually help

FAQ pages are the most-read + most-often-bad help content. Patterns:

### Good FAQ pattern

```mdx
<AccordionGroup>
  <Accordion title="Why was I charged twice this month?">
    Almost always, this is a proration — you upgraded mid-cycle and
    got charged the remaining days at the new rate. The higher charge
    is your new monthly amount, starting on the upgrade date. Check
    **Billing → Invoices** — both line items will appear there.

    If you see two full-month charges, that IS a billing bug. Open a
    ticket from Billing → Help; include both invoice numbers.
  </Accordion>

  <Accordion title="Why can't I delete my account?">
    Account deletion requires no active subscription, zero pending
    invoices, and the account to be at least 7 days old (anti-fraud
    delay). Cancel any active subscriptions first, wait for invoices
    to settle, then retry. Full walkthrough in
    [Cancelling your account](/account/cancel).
  </Accordion>
</AccordionGroup>
```

Each answer: the actual answer in the first sentence, the edge cases + escalation path after.

### Bad FAQ pattern

```mdx
❌ Too brief
Q: Why was I charged twice?
A: It could be a proration. Check your invoices.

❌ Too verbose
Q: Why was I charged twice?
A: Ah, this is a really common question. Our billing system uses
a technique called "proration" which is industry-standard. When you
make changes to your subscription mid-cycle, we calculate... (700
more words explaining billing theory)

❌ No escalation path
Q: Why was I charged twice?
A: It's probably a proration. [End of answer.]
```

Users stuck on "why was I charged" need: the answer, a self-serve verification step, and (for the 5% where the answer doesn't fit) a clear escalation path.

## Troubleshooting trees

For issues with multiple possible causes, structure as a decision tree:

```mdx
## My webhook isn't firing

### Is the webhook endpoint returning 2xx?

Check your server logs for any requests to the webhook URL in the
past 10 minutes.

**If yes — requests arrived but you expected different content:**
- Verify the `Content-Type: application/json` header was set.
- Compare the payload against [webhook schema](/webhooks/schema).

**If no — no requests arrived:**
- Is the webhook URL reachable from the internet? Test with
  `curl -X POST https://your.com/webhook -d '{}'`.
- Is the endpoint in the dashboard **enabled**? Check
  **Settings → Webhooks**.
- Has the endpoint failed more than 10 times? We auto-pause after
  repeated failures. Re-enable from **Settings → Webhooks**.

### If none of the above...

[Open a ticket](/support) with:
- Webhook endpoint URL
- The event ID you expected to trigger (from the event log)
- Your server's log showing no matching incoming request
```

Each decision point routes to a specific next-step. Users who can self-serve do. Users who can't arrive at the ticket form with the exact info support needs.

## Screenshots in help content

Much more generous than dev docs:

- **Every UI reference** has a screenshot. "Click the Save button" → screenshot showing the button highlighted.
- **Annotated with arrows or circles** — end-users miss unmarked details.
- **Retake every quarter** — UI changes, screenshots age. See [maintenance guide](/guides/maintenance).
- **Alt text is even more important** — some end-users rely on screen readers; some on slow connections. See [accessibility](/guides/accessibility).

Exceptions where you DON'T need a screenshot: decisions with three+ variables (use a table) or long linear flows (use a video or GIF).

## Support ticket integration

Help center + support team should share a priority queue:

<Steps>
  <Step title="Tag every support ticket by topic">
    Simple 1-word tag: billing / webhooks / auth / team / search / etc.
  </Step>
  <Step title="Weekly: top 3 topics by volume">
    Look at last week's ticket tags. The top 3 are your content gaps.
  </Step>
  <Step title="Does a page exist for each?">
    Top topic is "billing proration". Does `/help/billing/proration` exist? Is it the first search result for "why was I charged twice"?
  </Step>
  <Step title="If no page — write one">
    Draft from the best-quality support replies. Attribution to the support agent who wrote the original answer.
  </Step>
  <Step title="If page exists but isn't found — improve SEO">
    Add the user's exact phrasing to the H1 or first paragraph. Support team now copy-pastes link when answering the question. Over time, the ticket volume drops.
  </Step>
</Steps>

Over ~6 months, a disciplined support-to-docs pipeline can reduce ticket volume by 30-50% on high-frequency topics.

## When to use ticket-deflection chat vs docs

Many help centers add chatbots ("ask Oscar, our AI support agent"). The economics:

- **Chat works well for** — narrow-scope products with clear answers. "When does my trial end?" → chatbot can answer. "How do I integrate Acme with our custom auth flow?" → escalate.
- **Chat works badly for** — anything requiring judgement, anything where the LLM doesn't have access to user state, anything emotionally charged (billing disputes, account deletion).
- **Docs always supplement chat** — even the best chatbot routes to docs for long explanations. Your docs are the underlying source of truth.

NookDocs's [AI assistant](/configuration/ai-assistant) is a chatbot pattern, but powered by your docs as RAG source. Enable it on the help center tab and it handles 60-70% of basic questions without escalation.

## Internationalization consideration

End-users are more likely to be non-English-speakers than developers are. Help centers often need translation (`/fr/help`, `/es/help`) before dev docs do. See [internationalization](/guides/internationalization) for the setup.

Translation tips for help-center content specifically:

- **Professional translation over MT** — help content handles emotionally-sensitive topics (refunds, account issues). Machine translation errors here damage trust.
- **Regional variations matter** — "billing" and "invoicing" are the same to a US reader but different UX terms in some markets.
- **Currency + dates** — `$29/month` vs `€29/month` vs `¥3500/month`; `04/20/2026` vs `20/04/2026`.

## Common help-center mistakes

<AccordionGroup>
  <Accordion title="Same content on the marketing site AND help center">
    Pricing page on marketing says "$29 for Pro". Help center billing page says "$29 for Pro". When pricing changes, one gets updated. Readers see conflicting numbers + lose trust. Pick one canonical location.
  </Accordion>
  <Accordion title="FAQ that's really just brainstorm">
    "Frequently Asked Questions" where the questions weren't asked by anyone. Look at support tickets for real FAQs; don't invent.
  </Accordion>
  <Accordion title="Deep category nesting">
    Help → Account → Settings → Preferences → Notifications → Email → Digest. Flatten. End-users don't navigate 6 levels.
  </Accordion>
  <Accordion title="No contact link in troubleshooting dead-ends">
    Page ends with "If none of these solutions work, please contact support" with no link to support. Always include a link.
  </Accordion>
  <Accordion title="Outdated screenshots everywhere">
    UI redesigned 6 months ago. Every screenshot in the help center shows the old UI. End-users can't find the buttons. Quarterly screenshot audit is non-negotiable.
  </Accordion>
  <Accordion title="Help content locked behind login">
    "Sign in to see the answer to this question." Makes Google indexing impossible + pisses off users who haven't paid yet. Keep help content public; gate only account-specific info.
  </Accordion>
</AccordionGroup>

## Related

- [Developer documentation](/guides/developer-documentation) — sibling guide for the dev audience
- [Understand your audience](/guides/understand-your-audience) — end-user personas
- [Style and tone](/guides/style-and-tone) — voice patterns
- [Accessibility](/guides/accessibility) — especially relevant for end-user content
- [Internationalization](/guides/internationalization) — help content translation strategy
- [AI assistant config](/configuration/ai-assistant) — chatbot setup for support deflection

---

# Improving docs
Source: https://docs.nookdocs.com/guides/improving-docs

Metrics-driven iteration for documentation. The specific signals that indicate a page is failing, the ones that indicate it's winning, and how to set up a weekly review rhythm that actually ships improvements.

Docs improve the way software improves: someone notices a problem, someone diagnoses the cause, someone writes the fix, the fix ships. The difference is that docs teams usually don't have a bug tracker for content, don't have QA, and don't have release notes. Without structure, "improve the docs" becomes "rewrite the landing page for the fifth time this year" instead of fixing the ten pages driving the most user confusion.

This guide covers the signals that tell you what to improve, and the cadence that keeps improvement from becoming someone's side quest that never lands.

## Why metrics matter

<CardGroup cols={2}>
  <Card title="Intuition runs out" icon="brain">
    You've been inside the product for months. Every page looks fine to you. Users see broken flows you're blind to. Metrics surface what intuition misses.
  </Card>
  <Card title="Prioritisation gets easier" icon="list-ordered">
    "Rewrite 20 pages this quarter" without data picks the wrong 20. With data you pick the 20 that matter.
  </Card>
  <Card title="Victories are measurable" icon="award">
    "We improved the quickstart" doesn't justify your salary. "Completion rate on the quickstart went from 34% to 67% after the rewrite" does.
  </Card>
  <Card title="Scope stays bounded" icon="ruler">
    Without metrics, every page is "could be better" and rewrites sprawl. With metrics, you stop when the numbers improve.
  </Card>
</CardGroup>

## The five signals

### 1. Search queries returning zero results

The highest-leverage signal. Users typed something, your docs had nothing. Every zero-result query is either:

- A missing page you should write, or
- An existing page whose heading / alt terms don't match user vocabulary.

NookDocs's [analytics](/configuration/analytics) surfaces this in Top searches. Target: drive zero-result queries to under 5% of total searches.

Weekly routine:

```text
1. Open analytics → Top searches.
2. Filter to "no results" (column sorts zero first).
3. For each top query:
   - Does a page already cover this? (If yes → the page needs better H2s)
   - Is this a missing feature we should document? (If yes → write the page)
   - Is this a rare typo / joke query? (If yes → ignore)
```

### 2. High-bounce pages in the quickstart / tutorial path

Any page that's supposed to be step 1 → 2 → 3 of a flow, but where >50% of arrivers bounce, is broken.

```text
Expected: /quickstart → /quickstart/step-2 → /quickstart/step-3
Actual:   70% of /quickstart arrivers never reach step-2
```

Diagnostics:

- **Page too long?** Scroll-depth tracking (if you have it) — do users reach the "Next" link? If they're bouncing before scrolling, the intro is failing.
- **Broken example?** Copy-paste a snippet from the page into a fresh terminal. Does it work? 10% of bounces are "the example doesn't work."
- **Wrong prerequisites?** The page assumes Node 20 but many users have 18. Explicit prereq list up front.
- **Dense text?** Tutorial pages suffer from walls of prose. Break into steps; add code blocks; add screenshots.

### 3. Support tickets with URLs

Every ticket that includes a link to a specific docs page is a signal that the page didn't answer the question.

Monthly routine:

<Steps>
  <Step title="Dump last month's tickets">
    Export to a spreadsheet. Two columns: URL referenced, what the user was trying to do.
  </Step>
  <Step title="Group by URL">
    Pivot by the linked page. Top URLs are the ones with documentation gaps.
  </Step>
  <Step title="Read the top 10 pages with their tickets open side-by-side">
    "The user was trying to X but our page says Y" — mismatches become obvious.
  </Step>
  <Step title="Pick one fix per page">
    Either add a section answering the specific question, or rewrite the existing section that was ambiguous.
  </Step>
</Steps>

Target: support ticket count per docs page should trend down over time. If it's flat or rising, the page isn't improving.

### 4. Feedback widget thumbs-down with comments

NookDocs's built-in [feedback widget](/configuration/feedback) prompts readers for thumbs-up/down + a comment. Thumbs-down comments are direct user testing data you didn't have to run.

Patterns to notice:

- **"Outdated"** — screenshot / example / instructions don't match current UI. Fix and freshness-stamp.
- **"Incomplete"** — the answer stops before the reader's actual question. Add the missing step or edge case.
- **"Wrong"** — factual error. Fix urgently. Wrong docs erode trust faster than missing docs.
- **"Confusing"** — reader didn't know what to do after reading. Usually a voice + structure problem — see [style and tone](/guides/style-and-tone).

Aim to respond to every thumbs-down within a week during the first few months of shipping a page. After that, monthly review is enough.

### 5. Time-to-first-success

The most important metric and the hardest to measure. How long from landing on your docs to "the reader has something working"?

Proxies that work:

- **Signup → first API call** (if you're a SaaS API) — measurable in backend analytics.
- **Signup → first successful deploy** (if you're a dev platform).
- **Landing → completion of the quickstart** (if your quickstart ends with a clear "complete" signal, e.g. a success page or a redirect).

Benchmarks vary by product. For a dev-tool quickstart: under 5 minutes is great, 5-15 is fine, 15-30 is a concern, 30+ is a crisis.

## The improvement playbook

Given a page that's clearly failing (high bounce + support tickets + thumbs-down), run this sequence:

<Steps>
  <Step title="Open the page with a fresh reader">
    Someone who hasn't used the product. Watch them read it. Note where they pause, scroll back, frown, ask questions. 10 minutes of watching = 10 hours of analytics.
  </Step>
  <Step title="List the specific problems observed">
    "The reader didn't know what 'the widget' referred to in paragraph 3." "Couldn't find the Save button the instructions mentioned." Write each as a concrete user observation, not an abstract critique.
  </Step>
  <Step title="Pick the top 2-3 problems and fix only those">
    Don't rewrite from scratch. Targeted surgery. Each fix you make should map to a specific observed problem.
  </Step>
  <Step title="Ship it + date-stamp the change">
    `Last updated:` footer auto-updates from git. Commit message names the change so the next diagnostic has context.
  </Step>
  <Step title="Re-measure after two weeks">
    Did the bounce rate improve? Did the support tickets on this URL drop? If not, the fix missed the real problem — go back to step 1.
  </Step>
</Steps>

## The weekly review rhythm

30 minutes weekly, same day + time every week. Calendar block it.

<Steps>
  <Step title="Open the analytics dashboard">
    Top search queries (zero results first).
    Top pages by bounce rate.
    Top feedback comments.
  </Step>
  <Step title="Pick the one highest-leverage item">
    Usually the top zero-result query or the highest-volume bounce page. One page per week; don't spread.
  </Step>
  <Step title="Do the 5-step improvement playbook">
    Above. 30 min is enough for most fixes — a heading rewrite, a missing paragraph, an added code example.
  </Step>
  <Step title="Commit + push">
    Ship in the same session. Don't batch.
  </Step>
  <Step title="Log what you changed + why">
    Simple spreadsheet: date, page, change, measured problem, hypothesis. Review quarterly to see which types of changes produced the biggest metric improvements.
  </Step>
</Steps>

Weekly rhythm > quarterly "docs sprint". A sprint ships 20 changes at once and you can't attribute impact to any one of them. Weekly ships 1 change you can isolate.

## Quarterly audits

Broader lens, every ~12 weeks:

<CardGroup cols={2}>
  <Card title="Page inventory audit" icon="list">
    List every page. Flag ones not touched in 12+ months. Read each — is it still accurate? Fix or retire.
  </Card>
  <Card title="Search query trend" icon="trending-up">
    Compare this quarter's top queries vs last. New queries emerging signal new use cases you should cover. Dropped queries may indicate features users no longer hit.
  </Card>
  <Card title="IA check" icon="map">
    Readers finding what they need in two clicks? Sidebar still matches your product's shape? See [navigation guide](/guides/navigation).
  </Card>
  <Card title="LLM spot-check" icon="bot">
    Ask ChatGPT/Claude/Perplexity the top 5 questions about your product. Are your docs cited? If not, see [GEO](/guides/geo).
  </Card>
</CardGroup>

## Metrics that DON'T matter (mostly)

<AccordionGroup>
  <Accordion title="Total pageviews">
    Big number, satisfying to watch climb. Doesn't tell you anything about whether users found what they needed. Up + bounce rate up = getting more wrong traffic. Up + bounce down = getting more right traffic. Only the second is improvement.
  </Accordion>
  <Accordion title="Average time on page">
    Longer time usually means more confusion, not more engagement. Reference docs should be FAST to consume. Watch for TTFirstSuccess or task completion instead.
  </Accordion>
  <Accordion title="Word count">
    "Our docs grew to 100,000 words" means nothing. Quality per word matters, not words. Long pages often rank worse than short focused ones. See [SEO guide](/guides/seo).
  </Accordion>
  <Accordion title="Number of pages">
    "We have 500 docs pages" can mean "comprehensive" or "sprawling orphan graveyard". What matters is whether every page is linked, maintained, and solving real user problems.
  </Accordion>
  <Accordion title="Social shares / likes">
    Docs rarely get shared. A technical writing blog post can. A reference page on rate limits won't. Don't optimise docs for share-ability; optimise for the reader who's stuck.
  </Accordion>
</AccordionGroup>

## When you have no metrics

Early-stage products often launch docs before any measurable traffic. In that case:

1. **Ship the quickstart you're most confident in.** Don't wait for data.
2. **Watch 3-5 users complete it live.** Zoom + screen share. One hour gives you more signal than a quarter of analytics.
3. **Instrument early.** Add analytics on day one. Even low-volume data compounds.
4. **Cross-reference against support.** Even 5 tickets a week are signal.

Metrics help once you have 1000+ sessions/week. Before that, direct observation + team dogfooding is higher quality.

## Measure before AND after

The discipline that separates real improvement from theater: **measure the SAME metrics before AND after**. Don't just ship and declare victory.

```text
Pre-change measurements (baseline)
  /quickstart bounce rate: 67%
  /quickstart → /quickstart/step-2: 33%
  Support tickets referencing /quickstart: 14 last month
  Thumbs-down count: 8

[Ship the rewrite]

Post-change measurements (2 weeks later)
  /quickstart bounce rate: 41% (-26pp)
  /quickstart → /quickstart/step-2: 59% (+26pp)
  Support tickets referencing /quickstart: 4 this month (-71%)
  Thumbs-down count: 2 (-75%)
```

Numbers grounded the hypothesis. Attribution is defensible. Next improvement cycle has baseline.

## Common improvement mistakes

<AccordionGroup>
  <Accordion title="Rewriting the intro when the problem is mid-page">
    Intro paragraphs get rewritten most often because they're what writers see first. But most user confusion happens mid-page — a specific step, a specific code example, a specific screenshot. Diagnose before rewriting.
  </Accordion>
  <Accordion title="Big bang rewrites">
    "Let's do a full docs rewrite" takes 6 months, ships 1 change. Incremental improvements ship 24 changes over the same 6 months, each measurable. Ship weekly.
  </Accordion>
  <Accordion title="Optimising the wrong metric">
    "Pageviews are up 200%!" Pageviews coming from SEO on a topic you don't serve well = more bounces, more support tickets. Optimising pageviews = optimising the wrong metric.
  </Accordion>
  <Accordion title="Ignoring complaints that match existing hypotheses">
    You had a hunch the custom-domain docs were confusing. Three complaints roll in over three months. Each time, you think "one more data point". That's three data points. Ship a fix.
  </Accordion>
  <Accordion title="Not tracking which changes produced the improvement">
    Quarter ends, metrics improved, great. Which specific changes drove it? Was it the IA reshuffle, the new quickstart, the three bug fixes? Without a log, you can't reproduce the wins.
  </Accordion>
</AccordionGroup>

## Related

- [Analytics](/configuration/analytics) — the NookDocs dashboard these metrics come from
- [Feedback widget](/configuration/feedback) — the thumbs-up/down collector
- [Understand your audience](/guides/understand-your-audience) — personas that inform what "better" means per page
- [SEO for docs](/guides/seo) — search impressions as a metric source
- [Maintenance](/guides/maintenance) — sibling guide on keeping docs fresh over time

---

# Internationalization
Source: https://docs.nookdocs.com/guides/internationalization

Ship docs in multiple languages without burning out the translation budget. Strategy, tooling, RTL considerations, and the realistic priority order for when to translate what.

Translating docs is expensive. Professional translators bill ~$0.10-0.20 per word. A 20,000-word docs site hits $2,000-4,000 per language per major revision. Multiply by quarterly updates × 5 target languages and the budget runs deep into six figures. This is why most docs sites ship English-only for years.

But docs-in-your-native-language drives conversion rates dramatically — non-English speakers are 3-5× more likely to adopt a product when docs are in their language. Strategy matters: translate the right things in the right order, not everything at once.

This guide is about what to translate, when, and how — before you burn the budget on the wrong pages.

## When to internationalize (and when not to)

<CardGroup cols={2}>
  <Card title="Translate when..." icon="check">
    - You have real user traffic from a specific non-English market (analytics confirms)
    - Support tickets come in a non-English language at a sustainable rate
    - A major customer's contract requires it
    - Localised content gives you a compounding SEO advantage in a specific region
  </Card>
  <Card title="Don't translate when..." icon="x">
    - You're guessing a market will adopt your product once docs are translated (pre-market-fit translation is a bet, not a strategy)
    - Only 2% of traffic comes from non-English speakers (not worth the maintenance overhead)
    - You can't commit to keeping translations fresh (outdated translations worse than English-only)
    - Machine translation is "good enough" — for marketing maybe, for docs usually no
  </Card>
</CardGroup>

## The realistic priority order

Don't translate everything. Translate the highest-impact pages first:

<Steps>
  <Step title="1. Landing + Quickstart only">
    The two most-read pages. Translating these reduces evaluator bounce rate for the target language. Minimum viable internationalization.
  </Step>
  <Step title="2. Top 10 most-trafficked docs pages">
    Use analytics. Usually some mix of the main concepts page, auth, webhooks, errors list, pricing explainer.
  </Step>
  <Step title="3. Help center billing + account pages">
    Emotionally-sensitive content (payments, account deletion, privacy) benefits most from professional translation. Don't machine-translate these.
  </Step>
  <Step title="4. Remaining how-to guides">
    The 20-30 task-focused pages covering common use cases.
  </Step>
  <Step title="5. API reference — if at all">
    API reference is code-heavy and auto-generated. Translation overhead is high; reader benefit is low (developers reading API specs are usually comfortable in English). Often skip.
  </Step>
  <Step title="6. Changelogs, deep concepts, explanations">
    Lowest priority. Explanation pages are philosophical enough that translation distortion matters; many teams keep these English-only.
  </Step>
</Steps>

Most teams stop at step 2 or 3 — 15-25 translated pages cover 80% of user value.

## NookDocs's internationalization model

NookDocs supports language-aware navigation via the `languages` config key. Each language gets its own URL prefix and its own page tree:

```json
{
  "languages": [
    { "language": "en", "default": true, "label": "English" },
    { "language": "fr", "label": "Français" },
    { "language": "ja", "label": "日本語" }
  ]
}
```

Page structure:

```text
docs/
  introduction.mdx        ← default English
  fr/
    introduction.mdx      ← French
  ja/
    introduction.mdx      ← Japanese
```

URLs:

```text
docs.acme.com/introduction        (en, default)
docs.acme.com/fr/introduction     (fr)
docs.acme.com/ja/introduction     (ja)
```

Language switcher appears near the logo. Reader selects their language; sidebar updates to show that language's pages; search scopes to the selected language. See [localization config](/content/localization) for the full mechanics.

## Translation workflow — three approaches

### Approach 1: Full professional translation (highest quality, highest cost)

- Engage a vendor (Lokalise, Phrase, Crowdin) or direct translators.
- Per-page MDX files sent for translation. Component tags + URL anchors preserved; prose translated.
- Review cycle: translator draft → your native-speaker reviewer (ideally an employee in the market) → publish.
- Cost: $0.10-0.25/word. 20k-word site ≈ $2-5k per language per full translation.

Best for: customer-facing help center content, billing pages, legal text.

### Approach 2: Translation memory + hybrid (balanced)

- First pass via professional translation for the top 20 pages.
- Subsequent updates (minor edits, new pages) use a translation memory (TM) tool — the tool proposes translations based on prior approved ones + MT for new content.
- Human reviewer on each proposal before merge.

Best for: mature docs that stabilise + get minor updates.

### Approach 3: Machine translation (lowest quality, near-zero cost)

- Google Translate / DeepL API for bulk generation.
- Optional: lightweight human proofread.
- Usually lands at 70-85% quality for simple prose; worse for technical docs with terminology.

Best for: explanation / concept pages where approximate-correctness is OK. NEVER for security / billing / legal content where a mistranslation is dangerous.

## Handling terminology

Technical docs have product-specific terms that shouldn't be translated:

- **Brand names**: "Acme" stays "Acme" in every language.
- **API field names**: `customer_id` stays `customer_id`.
- **Feature names**: "Smart routing" might stay "Smart routing" or get a localised name — decide upfront, apply consistently.
- **Code examples**: Don't translate variable names, comments, or strings in code.

Build a glossary early. Share with all translators. Update when product naming changes.

Example glossary entry:

```yaml
- en: "API key"
  fr: "clé API"       # translated, lowercase kept
  de: "API-Schlüssel" # hyphenated per German convention
  ja: "APIキー"       # katakana for "API"

- en: "workspace"
  fr: "workspace"     # kept English — used as feature name
  de: "Workspace"     # kept English, German capitalisation rule
  ja: "ワークスペース" # transliterated
```

Decide per term whether to translate or keep English. Write both down.

## RTL (right-to-left) languages

Arabic, Hebrew, Persian, Urdu require RTL layout. CSS logical properties handle most of it:

- **Use `margin-inline-start` not `margin-left`** throughout your theme tokens.
- **`<html dir="rtl">`** set automatically by NookDocs for RTL language codes.
- **Directional icons** — chevron-right becomes chevron-left in RTL. Use CSS `transform: scaleX(-1)` or swap icons per direction.
- **Test visually** — RTL mode reveals layout issues you don't see in LTR. Budget an extra 20% engineering time for the first RTL language.

Our theme tokens ship with RTL-safe defaults. If you override theme tokens and use `margin-left` / `padding-left`, you'll break RTL layouts.

## Code examples in translated docs

Preserve code blocks exactly. Translate prose around them. The prose should reference code elements by their English identifier:

```markdown French example

Appelez `POST /api/payments` avec les champs suivants :

- `amount` : montant en cents
- `currency` : code ISO 4217 (`usd`, `eur`, `gbp`)
- `customer_id` : ID du client

La réponse contient :
```json
{
  "id": "pay_abc123",
  "status": "succeeded",
  "amount": 1000
}
```
```

The code is the code. Field names don't translate. Prose describes them in French.

## Search in multiple languages

Each language needs its own search index:

- **Postgres FTS** (what NookDocs ships) — supports multiple language configs (`english`, `french`, `german`, etc.) per index. Query uses the language-matching config.
- **Result ranking** scoped per language — a French reader searching "paiement" gets French results; the English "payments" page doesn't surface.

Language-specific tokenisation matters — French accents, German compound words, Japanese morpheme segmentation all work differently. The tokeniser choice affects search quality more than many other factors.

## When you MUST translate for legal reasons

Some regulations require docs in specific languages:

- **EU**: consumer-facing pricing + T&Cs need local language per market.
- **Japan**: financial / healthcare SaaS often requires Japanese docs.
- **France**: Toubon Law requires French docs for consumer-facing content.
- **Accessibility (WCAG)**: docs in the user's declared language, not just English.

These drive "translate or don't sell" decisions. Consult legal before assuming you can ship English-only.

## Measuring translation ROI

- **Conversion rate by language** — if French visitors signed up at 3% before translation, do they sign up at 5% after? Ship translations in waves + measure the delta.
- **Time-to-first-success by language** — cheaper than professional translation is asking "does the translation help real users complete tasks faster?"
- **Support ticket volume in target language** — if French-speaking users previously opened tickets in English (with awkward translations) and now open in French — that's adoption.
- **Churn by language cohort** — best leading indicator. Churn typically higher for non-English users pre-translation; watch for convergence.

If after 6 months the metrics haven't moved, reconsider the investment.

## The honest cost breakdown

For a typical 20,000-word dev docs site, per language, per year:

| Cost category | Amount |
|---|---|
| Initial translation (top 25 pages, 10k words) | $1,500-3,000 |
| Quarterly update translation (20% churn) | $400-800 × 4 = $1,600-3,200 |
| Internal reviewer time (5-10 hr/quarter) | Varies |
| Translation tool subscription | $0-1,200/year |
| Locale-specific QA (layout testing, RTL testing) | 5-20 hr/quarter eng time |
| **Total year 1** | **$4,000-12,000 per language + eng time** |

Multiply by number of languages. Budget accordingly.

## Common internationalization mistakes

<AccordionGroup>
  <Accordion title="Launching i18n before product-market fit">
    Translating your docs for a market you don't serve yet. Market changes, translations age, burn rate grows. Translate AFTER adoption signal, not before.
  </Accordion>
  <Accordion title="Machine-translating everything">
    Google Translate on 100 pages of docs. Native speakers spot errors within seconds. Trust erodes. Use MT only for approximate reference; professional for customer-facing.
  </Accordion>
  <Accordion title="Translating explanation pages before help-center pages">
    Explanations are philosophical ("why we designed X"); help-center pages are functional ("how to cancel"). Functional content has higher ROI per translated word.
  </Accordion>
  <Accordion title="Not handling terminology consistently">
    "API key" translated three different ways on different pages. Readers get confused; search breaks. Build the glossary first, enforce on every page.
  </Accordion>
  <Accordion title="Launching translations without a maintenance plan">
    Translations ship, then never update. Six months later they're wrong. Commit to the quarterly update cycle before translating, not after.
  </Accordion>
  <Accordion title="Skipping RTL visual QA">
    Arabic docs launch. Navigation is backwards, icons point the wrong way, margins collapse. Budget QA time — you can't eyeball RTL unless you speak Arabic.
  </Accordion>
</AccordionGroup>

## Related

- [Localization config](/content/localization) — the `languages` config + URL structure
- [Help center](/guides/help-center) — why translate help center before dev docs
- [Maintenance](/guides/maintenance) — freshness applies per-language
- [SEO for docs](/guides/seo) — localised SEO signals
- [Accessibility](/guides/accessibility) — language declaration + RTL support

---

# Knowledge base
Source: https://docs.nookdocs.com/guides/knowledge-base

Internal-only docs for engineers + operators at your own company. Runbooks, postmortems, onboarding, architecture docs. Different audience than public docs, same platform, different governance.

A knowledge base is docs for **your own team** — engineers, customer support, ops, new hires. Runbooks, postmortems, onboarding material, internal process docs, architecture deep-dives. Different readership than the public docs + help center, different maintenance model, usually different privacy requirements.

Many teams split internal KB from public docs (Notion / Confluence / GitHub wiki for internal; NookDocs for public). But there's a case for unifying — single tooling, same editor, consistent voice, shared components. This guide covers the unified pattern and the split pattern; pick the one that matches your scale.

## Public docs vs internal KB

| Axis | Public docs / help center | Internal knowledge base |
|---|---|---|
| **Audience** | Customers, prospects, integrators | Employees, contractors |
| **Voice** | Outward-facing, vetted | Terse, opinionated, operational |
| **Maintenance** | Scheduled (per release + quarterly) | Continuous, often ad hoc |
| **Privacy** | Public by default | Gated by default |
| **Content types** | Tutorials, reference, explanations | Runbooks, postmortems, decision docs |
| **Search intent** | "How do I X with Acme?" | "What's the current on-call runbook?" |
| **Review cadence** | PR review per change | Varies — sometimes none, sometimes heavier |

These differences push most teams toward separate tooling. But they can coexist — below.

## Two architectures

### Architecture 1: Separate tenant per audience

Run two NookDocs projects on separate subdomains:

```text
docs.acme.com       — public docs (open, indexed)
internal.acme.com   — knowledge base (private, auth-gated)
```

**Pros:**
- Clean privacy story — internal tenant sets `seo.indexing: "noindex"` + middleware-level auth.
- Different themes / branding if your public docs are marketing-adjacent.
- No leak risk — public readers literally can't reach internal content.

**Cons:**
- Two repos, two build pipelines, two editor experiences.
- Writers context-switch when a doc needs to live in both.

Best for: teams 20+ engineers where the KB has its own dedicated maintainers.

### Architecture 2: Single tenant, internal pages gated

One NookDocs project. Public content surfaces normally; internal content lives under pages with `hidden: true` or `authGroups: ["employees"]` (when the auth layer ships — see [personalization](/content/personalization)).

**Pros:**
- Single source of truth — a page that's "mostly public but with an internal section" can use `<Visibility for="agents">`-style splits (needs to be built — this is a roadmap extension of the existing `<Visibility>` component).
- One repo, one build, one editor.
- Easier to move content from internal to public as features launch.

**Cons:**
- Privacy-by-accident risk — a misconfigured page leaks internal content.
- Public-facing search surfaces must exclude internal pages at multiple layers (sitemap + search + AI assistant RAG).
- Auth layer needs to be real + battle-tested.

Best for: teams under 20 engineers, or teams where public docs and internal KB genuinely share content (integration partner docs, for example).

**Today on NookDocs:** Architecture 1 is the shipping pattern. Architecture 2 requires the auth layer + per-page viewer-based gating (both on the roadmap per [personalization guide](/content/personalization)).

## The four KB sections every team needs

<CardGroup cols={2}>
  <Card title="1. Onboarding" icon="graduation-cap">
    Week-one + month-one reading for new engineers. Architecture overview, repo map, dev environment setup, deployment walkthrough, team norms.
  </Card>
  <Card title="2. Runbooks" icon="book-open">
    Operational procedures. "How to deploy a hotfix", "Recovering from X incident", "Rotating the OAuth secret". Short, actionable, frequently used.
  </Card>
  <Card title="3. Decision records (ADRs)" icon="git-commit">
    Why we chose X over Y. Date, context, alternatives, decision, consequences. Lets future engineers understand legacy choices without polling Slack archeology.
  </Card>
  <Card title="4. Postmortems" icon="alert-triangle">
    After-incident writeups. Blameless. Actionable. Often the most-read KB pages because the lessons apply across teams.
  </Card>
</CardGroup>

## Onboarding flow

A great onboarding KB sequence for a new engineer:

<Steps>
  <Step title="Day 0 — pre-start">
    Background reading sent before day 1: company-wide mission, product overview, primary customer persona. Non-technical if the hire hasn't started yet.
  </Step>
  <Step title="Day 1 — orientation">
    Team structure, who owns what, how to reach people. Access setup (GitHub, Slack, dashboards, VPN). Dev environment stand-up checklist.
  </Step>
  <Step title="Week 1 — first PR">
    Pointer to the repo, code style guide, small starter issue, pairing partner. Ship something to production by Friday.
  </Step>
  <Step title="Month 1 — core architecture">
    Deep-dive pages: request lifecycle, data model, deployment story, observability stack. 1 page per major system.
  </Step>
  <Step title="Month 1 — team norms">
    PR review expectations, on-call rotation, oncall handoff ritual, meeting culture, how we communicate (sync vs async).
  </Step>
</Steps>

Most onboarding KBs fail by treating month-1 content as day-1 reading. Staged disclosure matters.

## Runbook pattern

Every runbook follows the same structure:

```mdx
---
title: Rotate the OAuth client secret
description: Required monthly OR when exposure suspected. 15-minute process; requires deploy + coordinated user session invalidation.
---

## TL;DR

1. Generate new secret in IdP admin console.
2. Deploy code change referencing new env var.
3. Confirm new secret works + old still works (grace period).
4. Remove old secret from IdP after 24h.

## Prerequisites

- IdP admin access (Okta console)
- Deploy access to production
- On-call coordination for any downtime window

## Steps

<Steps>
  <Step title="Generate new secret">
    ...
  </Step>
  ...
</Steps>

## Verification

- [ ] Users can still log in (check analytics dashboard for active sessions)
- [ ] No error spike in observability (10 min after deploy)
- [ ] Old secret rejected after revoke (test with old creds)

## Escalation

If step 3 fails (new secret doesn't work), revert deploy immediately.
Old secret remains valid during grace period. Page on-call lead if
revert + retry needed.

## Change log

- 2026-04-15 — Added IdP console screenshot (ESM)
- 2025-11-02 — Updated to new Okta admin flow (KTA)
```

Every runbook: TL;DR, prereqs, steps, verification, escalation, change log. Same every time. Readers under pressure scan for the right section.

## ADR (Architecture Decision Record) pattern

```mdx
---
title: "ADR-042: Use Postgres FTS instead of Elasticsearch for docs search"
description: 2026-04 decision. Trade-off between operational complexity and feature depth; FTS chosen for MVP.
---

## Context

We needed full-text search for tenant docs pages. Options considered:
- Elasticsearch (industry standard, high operational cost)
- Algolia (SaaS, fast, but adds a vendor)
- Postgres FTS (already in stack, less feature-rich)

## Decision

Ship Postgres FTS with pg_trgm + GIN index. Defer Elasticsearch
or Algolia until scale warrants.

## Consequences

**Good:**
- Zero new infrastructure to operate
- Syncs atomically with page writes (no eventual consistency)
- Free at current scale

**Trade-offs:**
- No fuzzy match beyond trigram (typos 1-2 chars work; longer distance don't)
- No synonym expansion without manual tables
- 100ms query latency at 100k pages; needs watching at 1M+

## Related ADRs

- ADR-038: Multi-tenant query isolation via project_id
- ADR-057: (Future) Embedding-based hybrid search
```

ADRs are append-only. Never edit — supersede by writing a new ADR referencing the old one.

## Postmortem pattern

```mdx
---
title: "PM-2026-04-18: API 5xx spike during deploy #14592"
description: Root cause, user impact, fix, lessons. Blameless.
---

## Summary

2026-04-18, 14:02 UTC. Deploy #14592 introduced a null-pointer crash
in the rate-limiter. ~8% of requests returned 500 for 23 minutes
before rollback.

## Timeline (UTC)

- **14:02** — Deploy #14592 completes (canary 10% traffic)
- **14:04** — Sentry error rate breaches alert threshold
- **14:06** — On-call paged
- **14:09** — Root cause identified (nil check missing in new code path)
- **14:12** — Rollback started
- **14:25** — Rollback complete; error rate back to baseline
- **14:30** — Customer comms sent via status page

## User impact

- ~2,400 failed API requests across ~180 tenants
- Support tickets from 8 tenants
- No data loss (idempotency keys preserved; failures returned HTTP
  500 without partial writes)

## Root cause

The rate-limiter code path added in #14592 accessed `request.user.tier`
without checking whether `user` was set. Unauthenticated requests
(API key without user) produced nil access → crash.

## Fix

- Short-term: rolled back #14592 (deployed 14:12).
- Short-term: hotfix in #14599 with nil guard shipped 15:30.
- Long-term: add unit test coverage for unauthenticated code paths.

## Lessons (blameless)

- The deploy pipeline's canary at 10% DID detect the issue — this is
  working as designed. Time-to-detect was 2 minutes.
- Time-to-revert was 10 minutes; could be faster with better
  tooling. Opened infra ticket #8812 to investigate.
- Test coverage gap: unauthenticated rate-limiter paths. Added to
  test suite in #14600.

## Action items

- [ ] @alice — add pre-commit check for nil access in rate-limiter
- [ ] @bob — faster rollback tooling (target TTR <5min)
- [ ] @carol — document canary traffic split in the deploy runbook
```

Blameless > detailed blame. Action items with owners + accountability, not just "we should do better."

## KB privacy + auth

For Architecture 1 (separate internal tenant):

- **`seo.indexing: "noindex"`** site-wide in the internal tenant's `nookdocs.config.json`. Ensures search engines don't index internal content.
- **Middleware auth** at the proxy / CDN layer. Cloudflare Zero Trust, Vercel auth, or your own OAuth-proxy in front of the internal domain.
- **No anonymous read** — every request requires a valid session cookie or bearer token.

For Architecture 2 (unified tenant with internal pages):

- **Roadmap:** per-page `authGroups` gating (not yet enforced at runtime).
- **Today:** use `hidden: true` frontmatter for "obscure by URL" content. NOT true privacy — if a URL leaks, content is readable. Don't put secrets here.

## When your KB grows past 100 pages

Scale challenges:

- **IA rot** — what started as 5 sections is now 20. Revisit [navigation IA](/guides/navigation).
- **Stale content explosion** — 100 pages of runbooks, many from years ago. Apply [maintenance](/guides/maintenance) quarterly audits more aggressively here than public docs.
- **Search quality** — more pages = more noise. Consider per-team scope filters in search.
- **Ownership fragmentation** — without clear per-page owners, no one updates. Add a `owner:` frontmatter field + quarterly review assignment.

At 500+ pages, consider splitting the KB further — per-team micro-KBs rolled up to a top-level index.

## Common KB mistakes

<AccordionGroup>
  <Accordion title="KB is where things go to die">
    Draft runbook gets written during an incident. Never revisited. Three months later the runbook is wrong + nobody notices. Require per-page `last_verified` frontmatter + a quarterly audit job that flags stale entries.
  </Accordion>
  <Accordion title="One giant 'Engineering Wiki' page">
    Everything in one 10,000-word monolith. Search finds nothing. Break into pages; accept that some overlap is fine.
  </Accordion>
  <Accordion title="Decision-by-Slack instead of ADR">
    "We decided to use Postgres in the #arch Slack thread 2 years ago." Two years later, no one remembers why. Write ADRs at the moment of decision, not retrospectively.
  </Accordion>
  <Accordion title="Postmortems that blame people">
    Blameful postmortems stop getting written — nobody wants to be named. Blameless ones compound as organisational learning. Always blameless.
  </Accordion>
  <Accordion title="Onboarding that's month-1 content on day-1">
    New hire drowns in 80 pages of reading. Stage disclosure — day 1 is the 10 pages they need today, not the 80 they'll need by month 3.
  </Accordion>
  <Accordion title="Running KB on an unmaintainable tool">
    Every KB eventually gets a "Notion became unbearable" moment. Assume this will happen. Keep KB content in version-controllable formats (Markdown > proprietary doc databases).
  </Accordion>
</AccordionGroup>

## Related

- [Developer documentation](/guides/developer-documentation) — external dev docs sibling
- [Help center](/guides/help-center) — end-user support docs sibling
- [Maintenance](/guides/maintenance) — KB decay is real
- [Navigation IA](/guides/navigation) — scaling IA for 100+ pages
- [Personalization](/content/personalization) — per-group gating (roadmap)
- [SEO noindex](/optimize/seo) — keeping KB out of search engines

---

# Linking
Source: https://docs.nookdocs.com/guides/linking

Internal links build topical authority. External links build trust. Both reward descriptive anchor text, anti-orphan auditing, and a policy for what to link out to. The linking playbook for docs.

Every link on your docs site serves one of three jobs: route the reader to a prerequisite, route them to a related-but-adjacent topic, or acknowledge an external source. Each job wants a different pattern. Sloppy linking — "click here", orphan pages, dead external refs — erodes both SEO and reader trust.

This guide covers the linking patterns that hold up.

## The three link jobs

<CardGroup cols={2}>
  <Card title="Prerequisite links" icon="arrow-left">
    "You need a custom domain set up before..." — link to the page that teaches the prerequisite. Goes early in the page, right after the intro.
  </Card>
  <Card title="Topical cluster links" icon="share-2">
    "For the DNS record specifics, see..." — link sideways to related-but-adjacent pages. Builds topical authority (SEO) + helps readers who want to go deeper.
  </Card>
  <Card title="External source links" icon="external-link">
    "The W3C WCAG 2.2 AA standard..." — link to the authoritative external source. Goes at the end of the page in a "Related" or "References" section.
  </Card>
  <Card title="Anchor links (same page)" icon="anchor">
    "Jump to [Troubleshooting](#troubleshooting)" — page-local navigation, especially on long pages. NookDocs auto-generates heading IDs.
  </Card>
</CardGroup>

## Descriptive anchor text

Screen reader users, SEO crawlers, and skimmers all pull anchor text to decide whether to follow a link. "Click here" gives them nothing.

```markdown
❌ For custom domain setup, [click here](/deploy/custom-domain).
❌ Read more about [rate limits](/api/rate-limits).
❌ See [this page](/optimize/seo) for SEO info.

✅ See the [custom domain guide](/deploy/custom-domain) for DNS records.
✅ For rate-limit headers, see [API rate limits](/api/rate-limits).
✅ The [SEO optimise page](/optimize/seo) covers sitemap + robots config.
```

Rules:

- **Anchor text describes the destination**, not the action. "Custom domain setup" beats "click here".
- **Anchor text reads naturally in prose**. Avoid awkward wrapping like "`[here](/…)`".
- **Avoid link text that duplicates with the surrounding sentence**. If the prose says "see custom domain setup", don't link the whole phrase — link just the noun: "see [custom domain setup](…)".

## Internal linking strategy

### Topical clusters, not flat lists

Topical authority in SEO comes from cluster structure: one **pillar** page that broadly covers a topic, linked to + from N **supporting** pages that each cover a narrower sub-topic.

```text
                    /deploy/custom-domain           (pillar)
                          │
      ┌──────────┬────────┼────────┬──────────┐
      ▼          ▼        ▼        ▼          ▼
 /deploy/      /deploy/  /deploy/ /deploy/   /deploy/
 cloudflare  vercel   route-53  monorepo   troubleshooting
 (support)   (support) (support) (support)  (support)
```

Patterns:

- **Pillar links OUT** to each supporting page. "For Cloudflare specifics, see [Cloudflare custom domain](/deploy/cloudflare)."
- **Supporting pages link BACK** to the pillar. "For general custom-domain setup, see the [custom domain overview](/deploy/custom-domain)."
- **Supporting pages link SIDEWAYS** to 2-3 sibling supporting pages. Not to all of them — cross-linking too densely dilutes signal.

### Every page links to 3-5 other pages

Minimum viable cross-link density. Pages with zero internal links are **orphans** — they exist but nothing points to them. Google discovers them via the sitemap but ranks them poorly because no internal signal confirms they matter.

Quick audit:

```bash
# Rough count of internal links per page
for f in docs/**/*.mdx; do
  count=$(grep -oE '\]\(/[^)]+\)' "$f" | wc -l | tr -d ' ')
  if [ "$count" -lt 3 ]; then
    echo "$count  $f"
  fi
done
```

Fix pages with fewer than 3 internal links — add 2-3 related-page references in the prose or a "Related" section at the end.

### "Related" section at the end

Every docs page should end with a `## Related` section listing 4-8 cross-links grouped by relationship:

```markdown
## Related

- [Prerequisites: custom domain setup](/deploy/custom-domain)
- [Next: configure SSL](/deploy/ssl-certificates)
- [Sibling: Cloudflare custom domain](/deploy/cloudflare-custom-domain)
- [Reference: schema for deploy settings](/configuration/schema-reference#deploy)
- [Guide: DNS concepts for writers](/guides/navigation)
```

Group by **relationship**, not alphabetically. Readers scan for the link that matches their next step.

## External links

### When to link out

Link externally when:

- **The reader needs the authoritative external source** — W3C specs, IETF RFCs, vendor API docs.
- **You're acknowledging prior art** — "The Diátaxis framework (Daniele Procida) …"
- **The information is not yours to duplicate** — legal text, vendor pricing tables, open-source changelogs.

Don't link externally:

- **Just to cite a competitor's similar feature** — invites readers to leave.
- **To pad the "Related" section** — internal links serve readers better.
- **To your own blog posts as references in reference docs** — blog posts go stale; prefer to move the canonical info into reference docs.

### External link hygiene

```mdx
[The WCAG 2.2 AA standard](https://www.w3.org/TR/WCAG22/)
```

- **`target="_blank"`** optional. Many users expect ctrl-click / cmd-click to decide themselves. Forcing new-tab is heavy-handed.
- **`rel="nofollow noreferrer"`** on user-generated content (comments, forum links — less relevant for curated docs).
- **Check quarterly for link rot**. Use a crawler like `lychee`:

```bash
lychee --exclude-all-private docs/**/*.mdx
```

Broken external links damage reader trust. Replace with updated URL or Internet Archive snapshot (`web.archive.org/web/YYYYMMDD/...`).

### Open in same tab vs new tab

Docs convention: **same tab**. Users know how to ctrl-click if they want a new tab. Forcing new tab breaks the back button.

Exceptions where `target="_blank"` makes sense:

- External downloads — "Download the migration tool" (keeps doc open).
- Third-party integrations where you explicitly want the reader to compare tabs.

## Anchor links (same-page)

Long pages benefit from a "jump to" pattern for the reader who already read the top and wants to get back to section X.

NookDocs auto-generates IDs from heading text:

```markdown
## Rate limit headers

...later on the page...

For implementation details, see [rate limit headers](#rate-limit-headers).
```

ID generation rules:

- Lowercase
- Spaces → hyphens
- Punctuation stripped
- Duplicate headings on same page get numeric suffixes (`#intro-2`)

Explicit ID override:

```markdown
## Custom heading text {#my-custom-id}

...

Link with [any text](#my-custom-id).
```

Useful for stable deep-linking when you might rename the heading later.

## Cross-version linking

When your docs carry multiple versions (`v1`, `v2`), link hygiene matters more:

- **Same-version links** — relative `[...](concept)` stays within the current version.
- **Cross-version links** — explicit version prefix `[v1 version of X](/v1/x)` when you want to reference an older version's behaviour.
- **Canonical version** — the `default: true` version is the canonical URL. Non-default versions carry `<link rel="canonical">` back to the default.

See [versioning](/content/versioning) for the mechanics.

## Link audit routine

Monthly, 30 minutes:

<Steps>
  <Step title="Check for broken internal links">
    ```bash
    lychee --include-file-extensions=mdx docs/
    ```
    Fix 404s. Pages that should link to deprecated URLs need redirect config.
  </Step>
  <Step title="Check for broken external links">
    Same tool, flag external-only. Broken external links replace with updated URL or Internet Archive snapshot.
  </Step>
  <Step title="Find orphan pages">
    ```bash
    # Any .mdx file never referenced by another
    for page in $(find docs -name "*.mdx"); do
      slug=${page#docs/}
      slug=${slug%.mdx}
      refs=$(grep -rlE "]\(/$slug\)" docs/ | wc -l)
      [ "$refs" -eq 0 ] && echo "ORPHAN: $slug"
    done
    ```
    Add the orphan to at least one sibling page's "Related" section.
  </Step>
  <Step title="Check anchor-link staleness">
    If you renamed a heading, the auto-generated ID changed. Check for stale fragment references.
    ```bash
    grep -oE '\(#[a-z0-9-]+\)' docs/**/*.mdx | sort -u
    ```
    Match against the heading IDs your renderer emits.
  </Step>
</Steps>

## Link-dense vs link-sparse writing

Different docs areas want different density:

| Section | Link density | Why |
|---|---|---|
| Reference docs | High (5-15 per page) | Each type/param/enum can link to related specs |
| Tutorials | Low (2-4 per page) | Too many links fragment the reader's flow |
| How-to guides | Medium (3-7) | Links for prerequisites + deeper dives |
| Explanations | Medium-high (4-10) | Concepts cross-reference heavily |

Linking too sparsely wastes internal SEO equity. Linking too densely fragments attention — the reader clicks away mid-read.

## Common linking mistakes

<AccordionGroup>
  <Accordion title='"Click here" / "read more" / "this page"'>
    Most common anti-pattern. Hurts SEO and accessibility equally. Find + replace ruthlessly. Anchor text should describe the destination.
  </Accordion>
  <Accordion title="Orphan pages that exist but no one links to">
    A page with zero inbound internal links. Google lists it but doesn't rank it. Add it to at least one sibling page's "Related" section — if it doesn't fit any, question whether the page should exist.
  </Accordion>
  <Accordion title="Links in navigation only, not in prose">
    If a page is only reachable from the sidebar, readers on mobile (where nav is hidden) can't get there mid-read. Always cross-link in prose too.
  </Accordion>
  <Accordion title="Anchor links to non-existent fragments">
    Linking to `#troubleshooting` after renaming the heading to "## Fixes". Auto-ID changed to `#fixes` but links still point at `#troubleshooting` — they now scroll to top. Use explicit IDs (`{#troubleshooting}`) on headings you know you'll link to.
  </Accordion>
  <Accordion title="External links that should be internal">
    "See our blog post about rate limits for more info" → link to blog. But the blog post is marketing, not reference. Move the actual information into reference docs and link internally.
  </Accordion>
  <Accordion title="Redirect chains">
    A link to `/old-path` redirects to `/intermediate` which redirects to `/new-path`. Each hop costs ~100ms + burns SEO equity. Update the original link to point directly at `/new-path`.
  </Accordion>
</AccordionGroup>

## Related

- [SEO for docs](/guides/seo) — internal linking as ranking signal
- [Content types](/guides/content-types) — Diátaxis mode affects link density
- [Style and tone](/guides/style-and-tone) — anchor-text writing as a voice decision
- [Redirects](/content/redirects) — managing link equity through URL changes
- [Navigation config](/configuration/navigation) — sidebar + tab structure

---

# Maintenance
Source: https://docs.nookdocs.com/guides/maintenance

Docs rot. Screenshots go stale, URLs break, features get renamed, instructions reference UIs that no longer exist. The maintenance rhythm that keeps a 300-page docs site from becoming a graveyard.

Good docs are a snapshot of the product at one moment. Product ships faster than docs write. Left alone, a docs site becomes a museum — 30% accurate, 70% describing features that were renamed, removed, or replaced. Users can't tell which 30% until they try each instruction.

This guide is about keeping docs fresh without treating maintenance as a second job.

## What rots, how fast

<CardGroup cols={2}>
  <Card title="Screenshots" icon="image-off">
    **Decay rate:** months. Any UI redesign invalidates every screenshot in the affected flow. Check quarterly at minimum.
  </Card>
  <Card title="External links" icon="external-link">
    **Decay rate:** weeks. 5-10% of external links in any large docs site break per year. Quarterly audits catch them.
  </Card>
  <Card title="Version-specific claims" icon="tag">
    **Decay rate:** days after a release. "In v2.3 we added..." is accurate for one release cycle, then potentially misleading.
  </Card>
  <Card title="API responses / field names" icon="code">
    **Decay rate:** whenever the API changes. If you're auto-generating from OpenAPI, this stays fresh. If hand-written, it rots silently.
  </Card>
  <Card title="Third-party tool references" icon="plug">
    **Decay rate:** unpredictable. "Open Cloudflare's SSL settings" — Cloudflare redesigned the UI last month. You don't know until a user reports confusion.
  </Card>
  <Card title="Copy-paste code examples" icon="terminal">
    **Decay rate:** with every library upgrade. Does `npm install stripe@latest` still produce the API from your example? Run examples quarterly.
  </Card>
</CardGroup>

## The staleness signals

How you detect rot without re-reading every page every week:

### 1. "Last updated" dates

NookDocs shows `Last updated: DATE` at the bottom of every page, sourced from the last git commit touching the file. Flag pages not updated in 12+ months for review.

```bash
# Pages not touched in 12 months
find docs -name "*.mdx" -mtime +365 | head -20
```

Older = more likely stale. Doesn't mean bad — some reference docs stay correct for years. But it's the shortlist for the freshness audit.

### 2. Broken link reports

Weekly automated run:

```bash
# Internal + external link check
lychee --include-file-extensions=mdx docs/
```

Breaks here:

- Internal 404s from page renames (should have been redirected) — see [redirects](/content/redirects).
- External 404s from vendor link rot — replace with updated URL or Internet Archive snapshot.

Wire into CI so broken links block the build. Prevents new rot from shipping.

### 3. Support ticket URLs

Same signal as [improving-docs](/guides/improving-docs) — tickets referencing a specific docs page mean the page didn't answer the user. But ALSO a staleness signal when the complaint pattern is "the instructions don't match the current UI."

Filter support tickets monthly for phrases like:
- "the button isn't where it says"
- "the setting has moved"
- "I don't see the option"
- "outdated"

Each is a maintenance-flagged page.

### 4. Thumbs-down feedback with "outdated"

NookDocs's feedback widget surfaces these in the dashboard. One-click flag.

### 5. Your own team surprise

When an engineer reads the docs for their own feature and says "wait, this is wrong" — that's a stale page. Capture these immediately; don't trust team memory.

## The quarterly freshness audit

Every ~12 weeks, 4-hour block:

<Steps>
  <Step title="List all pages last updated >12 months ago">
    Output from the `find` command above. Usually 10-50 pages for a mid-sized docs site.
  </Step>
  <Step title="Skim each page's title + first paragraph">
    Fast triage. Does the description still match the feature? Is the first paragraph still accurate? ~30 seconds per page.
  </Step>
  <Step title="Deep-read the pages that flagged in triage">
    Read the whole page. Note specific sentences that look suspicious. Usually 5-15 pages per audit.
  </Step>
  <Step title="Test every code example + link">
    Copy-paste into a fresh environment. Visit every external link. 80% of updates ship at this step.
  </Step>
  <Step title="Update or retire">
    Fresh content lands in the same commit that touched the page. Content no longer relevant gets retired — either deleted with a redirect, or kept as-is with a "This page covers v1 behaviour" banner.
  </Step>
</Steps>

Log in a tracker: date, page, change made, age of last update. Patterns emerge — which sections rot fastest, which writers' pages stay accurate longest.

## Keeping screenshots current

The most tedious maintenance. Tactics ranked by effort:

<CardGroup cols={2}>
  <Card title="Level 1 — manual quarterly recap" icon="eye">
    Four times a year, open every page with a screenshot, verify against the current UI. Retake stale ones. Takes a day per quarter for a mid-sized site.
  </Card>
  <Card title="Level 2 — annotations only" icon="highlighter">
    Don't capture the whole UI; capture a small region with an arrow/circle annotation. Less pixels to rot. When UI moves, re-capture the small region.
  </Card>
  <Card title="Level 3 — Mermaid / diagrams over screenshots" icon="workflow">
    Architectural + conceptual content → Mermaid. Mermaid source doesn't rot with UI redesigns. See [media guide](/guides/media).
  </Card>
  <Card title="Level 4 — automated Playwright capture" icon="camera">
    Script the screenshots. Checked into CI. Re-captured on every build. Roadmap item; not shipping in NookDocs yet but the pattern works today via `playwright test --update-snapshots`.
  </Card>
</CardGroup>

## Versioning as a maintenance strategy

If a version will be supported for years, don't edit the version-1 docs into version-2 docs — use NookDocs's [versioning](/content/versioning) to keep them separate.

```json
{
  "versions": [
    { "version": "v2", "tag": "Latest", "default": true },
    { "version": "v1", "tag": "Deprecated", "status": "deprecated" }
  ]
}
```

Each version's docs live at its own URL prefix (`/v1/...` / `/v2/...`). The default version's URLs canonical; others carry canonical tags back to default. Enables:

- Deprecation notices per version without editing the other version's content.
- Per-version search (optional).
- Clear link from `/v1/rate-limits` to "this page describes the v1 API — see `/v2/rate-limits` for the current behaviour."

## When to retire a page

Not every page should live forever. Candidates for retirement:

- **Features that no longer exist** — product was sunset, page doesn't apply anymore.
- **Tutorials for versions 2+ behind current** — maintenance cost exceeds reader value.
- **Duplicate pages** — two pages cover the same topic, one was written while you forgot the other existed.
- **Pages with no inbound links + near-zero traffic** — nobody's reading; no one would notice it gone.

Retirement options:

1. **Hard delete** — gone from repo + db + sitemap + llms.txt. Add a [redirect](/content/redirects) so inbound links don't 404.
2. **Hide** — frontmatter `hidden: true`. Page still renders at its URL; removed from sidebar + search + sitemap. For pages where URLs shouldn't 404 but shouldn't be discoverable.
3. **Banner + keep** — add a prominent callout: "This page describes behaviour for Acme v1, which reached end-of-life 2025-06-01. See the [current docs](/) for v2+ content." Keep the content for readers who land via old links / search results.

## The "latest commit" rule

Every page carries an implicit contract: **the last git commit on this file is approximately when this content was last verified**. Break the rule (e.g. a cosmetic commit that doesn't actually verify) and the `Last updated` footer lies.

Implication for edits:

- **Don't bulk-update timestamps without re-reading.** If you're bumping the mtime just to avoid the "stale" triage, you're making the triage useless. Actually verify, then commit.
- **Small fixes are fine.** Typo fixes, link updates, one-sentence additions — commit each. Git history becomes a maintenance log.
- **Avoid mass search-and-replace commits.** A commit that touches 50 pages with one find-and-replace marks all 50 as "recently updated" — but didn't actually verify any. Flag these in commit messages so quarterly audits know.

## Deprecation process

When a feature gets deprecated:

<Steps>
  <Step title="Mark the page in-situ">
    Add a banner callout at the top:
    ```mdx
    <Banner variant="warning">
      `colors.primary` is deprecated as of v2.4. Use `colors.light` /
      `colors.dark` instead. `colors.primary` continues to work through
      v3.0 (sunset 2026-12-01).
    </Banner>
    ```
  </Step>
  <Step title="Update cross-references">
    Every page linking to the deprecated feature should mention the deprecation inline OR link to the new approach.
  </Step>
  <Step title="Add a migration section">
    On the page, a clear "## Migrating to replacement" section with before/after examples.
  </Step>
  <Step title="Update changelog">
    New `<Update>` entry in `/changelog` announcing the deprecation + sunset date.
  </Step>
  <Step title="Schedule the retirement">
    Calendar reminder for sunset date. On that date: hide or redirect the page, remove from nav, announce completion in the changelog.
  </Step>
</Steps>

## Common maintenance mistakes

<AccordionGroup>
  <Accordion title="No review cadence at all">
    "We'll review the docs when we have time." You won't. Block a recurring calendar entry. Weekly quick review + quarterly deep audit.
  </Accordion>
  <Accordion title="Tolerating 'minor' staleness">
    "The screenshot is from two versions ago but it's mostly the same." Users can't tell what's different. Either retake or remove. No half-measures.
  </Accordion>
  <Accordion title="Retaining obsolete content 'just in case'">
    Old page with 4-year-old instructions, kept because "someone might need it". Nobody needs it; it's clutter. If it's truly historical, link from a single `/archive` index rather than leaving in the main nav.
  </Accordion>
  <Accordion title="No deprecation signaling">
    Feature was removed but docs still describe it. User implements it, hits an error, opens a ticket. Always ship the deprecation banner before the removal.
  </Accordion>
  <Accordion title="Maintenance as one person's side job">
    "Alice maintains the docs" = Alice quits and docs rot silently for two quarters. Spread ownership. Every engineer who ships a feature updates or writes the doc for it.
  </Accordion>
  <Accordion title="No git-based freshness audit">
    You rely on memory + guesswork for which pages are stale. `find -mtime +365` takes 10 seconds and gives you the shortlist. Use it.
  </Accordion>
</AccordionGroup>

## Maintenance tool checklist

Automate what you can:

- **CI link checker** — `lychee` or similar runs on every PR. Broken links fail the build.
- **Sitemap auto-regen** — NookDocs does this on every sync.
- **Deprecation calendar** — Google Calendar entry for each sunset date. Ritual > memory.
- **Quarterly freshness audit reminder** — recurring event, non-negotiable.
- **Feedback widget** — always on. Thumbs-down with comment = maintenance signal.
- **Analytics dashboard** — weekly skim for anomalies (bounce spikes, zero-result search growth).
- **Screenshot naming convention** — `component-state-YYYYMM.png` makes the most stale one obvious in a file browser.

## Related

- [Improving docs](/guides/improving-docs) — sibling guide on metrics-driven improvement
- [Versioning](/content/versioning) — version-based content separation
- [Redirects](/content/redirects) — handling URL changes during retirement
- [Analytics](/configuration/analytics) — the in-platform metrics source
- [Feedback widget](/configuration/feedback) — reader-signal collector
- [Media guide](/guides/media) — screenshot discipline

---

# Media
Source: https://docs.nookdocs.com/guides/media

Screenshots, diagrams, videos, embeds — what to capture, how to annotate, how to size, how to write alt text that serves both humans and LLMs. Media discipline that actually ships.

The difference between good docs and great docs is often how media is handled. Bad: blurry screenshots from arbitrary zoom levels, hero videos that autoplay loudly, "see the image below" with no fallback for readers who can't. Good: purposeful media that carries information prose can't, annotated for clarity, captioned for scannability, alt-texted for accessibility + LLM ingestion.

This guide covers the media discipline for docs.

## When to use media

<CardGroup cols={2}>
  <Card title="UI screenshots — yes" icon="monitor">
    Any step that says "click the X in the Y of the dashboard" should have a screenshot showing where. Prose alone forces the reader to hunt.
  </Card>
  <Card title="Architecture diagrams — yes" icon="network">
    System overviews, data flow, request lifecycles. One diagram can replace five paragraphs. Use Mermaid for maintainability.
  </Card>
  <Card title="Short videos / GIFs — sometimes" icon="video">
    Interactions that can't be captured in a single screenshot (drag-and-drop, hover-reveal, animation timing). Keep under 15 seconds. Always pair with prose fallback.
  </Card>
  <Card title="Decorative hero images — rarely" icon="image-off">
    Only when the image is the product (a design tool, a data visualisation product). Otherwise cut — hero images delay first-paint and agents can't see them anyway.
  </Card>
</CardGroup>

## Screenshot discipline

### Capture

- **Browser zoom 100% + device pixel ratio @2x** — retina-sharp on modern displays.
- **Same browser, same OS, same theme** across the whole docs site. Mixed Safari / Firefox / macOS / Windows chrome is distracting.
- **Crop to the relevant UI**. Full-window screenshots are 1400×900 of which 10% is useful. Crop to 600×400 of the dashboard panel being discussed.
- **Hide personal data** — your real email, your real API keys, your real customers' names. Use `demo@acme.com` and `sk_test_demo...`.
- **Consistent window chrome** — either keep the browser title bar / URL bar visible (if URL is informative) or hide entirely (distracting). Pick one and stick with it.

Recommended tools:

| Tool | Good for |
|---|---|
| macOS Cmd+Shift+4, Space | Window capture with shadow, @2x |
| [CleanShot X](https://cleanshot.com) | Annotation + cropping + scrolling capture |
| [Shottr](https://shottr.cc) | Free alternative, fewer annotation features |
| [Flameshot](https://flameshot.org) | Cross-platform OSS |

### Annotation

Annotate only what the reader needs to find. Arrows, numbered circles, red outlines around the specific clickable area. Don't annotate the whole screenshot — it defeats the purpose.

```text
❌ Arrow 1 → Settings. Arrow 2 → General. Arrow 3 → Save. Arrow 4 → ...
   (Seven arrows across the whole screenshot.)

✅ Arrow → "Custom domains" section in the Settings sidebar.
   (One arrow, one focus point, one prose step.)
```

Colour choice: high-contrast red (#DC2626) or yellow (#EAB308) against most UI. Avoid green (reads as "success") or purple (too subtle).

### Where the file lives

Two places work, and the choice matters more than it looks.

**In your repo, under `public/`.** The file is versioned with the page that uses
it, and `<Image>` runs it through the image optimizer: the reader gets a resized
AVIF or WebP sized to their screen, not the file you committed. A 340KB
screenshot can reach a phone as about 40KB without you doing anything.

**On a CDN or object store, as an `https://` URL.** Nothing enters your repo. No
push waits on the upload, no clone re-downloads it, and the file can be replaced
without a commit.

<Note>
  An external URL is served as-is. Next.js does not optimize images it doesn't
  host — a 3MB PNG behind an `https://` URL arrives as 3MB, on every device. The
  optimizer is the thing you give up, so the size you upload is the size readers
  pay for.
</Note>

Which one depends on the file:

| File | Put it | Why |
|---|---|---|
| Screenshots, diagrams, icons | `public/` | Small enough that Git doesn't care, and optimization is free |
| Video (`.mp4`, `.webm`) | CDN | Video never goes through the optimizer, so `public/` costs repo weight and returns nothing |
| Anything over a few MB | CDN | See below |
| Assets you already host | CDN | No reason to copy them into the repo |

The reason to keep large binaries out of Git is that they never leave. Git
stores each version of a binary in full — it can't diff them — so a 5MB video
replaced three times is 15MB in the history of every clone, forever, including
the versions nobody uses. Deleting the file doesn't shrink it. Text files don't
behave this way, which is why a repo of pure MDX stays small for years.

That weight is paid on every `git clone`, every CI checkout, and every sync,
because a sync fetches the whole repository — a 200MB media folder is
re-downloaded when you fix a typo in one page.

### Sizing

Target dimensions for common slots in NookDocs layouts:

| Use case | Dimensions | File size |
|---|---|---|
| Inline full-width | 1600 × 900 (16:9) | &lt;200KB |
| Inline narrow (next to text) | 800 × 600 | &lt;80KB |
| Hero / section break | 1600 × 900 or 1200 × 600 | &lt;250KB |
| Small inline (icon-size) | 200 × 200 | &lt;30KB |

These are firm for **external URLs**, where the number you upload is the number
the reader downloads. Under `public/` they are a guide to keeping the repo light
— the optimizer is already handling what reaches the browser, so a retina
screenshot landing somewhat over is not a problem worth solving twice.

Compress before committing:

- PNG → [TinyPNG](https://tinypng.com) (free up to 20/month, retains transparency).
- JPG → 85% quality in most tools; 70% is usually the sweet spot between size + quality.
- WebP → modern replacement, 25-35% smaller than JPG at same quality. Supported in all modern browsers.

```bash
# Bulk compress a directory
find ./images -name "*.png" -exec pngquant --ext .png --force {} \;
find ./images -name "*.jpg" -exec jpegoptim --max=85 {} \;
```

## Alt text that works

Alt text serves three audiences:

1. **Screen reader users** — hear the alt text read aloud.
2. **Users on slow connections** — see alt text while the image loads (or if it fails).
3. **LLMs ingesting the page** — can't see the image, extract meaning from alt + surrounding prose.

Good alt text names what the image shows + why it's in the doc.

```markdown
❌ alt="screenshot.png"
❌ alt="dashboard"
❌ alt="Image of the dashboard"

✅ alt="Custom Domains panel in Settings showing docs.acme.com verified with a green check"
✅ alt="Mermaid diagram: request flow from browser through CDN to origin, with cached response returning in 15ms"
✅ alt="Code editor sidebar showing _snippets folder expanded with three mdx files inside"
```

Rules of thumb:

- **Name what the image shows**, not the image type. "Image of X" is noise — screen readers already announce "image".
- **Mention the key UI element or data point**. If the screenshot shows the "Save" button, name it.
- **Be as short as possible while being specific**. ~8-15 words is usually right.
- **Decorative images get `alt=""`**. Empty alt = screen reader skips. Missing alt = screen reader reads the filename.

## Captions

Captions serve sighted readers — they reinforce what the image shows AND what to do with it:

```mdx
<Frame caption="After adding a custom domain, the entry flips to 'Verified' once DNS propagates. Typical: 30-60 seconds.">
  ![Custom Domains panel with docs.acme.com showing as Verified with a green check](/images/custom-domain-verified.png)
</Frame>
```

Alt text names the content. Caption explains the implication. Together they cover both "what is this showing me" and "so what".

## Diagrams — prefer Mermaid

Diagrams render as images when you ship PNG / SVG. Mermaid diagrams render as live SVG from Markdown-like source — which means:

- **Searchable text** (SEO + accessibility).
- **Version-controlled source** — `git diff` shows what changed in the diagram.
- **Editable in-repo** — update without round-tripping through a design tool.
- **Automatically theme-aware** — respects light / dark mode via NookDocs's theme tokens.

````mdx
<Mermaid>
```mermaid
sequenceDiagram
  Browser->>CDN: GET /docs/quickstart
  CDN->>Origin: cache miss, fetch
  Origin-->>CDN: HTML + headers
  CDN-->>Browser: HTML (cached 5 min)
```
</Mermaid>
````

Use PNG/SVG only when:

- The diagram is too complex for Mermaid syntax (hand-drawn, annotated with multiple overlays).
- You need photo-real elements (product screenshots composited into a flow).

## Video + animation

Video is tempting for "show the interaction" cases but carries real costs: file size, auto-play UX debates, screen reader + accessibility overhead, LLM invisibility.

Rules for when to use:

- **≤15 seconds** — anything longer, split into smaller clips or use static screenshots with numbered steps.
- **Silent** — no voiceover. Users reading docs are often in shared workspaces. The doc's prose carries narration.
- **No autoplay** — reader presses play. Exception: ultra-short GIFs (under 3 seconds) documenting a single interaction.
- **Provide transcript or caption** — describe what happens in prose either above or below the video. LLMs + screen readers need this; sighted users benefit too.

Formats:

| Format | Best for | Caveats |
|---|---|---|
| MP4 (H.264) | Longer demos (5-15s) | Needs `<video>` element. Supports audio if you ever need it. |
| GIF | Micro-interactions (&lt;3s) | Huge files. Prefer MP4 + poster image for anything over 2s. |
| WebM | Same as MP4 | Smaller than MP4. Browsers auto-fall back to MP4 via `<source>` chain. |
| APNG | High-fidelity short animations | Limited tooling. Rarely worth the effort. |

Embed with the `<Video>` component:

```mdx
<Video
  src="/videos/custom-domain-setup.mp4"
  poster="/images/custom-domain-setup-poster.png"
  caption="Adding a CNAME record in Cloudflare, pasting the target into Acme dashboard, and watching the verification flip green."
/>
```

## Third-party embeds

YouTube, Loom, Vimeo — use the `<Embed>` component:

```mdx
<Embed
  src="https://www.youtube.com/embed/dQw4w9WgXcQ"
  title="Walkthrough: Setting up a custom domain"
/>
```

NookDocs whitelists YouTube, Loom, Vimeo, Figma, CodePen, and StackBlitz. Other origins render as a notice with a link to the external resource (avoids XSS from untrusted iframes).

Loom vs YouTube:

- **Loom** — internal demos, quick walkthroughs, no publishing to YouTube. Loom handles the loading / hosting.
- **YouTube** — evergreen content, marketing videos, anything you want to rank in YouTube search. More control over thumbnails + end screens.

## Media organisation in the repo

```text
docs/
  images/
    features/
      copy-for-llms-dropdown.png
      copy-for-llms-menu-open.png
    api/
      rate-limit-headers.png
    concepts/
      architecture-overview.svg
  videos/
    custom-domain-setup.mp4
```

Conventions:

- **Organise by doc path**, not by media type. `images/features/copy-for-llms.png` beats `images/screenshots/copy-for-llms.png`.
- **Lowercase, hyphenated filenames**. `custom-domain-setup.png` beats `CustomDomainSetup.png`.
- **No version numbers in filenames**. If the screenshot gets updated, replace in place — Git tracks the history.
- **Reference with absolute paths** in MDX: `/images/features/custom-domain.png`. Relative paths break when the page moves.

## Image optimisation at serve time

NookDocs doesn't yet ship Next.js `<Image>` auto-optimisation (lazy loading, responsive srcset, modern format delivery) for user-repo images — they serve as-is from `/api/assets/<path>`. Compress before committing.

Roadmap: `/images/<path>?w=800&q=85` responsive URLs with on-the-fly resize. Until then, ship the right size at commit time.

## Common media mistakes

<AccordionGroup>
  <Accordion title="Screenshots that span the whole browser window">
    1600×900 screenshot where the relevant UI is a 400×200 panel. Crop. Readers' eyes track to whitespace otherwise.
  </Accordion>
  <Accordion title="Out-of-date screenshots">
    UI gets rebuilt, screenshots don't update. Pages ship showing last-year's UI. Set a quarterly "screenshot audit" reminder, or better — use Playwright to auto-capture screenshots as part of CI (roadmap).
  </Accordion>
  <Accordion title="Text inside screenshots that's not in prose">
    A screenshot showing an error message. The error text is only in the pixels. LLMs, screen readers, and Ctrl-F users can't find it. Rewrite the prose to include the error message as quoted text.
  </Accordion>
  <Accordion title="Diagrams as PNGs when Mermaid would work">
    A flow chart committed as a 400KB PNG. Same diagram in Mermaid is ~500 bytes of source + rendered as inline SVG. Diff-friendly, theme-aware, accessible.
  </Accordion>
  <Accordion title="Video without a text fallback">
    A 30-second video of a multi-step process. Readers who can't watch (audio-only environment, slow connection, screen reader) get nothing. Always provide prose that covers the same ground.
  </Accordion>
  <Accordion title="Decorative illustrations cluttering technical docs">
    Friendly cartoon character next to every section heading. Looks nice in Figma, burns attention + load time. Reference docs don't need decorations; save illustration for landing + marketing.
  </Accordion>
</AccordionGroup>

## Related

- [Accessibility](/guides/accessibility) — alt text + contrast requirements
- [Style and tone](/guides/style-and-tone) — prose that accompanies media
- [Frame component](/components/frame) — the wrapper for annotated images
- [Image component](/components/image) — light/dark variants + sizing props
- [Video component](/components/video) — the embed wrapper
- [Mermaid component](/components/mermaid) — inline diagram source

---

# Migrating from a custom MDX setup
Source: https://docs.nookdocs.com/guides/migrating-from-mdx

You already use MDX — via Next.js + next-mdx-remote, Astro, Docusaurus, Contentlayer, or a hand-rolled pipeline. Here's the path from custom MDX to NookDocs without losing content, URLs, or tooling you like.

If you're reading this, you probably have a working custom MDX-based docs setup — maybe Next.js + `next-mdx-remote`, maybe Astro's content collections, maybe Contentlayer, maybe your own pipeline. It works. The question is: why migrate at all?

This guide is for teams who've decided "yes, moving to NookDocs makes sense" and need the playbook. It's the sibling of [migration playbooks](/guides/migration-playbooks) but narrower — specifically about moving from one MDX setup to another, preserving the bits you already got right.

## What NookDocs brings vs custom MDX

<CardGroup cols={2}>
  <Card title="Component library you don't maintain" icon="package">
    47 components + docs + theme tokens. Custom MDX requires you to build + maintain all of these yourself.
  </Card>
  <Card title="Managed rendering + hosting" icon="server">
    No Next.js config to maintain, no deploy pipeline to tune, no edge caching to debug. Trade: less control.
  </Card>
  <Card title="Dashboard editor" icon="edit">
    Non-technical writers edit without a dev environment. Custom setups require local dev or Netlify-CMS-style additions.
  </Card>
  <Card title="Built-in AI affordances" icon="sparkles">
    `/llms.txt`, `.md` URLs, Copy-for-LLMs, AI assistant, RSS feeds, contextual menu. Custom MDX doesn't ship any of this by default.
  </Card>
</CardGroup>

## What you give up

<CardGroup cols={2}>
  <Card title="Custom React components in MDX" icon="code">
    NookDocs accepts the built-in component set + aliases. Your custom `<PricingWidget>` doesn't render (unless you [go headless](/guides/custom-frontend)).
  </Card>
  <Card title="Custom build hooks" icon="workflow">
    Pre-build scripts that generated docs from OpenAPI, TypeScript types, or metadata files. NookDocs handles OpenAPI + schema-reference generation natively; custom scripts migrate to CI.
  </Card>
  <Card title="Custom layouts per-page" icon="layout">
    "This page has a right-sidebar, that one has a 2-column grid" needs adapting to NookDocs's layout system (see [custom-layouts](/guides/custom-layouts)).
  </Card>
  <Card title="Full deploy-pipeline control" icon="truck">
    You stop managing Vercel / Netlify / CloudFront / Lambda@Edge. Some teams miss this; most don't.
  </Card>
</CardGroup>

## Content audit (before any code moves)

Before touching configuration, audit your existing content:

<Steps>
  <Step title="List every MDX file">
    `find docs -name "*.mdx" | wc -l` — know how many pages you're migrating. Typical mid-sized site: 100-300.
  </Step>
  <Step title="Inventory custom components used">
    Grep every `<CapitalisedComponent>` tag across your MDX. Build a frequency table.
    ```bash
    grep -rho '<[A-Z][A-Za-z]*' docs/ | sort | uniq -c | sort -rn
    ```
    Map each to NookDocs equivalent. Components with no equivalent need: (a) substitute to a closest-match NookDocs component, (b) inline their rendered output, or (c) use [`<Visibility for="humans">`](/llm-first/human-vs-agent) wrap to keep custom content for web readers while stripping for LLMs.
  </Step>
  <Step title="Inventory front-matter fields">
    What frontmatter fields do you use? NookDocs supports: `title`, `description`, `icon`, `hidden`, `rss`, `sitemap`, `openapi`, `timestamp`, plus forward-compatible unknown fields. Extra fields stay in the MDX but won't drive behaviour.
  </Step>
  <Step title="Inventory build-time magic">
    Do you currently inject data at build? Auto-generate certain pages? Use `@next/mdx` features like `getStaticProps`-per-page? Each one needs a migration path.
  </Step>
  <Step title="Inventory non-MDX content">
    Static assets (images, PDFs, videos) and custom CSS / fonts migrate into the public/ folder of your NookDocs repo — CSS also has a `customCss` config key.

    Custom scripts do not have a path. NookDocs injects analytics and support widgets from a fixed list of [supported integrations](/configuration/integrations), and the site's Content Security Policy allows exactly those hosts and no others — a `<script>` you add yourself is blocked in the reader's browser. If you depend on a provider that is not on that list, ask us and we will add it.
  </Step>
</Steps>

## Mapping custom components to NookDocs

Common component mappings:

| Custom component | NookDocs equivalent | Notes |
|---|---|---|
| `<Alert type>` | `<Callout type>` | Same API usually works as-is |
| `<InfoBox>` / `<NoteBox>` | `<Note>` | Direct swap |
| `<Tabs>` + `<Tab>` | `<Tabs>` + `<TabsList>` + `<TabsTrigger>` + `<TabsContent>` | More verbose; migration script can rewrite |
| `<CodeTabs>` | `<CodeGroup>` | Direct swap; language comes from fence tag |
| `<Steps>` + `<Step>` | `<Steps>` + `<Step title>` | Direct swap; some custom setups use `number` instead of `title` — rename |
| `<ApiParam>` | `<ParamField>` | Prop names may differ; see [schema-reference](/configuration/schema-reference) |
| `<Details>` / `<Expand>` | `<Expandable>` or `<Accordion>` | `<Expandable>` is lighter; `<Accordion>` groups better |
| `<Image src alt>` | `<Image>` or `<Frame caption>` | `<Frame>` wraps with a caption + border |
| `<Video>` / `<Embed>` | `<Video>` / `<Embed>` | Usually direct swap |
| `<FileTree>` / `<Tree>` | `<FileTree>` | Same API |
| `<Mermaid>` | `<Mermaid>` | Same; content is inline Mermaid source |

Custom components with no good equivalent go one of three ways:

1. **Rewrite content** — instead of `<PricingWidget>`, write a markdown table.
2. **Inline rendered output** — screenshot the widget, inline it with `<Frame>`.
3. **Drop + simplify** — the widget was probably over-engineered; plain prose works.

## The migration steps — specific to custom MDX

<Steps>
  <Step title="Clone your existing repo to a scratch directory">
    Keep it as a read-only reference. All migration work happens in a new repo.
  </Step>
  <Step title="Run the NookDocs CLI against the scratch directory">
    ```bash
    nookdocs migrate ./my-custom-mdx-docs --from mintlify
    ```
    Even though it's not Mintlify, the `--from mintlify` path does the most work (maps `docs.json`-style config + does component rewriting). Adjust manually afterwards.

    (If Docusaurus / Astro / Contentlayer support lands in the CLI, use that — see [migrate command](/cli/migrate).)
  </Step>
  <Step title="Manually port your config">
    Map your custom config fields to `nookdocs.config.json`. Navigation, theme colours, logo, integrations, SEO settings. Use the [schema reference](/configuration/schema-reference) as the canonical field list.
  </Step>
  <Step title="Port custom components">
    For each unmapped custom component, decide: rewrite, inline, or drop. Batch by component type — "rewrite every `<PricingWidget>` first, then every `<TeamList>`, …".
  </Step>
  <Step title="Port build-time scripts">
    If you have pre-build scripts that generate content, adapt them to NookDocs's flow:
    - **OpenAPI auto-gen** → use NookDocs's built-in OpenAPI support (point `api.openapi` at the spec file).
    - **Custom schema-reference** → replace with the built-in generator at `scripts/generate-schema-reference.mjs`.
    - **Other generators** → port to a `scripts/generate-*.mjs` file + wire into `npm run build`.
  </Step>
  <Step title="Port assets">
    Images, PDFs, videos go under `docs/images/` etc (or `public/` if served from the tenant root). Relative paths in MDX should resolve to the same location.
  </Step>
  <Step title="Set up redirects">
    URL structure might shift during migration. Build the redirect map. Commit to `nookdocs.config.json#redirects`.
  </Step>
  <Step title="Smoke test on staging">
    Deploy to a staging subdomain. Click through every top-level page. Test search. Test the AI assistant. Compare against the old site side-by-side.
  </Step>
  <Step title="Cutover">
    DNS flip or CDN rewrite. Traffic reaches NookDocs; redirects from old URLs route. See [migration playbooks](/guides/migration-playbooks) for cutover mechanics.
  </Step>
</Steps>

## Specific platform notes

### From Next.js + next-mdx-remote

- Your `pages/[...slug].tsx` route becomes unnecessary — NookDocs handles routing.
- `serialize()` + `MDXRemote` happen server-side on NookDocs; no-op for you.
- `remark` / `rehype` plugins: built-in behaviour usually covers the common ones (syntax highlighting, frontmatter). Custom ones don't migrate.
- Middleware for auth / rewrites: rebuild at the NookDocs layer via `config.redirects` + per-page `hidden:true`.

### From Docusaurus

- Docusaurus-specific `<Tabs>` / `<TabItem>` → NookDocs `<Tabs>` + children shape.
- Sidebar config in `sidebars.js` → `nookdocs.config.json#navigation`.
- Docusaurus versioning (`versioned_docs/`) → NookDocs [versioning](/content/versioning).
- Algolia DocSearch → built-in Postgres FTS replaces, unless you specifically want Algolia features.
- React components in MDX → most won't render; port or drop.

### From Astro content collections

- Astro's schema validation in `config.ts` → NookDocs validates at sync time via `src/lib/config/schema.ts`.
- Astro's `.astro` components in MDX → don't render; rewrite.
- Content collection frontmatter → most fields map 1:1; extras preserved but inert.
- Astro's image optimisation → NookDocs serves images via `/api/assets/`; optimisation is on the roadmap, not shipping yet.

### From Contentlayer

- `contentlayer.config.ts` definitions → map to `nookdocs.config.json`.
- Build-time Contentlayer transforms → port to `scripts/*.mjs` + `npm run build` chain.
- Generated TypeScript types → NookDocs has `public/schema.json` for config types; content pages don't have generated types (they're just MDX).

### From a hand-rolled MDX pipeline

Usually easier than migrating from a framework, because you already understand the moving parts. Main decisions:

- Keep your OpenAPI spec? Yes — point `api.openapi` at it.
- Keep your custom plugins? Probably drop — they're hard to port and usually replicate something NookDocs already does.
- Keep your search? Replace with built-in unless you have a specific reason.

## Pitfalls specific to MDX-to-MDX migration

<AccordionGroup>
  <Accordion title="Assuming all MDX is equivalent">
    MDX has flavours — MDX v1 vs v2 vs v3 have different parser strictness. `safe-mdx` (what NookDocs uses) is MDX 3-compatible. Older MDX content with, e.g., inline `import` statements, won't work. Remove imports; use built-in components instead.
  </Accordion>
  <Accordion title="Custom components that rendered fine but break MDX parsing">
    JSX like `<Component {...spread}>` or `<Component>{children.map(...)}</Component>` is valid in a custom React-backed pipeline but parses as uninterpretable JSX in `safe-mdx`. Replace with static equivalents.
  </Accordion>
  <Accordion title="URL structure change breaks inbound SEO">
    Your previous setup put pages at `/docs/v2/api` but NookDocs serves them at `/api`. Inbound Google traffic 404s. Redirect configuration is non-negotiable — see [migration playbooks](/guides/migration-playbooks) for the redirect map discipline.
  </Accordion>
  <Accordion title="Losing version-specific UI affordances">
    Your custom setup had a clever version banner at the top of every page via a layout wrapper. NookDocs has `<Banner>` in config — set it site-wide. If you needed per-page banners, add to each page's frontmatter or use `<Visibility for="humans">` at the top.
  </Accordion>
  <Accordion title="Build-time data injection doesn't transfer">
    Custom setup fetched data at build time (pricing tiers, contributor counts). NookDocs doesn't run arbitrary build scripts per-tenant. Inline the data you care about; for truly dynamic content, use the AI assistant or a separate API call from a custom frontend.
  </Accordion>
</AccordionGroup>

## What's easier AFTER migration

- **Non-dev writers can edit without a dev environment.**
- **AI affordances "just work"** — `/llms.txt`, `.md` URLs, Copy-for-LLMs dropdown, RSS feeds on any page.
- **Component library stops being your job** — upgrades + a11y fixes + dark-mode tuning all live in NookDocs.
- **Deploys are automatic** — push to GitHub, ~30s later it's live.
- **Search is built-in** — Postgres FTS with on-site ⌘K, no external service.

## When to NOT migrate

- If you've built significant custom tooling (plugins / layouts / generators) that would take weeks to reimplement.
- If your content has exotic React components central to the experience.
- If you have a team of engineers who actively enjoy maintaining the docs infra.

In those cases, [headless / custom frontend](/guides/custom-frontend) is a middle path: use NookDocs as the content store + editor + API, render yourself.

## Related

- [Migration playbooks](/guides/migration-playbooks) — generic phased migration strategy
- [Migrate from Mintlify (CLI)](/cli/migrate-from-mintlify) — closest to the mechanical conversion flow
- [Custom frontend](/guides/custom-frontend) — alternative if you want to keep custom rendering
- [Schema reference](/configuration/schema-reference) — target config shape
- [Component library](/components/callout) — target component set

---

# Migration playbooks
Source: https://docs.nookdocs.com/guides/migration-playbooks

Moving docs from Mintlify, ReadMe, GitBook, Docusaurus, or a legacy CMS to NookDocs. Phased strategies, what to keep vs rewrite, redirect maps, cutover timing, rollback plans.

Migrating a docs site isn't a copy-paste job. You're moving content AND inbound links AND SEO equity AND writer muscle memory. Doing all four in one weekend is usually a disaster. This guide covers the phased approach that keeps your docs online, your Google rankings intact, and your writers productive during the transition.

The [CLI migration command](/cli/migrate) handles the mechanical file-conversion part. This guide is about everything AROUND that.

## Why migrate (and why NOT to)

<CardGroup cols={2}>
  <Card title="Do migrate when..." icon="check-circle">
    - Current platform pricing scales poorly with team + content size
    - You need AI-native features (llms.txt, MCP, Copy-for-LLMs) your current platform doesn't ship
    - Current platform's editor slows your writers down
    - You want full Git control, not a proprietary lock-in
  </Card>
  <Card title="Don't migrate when..." icon="x-circle">
    - You're hoping a migration will fix your writing quality (it won't — content stays the same, framing changes)
    - You haven't shipped consistently for 6 months (migration doesn't replace discipline)
    - You're 2 weeks before a major product launch (bad timing — migrate in a quiet window)
    - Your team hasn't used the target platform for at least 2 weeks in sandbox (unknown unknowns)
  </Card>
</CardGroup>

## The three-phase approach

<Steps>
  <Step title="Phase 1 — Parallel (2-4 weeks)">
    New platform runs alongside the old. Content migrated + published to a staging domain (`docs-beta.acme.com`). Writers author new content in the new platform; old platform accepts minor edits only. No public cutover yet.
  </Step>
  <Step title="Phase 2 — Soft cutover (1-2 weeks)">
    New platform becomes the canonical. Old platform URLs 301/308 redirect to new platform equivalents. Search Console verified on both domains. Public announcement lands at the end of this phase.
  </Step>
  <Step title="Phase 3 — Old-platform sunset (4-8 weeks)">
    Old platform content stays accessible via redirects for SEO continuity. After Google has re-indexed (~4 weeks), you can decommission the old platform. Redirect rules stay in place indefinitely.
  </Step>
</Steps>

Don't compress these phases. The redirects need time to take effect in Google's index; your team needs time to absorb the new editor; the URL-change dust needs to settle.

## Phase 1 — Parallel setup

### Mechanical migration

Run the CLI once against a copy of your old-platform repo:

```bash
nookdocs migrate ./old-mintlify-repo --output ./nookdocs-staging
```

Output: a `nookdocs-staging` directory with `nookdocs.config.json` + `docs/` + migrated assets. Commit to a new GitHub repo, hook up via the NookDocs dashboard, and deploy to a staging subdomain (`staging.nookdocs.site` or your own `docs-beta.acme.com`).

See [migrate-from-mintlify](/cli/migrate-from-mintlify) for the mechanical conversion matrix.

### Content audit during migration

The migration is a forcing function for a content audit you should have done anyway:

<CardGroup cols={2}>
  <Card title="What to KEEP" icon="check">
    Pages with clear inbound search traffic. Pages referenced from support tickets. Pages covering currently-active product features. The top ~60% of pages by traffic.
  </Card>
  <Card title="What to REWRITE" icon="pencil">
    Pages with high bounce + low engagement. Pages that felt awkward on old platform. Pages mixing Diátaxis modes. Take this chance — reshape the content in the new platform before committing to it.
  </Card>
  <Card title="What to MERGE" icon="git-merge">
    Two or three pages that cover overlapping topics. Migration is the moment to consolidate — fewer pages, stronger topical clusters (see [SEO guide](/guides/seo)).
  </Card>
  <Card title="What to RETIRE" icon="trash-2">
    Pages with no inbound links + near-zero traffic. Pages covering retired features. Pages nobody's touched in 2+ years. Don't migrate what you'd delete.
  </Card>
</CardGroup>

### Writer training

Two weeks minimum on the new platform before writers switch full-time:

- **Everyone signs in + edits a test page.** Muscle memory starts here.
- **Walk through the editor + Git workflow.** Especially important when moving from a WYSIWYG platform to MDX.
- **Document internal conventions.** Which component for which scenario, which frontmatter fields are required, etc. One short internal page.
- **One writer ships a test page each week.** Real publishing, even if to staging. Surfaces issues before cutover.

## Phase 2 — Soft cutover

The scary phase. Done right, your users don't notice. Done wrong, Google delists half your content for a month.

### Redirect map — the most important artifact

Every URL on the old platform must redirect to its new equivalent. Build the map BEFORE cutover, audit it, test a sample.

Format: two-column CSV.

```csv
old_url,new_url
/docs/getting-started,/quickstart
/essentials/markdown,/content/format-text
/essentials/code,/features/code-blocks
/essentials/images,/guides/media
/api-reference/endpoint/list-users,/api-reference/users/list-users
/blog,https://acme.com/blog
```

Generate the initial map automatically from the old platform's sitemap + the new platform's file structure, then audit by hand. Expect 5-15% of entries to need manual override — the auto-match usually gets 85%+.

### Three places to set redirects

Pick the layer that matches your deployment:

<Steps>
  <Step title="DNS layer (preferred when old platform becomes unreachable)">
    Point `docs.acme.com` DNS at NookDocs. NookDocs's `nookdocs.config.json#redirects` handles path remapping. Works if old platform is being fully sunset.
  </Step>
  <Step title="Old-platform redirect config">
    Most docs platforms support `redirects` config. Keep `docs.acme.com` pointed at the OLD platform, configure redirects in old platform to send users to `docs.acme.com/new-path` (same domain) or `https://docs-v2.acme.com/new-path`.
    Preferred when you want to keep the old platform reachable for 4-8 weeks during Phase 3.
  </Step>
  <Step title="CDN / reverse proxy layer (most control)">
    Cloudflare Workers, Vercel rewrites, or Nginx. Proxy intercepts every request to `docs.acme.com`, checks the redirect map, returns 301/308 for matches, passes others through to the new platform.
    Most flexible, most work. Only needed when the other two options don't fit.
  </Step>
</Steps>

### Status codes that matter

- **301 Moved Permanently** — older HTTP 1.0. Widely supported.
- **308 Permanent Redirect** — HTTP 1.1. Preserves the request method. Google treats it identically to 301. **Prefer 308 for new deployments.**
- **302 / 307 Temporary** — don't use for a migration. Temporary tells Google not to transfer ranking signals. You want permanent.

NookDocs's [redirects config](/content/redirects) uses `permanent: true` → 308. Set it for the migration.

### Search Console continuity

Before cutover:

- **Verify new domain in Search Console.** `docs-v2.acme.com` if using a new domain, or verify the same property post-migration if reusing `docs.acme.com`.
- **Submit the new sitemap.** `docs-v2.acme.com/sitemap.xml` — NookDocs auto-generates.
- **File "Change of Address" if moving to a new domain.** Search Console → Settings → Change of Address. Tells Google explicitly that content moved.

After cutover:

- **Daily Search Console checks for 2 weeks.** Coverage → Indexed pages should stabilise. If you see a sudden drop, a redirect may be broken.
- **Search traffic drop tolerance:** 20-30% for the first month is normal. Should recover within 6-12 weeks. If not, re-audit redirects + freshness signals.

### LLM-crawler continuity

AI engines re-crawl on their own schedule (weekly to monthly). After cutover:

- **`/llms.txt` auto-updates** on NookDocs. Verify with `curl`.
- **Sitemap auto-updates.** Same.
- **Custom `Accept: text/markdown` + `X-Llms-Txt` headers** (when shipped — roadmap) help AI engines discover faster.

Spot-check AI answers weekly for a month. ChatGPT / Perplexity / Claude / Google AI → ask the top 5 questions about your product. Verify citations point at new URLs, not 404s.

## Phase 3 — Sunsetting the old platform

4-8 weeks after cutover:

<Steps>
  <Step title="Verify Google re-indexed">
    Search Console → Coverage → Indexed pages. New-platform URLs up; old-platform URLs dropping as redirects take effect. 80%+ indexed is a good signal.
  </Step>
  <Step title="Verify organic traffic stabilised">
    Analytics on new platform: traffic trend flat or rising. Traffic drop from the cutover week has recovered.
  </Step>
  <Step title="Verify no remaining traffic to old platform">
    Old-platform analytics: traffic declining steadily. Under 5% of pre-cutover levels means almost everyone uses the redirect.
  </Step>
  <Step title="Decommission carefully">
    - Keep redirects in place indefinitely (301/308 at DNS or CDN layer).
    - Can cancel old platform subscription once redirects are owned by a different layer.
    - Archive the old platform content (git repo) before cancelling, in case you need to refer back.
  </Step>
</Steps>

## Rollback plan

If Phase 2 goes badly — traffic tanks, writers can't work, editor breaks — have a rollback ready:

1. **Flip DNS back** to the old platform (5-minute TTL so changes propagate fast).
2. **Disable redirects** on the new platform.
3. **Writers resume on old platform** until issues resolved.
4. **Postmortem**, new timeline, retry.

You should be able to roll back within 30 minutes. If you can't, the rollback plan isn't real.

## Common migration mistakes

<AccordionGroup>
  <Accordion title="Migrating everything at once">
    Every page, every asset, every redirect in one weekend push. Guaranteed to break something. Phase it.
  </Accordion>
  <Accordion title="Skipping the redirect map">
    "We'll add redirects as users complain" → Google sees 404s, delists your content, rankings collapse, recovery takes 6 months. Redirect map is non-negotiable.
  </Accordion>
  <Accordion title="Keeping old-platform content online without redirects">
    Two copies of the same content at different URLs = Google picks one arbitrarily to rank, often the wrong one. Redirect or delete; don't leave both accessible.
  </Accordion>
  <Accordion title="Migrating during product launch week">
    Docs traffic spikes during launches. Migration during high-traffic period maximises user pain per incident. Pick a quiet calendar window.
  </Accordion>
  <Accordion title="No writer buy-in">
    Engineering team picks the new platform; writers find out at cutover. Writers hate it; content quality drops for 2 months. Involve writers from the evaluation phase.
  </Accordion>
  <Accordion title="Under-allocating time for content rewrite">
    "The CLI converted everything, we're done!" The CLI handled the mechanical transform. Content still needs human review — naming, voice, Diátaxis fit. Budget 2-4 weeks of author time post-migration for polish.
  </Accordion>
  <Accordion title="Missing the AI-crawler story">
    Old platform had its own `llms.txt` or equivalent. Old URL's been indexed by ChatGPT for months. New platform has a fresh `llms.txt` at different URLs. Spot-check AI answers weekly post-cutover.
  </Accordion>
</AccordionGroup>

## Migration checklist

Print this. Walk through linearly.

**Pre-migration (2-4 weeks out):**
- [ ] Run CLI migration against current repo → review output
- [ ] Audit content: keep / rewrite / merge / retire
- [ ] Build redirect map (old URL → new URL)
- [ ] Stand up new platform on staging subdomain
- [ ] Writers trained + one test page shipped each
- [ ] Verify `nookdocs.config.json` settings (theme / colors / SEO / contextual menu)
- [ ] Backup old platform content (git repo cloned)

**Cutover day:**
- [ ] Flip DNS or CDN rewrite to new platform
- [ ] Verify redirects work for sampled old URLs
- [ ] Verify new platform serves correctly on canonical URL
- [ ] Submit new sitemap to Search Console + Bing Webmaster
- [ ] If new domain: file Change of Address in Search Console
- [ ] Send announcement (blog post + Twitter + users' email list)

**Post-cutover (weekly, for 4 weeks):**
- [ ] Search Console coverage trend (indexed pages)
- [ ] Analytics traffic trend
- [ ] Support ticket volume (any spikes = hidden breakage)
- [ ] AI engine citation spot-check (ChatGPT/Perplexity/Claude)
- [ ] Broken link audit (`lychee` or similar)
- [ ] Redirect map audit (any entries receiving traffic but not redirecting correctly)

**Sunset (4-8 weeks post-cutover):**
- [ ] Old platform traffic under 5% of pre-cutover
- [ ] Keep redirects at DNS/CDN layer
- [ ] Archive old platform content
- [ ] Cancel old platform subscription
- [ ] Retrospective: what went well, what'd we change next time

## Related

- [Migrate from Mintlify (CLI)](/cli/migrate-from-mintlify) — the mechanical conversion
- [Migrate command](/cli/migrate) — CLI flags + platform detection
- [Redirects](/content/redirects) — the redirect config reference
- [SEO for docs](/guides/seo) — what matters for ranking continuity
- [Improving docs](/guides/improving-docs) — post-migration improvement loop
- [Maintenance](/guides/maintenance) — post-migration freshness

---

# Navigation IA
Source: https://docs.nookdocs.com/guides/navigation

Information architecture for docs. How to group pages, how deep to nest, when to split a tab, when to flatten a group. The IA principles behind the sidebar, not the config reference.

The docs sidebar is the contract you make with a reader: "here's the shape of what we document, pick a starting point". Bad IA reads like a sitemap dump. Good IA has hierarchy that matches how users think about the product. This guide covers the principles; for the config syntax, see [navigation configuration](/configuration/navigation).

## First principle: match user mental models

Docs IA fails when it mirrors your internal team structure instead of users' tasks.

```text
❌ Organised by team that built it
├── Platform Team
│   ├── Auth
│   ├── Rate limiting
│   └── Multi-region
├── Integrations Team
│   ├── Slack
│   └── Stripe
└── AI Team
    ├── Assistant
    └── Embeddings

✅ Organised by user task
├── Get Started
├── Authenticate
├── Common Integrations
│   ├── Slack
│   └── Stripe
├── AI Features
└── Deployment
```

Users come to docs with a job to do, not an org chart in mind.

## The three shapes of docs IA

Most documentation sites fit one of three shapes:

<CardGroup cols={2}>
  <Card title="Tutorial-first (narrative)" icon="book-open">
    **Best for:** beginner-heavy tools, SaaS with a high learning curve.
    **Shape:** one long linear sequence. "Start here → Next → Next." Sidebar reads top-to-bottom.
    **Example:** React's old docs (pre-new-docs redesign).
  </Card>
  <Card title="Reference-first (lookup)" icon="book">
    **Best for:** mature APIs with experienced users.
    **Shape:** heavy top-level categories (Auth / Objects / Webhooks / Errors), flat lists underneath.
    **Example:** Stripe, Twilio, AWS.
  </Card>
  <Card title="Task-first (goal-oriented)" icon="target">
    **Best for:** complex platforms with multiple personas.
    **Shape:** sections named by user goal ("Deploy", "Authenticate", "Customise"). Mix of tutorial + reference inside each.
    **Example:** Vercel, Supabase, NookDocs.
  </Card>
  <Card title="Hybrid (the most common)" icon="split">
    **Reality:** most real docs are 60% task-first + 30% reference + 10% tutorial. Top-level sections are tasks; deep in the reference trees, flat lookup lists. Tutorials siloed in their own section.
  </Card>
</CardGroup>

## The two-click rule

From any landing page, the user should reach the content they want in **two clicks**: pick a section, pick a page.

```text
Docs landing page
├── Click 1: "Deploy"         (top-level nav)
└── Click 2: "Custom domain"  (sidebar page)
= target page reached
```

Three clicks is okay but indicates the section could split. Four is too many — the reader either gives up or falls back to search.

Corollary: **if your sidebar has three levels of nesting, flatten one.** Users don't read past the second indent level. Either:

- Merge sibling groups together.
- Split the nested group into its own top-level tab.
- Move the contents of the deepest groups into their parent (flatten the tree by one level).

## Group granularity

### Too broad

```text
├── Documentation     (200+ pages, everything the product has)
```

One group for 200 pages means every page is equally visible — which means none of them are. Readers' eyes glaze.

### Too narrow

```text
├── Authentication
├── OAuth 2.0
├── JWT
├── API Keys
├── Session Cookies
├── Webhook Signatures
├── Password Hashing
├── ...
```

Seven groups for what's really one topic (auth). Fragmented + distracting.

### Right

```text
├── Authentication
│   ├── API keys
│   ├── OAuth 2.0
│   ├── JWT tokens
│   └── Webhook signatures
```

One group covering the domain. Sub-pages for distinct topics within. Reader skims the group header, finds the right page one level down.

**Rule of thumb:** 5-12 pages per group is the sweet spot. Less than 5 — consider merging with a sibling group. More than 12 — split or nest.

## Section order matters

Sidebar order = reading order for first-time visitors. The default reading journey should make sense:

<Steps>
  <Step title="Orientation (1-3 pages)">
    "Introduction", "Quickstart", "Concepts". Let new readers know WHERE they are and WHAT's possible.
  </Step>
  <Step title="Core workflows (ordered by frequency)">
    The 80% use cases first. Authentication before advanced configuration. Basic CRUD before webhooks.
  </Step>
  <Step title="Customisation + configuration">
    Once the reader has something working, they want to tweak it. Theme, branding, per-page controls.
  </Step>
  <Step title="Advanced + edge cases">
    Multi-region, monorepo setup, self-hosted, custom React components. Late-sequence material.
  </Step>
  <Step title="Reference (lookup, not reading)">
    Schema reference, component library, API endpoints. Users jump here via search, not linear reading.
  </Step>
  <Step title="Meta (changelog, migration, contribution)">
    Bottom of the sidebar. Readers seek these specifically.
  </Step>
</Steps>

## Tabs vs groups

NookDocs supports tabs (top-level horizontal nav) AND groups (sidebar sections). When to use which:

| Use tabs for | Use groups for |
|---|---|
| Major product areas (Docs / API Reference / Changelog / Guides) | Sub-topics within an area (Authentication / Deploy / Integrations inside Docs) |
| Content that has its own lifecycle (versioned API Reference separate from prose Docs) | Related pages that should share the same reading context |
| Audience switches (Developers tab vs Admins tab) | Task clusters (all custom-domain topics in one Deploy group) |

**Rule of thumb:** 3-6 tabs. Fewer than 3 isn't using the tab system; more than 6 crowds the top bar on mobile.

## Drill-down vs expand-all

NookDocs supports two sidebar behaviours — the default varies by theme:

### Expand-all (drill-down: false)

Every group label is a toggle. Click to expand. State persists per-session. Only one group expanded at a time is common.

Works well for:
- Reference-heavy docs where readers know what they're looking for.
- Large sidebars (20+ groups) where showing everything is overwhelming.

### Drill-down (drill-down: true, group.root set)

Group label is a link. Click navigates to a group landing page. Sidebar shows the current section's pages only.

Works well for:
- Task-first IA where each section is a distinct topic with its own landing.
- Marketing-adjacent docs where the "group landing" can pitch what's inside.

Configure via [interaction.drilldown](/configuration/navigation) + per-group `root` frontmatter.

## Nested groups — use sparingly

Nested groups create three-level hierarchy in the sidebar:

```text
Tab                      (top nav)
└── Group                (bold label)
    ├── Subgroup         (bold label, indented)
    │   ├── Page         (link)
    │   └── Page
    └── Subgroup
```

Cost: readers' eyes stop at level 2 (depth-of-field drops off fast). Pages buried in subgroups get less traffic.

**Use nesting when:** the taxonomy really has three levels (e.g. Integrations → Analytics → 13 providers). 16 flat "Integrations" pages is harder to scan than "Analytics (13) + Privacy (1) + Support (2)".

**Avoid nesting when:** there are only 2-4 pages in the subgroup. Flatten. We flattened NookDocs's own Integrations IA after realising the subgroup labels added noise.

## Tab naming

Tabs have ~60 chars total on desktop, ~30 on mobile before truncation. Keep each tab name 1-2 words:

| Good | Bad |
|---|---|
| Documentation | Full Documentation Set |
| API Reference | Complete REST API Reference |
| Changelog | Recent Updates & Releases |
| Guides | Writing & Publishing Guides |
| LLM-first | AI & LLM Integration |

Two-word tabs beat one-word when the one-word is generic ("Docs", "Info", "Resources" — all meaningless). Three-word tabs are almost always over-explaining.

## Group label naming

Same discipline. 1-2 words describing the topic, not the team or the abstraction:

| Good | Bad |
|---|---|
| Deploy | Deployment Operations |
| Authentication | Auth & Security Configuration |
| AI Tools | Artificial Intelligence Integration Layer |
| Analytics | Metrics, Reports & Analytics Suite |

Verbs-as-labels ("Deploy", "Authenticate", "Customise") read more clearly than nouns-as-labels ("Deployment", "Authentication", "Customisation") because they match user intent.

## Empty-state + orphan audits

Monthly IA hygiene:

<Steps>
  <Step title="Every nav group has ≥3 pages">
    A group with 1-2 pages is a signal — either merge with a sibling group or reconsider whether those pages need their own group.
  </Step>
  <Step title="Every page is in ≥1 nav group">
    Pages that exist but aren't navigated to are orphans. Either add to a group or delete.
  </Step>
  <Step title="No page is in multiple groups">
    Duplicates confuse readers. Pick the canonical location; link cross-group via prose if needed.
  </Step>
  <Step title="Sidebar fits one viewport height">
    Desktop 900px viewport ≈ 40 items visible. If the expanded sidebar scrolls, consider splitting the tallest group into a new tab.
  </Step>
</Steps>

## Mobile considerations

On mobile, the sidebar lives behind a hamburger. Opening the menu is one tap; finding the target is the hard part.

- **Tab strip horizontal scroll** — all tabs reachable via swipe. Don't let tab count blow past 6.
- **Groups collapse by default on mobile** — readers see group headers, tap to expand. Keeps initial view scannable.
- **Search takes priority** — on mobile, most users search instead of browse. Make the search affordance prominent.

## Topical clusters = SEO

IA choices affect SEO (see [linking guide](/guides/linking)). Strong topical clusters — pillar + supporting pages grouped together — signal topical authority. Scattered pages on related topics (one in "Deploy", one in "Configuration", one in "Advanced") look less authoritative.

When revising IA, consider the SEO cost of moving pages between sections — URL changes need [redirects](/content/redirects). Don't churn the IA for aesthetic reasons.

## Common IA mistakes

<AccordionGroup>
  <Accordion title="Internal team names as group labels">
    "Platform team" group. Users don't know your team structure. Rename to the USER-facing category the team works on.
  </Accordion>
  <Accordion title="Alphabetical ordering by default">
    Auth, Billing, Dashboard, Deploy, Integrations, Users... — alphabetical order is a weak signal. Order by user journey or frequency instead.
  </Accordion>
  <Accordion title="One-page groups">
    A group named "FAQ" with one page. Either put the page in an adjacent group or expand it into multiple pages.
  </Accordion>
  <Accordion title="Seven-word group labels">
    "How to set up and manage your custom domains". Compress to the noun phrase: "Custom domains".
  </Accordion>
  <Accordion title="Mixed tab-level and group-level taxonomies">
    A "Components" top tab AND a "UI Components" group inside Documentation. Pick one. Tabs are for coarse-grained sibling-content types (docs vs reference vs changelog); groups are for sub-topics within.
  </Accordion>
  <Accordion title="Landing pages with no content">
    A "Deploy" group where clicking the label loads an empty placeholder. Either make it a link-free expand toggle (no `root`) or write a real landing page (`root: docs/deploy/index` + substantive content).
  </Accordion>
</AccordionGroup>

## Related

- [Navigation configuration](/configuration/navigation) — the config reference for the sidebar
- [Content types](/guides/content-types) — Diátaxis affects where pages go
- [Linking](/guides/linking) — cross-links complement IA
- [SEO for docs](/guides/seo) — topical clusters as ranking signal
- [Understand your audience](/guides/understand-your-audience) — persona research informs IA decisions

---

# SEO for docs
Source: https://docs.nookdocs.com/guides/seo

Classic search still drives 40-60% of docs traffic. Title + meta + headings + links + sitemap + schema.org — the on-page SEO playbook for technical documentation in 2026.

AI answer engines got all the attention in 2025, but classic Google / Bing search still sends most of the qualified traffic to docs sites. The SEO playbook for docs is narrower than for marketing sites — you don't buy links, you don't run A/B tests on H1s, you don't chase long-tail keyword variants. What you DO is emit clean on-page signals so searchers looking for specific answers land on the page that has them.

This guide is the boring reliable playbook. For the generative-engine sibling, see [GEO](/guides/geo).

## The on-page signals that matter

Google's ranking factors are hundreds of signals, but for a docs page the load-bearing ones are a handful:

<CardGroup cols={2}>
  <Card title="Title tag" icon="type">
    The `<title>` that shows in the tab + Google result. Format: `{Page title} | {Site name}`. First 50-60 chars visible. Put the most valuable keyword first.
  </Card>
  <Card title="Meta description" icon="align-left">
    The ~155-char blurb under the title in the SERP. Not a direct ranking factor but drives click-through. Be specific about what the page delivers.
  </Card>
  <Card title="H1 match to query" icon="heading-1">
    One H1 per page, and it's the page title. Match the query phrasing a real user types ("Add a custom domain", not "Custom domain configuration").
  </Card>
  <Card title="H2-H3 keyword coverage" icon="list">
    Subheadings cover the natural sub-questions. "Add a custom domain" wants H2s like "DNS setup", "SSL verification", "Troubleshooting".
  </Card>
  <Card title="Internal links" icon="link">
    Every docs page should link to and be linked from 3-5 related pages. Build topical clusters, not orphans.
  </Card>
  <Card title="Canonical URL" icon="bookmark">
    `<link rel="canonical">` points at the single authoritative URL. Prevents duplicate-content penalties when a tenant has multiple domains.
  </Card>
  <Card title="Sitemap.xml" icon="map">
    Complete, fresh, only non-hidden pages. Submitted to Search Console + Bing Webmaster.
  </Card>
  <Card title="Schema.org JSON-LD" icon="braces">
    `TechArticle`, `BreadcrumbList`, `FAQPage`, `HowTo` — helps Google render enhanced SERP features.
  </Card>
</CardGroup>

## What NookDocs emits automatically

Every tenant ships these with zero configuration — the defaults are SEO-correct. Verify once, then forget about them:

- `<title>` from page frontmatter `title` + site `seo.title`, format `{Page} | {Site}`.
- `<meta name="description">` from frontmatter `description`, fallback to site `seo.description`.
- `<link rel="canonical">` to the primary domain's absolute URL per page.
- `<meta name="robots">` honouring `seo.indexing` site-wide + page `hidden: true`.
- `/sitemap.xml` at the docs root, regenerated on every page sync.
- `/robots.txt` at the docs root, references the sitemap.
- Open Graph + Twitter card tags from frontmatter fallback to site defaults.
- H1 from the frontmatter `title` — one per page, always.

See [Optimize → SEO](/optimize/seo) for the full config reference. The guide here is the *thinking* behind those defaults.

## Title tag — the 50-60 char budget

Google truncates page titles at ~60 characters. NookDocs stitches your page title with your site name:

```text
# Frontmatter
title: Add a custom domain

# Rendered <title>
Add a custom domain | Acme Documentation
```

The page title should stand on its own (user knows it's "Acme" from the site name). Patterns that work:

| Good | Why |
|---|---|
| `Add a custom domain` | Verb-first, matches query phrasing, leaves room for site name |
| `API rate limits` | Noun phrase, matches lookup queries |
| `Configure Stripe webhooks` | Specific integration named, high-intent query |

Patterns that don't:

| Bad | Why |
|---|---|
| `Learn how you can use our powerful custom domain system` | 60+ chars before site name, weasel words |
| `Docs` | Meaningless, won't rank for anything |
| `Acme — Custom Domains — Setup Guide` | Site name repeated by the platform; reads as dupe |
| `Custom Domain Configuration (Advanced)` | Parenthetical suffix burns chars |

## Meta description — the 155-char pitch

Meta descriptions aren't a direct ranking factor (since ~2009) but they drive click-through, which affects ranking indirectly. Write each page's `description` as a self-contained pitch for that page:

```markdown
# Good — specific, verb-first, names the affordance

description: "Add a CNAME record pointing to our edge, verify via the dashboard, and get auto-provisioned Let's Encrypt SSL in under 60 seconds."

# Bad — vague, reads like table of contents

description: "Learn about custom domains and how to set them up."
```

Aim for 140-160 chars. Google truncates longer; shorter wastes SERP real estate.

## Heading hierarchy

One H1 per page (your page title). H2s are major sections. H3s are subsections. Don't skip levels (no H4 directly under H1).

```markdown
# Add a custom domain              (H1 — from frontmatter)

## DNS setup                        (H2)
### CNAME for subdomain             (H3)
### ALIAS for apex                  (H3)

## SSL verification                 (H2)

## Troubleshooting                  (H2)
### DNS not propagating             (H3)
### CAA record blocking Let's Encrypt (H3)
```

Why this matters: Google's "People also ask" + "Things to know" SERP features scrape H2/H3 as candidate answers. Clear hierarchy = eligible for featured snippets.

## Internal linking strategy

Topical clusters rank better than orphaned pages. Minimum viable cluster structure:

<Steps>
  <Step title="Pillar page">
    Broad topic, ~1500-2000 words. Link OUT to 5-10 supporting pages.
    Example: `/deploy/custom-domain` pillar links to DNS providers, SSL specifics, multi-domain, troubleshooting.
  </Step>
  <Step title="Supporting pages">
    Narrower topic, ~500-1000 words. Link BACK to the pillar. Link SIDEWAYS to 2-3 sibling supporting pages.
    Example: `/deploy/cloudflare-custom-domain` links to pillar + `/deploy/vercel-custom-domain` sibling.
  </Step>
  <Step title="Glossary / reference pages">
    Short definitions, linked from every page that uses the term.
    Example: `/glossary/cname` referenced from every DNS-adjacent page.
  </Step>
</Steps>

Descriptive anchor text ranks better than "click here":

```markdown
❌ For more info, [click here](/deploy/custom-domain).
✅ See [adding a custom domain](/deploy/custom-domain) for DNS record specifics.
```

## Keyword research for docs — narrower than marketing

Docs SEO isn't about finding clever long-tail keywords competitors missed. It's about naming things the way users search for them.

Sources for the actual queries your users type:

- **Search Console "Performance" report.** Queries your docs already surface for, even if on page 2-3. Rewrite pages to rank higher.
- **Your own search bar analytics.** What users type into your on-site search tells you the exact phrasing they expect. [Analytics dashboard](/configuration/analytics) surfaces top queries.
- **Support tickets + Slack questions.** Every repeated question is a page that should exist.
- **Reddit + Stack Overflow for your product.** Phrases users use when asking the community to translate their problem.

Three things NOT to do:

- **Keyword-stuffing** — cramming a phrase into the page 20 times. Google's been on to this since 2003. Write natural prose.
- **Long-tail page farming** — spawning `/add-custom-domain`, `/how-to-add-custom-domain`, `/custom-domain-setup-guide` that all say the same thing. Canonicalise to one page.
- **Exact-match domains** — `customdomainsetup.com`. Users don't type domain names as queries anymore.

## Schema.org JSON-LD (roadmap)

Schema.org JSON-LD is structured data Google uses to render SERP enhancements — breadcrumbs in the results, FAQ accordions, HowTo cards, video carousels. NookDocs doesn't emit these automatically yet (roadmap). When it lands the shape will be:

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Add a custom domain",
  "description": "...",
  "author": { "@type": "Organization", "name": "Acme" },
  "datePublished": "2026-04-20",
  "dateModified": "2026-04-20"
}
</script>
```

Until then, the visible signals (title, description, canonical, sitemap) cover ~95% of docs-relevant SERP ranking. Schema is nice-to-have, not critical.

## Indexing controls

Three levers, scoped differently:

- **Site-wide `seo.indexing: "noindex"`** — everything gets `<meta name="robots" content="noindex, nofollow">` + `Disallow: /` in robots.txt. Use for staging and private docs.
- **Per-page `hidden: true` frontmatter** — drops the page from sitemap + search + llms.txt. Page still renders at its URL for anyone with the link.
- **Per-page `noindex: true` frontmatter** (if supported) — page renders + appears in sitemap but carries a robots noindex meta. Useful for gated flows where you want the URL discoverable but not indexed.

See [Optimize → SEO](/optimize/seo) for the config details.

## Image SEO

Images rank in Google Images if you help them:

- **Descriptive `alt` text**, not just filename. `alt="Dashboard showing the Custom Domains panel with two verified entries"` beats `alt="dashboard.png"`.
- **Lowercase hyphenated filenames**. `custom-domain-dashboard.png` beats `IMG_2341.PNG`.
- **Near your heading**. Images right below an H2 rank for that heading's keywords.
- **Reasonable size**. 1600×900 retina-friendly for hero images, 800×600 for inline, &lt;300KB compressed.

See the dedicated [media guide](/guides/media) for the full image + video story.

## Featured-snippet optimisation

Google's featured snippet ("People also ask", top-of-SERP answer box) pulls from the first passage after an H2 that matches a question-shaped query. To target:

```markdown
## What is a CAA record?

A CAA (Certificate Authority Authorization) record is a DNS record
that tells certificate authorities which issuers are allowed to
issue SSL certificates for your domain. Add Let's Encrypt to your
CAA record before requesting SSL:

    acme.com.  IN  CAA  0 issue "letsencrypt.org"
```

The H2 phrases the exact query. The first paragraph is the answer. The code block is the actionable takeaway. Google's extractor loves this shape.

## Common SEO mistakes in docs

<AccordionGroup>
  <Accordion title="Same title on many pages">
    "Documentation" on every page title — happens when frontmatter `title` is empty and the site name fallback kicks in. Every page MUST have a unique, specific `title`.
  </Accordion>
  <Accordion title="Missing canonical tags">
    If your tenant has multiple custom domains, each renders separately and Google sees duplicates. NookDocs auto-sets canonical to the primary domain. Verify with `curl -sI https://docs.acme.com/any-page | grep -i canonical`.
  </Accordion>
  <Accordion title="Orphaned pages">
    A page nothing else links to. Google discovers it via the sitemap but won't rank it well — backlinks and internal links both count. Audit with a crawler like Screaming Frog quarterly.
  </Accordion>
  <Accordion title="Big one-page mega-guides">
    "The Complete Guide to Acme" as a single 10,000-word page ranks for nothing specific. Split into 10 focused pages each covering one sub-topic with its own clean headings and internal links.
  </Accordion>
  <Accordion title="JavaScript-rendered content">
    Next.js SSR handles this correctly out of the box — your docs pages render to HTML on the server. The danger is third-party scripts (chat widgets, analytics) injecting content that Googlebot can't crawl. Keep the actual docs content static-HTML-rendered.
  </Accordion>
  <Accordion title="Search Console not verified">
    You can't improve what you can't measure. Add the property to Google Search Console + Bing Webmaster Tools within the first week of launching. Check query reports weekly for 2 months to understand what ranks.
  </Accordion>
</AccordionGroup>

## Monthly SEO routine (30 minutes)

1. **Search Console → Performance** — sort queries by position. Queries in positions 5-20 are quick wins. Pick one, rewrite the page's H1/H2s to match the query language.
2. **On-site search dashboard** — top queries that returned 0 results. Each is a missing page. Add it.
3. **Check for broken internal links** — use a crawler or `linkcheck` script. Fix any 404s.
4. **Freshness audit** — pages not touched in 12+ months. Update the content even if the feature's unchanged — Google likes fresh dates. NookDocs shows "Last updated" automatically from git.

## Related

- [GEO — AI search optimization](/guides/geo) — the AI-engine sibling to classic SEO
- [Optimize → SEO](/optimize/seo) — the mechanics + config reference
- [Style and tone](/guides/style-and-tone) — the voice that SEO rewards
- [Content types](/guides/content-types) — Diátaxis framework — smaller focused pages rank better
- [llms.txt](/optimize/llms-txt) — complementary AI-crawler index

---

# Style and tone
Source: https://docs.nookdocs.com/guides/style-and-tone

Second person, active voice, imperative instructions, heading intent, the foundations of technical writing that still rank in 2026 — the Microsoft / Google style guides distilled to one page you'll actually reference.

Most technical writing problems aren't vocabulary problems. They're **voice** problems. The page reads like a marketing brochure, a research paper, or a note-to-self, when it should read like a colleague explaining the task at your desk. This guide is the shortest path to voice that works for docs.

## The four rules

<CardGroup cols={2}>
  <Card title="1. Second person — 'you'" icon="user">
    "You add the record to your DNS provider." Not "users add", not "one adds", not "the record is added by the user". Second person is direct, unambiguous, and accessible.
  </Card>
  <Card title="2. Active voice" icon="arrow-right">
    "The parser reads the file." Not "the file is read by the parser." Active voice is shorter, clearer, and keeps the subject front and centre.
  </Card>
  <Card title="3. Imperative for instructions" icon="command">
    "Click **Save**." Not "you can click Save", not "clicking Save will...", not "users should click Save". Tell, don't suggest.
  </Card>
  <Card title="4. Specific over vague" icon="target">
    "Sets `colors.primary` to hex `#0ea5e9`." Not "sets your brand colour to a nice blue." Docs earn trust by being precise.
  </Card>
</CardGroup>

## The twenty words to avoid

Remove these from your writing. They either add nothing or actively mislead.

| Avoid | Because |
|---|---|
| `easily`, `simply`, `just` | If it were easy the reader wouldn't be reading docs. Removing the word doesn't change the meaning; its presence implies the reader is slow. |
| `please` | Begging. Imperative without please is direct; with please is weirdly formal. |
| `obviously`, `clearly`, `of course` | If it were obvious you wouldn't document it. These words make readers feel dumb. |
| `very`, `really`, `quite`, `rather` | Intensifiers without specificity. "Very fast" is slower than "under 50ms". |
| `excellent`, `awesome`, `great`, `powerful` | Marketing adjectives in reference content. Reference docs describe, they don't sell. |
| `leverage`, `utilize` | Say "use". Every time. |
| `functionality`, `capabilities` | Say "feature" or just name the thing. "The feedback functionality" → "the feedback widget". |
| `in order to` | Say "to". Always shorter, always clearer. |
| `synergy`, `solution` | Corporate filler. Name the actual thing. |
| `best practice` | Overused. If it's truly a best practice, show the evidence. If not, say "recommended pattern". |
| `would`, `could`, `might` | Softens claims unnecessarily. "You might want to set..." → "Set...". Take a position. |
| `robust`, `scalable`, `enterprise-grade` | Unverifiable claims. Quantify or skip. |

Quick before-and-after:

```markdown
❌ "In order to easily leverage the powerful feedback functionality,
   simply click the Configure button. You might want to explore
   some of the awesome customization options!"

✅ "To configure feedback, click **Configure**. You can customise
   prompts, reasons, and the GitHub-issue integration."
```

63 → 24 words. Same meaning. Reads like a colleague.

## Heading intent

Each heading announces what the reader will find in the section. Bad headings waste attention.

| Heading intent | Good | Bad |
|---|---|---|
| Reference | `## Rate limit headers` | `## About the headers` |
| How-to | `## Add a custom domain` | `## Custom domains` (is it a how-to? a concept?) |
| Explanation | `## Why we rate-limit per API key, not per IP` | `## Rate limiting` |
| Troubleshooting | `## Fix: 429 with `Retry-After: 3600`` | `## Common issues` |

Headings answer the question "what question is this section for?". If you can't answer that, rewrite.

### Verb-first headings for how-to

For sections that teach a task, start with a verb.

```markdown
❌ "Authentication setup"
✅ "Set up authentication"

❌ "Adding a custom domain"
✅ "Add a custom domain"

❌ "Configuration of the AI assistant"
✅ "Configure the AI assistant"
```

The verb-first form matches user queries ("how do I ...") and signals what the reader will DO.

## Sentence shape

<Steps>
  <Step title="One idea per sentence">
    If your sentence has three commas and an "and" in the middle, it's probably two sentences. Split.
  </Step>
  <Step title="Subject near the verb">
    "The parser, after walking every ref and resolving the composition keywords, builds the schema tree." → "The parser walks refs, resolves composition keywords, and builds the schema tree."
  </Step>
  <Step title="Concrete nouns, concrete numbers">
    "Takes a while" → "Takes about 5 seconds." "Lots of memory" → "Uses 512 MB peak."
  </Step>
  <Step title="No nested negatives">
    "It's not uncommon for users not to realize..." → "Users often don't realize..."
  </Step>
</Steps>

## Paragraph structure

- **One idea per paragraph.** If you switch topic mid-paragraph, break.
- **First sentence carries the claim.** Subsequent sentences qualify, illustrate, or limit the claim. Not the reverse.
- **Aim for 40-80 words.** Paragraphs over 100 words usually mean two ideas squashed together.

## Tone registers for different content types

Reference docs, tutorials, and explanations each want a slightly different register:

<CardGroup cols={2}>
  <Card title="Reference" icon="book">
    **Register:** dispassionate, exhaustive, flat.
    **Voice:** third person on the subject, second person on the reader.
    **Example:** "The `theme` field accepts one of ten slugs. You set it by editing `nookdocs.config.json`."
  </Card>
  <Card title="How-to" icon="list-ordered">
    **Register:** direct, imperative, time-bound.
    **Voice:** second person throughout.
    **Example:** "Add the CAA record. Wait 60 seconds for DNS propagation. Trigger verification from the dashboard."
  </Card>
  <Card title="Tutorial" icon="graduation-cap">
    **Register:** encouraging, first-person plural in setup, imperative in steps.
    **Voice:** "We'll build X. First, install the SDK."
    **Example:** "Let's set up your first Acme integration. Start by installing the package."
  </Card>
  <Card title="Explanation" icon="brain">
    **Register:** narrative, opinionated, comparative.
    **Voice:** first person plural for product claims; second person for reader engagement.
    **Example:** "We built rate-limiting per API key rather than per IP because most of our users sit behind corporate NAT."
  </Card>
</CardGroup>

See [content types](/guides/content-types) for the Diátaxis framework that maps these four modes to distinct page types.

## Accessibility notes that affect tone

- **Write for a screen reader.** Imagine the page read aloud by VoiceOver or JAWS. "Click the button" works. "Click the one in the red circle" does not — screen readers don't narrate colour.
- **Avoid spatial instructions.** "Above" and "below" fail in single-column mobile layouts. Use named anchors: "See the [Rate limits section](#rate-limits)."
- **Expand acronyms on first use.** "CAA (Certificate Authority Authorization) record." Subsequent uses can be bare.
- **Number formats consistently.** `1,000` not `1000` or `1k` — screen readers handle commas better.

## Tone patterns that don't work

<AccordionGroup>
  <Accordion title="Conversational filler in reference docs">
    "Hey! Let's talk about rate limits. They're pretty interesting actually..." — fine for blog posts, hostile in reference docs. Users are trying to solve a specific problem, not hang out.
  </Accordion>
  <Accordion title="Academic passive voice">
    "It was determined that the optimal approach is..." — sounds rigorous, reads as throat-clearing. Say "We chose X because Y" and move on.
  </Accordion>
  <Accordion title="Faux-humble qualifiers">
    "In our humble opinion, you might perhaps want to consider..." — take a position. Your users came for guidance; qualifiers signal uncertainty.
  </Accordion>
  <Accordion title="Internal team jargon">
    "As discussed in the Q3 OKR review..." — your users don't know what Q3 OKR meant. Restate context or remove the reference.
  </Accordion>
  <Accordion title="Mixed tense in a how-to">
    "First, you'll run npm install. Then the config was loaded. Now we verify." — pick one tense (present imperative for how-tos) and stick.
  </Accordion>
</AccordionGroup>

## Edit passes

Write first, edit second. One-pass writing produces voice problems. A three-pass edit catches them:

1. **Shape pass.** Does each paragraph have one idea? Does each section have a verb-first heading? Are there dead intro paragraphs?
2. **Voice pass.** Any "we" that should be "you"? Any passive that should be active? Any suggestive language that should be imperative?
3. **Density pass.** Can each sentence lose 2-3 words without losing meaning? Are there filler adjectives to cut? Can prose become a table or a list?

Aim for 30% shorter on the third pass than the first draft. If you're cutting less, you weren't over-writing.

## References

- [The Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) — the definitive modern reference, freely available.
- [Google Developer Documentation Style Guide](https://developers.google.com/style) — complementary, slightly more opinionated.
- [Diátaxis](https://diataxis.fr) — the content-types framework; see [our guide](/guides/content-types).

## Related

- [Writing for LLMs](/guides/writing-for-llms) — dual-audience extension of the same foundations
- [Content types](/guides/content-types) — Diátaxis framework
- [GEO — AI search optimization](/guides/geo) — ranking in AI answer boxes
- [Component library](/components/callout) — the primitives that enforce structure

---

# Understand your audience
Source: https://docs.nookdocs.com/guides/understand-your-audience

Docs ship to multiple reader personas — and now to LLM agents. User research, persona frameworks, and how to validate your assumptions before you rewrite everything for one bad theory.

The biggest wastes in docs writing come from false assumptions about the reader. "Our users are senior engineers" — actually half are JR engineers onboarding. "They'll read the quickstart first" — actually most land deep on a Google-indexed reference page. "They don't need the basics explained" — actually even experts appreciate concise recaps.

This guide covers how to find out who actually reads your docs, what they're trying to do, and how to ship content that matches.

## Why persona research matters for docs

<CardGroup cols={2}>
  <Card title="Voice depends on it" icon="mic">
    Writing for JR engineers wants more hand-holding; senior engineers want density + escape hatches. You can't split the difference without sounding flat for both.
  </Card>
  <Card title="Navigation depends on it" icon="map">
    Task-first IA assumes you know your users' main tasks. Wrong tasks → users bounce.
  </Card>
  <Card title="Examples depend on it" icon="code">
    "A real-world example" for a Stripe integration in 2024 was probably SaaS billing. In 2026 it's as likely to be AI API metering. Examples age without persona grounding.
  </Card>
  <Card title="Priority depends on it" icon="list-ordered">
    You have time to write 5 pages this quarter. Which 5 matter most? Only persona research answers that.
  </Card>
</CardGroup>

## The audience — three groups now

Classically, docs audiences were:

1. **Evaluators** — deciding whether to adopt your product.
2. **Implementers** — building the first integration.
3. **Operators** — maintaining a running integration.

In 2026 add:

4. **LLM agents** — reading on behalf of human users to answer questions or generate code.

All four deserve tuned content. See [writing for LLMs](/guides/writing-for-llms) for the agent-specific story; this guide focuses on the three human groups.

### Evaluators

Shape: senior-ish, time-constrained, comparing 2-3 alternatives. Wants to understand trade-offs + pricing + capabilities in 15 minutes.

Reads:
- Landing page (marketing site, not docs).
- "Introduction" / overview.
- "Concepts" / architecture.
- A couple of reference pages to check claims.

Almost never finishes a tutorial. Rarely reads past the third paragraph of any page.

**Content tuning:** first paragraph of every page answers "what is this for". Architecture page exists and shows the big picture. Pricing + tiering surfaced.

### Implementers

Shape: mid-level, task-focused, usually on a deadline. Wants the first working integration ASAP.

Reads:
- Quickstart / tutorial.
- Authentication specifics.
- 2-3 core API endpoints relevant to their use case.
- Error code reference when something breaks.

Doesn't read architectural explanations unless they hit a design decision they disagree with.

**Content tuning:** working examples in every language they might use. Complete copy-paste snippets. Error codes documented by error message text (so Ctrl-F finds them).

### Operators

Shape: senior, managing an already-working integration. Needs rate limits, webhooks, monitoring, migration docs.

Reads:
- Webhook reference.
- Rate limit docs.
- Changelog + migration guides for version bumps.
- Security / compliance docs.

Skips tutorials entirely.

**Content tuning:** Every breaking change documented with migration steps. Every quota numerically exact. Security posture explicit.

## How to learn who your actual readers are

### Analytics

NookDocs's [analytics](/configuration/analytics) + on-site search logs are the cheapest signal:

- **Top landing pages** — where readers arrive. Reveals which content Google sends traffic to.
- **Top search queries** — what readers look for. Reveals gaps (queries returning 0 results) and winning terms.
- **Session paths** — what readers visit after landing. Reveals whether the "next step" you expected actually works.
- **Bounce rate per page** — high bounce on a reference page is usually fine; high bounce on a tutorial's step 2 signals that step is broken.

### Support + forum questions

Every repeated question is a missing or hard-to-find docs page:

1. Dump 3 months of support tickets into a spreadsheet.
2. Tag each by topic (auth / webhooks / billing / deploy / …).
3. Sort by frequency.
4. For the top 20 topics, check: is there a docs page covering this? Is it findable via search? Is it the first result?

Usually the answers are: half the time no page exists, a third of the time the page exists but is unfindable, and the rest of the time the page exists but doesn't answer the question directly.

### Forums + Stack Overflow

Search for your product name on Stack Overflow, Reddit, Hacker News. Read the top 50 questions.

Patterns to notice:

- **Exact phrasing of queries** — "how to X with Acme" gives you the precise SEO + GEO target phrases.
- **Misconceptions** — if the same misconception appears 5 times, your docs aren't clarifying it. Write a page that directly addresses it.
- **Workarounds** — if the community invented workarounds for a missing feature, that's a product gap to close + a docs gap to fill.

### User interviews

Expensive but highest-signal. 5 interviews with recent implementers tells you more than 500 session replays.

Targeted questions:

- "Walk me through the first day you used Acme. What did you read?"
- "When you got stuck, what did you try? What worked, what didn't?"
- "Is there a piece of our docs you wish existed?"
- "Did you ever feel condescended to by the docs? Or felt like it assumed you knew something you didn't?"

**Avoid** asking users to rate their own skill level — self-assessment is unreliable. Infer skill level from the vocabulary they use.

### LLM-assisted research

Paste your product name + common questions into ChatGPT / Claude / Perplexity. See what they answer.

Signals:
- **Missing citations** — the LLM answers correctly but doesn't cite your docs. Your docs aren't ranking for that query (see [GEO](/guides/geo)).
- **Wrong answers** — the LLM makes up features you don't have, OR misses features you do. Your docs need clearer canonical pages.
- **Outdated answers** — LLM cites your 2022 blog post when the correct answer is in a 2025 docs page. Update old content and add redirects.

## Building a persona

Once you have data, codify into 2-3 personas. Each persona gets a card:

```markdown
# Persona: Mid-level Developer (Mia)

## Context
- 3-5 years of dev experience
- Shipping a side project or startup MVP
- Evaluating Acme vs Competitor X

## Goals
- Ship first integration in <1 hour
- Understand pricing before committing
- Find runnable code examples

## Pain points
- Abandoned Competitor X because docs assumed too much
- Doesn't have time to read 10k-word concept guides
- Gets frustrated when "See below" references scroll offscreen

## Vocabulary
- Says "JWT" not "JSON Web Token"
- Says "endpoint" not "route"
- Says "env var" not "environment variable"

## What she reads first
- Landing page
- Quickstart
- Auth doc (because every integration starts with auth)

## What she skips
- Architecture explanations
- Migration guides (not a current operator yet)
- Comparison pages
```

Typical team has:
- **2-3 primary personas** — 80% of docs optimisation targets these.
- **1-2 edge personas** — niche but important (security auditors, compliance officers).

Don't split further than that. Three personas × three voice variations × three example variations = nine versions of every page. You won't ship.

## Persona-specific content tuning

### Introduction paragraphs

First paragraph of every page should work for all primary personas. Usually means: answer the "what is this" in 1 sentence, signal who it's for in the next.

```markdown
# Rate limits

Acme caps each API key at 100 requests per minute by default. Operators
tuning quotas, implementers debugging 429 errors, and architects
evaluating production readiness all land here. Enterprise plans scale
to 1000/min.
```

One sentence per likely reader. Implementer reads line 1 + 2 + stops. Architect reads line 2 + skips to the Enterprise mention. Operator reads the whole thing.

### Examples

Every working example should be one that the dominant persona might actually ship. Generic `foo/bar` examples frustrate — readers have to translate back to their domain every time.

```markdown
❌ Generic
const response = await fetch("/api/foo", { body: JSON.stringify({ bar: 123 }) });

✅ Plausible for an implementer reading this
const response = await stripe.paymentIntents.create({
  amount: 2000,
  currency: "usd",
  payment_method_types: ["card"],
});
```

### Escape hatches for advanced readers

Beginners want step-by-step. Advanced readers want "just show me the config". Use callouts to provide both without bloating the main prose:

```mdx
<Accordion title="Quick version (if you know DNS + CNAMEs)">
  Add `cname.nookdocs.site` as a CNAME target for your subdomain.
  SSL provisions automatically within 30 seconds of verification.
</Accordion>

## Step-by-step version

<Steps>
  <Step title="Open your DNS provider">
    ...
  </Step>
  ...
</Steps>
```

Advanced reader clicks the accordion, gets the TL;DR, moves on. Beginner reads the step-by-step. Both groups served, no duplication of conceptual content.

## Common persona mistakes

<AccordionGroup>
  <Accordion title="Writing for the version of you that already knows everything">
    The most common miss. You've been working on the product for months; you've internalised every concept. Your first docs draft skips all the context the reader needs. Have someone fresh read every new page and flag what's missing.
  </Accordion>
  <Accordion title="Assuming one monolithic 'developer' persona">
    "Developers" covers 80% of your audience but internally splits into very different subgroups: backend engineers want different examples than frontend engineers; junior engineers want more hand-holding than senior; agencies building custom work want different patterns than startups building their own product. At least split by experience level OR role.
  </Accordion>
  <Accordion title="Personas based on vibes, not data">
    "Our users are technical founders." Based on what? Sales intuition isn't user research. Validate against actual session data + tickets before rewriting to match the persona.
  </Accordion>
  <Accordion title="Optimising for evaluators at the expense of operators">
    Everyone loves a shiny landing + quickstart. Meanwhile the migration guide for last year's breaking change is 50 words, the rate-limit page is 30 words, the troubleshooting section for webhooks is one Accordion with stale advice. Operators outnumber evaluators for mature products.
  </Accordion>
  <Accordion title="Forgetting the LLM persona">
    Every content choice still needs to serve human readers. But neglecting the agent persona means your docs don't rank in AI answer boxes + LLMs hallucinate features you don't have. See [writing for LLMs](/guides/writing-for-llms) for the explicit agent-targeting story.
  </Accordion>
  <Accordion title="Persona creep">
    Adding more personas every quarter. "We need a Security Auditor persona!" "Let's add a Compliance Officer persona!" Each new persona adds optimisation overhead. Cap at 3-5 and push back on new additions unless they're >5% of the audience.
  </Accordion>
</AccordionGroup>

## Research cadence

Cheap signals weekly, expensive signals quarterly:

- **Weekly (15 min):** Scan top 20 search queries + top 5 bounce pages in analytics.
- **Monthly (1 hr):** Review last month's support tickets. Tag + count. Update docs for top 3 themes.
- **Quarterly (1 day):** 3-5 user interviews. Recalibrate persona cards if patterns shifted.
- **Annually (1 week):** Full IA audit through the current persona lens. Move pages, split sections, retire content.

## Related

- [Style and tone](/guides/style-and-tone) — voice tuning per persona
- [Content types](/guides/content-types) — different personas want different Diátaxis modes
- [Writing for LLMs](/guides/writing-for-llms) — the fourth persona + its content needs
- [SEO for docs](/guides/seo) — Search Console queries are the cheapest persona signal
- [Analytics](/configuration/analytics) — the on-platform data source

---

# Writing docs with Windsurf
Source: https://docs.nookdocs.com/guides/windsurf

Cascade-driven multi-file edits + `.windsurf/rules/` memory files turn Windsurf into a NookDocs-fluent authoring environment. Best for non-developer writers who want agent power without a terminal.

[Windsurf](https://codeium.com/windsurf) is Codeium's editor — a VS Code fork with "Cascade", an agent that plans multi-step edits across files. Unlike Cursor's inline-first approach or Claude Code's terminal-first approach, Windsurf sits between them: GUI-first, but agent-capable. Good match for docs teams with non-developer writers who'd struggle in a terminal but want agent-level help.

This page gives you Windsurf-specific rules + prompt patterns for NookDocs repos.

## Install + setup

<Steps>
  <Step title="Install Windsurf">
    Download from [codeium.com/windsurf](https://codeium.com/windsurf). Same platform support as Cursor (macOS / Windows / Linux).
  </Step>
  <Step title="Open your docs repo">
    `File → Open Folder...` and point at the local clone.
  </Step>
  <Step title="Configure rules">
    Create `.windsurf/rules/nookdocs.md` at the repo root. Windsurf auto-loads any `.md` file in `.windsurf/rules/` as persistent memory for Cascade.
  </Step>
  <Step title="Optional: configure Windsurf global memory">
    Settings → Memory → add cross-repo rules for your personal authoring style if you work on multiple docs sites.
  </Step>
</Steps>

## The `.windsurf/rules/nookdocs.md` template

Windsurf's rules files are plain Markdown — Cascade treats them as persistent context that applies to every agent action in the repo.

```markdown .windsurf/rules/nookdocs.md
# NookDocs authoring rules

This repo is a NookDocs documentation site. Pages live under `docs/`,
config at `nookdocs.config.json`.

## Component library

Full spec: https://nookdocs.com/nookdocs-components.llm.md

Use these components (don't invent others, don't import anything):

**Content**
- `<Callout type>`, `<Note>`, `<Tip>`, `<Warning>`, `<Info>`,
  `<Danger>`, `<Check>` — inline notices
- `<Badge>`, `<Pill>`, `<Tag>`, `<Kbd>` — inline labels
- `<Snippet>` — reusable content (inline children until Phase 4
  file-based ships)

**Layout**
- `<Card title icon href>`, `<CardGroup cols>` — card grids
- `<Tile>`, `<Tiles cols>` — lighter alternative to cards
- `<HeroCard>`, `<LinkCard>` — landing-page + link affordances

**Code**
- `<CodeGroup>` — tabbed multi-language code blocks
- `<CodeBlock>`, `<TerminalBlock>` — single-language
- `<RequestExample>`, `<ResponseExample>` — API-specific wrappers

**Navigation**
- `<Tabs>` + `<TabsList>` + `<TabsTrigger>` + `<TabsContent>`
- `<Accordion>` + `<AccordionGroup>` + `<AccordionItem>` +
  `<AccordionTrigger>` + `<AccordionContent>`

**Procedural**
- `<Steps>` + `<Step title="...">` — ordered instructions

**Media**
- `<Frame caption>` — wrap images with caption
- `<Image>`, `<Video>`, `<Embed>`, `<Mermaid>`

**API**
- `<ParamField path type required default>` — request params + config
  keys
- `<ResponseField name type>` — response body fields
- `<ApiMethod>` — endpoint header

**Meta**
- `<Update date label version tags>` — changelog entries
- `<Visibility for="humans|agents">` — audience-split content
- `<Tooltip>`, `<View>`, `<Expandable>`, `<Prompt>`

## Frontmatter

Every page:

    ---
    title: Page title (verb-first for how-tos)
    description: 1-sentence specific pitch, 140-160 chars.
    icon: lucide-icon-name
    ---

Changelog pages add `rss: true` to expose the RSS subscribe button.

## Authoring discipline

1. Second person, active voice, imperative for instructions.
2. Lead with the answer. Skip "In this guide we will..." intros.
3. Verb-first H2 headings for how-to sections.
4. `<ParamField>` for every config key + API param.
5. Fenced code blocks with language tags — always.
6. Multi-language examples go in `<CodeGroup>`.
7. Cross-link to 3-5 related pages in `## Related` at the bottom.
8. `<Visibility for="agents">` for LLM-directive content;
   `<Visibility for="humans">` for UI-only content.

## Verification (run after every edit)

```bash
# Parse-check
node --input-type=module -e "
  import { mdxParse } from 'safe-mdx/parse';
  import { readFileSync } from 'fs';
  mdxParse(readFileSync('docs/PATH.mdx','utf-8'));
"

# Cross-layer sync (config changes)
npm run check:sync
```

## Things NOT to do

- No ES imports in MDX. Components are globally available.
- No HTML tags (use the components listed above).
- No marketing language in reference docs ("powerful", "seamless",
  "easily", "simply" — all banned).
- No `<h1>` in the body — the title comes from frontmatter.
- No orphan pages. Every new page links from at least one sibling.
```

Commit this at `.windsurf/rules/nookdocs.md`. Cascade uses it as persistent context.

## Cascade workflows

Cascade is Windsurf's multi-step agent. Three patterns that work well for docs:

### Cascade pattern 1: "Add a new page with full nav integration"

Open Cascade (Cmd/Ctrl+L), write:

```text
Create a new documentation page at docs/configuration/webhooks.mdx covering
webhook configuration. Use the structure from docs/configuration/feedback.mdx
as a template. The page should cover:

- Retry policy (ParamField for maxRetries, backoffStrategy, retryDelay)
- Signature verification (ParamField for secret, algorithm)
- Payload schema (ResponseField for each field in the webhook body)

Include one complete JSON example at the end showing all fields set.

Then add the page to nookdocs.config.json navigation under the Configuration
group, positioned after custom-domain.

Finally run parse-check + npm run check:sync to verify no errors.
```

Cascade plans the steps (create file → write content → update nav → run checks), executes them in order, shows you the diff per step. Approve or redirect at each step.

### Cascade pattern 2: "Audit + fix across multiple pages"

```text
Audit every file in docs/integrations/analytics/ against these rules:
1. Frontmatter has title + description + icon
2. Description is 100-160 chars and specific (not generic)
3. ParamField present for integrations.<key> with required + type
4. Related section at the end with 3-5 cross-links

List issues per file, then fix all of them in a single batch commit.
```

Cascade loops through each file, reports, then fixes. Useful for enforcing consistency across similar pages (integrations, API endpoints, component references).

### Cascade pattern 3: "Follow the link to fix a downstream ref"

```text
I renamed `docs/features/copy-for-llms.mdx` to
`docs/optimize/markdown-export.mdx`. Find all internal links pointing at
the old path across docs/ and fix them. Also add a redirect entry to
nookdocs.config.json#redirects so external inbound links don't 404.
```

Cascade handles the multi-file edit + the config update. Verify with a grep before accepting.

## Cascade vs Chat vs Command

Windsurf has three editor-level interaction surfaces:

<CardGroup cols={2}>
  <Card title="Chat (Cmd+L)" icon="message-square">
    Read-only Q&A about current file or repo. "What components does this page use?" — no file changes. Fast.
  </Card>
  <Card title="Command (Cmd+I)" icon="terminal">
    Single-file inline edit. Select text, describe transform, approve. Like Cursor's Cmd+K.
  </Card>
  <Card title="Cascade (Cmd+Shift+L)" icon="waves">
    Multi-step, multi-file agent. Plans ahead, executes, reports. For broader refactors + new-page creation.
  </Card>
  <Card title="Autocomplete (inline)" icon="zap">
    Tab-complete as you type. Context-aware — suggests MDX components when editing a `.mdx` file.
  </Card>
</CardGroup>

Typical docs workflow uses all four: Autocomplete for typing speed, Command for targeted rewrites, Cascade for new pages + refactors, Chat for "how does X work" questions.

## Non-developer writer workflow

Windsurf's GUI-first nature makes it the easier onboarding for writers without terminal experience. Baseline workflow:

<Steps>
  <Step title="Clone the repo via Windsurf's Source Control panel">
    File → Open Folder from URL (Windsurf offers this UX directly; no `git clone` command required).
  </Step>
  <Step title="Create a branch for your changes">
    Source Control sidebar → ••• → Branch → Create Branch. Name it `docs/your-topic`.
  </Step>
  <Step title="Open Cascade, describe the task">
    "Add a quickstart page for our new Stripe integration." Cascade walks the steps.
  </Step>
  <Step title="Approve each step + review diff">
    Cascade pauses at each file change. Click Accept or edit the plan.
  </Step>
  <Step title="Commit + push via the Source Control panel">
    Stage changes → commit message → push. No terminal required.
  </Step>
</Steps>

Writers without Git background can be productive in Windsurf within ~30 minutes of pairing with an engineer for the first task.

## What Windsurf does well

- **GUI-first editing for non-dev writers.** Source Control panel replaces terminal for the common git tasks.
- **Cascade multi-step planning.** Transparent plan-and-execute; writer can intervene between steps.
- **Persistent rules files** — `.windsurf/rules/` applies repo-wide context to every Cascade session.
- **Global memory** — Windsurf can remember personal authoring preferences across repos.
- **Fast tab-complete** — Codeium's underlying model is optimised for latency.

## What Windsurf doesn't do well

- **Single-line tight edits.** Cascade has overhead; for a two-word typo fix, direct edit is faster.
- **Terminal-heavy workflows.** Engineers working on build pipelines + CI often prefer Claude Code.
- **Custom / less-common models.** Windsurf's model menu is narrower than Cursor or Claude Code. Primarily Codeium + Anthropic + OpenAI options.

## Collaboration pattern

If your team splits writers + engineers across Windsurf + Cursor / Claude Code, keep the context files in sync:

```text
.windsurf/rules/nookdocs.md   ← Windsurf writers read this
.cursor/rules/nookdocs.mdc    ← Cursor engineers read this
AGENTS.md                       ← Claude Code reads this
```

All three files can have **similar content** with format differences. Keep the source of truth in `AGENTS.md`; mirror to the other two. Nothing prevents you from committing all three — each tool reads its own.

## Related

- [Claude Code](/guides/claude-code) — CLI agent sibling
- [Cursor](/guides/cursor) — editor-based sibling (more inline-first than Windsurf)
- [Writing for LLMs](/guides/writing-for-llms) — broader theory
- [Component spec](/llm-first/component-spec) — the URL all three tools reference
- [Style and tone](/guides/style-and-tone) — the authoring rubric the rules enforce

---

# Writing for LLMs
Source: https://docs.nookdocs.com/guides/writing-for-llms

Docs are read by humans AND by LLMs. LLMs skim differently, chunk at different boundaries, and penalise different patterns. Author pages that keep humans happy AND degrade well when a model ingests them.

Most technical writing advice was written for humans. That advice still applies — but there's a second audience every public docs site now has: **LLMs ingesting the page to help users**. Claude, ChatGPT, Cursor, Windsurf, Perplexity, Google AI Overviews — they all read your docs, they all summarise, and they all get asked "how do I X with Acme?" by your users.

This guide covers what's different about the LLM audience and how to author pages that serve both.

## What LLMs actually see

LLMs don't read HTML. They read **text extracted from HTML** — or in our case, the raw MDX you publish at `/<page>.md`. The implications:

<CardGroup cols={2}>
  <Card title="Visual hierarchy disappears" icon="eye-off">
    Bold, italic, font sizes, colour, callout background — gone. Headings survive because they're prefixed with `##` in Markdown. Everything else is flat paragraphs.
  </Card>
  <Card title="Images are caption-only" icon="image-off">
    LLMs can't see your screenshots. Only the `alt` text + `caption` prop + prose around the image survive. Make the text carry the meaning.
  </Card>
  <Card title="Tables turn into rows of text" icon="table">
    Table headers convert to column labels in each row's text. A 10-row table becomes 10 paragraphs each restating the column names.
  </Card>
  <Card title="Code blocks preserve verbatim" icon="code">
    Fenced code blocks round-trip cleanly through every LLM. This is the most LLM-friendly content type you can ship.
  </Card>
</CardGroup>

## How LLMs skim

LLMs don't read top-to-bottom like a human might. They:

1. **Chunk** the page into ~500-token windows (varies by model).
2. **Embed** each chunk into a vector space for similarity search.
3. **Retrieve** the chunks most similar to the user's question.
4. **Synthesise** an answer from the top-N retrieved chunks.

Implications for authoring:

- **Each ~500 tokens should stand alone.** If paragraph 3 assumes you read paragraph 1, the LLM might retrieve just paragraph 3 and give the user a disconnected answer. Repeat key terms inside each major section.
- **Section headings are anchors.** A good `## Rate limits` heading lets the retrieval step match on "rate limit" exactly. Vague headings (`## More info`) don't match anything.
- **First sentence of each section is load-bearing.** Many retrieval pipelines emphasise the first line. Lead with the answer, then elaborate. Don't build up to the point.

## Chunk boundaries

The retrieval chunker usually splits on **paragraph breaks** and then further on **~500-token windows**. Split-friendly authoring:

- **Keep paragraphs focused.** One idea per paragraph. A paragraph of "X, Y, Z all related" retrieves as one chunk — helpful. A paragraph that pivots mid-way gets split mid-thought — unhelpful.
- **Use `##` boundaries aggressively.** Every 200-400 words, start a new `##` section. Gives the chunker natural split points.
- **List-heavy content chunks well.** A 10-item bulleted list usually stays together because lists have bullet-to-bullet affinity. Mixed paragraph + list content splits unpredictably.

## Token economics

Every chunk the retrieval step pulls costs input tokens on the answering model. Expensive models (GPT-4, Claude Opus) are ~5× costlier than cheap ones (Claude Haiku, GPT-4o-mini). If your docs page is 10,000 tokens and the LLM pulls the whole thing into context for every question, that's real money per query.

Tactics:

- **Keep pages under ~2000 words** (roughly 3000 tokens) when possible. Split long pages into multiple focused pages linked together.
- **Remove throat-clearing.** "In this section we will discuss…" — delete. Start with the first substantive sentence.
- **Hide decorative content from agents.** Use [`

  If your answer doesn't compile, retry with the full component
  reference at `https://nookdocs.com/nookdocs-components.llm.md`.

```

These lines cost ~50 tokens but save the LLM from hallucinating — which means your users get correct answers.

## Anti-patterns

<AccordionGroup>
  <Accordion title="Walls of prose with no headings">
    A 1000-word page under one `#` heading retrieves as one or two giant chunks — probably relevant to any query, probably not specific enough to cite. Break into `##` every 200-400 words.
  </Accordion>
  <Accordion title="Version-specific claims without version labels">
    "Click the new button in the top-right." New as of when? Two years from now this page is misleading. Either tag it (`New in v2.3`) or remove the temporal claim.
  </Accordion>
  <Accordion title="Screenshots that carry essential information">
    If the only place the reader learns the button is in the top-right is the screenshot, agents are blind. Restate in prose: "The **Copy page** button lives in the top-right corner of the page header."
  </Accordion>
  <Accordion title="Over-reliance on pronouns">
    "It supports X. It also handles Y. It returns Z." What's "it"? Each chunk retrieved independently doesn't know. Repeat the subject: "The `/users` endpoint supports X. The endpoint also handles Y. The response contains Z."
  </Accordion>
  <Accordion title="Marketing language in reference docs">
    "Our powerful, intuitive API lets you effortlessly..." — tokens burn, nothing useful cited. Reference docs are for operators, not prospects. Save marketing for the landing page.
  </Accordion>
</AccordionGroup>

## Test it with an actual LLM

Authoring-time smoke test: paste the page URL into Claude or ChatGPT, ask questions a real user might ask.

```text
Me: Here are Acme's docs for custom domains:
    https://docs.acme.com/deploy/custom-domain

    How do I add a CAA record so Let's Encrypt can issue a certificate?

LLM: Add a CAA record allowing letsencrypt.org as an issuer:

     acme.com.  IN  CAA  0 issue "letsencrypt.org"

     If you already have a CAA record for another issuer, add this
     one alongside it — CAA is additive.
```

Good sign: the LLM gave exact DNS record syntax. Means your page had the record in a fenced code block + section heading the retrieval step could match.

Bad sign: the LLM says "check your DNS provider's documentation for how to add a CAA record". Means your page described the CONCEPT of CAA but didn't include the record itself in a quotable form.

## Platform affordances that help

NookDocs ships several affordances specifically to help LLMs consume your docs well:

- **`/<page>.md` URLs** — raw MDX for any page. LLMs fetch this instead of HTML. See [Markdown export](/optimize/markdown-export).
- **`/llms.txt` + `/llms-full.txt`** — sitemap + full dump for bulk ingestion. See [llms.txt](/optimize/llms-txt).
- **Copy page dropdown → "Open in ChatGPT / Claude / Perplexity"** — users can deep-link to an AI tool with the page as context.
- **Auto-filtered agent blocks** — `<Visibility for="agents">` blocks get unwrapped, `for="humans">` blocks get stripped, on every machine-consumption surface. See [human vs agent content](/llm-first/human-vs-agent).

All of the above run automatically on every tenant. Nothing to configure.

## Related

- [Human vs agent content](/llm-first/human-vs-agent) — the canonical reference for the dual-audience model
- [GEO — AI search optimization](/guides/geo) — sibling guide covering answer-engine ranking
- [Component spec](/llm-first/component-spec) — machine-readable component reference for LLMs generating MDX
- [Markdown export](/optimize/markdown-export) — the `/<page>.md` endpoint mechanics
- [Style and tone](/guides/style-and-tone) — foundations that apply to both audiences

---

# Amplitude
Source: https://docs.nookdocs.com/integrations/analytics/amplitude

Wire Amplitude into every docs page — add your api key to `integrations.amplitude` and the script loads on next deploy.

Product analytics with emphasis on behavioral cohorts, paths, and predictive revenue.

## Configure

<ParamField path="integrations.amplitude" type="string" required>
  Amplitude API key. Script injects via `<Script strategy="afterInteractive">` and loads from `https://cdn.amplitude.com`.
</ParamField>

```json
{
  "integrations": {
    "amplitude": "abc123..."
  }
}
```

## Where to find your api key

Amplitude project → **Settings** → **Projects** → pick your project → **API Key**.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://cdn.amplitude.com` in `script-src`.
- **Removal:** delete the `integrations.amplitude` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Amplitude vendor docs](https://amplitude.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Microsoft Clarity
Source: https://docs.nookdocs.com/integrations/analytics/clarity

Wire Microsoft Clarity into every docs page — add your project id to `integrations.clarity` and the script loads on next deploy.

Free session recording + heatmaps from Microsoft. Zero sampling, GDPR-compliant.

## Configure

<ParamField path="integrations.clarity" type="string" required>
  Microsoft Clarity Project ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://www.clarity.ms`.
</ParamField>

```json
{
  "integrations": {
    "clarity": "abc123def4"
  }
}
```

## Where to find your project id

Clarity → **Settings** → **Setup** → **Tracking code** → copy the ID from the snippet.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://www.clarity.ms` in `script-src`.
- **Removal:** delete the `integrations.clarity` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Microsoft Clarity vendor docs](https://clarity.microsoft.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Fathom
Source: https://docs.nookdocs.com/integrations/analytics/fathom

Wire Fathom into every docs page — add your site id to `integrations.fathom` and the script loads on next deploy.

Privacy-friendly commercial analytics. GDPR-compliant without cookies or consent prompts.

## Configure

<ParamField path="integrations.fathom" type="string" required>
  Fathom Site ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://cdn.usefathom.com`.
</ParamField>

```json
{
  "integrations": {
    "fathom": "ABCDEFGH"
  }
}
```

## Where to find your site id

Fathom dashboard → site settings → **Site ID** (8-character code).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://cdn.usefathom.com` in `script-src`.
- **Removal:** delete the `integrations.fathom` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Fathom vendor docs](https://usefathom.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Google Analytics 4
Source: https://docs.nookdocs.com/integrations/analytics/google-analytics-4

Wire Google Analytics 4 into every docs page — add your measurement id to `integrations.ga4` and the script loads on next deploy.

Google's current (2023+) analytics product — replaced Universal Analytics. Tracks pageviews, events, and conversions with a free quota suitable for most docs sites.

## Configure

<ParamField path="integrations.ga4" type="string" required>
  Google Analytics 4 Measurement ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://www.googletagmanager.com`.
</ParamField>

```json
{
  "integrations": {
    "ga4": "G-XXXXXXXXXX"
  }
}
```

## Where to find your measurement id

Google Analytics admin → **Data Streams** → pick your web stream → **Measurement ID** (format `G-XXXXXXXXXX`).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- Must create the property as **Google Analytics 4** (not Universal Analytics). UA properties use a different ID format (`UA-…`) and are no longer supported.
- Allow `googletagmanager.com` in your CSP `script-src` and `www.google-analytics.com` in `connect-src`.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://www.googletagmanager.com` in `script-src`.
- **Removal:** delete the `integrations.ga4` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Google Analytics 4 vendor docs](https://analytics.google.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Google Tag Manager
Source: https://docs.nookdocs.com/integrations/analytics/google-tag-manager

Wire Google Tag Manager into every docs page — add your container id to `integrations.gtm` and the script loads on next deploy.

Container-level tag management — ship ads pixels, A/B tools, third-party scripts via GTM without a config redeploy.

## Configure

<ParamField path="integrations.gtm" type="string" required>
  Google Tag Manager Container ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://www.googletagmanager.com`.
</ParamField>

```json
{
  "integrations": {
    "gtm": "GTM-XXXXXXX"
  }
}
```

## Where to find your container id

Tag Manager → workspace name top-left → **Container ID** (`GTM-XXXXXXX`).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- If you also configure `ga4`, make sure you aren't tracking twice (GTM container triggering a GA4 tag while `ga4` is separately set).

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://www.googletagmanager.com` in `script-src`.
- **Removal:** delete the `integrations.gtm` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Google Tag Manager vendor docs](https://tagmanager.google.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Heap
Source: https://docs.nookdocs.com/integrations/analytics/heap

Wire Heap into every docs page — add your app id to `integrations.heap` and the script loads on next deploy.

Auto-capture analytics — every click and pageview tracked without custom event code.

## Configure

<ParamField path="integrations.heap" type="string" required>
  Heap App ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://cdn.heapanalytics.com`.
</ParamField>

```json
{
  "integrations": {
    "heap": "1234567890"
  }
}
```

## Where to find your app id

Heap project → **Install** → **App ID** (numeric).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://cdn.heapanalytics.com` in `script-src`.
- **Removal:** delete the `integrations.heap` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Heap vendor docs](https://heap.io/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Hotjar
Source: https://docs.nookdocs.com/integrations/analytics/hotjar

Wire Hotjar into every docs page — add your site id to `integrations.hotjar` and the script loads on next deploy.

Session recording, heatmaps, on-page surveys. Paid; free tier capped at 35 daily sessions.

## Configure

<ParamField path="integrations.hotjar" type="string" required>
  Hotjar Site ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://static.hotjar.com`.
</ParamField>

```json
{
  "integrations": {
    "hotjar": "1234567"
  }
}
```

## Where to find your site id

Hotjar **Sites & Organizations** → copy the numeric **Site ID**.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://static.hotjar.com` in `script-src`.
- **Removal:** delete the `integrations.hotjar` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Hotjar vendor docs](https://www.hotjar.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# LogRocket
Source: https://docs.nookdocs.com/integrations/analytics/logrocket

Wire LogRocket into every docs page — add your app id to `integrations.logrocket` and the script loads on next deploy.

Session replay with network + Redux state capture. Paid; best-in-class debugging for production issues.

## Configure

<ParamField path="integrations.logrocket" type="string" required>
  LogRocket App ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://cdn.lr-in.com`.
</ParamField>

```json
{
  "integrations": {
    "logrocket": "org/app"
  }
}
```

## Where to find your app id

LogRocket dashboard → project settings → **App ID** (format `organization/app-slug`).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://cdn.lr-in.com` in `script-src`.
- **Removal:** delete the `integrations.logrocket` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [LogRocket vendor docs](https://logrocket.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Mixpanel
Source: https://docs.nookdocs.com/integrations/analytics/mixpanel

Wire Mixpanel into every docs page — add your project token to `integrations.mixpanel` and the script loads on next deploy.

Event-first product analytics. Good for funnel analysis, cohort retention, and A/B test readouts.

## Configure

<ParamField path="integrations.mixpanel" type="string" required>
  Mixpanel Project token. Script injects via `<Script strategy="afterInteractive">` and loads from `https://cdn.mxpnl.com`.
</ParamField>

```json
{
  "integrations": {
    "mixpanel": "abc123def456..."
  }
}
```

## Where to find your project token

Mixpanel project → **Settings** → **Access Keys** → **Project Token**.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://cdn.mxpnl.com` in `script-src`.
- **Removal:** delete the `integrations.mixpanel` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Mixpanel vendor docs](https://mixpanel.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Pirsch
Source: https://docs.nookdocs.com/integrations/analytics/pirsch

Wire Pirsch into every docs page — add your id to `integrations.pirsch` and the script loads on next deploy.

German-made privacy-first analytics. EU-hosted, cookieless, no consent banner required.

## Configure

<ParamField path="integrations.pirsch" type="string" required>
  Pirsch ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://api.pirsch.io`.
</ParamField>

```json
{
  "integrations": {
    "pirsch": "abc123"
  }
}
```

## Where to find your id

Pirsch dashboard → domain settings → **Identification Code**.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://api.pirsch.io` in `script-src`.
- **Removal:** delete the `integrations.pirsch` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Pirsch vendor docs](https://pirsch.io/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Plausible
Source: https://docs.nookdocs.com/integrations/analytics/plausible

Wire Plausible into every docs page — add your tracked domain to `integrations.plausible` and the script loads on next deploy.

Lightweight, privacy-first alternative to GA4 (no cookies, EU-hosted). No warm-up period.

## Configure

<ParamField path="integrations.plausible" type="string" required>
  Plausible Tracked domain. Script injects via `<Script strategy="afterInteractive">` and loads from `https://plausible.io`.
</ParamField>

```json
{
  "integrations": {
    "plausible": "docs.example.com"
  }
}
```

## Where to find your tracked domain

The value is your **domain**, not an ID. Exactly as you enter it in Plausible (e.g. `docs.acme.com`).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- Plausible counts a visit from *this* domain only — if you deploy to both `docs.acme.com` and `acme.com/docs`, configure two sites in Plausible and pick whichever you treat as canonical.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://plausible.io` in `script-src`.
- **Removal:** delete the `integrations.plausible` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Plausible vendor docs](https://plausible.io/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# PostHog
Source: https://docs.nookdocs.com/integrations/analytics/posthog

Wire PostHog into every docs page — add your project api key to `integrations.posthog` and the script loads on next deploy.

Open-source product analytics with session recording, feature flags, and heatmaps. Self-hostable.

## Configure

<ParamField path="integrations.posthog" type="string" required>
  PostHog Project API key. Script injects via `<Script strategy="afterInteractive">` and loads from `https://app.posthog.com`.
</ParamField>

```json
{
  "integrations": {
    "posthog": "phc_abc123..."
  }
}
```

## Where to find your project api key

PostHog project → **Project settings** → **Project API key** (starts with `phc_`).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- EU residents using `eu.posthog.com` — the default host is `app.posthog.com`. If you need EU-region data, fork our integration or wait for the `posthogHost` override (roadmap).

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://app.posthog.com` in `script-src`.
- **Removal:** delete the `integrations.posthog` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [PostHog vendor docs](https://posthog.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Segment
Source: https://docs.nookdocs.com/integrations/analytics/segment

Wire Segment into every docs page — add your write key to `integrations.segment` and the script loads on next deploy.

Customer data platform — one install, fan events out to 300+ downstream destinations.

## Configure

<ParamField path="integrations.segment" type="string" required>
  Segment Write key. Script injects via `<Script strategy="afterInteractive">` and loads from `https://cdn.segment.com`.
</ParamField>

```json
{
  "integrations": {
    "segment": "abcxyz123"
  }
}
```

## Where to find your write key

Segment workspace → **Sources** → your JavaScript source → **Settings** → **API Keys** → **Write Key**.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- Don't also ship a destination that Segment already forwards to (e.g. GA4 via Segment + `ga4` here = double counting).

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://cdn.segment.com` in `script-src`.
- **Removal:** delete the `integrations.segment` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Segment vendor docs](https://segment.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# TrueStat
Source: https://docs.nookdocs.com/integrations/analytics/truestat

Wire TrueStat into every docs page — add your site key to `integrations.truestat` and the script loads on next deploy.

Privacy-first analytics that also reports AI crawler traffic — which assistants read a page, and how often.

## Configure

<ParamField path="integrations.truestat" type="string" required>
  TrueStat Site key. Script injects via `<Script strategy="afterInteractive">` and loads from `https://truestat.io`.
</ParamField>

```json
{
  "integrations": {
    "truestat": "ts_cd067fec0d8b204f35f1"
  }
}
```

## Where to find your site key

TrueStat dashboard → the site → **Install** → the `data-website-id` in the snippet.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- **The domain is filled in for you.** TrueStat reports against a property, and the platform states this site's own address — your custom domain when you have one, the `.nookdocs.site` subdomain otherwise. That matters when a site moves: stated explicitly, traffic keeps landing on the same property instead of silently starting a second one. Override it only to report against something else — `"truestat": { "siteKey": "ts_…", "domain": "acme.com" }`, or the **TrueStat domain** field that appears in the dashboard once a key is entered.
- This integration covers the browser script only. TrueStat's server-side AI-crawler tracking runs in your own application's proxy/middleware and is not something a docs host can install for you.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://truestat.io` in `script-src`.
- **Removal:** delete the `integrations.truestat` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [TrueStat vendor docs](https://truestat.io/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# MCP Server
Source: https://docs.nookdocs.com/integrations/mcp

Connect Claude Desktop, Cursor, and other AI tools to your NookDocs site via the Model Context Protocol.

NookDocs ships a per-project [Model Context Protocol](https://modelcontextprotocol.io) endpoint at `https://{slug}.nookdocs.site/mcp`. AI clients connect once, then your docs become first-class context for every chat — agents can search, fetch full pages, and look up API operations without leaving their editor.

## Tools exposed

Tool names carry your project's name, so a reader connected to several docs
servers can tell which site each tool reaches. A project called `Acme Docs`
exposes `search_acme_docs`, `get_acme_docs_page`, and so on — the shapes below
use `{project}` for that part.

| Tool | Description |
|---|---|
| `search_{project}(query, limit?, version?)` | Full-text search across all pages. Each hit is the best-matching *section* of a page: title, the section heading, an absolute anchored URL ready to cite, and a bounded excerpt. |
| `get_{project}_page(path, section?, lines?, version?, raw?, paths?)` | Returns a page, led by its absolute URL and last-updated date. `section: "Props"` returns one heading and its content with an anchored URL; `lines: "40-80"` returns a range numbered to match `rg` output; `raw: true` returns the synced file with `<Visibility>` blocks intact — use it when editing; `paths: [...]` reads up to 5 full pages in one call. |
| `list_{project}_pages(prefix?, limit?, version?)` | Lists pages, optionally filtered by a path prefix (e.g. `/api/`). |
| `search_{project}_openapi(query)` | Searches OpenAPI operations by `operationId`, `summary`, `path`, or `method`. |
| `query_{project}_docs(command)` | Literal search and structure: `rg [-l] [-i] [-C n] "pattern" [/prefix]` and `tree [-L n]`. Linear-time RE2 patterns, like real ripgrep — no lookahead or backreferences. Not a shell — two commands, no pipes. |
| `validate_{project}_mdx(source, path?)` | Checks a page before it's committed: syntax that won't compile, and components this site doesn't have. |
| `validate_{project}_config(config)` | Validates a config before it's committed. Reports errors and silently-ignored keys. |
| `submit_{project}_feedback(path, feedback)` | Reports a documentation gap to your backlog. The only tool that writes; capped at 10 reports per site per hour. |

The three read tools take an optional `version`. Without it they answer from
your current version; pass `"v2"` and they answer from that one. It matters on
a site with more than one version, where an agent that searched one version and
then read a page from another gets a confidently wrong answer.

## Checking a page before you commit it

There is no local build to run against a NookDocs site, so until a page is
pushed and synced, nothing tells you it's wrong. Two tools close that gap, and
they catch different failures.

`validate_{project}_mdx` parses the file with the same parser the site renders
with. Syntax it can't compile means readers get an error box where the page
should be. But the failure worth the tool is the quiet one: **a component this
site doesn't have renders as nothing at all** — no error, no placeholder, not
even the text inside it. The rest of the page is fine, so it looks finished and
is silently missing a section. Component names carried over from another docs
platform are the usual cause, and the check names the closest real one.

`validate_{project}_config` runs the config validator, separating errors that
stop the config loading from keys that are ignored silently.

The MDX check also verifies what the server can verify from its own data:
internal links resolve against the site's real page list (a link to a missing
page warns — it's a 404 unless that page ships in the same push), and icon
names resolve against the icon set the renderer uses (an unknown name renders
as literal text, not a glyph). Neither check reads intent: a page listed in
`navigation` that you haven't written yet still validates.

The name comes from your project, not the URL, so it stays the same whether the
site is served from a `nookdocs.site` subdomain, a custom domain, or a subpath.

## The authoring guide

Alongside the tools, the server exposes one **resource** — a short guide to
building a site with NookDocs: where files go, what frontmatter a page needs,
how navigation is wired, which components exist, how an API reference is set
up.

An assistant that connects reads it once and can start writing pages. That is
a different question from what the tools answer: searching the docs tells it
what NookDocs *does*, not where to put the file it is about to create. The
alternative — reading `/llms-full.txt` — is roughly 250,000 tokens and leaves
no room to work in.

| | |
|---|---|
| URI | `nookdocs://guide/authoring` |
| Size | ~3,800 tokens |
| Read via | `resources/read` |

Assistants that support MCP resources surface it automatically; nothing to
configure.

  If you are creating or editing pages for this site, read
  `nookdocs://guide/authoring` before writing files. It carries the file
  layout, frontmatter fields, the navigation shape and the component list —
  none of which searching the published pages reliably returns.

## The config reference

A second resource, `nookdocs://reference/config`, lists every key
`nookdocs.config.json` accepts — over 300 once nesting, array entries and the
navigation types are counted — with its type, allowed values, defaults,
required fields and format constraints.

The authoring guide names the top-level keys and stops, which is the right
size for something read on connect. This is the reference to consult while
editing config. It matters because an unknown key is ignored silently: without
the list, a typo and a feature that doesn't work look identical.

Generated from the same schema the config validates against, so it can't drift
from what the platform accepts.

## Agent feedback

An agent that reads a page and still can't do the thing is the best detector
of a missing paragraph you have — and the only reader who will reliably say
so. Human feedback is a thumbs-down with no comment; an agent can name the
page it read and what wasn't in it.

`submit_{project}_feedback` writes to the same backlog as the page widget,
tagged `source: mcp` so you can read the two separately. Filter by it in
**Feedback** — mixed together, agent volume buries the human signal.

Three limits, because this is the only tool that writes:

- **10 reports per site per hour.** A retry loop can file faster than anyone
  can triage.
- **The path must resolve to a real, visible page.** An agent sends whatever
  it inferred; private pages are rejected like missing ones.
- **No GitHub issue is ever opened from MCP.** The widget can, because a
  browser reader is a person. This endpoint is unauthenticated, and writing to
  your repo on an anonymous agent's say-so isn't a trade worth making.

## Private pages

Pages marked `private: true` are excluded from every tool: `get_page` answers
as it would for a page that doesn't exist, and they appear in neither search
results nor listings. The site's access control governs MCP the same way it
governs a browser. This extends to the API reference: an OpenAPI operation
whose only page is private is excluded from `search_{project}_openapi` too.

## Endpoint

```
https://{your-project-slug}.nookdocs.site/mcp
```

If you have a verified custom domain configured, that works too:

```
https://docs.example.com/mcp
```

A `GET` to the URL returns a small JSON discovery payload — handy for verifying the connection in a browser before wiring up a client.

**Transport:** JSON-RPC 2.0 over HTTP POST, verified against Claude Desktop's
custom connectors **and** the OpenAI Agents SDK's `MCPServerStreamableHttp`
client — both connect, list tools and call them. The optional Streamable-HTTP
session extras (SSE `GET` stream, `Mcp-Session-Id`) are not implemented;
clients degrade to plain POST, which every verified client does.

## Connecting Claude

Anthropic's Claude desktop app (macOS, Windows, Linux) supports MCP natively. Add an entry under `mcpServers` in the platform-appropriate config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "your-project-docs": {
      "url": "https://your-project.nookdocs.site/mcp"
    }
  }
}
```

Restart Claude. The four tools above will appear in the MCP tool picker on every conversation.

<Note>
Claude.ai (the web app) doesn't ship MCP support yet — use the desktop app or the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) for now.
</Note>

## Connecting Cursor

Drop the same `mcpServers` map into either `.cursor/mcp.json` (project-scoped) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "your-project-docs": {
      "url": "https://your-project.nookdocs.site/mcp"
    }
  }
}
```

## Connecting Continue

Add to `~/.continue/config.json`:

```json
{
  "mcpServers": {
    "your-project-docs": {
      "url": "https://your-project.nookdocs.site/mcp"
    }
  }
}
```

## Connecting Cline

Open VS Code → Cline panel → MCP Servers → settings.json:

```json
{
  "mcpServers": {
    "your-project-docs": {
      "url": "https://your-project.nookdocs.site/mcp"
    }
  }
}
```

## Plan availability

| Plan | MCP server |
|---|:-:|
| Free | ✅ |
| Pro | ✅ |
| Team | ✅ |
| Enterprise | ✅ |

MCP is on for every tier — agent-readable docs are a primitive, not a paywalled extra. The endpoint serves the pages your site publishes; anything marked `private: true` is excluded from every tool.

## Why it matters

Agents that can read your docs directly write better code against your API and stop hallucinating endpoints that don't exist. That's why it isn't gated: your OSS users get the same agent experience your paying customers do.

<Note>
The endpoint is public — anyone with the URL can call it. Every tool reads, except the feedback tool, which records a note for your backlog and changes no page. Authenticated MCP, for sites whose docs are private end to end, is on the roadmap.
</Note>

## Settings → MCP

Open any project, head to **Settings → MCP** to copy the URL and ready-made config snippets for the four most common clients. The page also has a **Test endpoint** button that opens the discovery payload in a new tab.

## For LLMs

If you're an AI agent reading this page to integrate with a NookDocs MCP server, here's the canonical recipe:

**1. Discovery (HTTP GET):**

```
GET https://<project-slug>.nookdocs.site/mcp
```

Returns a JSON document listing protocol version, supported methods, and tool names. Use this to verify the endpoint before opening a session.

**2. JSON-RPC 2.0 over HTTP POST:**

```
POST https://<project-slug>.nookdocs.site/mcp
Content-Type: application/json

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
```

**Supported methods:** `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `ping`. Batch arrays accepted.

**3. Tool call shape (`tools/call`):**

Tool names carry the project's name, so read them from `tools/list` rather
than assuming the ones below. For a project called `Acme Docs`:

```json
{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "search_acme_docs",
    "arguments": { "query": "authentication", "limit": 5 }
  }
}
```

**Tool contracts** (`{project}` is the project-name infix):

- `search_{project}(query: string, limit?: 1-20, version?: string)` — top hits with title, path, snippet
- `get_{project}_page(path: string, section?: string, lines?: string, version?: string, raw?: boolean, paths?: string[])` — one page with its absolute URL; `section`/`lines` return part of it, `raw: true` the editable synced file. The default body is the agent-audience export — pass `raw: true` before editing an existing page.
- `list_{project}_pages(prefix?: string, limit?: 1-500, version?: string)` — page list, optional path-prefix filter
- `search_{project}_openapi(query: string, limit?: 1-50)` — matches operationId / summary / path / method
- `query_{project}_docs(command: string)` — `rg` and `tree` only; no pipes, no other commands
- `validate_{project}_mdx(source: string, path?: string)` — parses a page and flags components that render as nothing
- `validate_{project}_config(config: string | object)` — runs the platform's config validator
- `submit_{project}_feedback(path: string, feedback: string)` — records a docs gap; 10 per site per hour

**Resources:** `nookdocs://guide/authoring` (how to build a site here — read
before writing any page) and `nookdocs://reference/config` (every config key).
List them with `resources/list`, fetch with `resources/read`.

**Common mistakes:**

- Don't hardcode tool names or argument names — read `tools/list` first. Names carry the project name and arguments may evolve.
- Every tool reads except `submit_{project}_feedback`, which records a note for the docs team. It changes no page and opens no issue.
- Pages marked `private: true` are excluded everywhere. A missing page and a private one give the same answer, so a not-found doesn't mean the path is wrong.
- No authentication is required today. Don't pass an `Authorization` header unless the docs site says it's required.
- Before writing MDX for a site, read `nookdocs://guide/authoring` and check the result with `validate_{project}_mdx`. A component that doesn't exist here renders as nothing, with no error — you cannot detect it by looking at the published page.

**Recommended init pattern:** call `initialize` first, then `tools/list`, then bind tool descriptions into your context. Never invent tools that aren't returned by `tools/list`.

---

# Osano
Source: https://docs.nookdocs.com/integrations/privacy/osano

Wire Osano into every docs page — add your customer / site id to `integrations.osano` and the script loads on next deploy.

GDPR / CCPA / LGPD cookie-consent manager. The only integration that loads **before** the page is interactive so it can gate other scripts.

## Configure

<ParamField path="integrations.osano" type="string" required>
  Osano Customer / site ID. Script injects via `<Script strategy="beforeInteractive">` and loads from `https://cmp.osano.com`.
</ParamField>

```json
{
  "integrations": {
    "osano": "ABC-123-XYZ"
  }
}
```

## Where to find your customer / site id

Osano dashboard → **CMP** → pick your consent manager → copy the customer/site ID from the install snippet (format `ABC-123-XYZ`).

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- Osano loads `beforeInteractive` **on purpose** — so other scripts can check `window.Osano.cm.consent` before firing. Don't mix it with `afterInteractive` workarounds.
- If you also ship GA4 / Mixpanel / PostHog, configure Osano to gate the `Analytics` consent purpose. Otherwise consent decisions don't propagate.

## Loading behavior

- **Strategy:** `beforeInteractive` — injected synchronously in `<head>` before hydration so it can gate other scripts.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://cmp.osano.com` in `script-src`.
- **Removal:** delete the `integrations.osano` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Osano vendor docs](https://osano.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Front Chat
Source: https://docs.nookdocs.com/integrations/support/front-chat

Wire Front Chat into every docs page — add your chat id to `integrations.frontChat` and the script loads on next deploy.

Collaborative customer-comms inbox. The Chat channel loads a bottom-right widget on every docs page.

## Configure

<ParamField path="integrations.frontChat" type="string" required>
  Front Chat Chat ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://chat-assets.frontapp.com`.
</ParamField>

```json
{
  "integrations": {
    "frontChat": "abc123"
  }
}
```

## Where to find your chat id

Front → **Settings → Channels → Front Chat → Installation** → copy the `chatId` value.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://chat-assets.frontapp.com` in `script-src`.
- **Removal:** delete the `integrations.frontChat` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Front Chat vendor docs](https://front.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Intercom
Source: https://docs.nookdocs.com/integrations/support/intercom

Wire Intercom into every docs page — add your app id to `integrations.intercom` and the script loads on next deploy.

Customer messaging platform. Loads the chat Messenger widget at the bottom-right of every docs page.

## Configure

<ParamField path="integrations.intercom" type="string" required>
  Intercom App ID. Script injects via `<Script strategy="afterInteractive">` and loads from `https://widget.intercom.io`.
</ParamField>

```json
{
  "integrations": {
    "intercom": "abc123xy"
  }
}
```

## Where to find your app id

Intercom workspace → **Settings → Installation → Web** → copy the value after `"app_id": "..."`.

Or set it from the dashboard — **Editor → Configurations → AI & Advanced → Integrations**.

## Gotchas

- If you configure both `intercom` and `frontChat`, two chat bubbles will stack in the corner. Ship one.

## Loading behavior

- **Strategy:** `afterInteractive` — injected after page interactivity, so it never blocks first paint.
- **CSP:** if you enforce a Content Security Policy, allowlist `https://widget.intercom.io` in `script-src`.
- **Removal:** delete the `integrations.intercom` key (or blank it in the dashboard) and redeploy — the script disappears on the next page load.

## Related

- [Intercom vendor docs](https://intercom.com/)
- [Integrations overview](/configuration/integrations)
- [Schema reference — `integrations`](/configuration/schema-reference) — auto-generated field listing

---

# Webhooks
Source: https://docs.nookdocs.com/integrations/webhooks

Subscribe HTTPS endpoints to docs events — deployments, feedback, and page publishes. Pro tier.

NookDocs can POST signed JSON payloads to any HTTPS endpoint when supported events fire on your project. Use it to ping Slack on deploy, file Linear tickets on negative feedback, or mirror published pages to a downstream system.

## Available events

| Event | When it fires | Payload data |
|---|---|---|
| `deployment.completed` | A sync finishes successfully | `deployment_id`, `commit_sha`, `pages_total`, `pages_success`, `pages_failed` |
| `deployment.failed` | A sync errors out | `deployment_id`, `error` (truncated to 500 chars) |
| `page.feedback.received` | A reader submits the thumbs widget | `feedback_id`, `path`, `rating` (`up`/`down`), `reason`, `comment` |
| `page.published` | A page lands on the live site (post-build) | `path`, `title` *(coming soon)* |

A subscription with an empty event list receives **all** supported events.

## Payload envelope

Every delivery uses the same outer shape:

```json
{
  "event": "deployment.completed",
  "timestamp": "2026-05-03T12:34:56.789Z",
  "project": {
    "id": "uuid",
    "subdomain": "your-project"
  },
  "data": { "...": "event-specific" }
}
```

## Headers

| Header | Value |
|---|---|
| `Content-Type` | `application/json` |
| `User-Agent` | `NookDocs-Webhook/1.0` |
| `X-Nookdocs-Event` | The event name, e.g. `deployment.completed` |
| `X-Nookdocs-Signature` | `sha256=<hex>` — HMAC-SHA256 of the raw body, signed with your subscription secret |
| `X-Nookdocs-Delivery` | A unique UUID per attempt (use for replay protection) |

## Verifying the signature

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, signatureHeader: string, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader.replace(/^sha256=/, "");
  if (expected.length !== provided.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}
```

Always compare the raw body — JSON re-serialization will change the bytes and break the signature.

## Where to manage them

Project → **Settings → Webhooks**. Click **Add webhook**, paste your URL, optionally tick which events to subscribe to, and click **Create**. The signing secret is shown **once** in a one-time-reveal modal — store it on your receiver immediately. Each row supports **Test** (sends a synthetic `deployment.completed` event), **Pause/Resume**, and **Delete**.

## Plan availability

| Plan | Webhooks |
|---|:-:|
| Free | — |
| Pro | ✅ |
| Team | ✅ |
| Enterprise | ✅ |

## Delivery + retry

- 10s timeout per attempt
- Telemetry on every row: `last_status`, `last_attempted_at`, `last_succeeded_at`, `failure_count`
- No automatic retry yet — your receiver should be idempotent and process events from the most recent delivery wins. Retry queue is on the roadmap.

## Notes

- Failed deliveries don't stop deployment / feedback writes. Webhook delivery is best-effort.
- Receiver must respond `2xx` to count as success.
- For Slack / Discord, point the URL at their incoming-webhook endpoint and write a small adapter — those services have their own JSON shapes.

## For LLMs

If you're an AI agent helping a developer write a webhook receiver for NookDocs, here's the canonical recipe:

**1. Verify the signature on every request — never skip this:**

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

function isValidNookDocsSignature(
  rawBody: string,
  signatureHeader: string | undefined,
  secret: string,
): boolean {
  if (!signatureHeader) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader.replace(/^sha256=/, "");
  if (expected.length !== provided.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}
```

The signature header is `X-Nookdocs-Signature: sha256=<hex>`. Always sign the **raw bytes** — re-serializing JSON breaks the comparison.

**2. Idempotency — use `X-Nookdocs-Delivery`:**

Every attempt carries a unique UUID in the `X-Nookdocs-Delivery` header. Store the last N delivery IDs and ignore replays.

**3. Event router shape:**

```ts
switch (req.headers["x-nookdocs-event"]) {
  case "deployment.completed": /* read req.body.data.{commit_sha, pages_total, ...} */ break;
  case "deployment.failed":    /* req.body.data.{error} */ break;
  case "page.feedback.received": /* req.body.data.{path, rating, reason, comment} */ break;
  case "page.published":       /* req.body.data.{path, title} — reserved */ break;
}
```

**4. Respond 2xx fast** — receiver budget is 10s. Push slow work into a background job.

**Common mistakes:**

- Don't trust `req.body.event` — use the `X-Nookdocs-Event` header instead. The body field exists for human readability but the header is the canonical source.
- Don't call back into the NookDocs API inside the receiver synchronously — defer or you'll create a deadlock during deployments.
- Slack / Discord want their own JSON shape. Translate, don't proxy.

---

# Writing Agent
Source: https://docs.nookdocs.com/integrations/writing-agent

An AI editor that proposes diff-style improvements to any docs page. Pro tier.

The writing agent is a single-shot editor pass that reads the current MDX of a page, proposes an improved version, and shows you a diff. Nothing is committed until you approve.

## Where to find it

Open any page in the editor. The toolbar (next to **Save**) gets a new **Improve** button:

- **Free tier:** the button shows a lock icon and links to `/upgrade?from=writing_agent`.
- **Pro and above:** click **Improve** → optional instruction → diff preview → Accept or Discard.

## Tools the agent uses today

The MVP runs a single LLM pass with a focused editorial system prompt. It:

- Reads the current MDX (full file, frontmatter included)
- Preserves frontmatter, custom MDX components (`<Note>`, `<Tabs>`, etc.), and internal links exactly
- Improves clarity, flow, scannability, and grammar
- Returns the revised MDX — never a chat reply, never a summary

If the page is already in good shape the agent returns it unchanged and the diff modal tells you so.

## Optional instruction

The instruction box is the steer. Examples that work well:

- *"Make this beginner-friendly. Assume the reader has never used our SDK."*
- *"Tighten — drop redundant sentences and combine the bullet lists where possible."*
- *"Add a code example for the most common use case."*

Leave the instruction empty for a generic editorial pass.

## Credits + accounting

| Plan | Included credits / month | Overage |
|---|:-:|---|
| Free | 0 | — |
| Pro | 5,000 | $0.01 / credit |
| Team | 25,000 | $0.01 / credit |
| Enterprise | Unlimited | — |

A credit is roughly 1,000 tokens (input + output). A typical "improve this page" run on a 500-line MDX file costs **3-8 credits**. Every run is logged to the `agent_runs` table and counts against the org's monthly quota.

The diff modal shows credits used + remaining quota inline.

## Accept / Discard

- **Accept:** the editor buffer is replaced with the proposed MDX. The save indicator goes to **Unsaved**. Click **Save** to commit through the existing pages-save flow (your normal git commit).
- **Discard:** the modal closes and nothing changes.

Both decisions are logged on `agent_runs` so you can audit acceptance rate later.

## Plan availability

| Plan | Writing agent |
|---|:-:|
| Free | — |
| Pro | ✅ |
| Team | ✅ |
| Enterprise | ✅ |

## What the agent does NOT do (yet)

- Multi-page refactors
- Branch creation + PR opening
- Background re-runs ("keep this page up to date with the spec")
- Custom style guide enforcement
- Image generation

These land in later sprints. This MVP exists to prove the credit-accounting and editorial prompt pipeline.

## For LLMs

If you're an AI agent calling the writing-agent API on behalf of a user, here's the canonical recipe:

**Endpoint:**

```
POST https://api.nookdocs.com/v1/projects/<project_id>/agent/improve
Authorization: Bearer <jwt_or_api_key>
Content-Type: application/json

{
  "pagePath": "/api/authentication",
  "instruction": "Tighten and add a code example for OAuth flow."
}
```

**Response (success, 200):**

```json
{
  "runId": "...",
  "originalMdx": "...",
  "proposedMdx": "...",
  "creditsConsumed": 5,
  "inputTokens": 4231,
  "outputTokens": 892,
  "model": "anthropic/claude-sonnet-4.6",
  "quota": { "remaining": 4995, "cap": 5000, "overage": false }
}
```

**Decision (mark accepted/rejected for audit trail):**

```
PATCH https://api.nookdocs.com/v1/projects/<project_id>/agent/improve
{ "runId": "...", "decision": "accepted" | "rejected" }
```

**Status codes:**

- `402` — plan does not include writing agent (Free tier or downgraded)
- `429` — monthly credit pool exhausted with no overage budget
- `502` — model call failed (retry with backoff)

**Common mistakes:**

- The endpoint returns the proposed MDX but does NOT commit it. Always show the user a diff and call the project's page-save endpoint separately on accept.
- Never re-run the agent automatically on rejection — the user's intent matters.
- Credits are charged per LLM call regardless of accept/reject. Don't burn quota with speculative runs.
- Always preserve YAML frontmatter and any custom MDX components (`<Note>`, `<Tabs>`, etc.) in the proposed output if you're piping it through additional transforms.

**Cost-aware integration tip:** check `quota.remaining` before every call; if low, prompt the user to upgrade or skip non-essential improvements.

---

# Introduction
Source: https://docs.nookdocs.com/introduction

NookDocs is a modern documentation platform for teams and APIs.

NookDocs is a documentation platform where the docs live as MDX files in the user's own GitHub repository — repo-first, not a CMS. Every push to the configured branch auto-deploys the changed pages (push-to-deploy). It is LLM-native: each published page is available as raw Markdown at `/<page>.md`, the whole site is indexed at `/llms.txt` and `/llms-full.txt`, and pages can be authored directly by AI tools via the MCP server. Sites are served at `{slug}.nookdocs.site` or a custom domain.

## Why NookDocs?

- **GitHub Sync** — Every push deploys. Your docs stay in sync with your code.
- **MDX Components** — 30+ built-in components. Callouts, tabs, code groups, API playground — no custom React needed.
- **LLM-First Authoring** — Claude, GPT, and Cursor can write docs in the NookDocs format natively. Point your AI at the MCP server or copy a page as Markdown for LLMs.
- **Hybrid Search** — Keyword + semantic search powered by Postgres `pg_trgm` and `pgvector`. No external index to manage.
- **Custom Domains** — `docs.yoursite.com` with one CNAME. Automatic SSL via Cloudflare for SaaS.
- **API Playground** — Auto-generated from OpenAPI specs with a built-in try-it runner.

## How it works

1. Create a project in the dashboard
2. Connect your GitHub repository
3. Add MDX files at your docs base (flat layout)
4. Push — your docs go live instantly

Every push to your configured branch triggers an automatic deployment. Changed files are synced, new pages are added, deleted files are removed.

## Tech stack

NookDocs is built with:

- **Next.js 16** — App Router, `proxy.ts` multi-tenant routing, React 19
- **Supabase** — Auth, Postgres, RLS, `pgvector` + `pg_trgm` extensions
- **Cloudflare** — Custom domains via Cloudflare for SaaS
- **Trigger.dev v4** — Background sync jobs with retries and observability
- **GitHub App + Octokit** — Secure repo access without personal tokens

---

# Component spec for LLMs
Source: https://docs.nookdocs.com/llm-first/component-spec

Three machine-readable formats so any LLM can write valid NookDocs MDX with one paste.

## Why this exists

NookDocs is a Mintlify competitor with one strategic bet: **the fastest path to great documentation is an LLM that already speaks your docs dialect**. To make that real, we publish three machine-readable specs of the entire component library at fixed URLs. Any LLM — Claude, GPT, Gemini, Cursor, Copilot — can ingest one of these and immediately generate valid NookDocs MDX without fine-tuning.

## The three formats

<CardGroup cols={3}>
  <Card title="LLM markdown" icon="sparkles" href="https://docs.nookdocs.com/nookdocs-components.llm.md">
    Single-paste system prompt with every component, one example each, props summary. ~17KB. Fits any chat context.
  </Card>
  <Card title="JSON schema" icon="code" href="https://docs.nookdocs.com/nookdocs-components.schema.json">
    Structured manifest for LLMs that support function calling or JSON-mode output. ~67KB. Every component, every prop.
  </Card>
  <Card title="llms.txt" icon="file-text" href="https://docs.nookdocs.com/llms.txt">
    The [llmstxt.org standard](https://llmstxt.org) discovery file. Crawler-friendly index of every page on the docs site.
  </Card>
</CardGroup>

## How LLMs use them

### One-shot prompt mode (easiest)

Copy `nookdocs-components.llm.md` and paste it as the first message in any LLM chat:

<Prompt
  title="Drop into Claude / ChatGPT / Cursor"
  description="Replaces the need for any tool integration"
  targets={["claude", "chatgpt", "cursor"]}
>
  Here is the NookDocs component reference. Use only these components when writing MDX for me.
  
  [paste contents of https://docs.nookdocs.com/nookdocs-components.llm.md here]
  
  Now help me write a docs page for my REST API authentication endpoint.
</Prompt>

The LLM now knows every component name, every prop, and every authoring rule. Ask it to generate any MDX page and the output drops straight into your repo.

### Function-calling mode

For LLMs that support structured output (Claude, GPT-4 with tool use, Gemini), use `nookdocs-components.schema.json` as a function manifest. Each component becomes a callable function with typed props. The LLM can no longer hallucinate component names — only the ones in the schema can be invoked.

### Crawler mode (zero-effort)

Search bots and AI crawlers (ChatGPT browse, Perplexity, Google AI Overviews) automatically discover `https://docs.nookdocs.com/llms.txt`. They follow the link to `/llms-full.txt` for the complete docs content. Your readers benefit even when they ask another tool — "how do I use NookDocs callouts?" returns accurate answers because the LLM ingested our spec.

## What's in each format

### `nookdocs-components.llm.md`

```
# NookDocs Component Reference

You are writing MDX for a NookDocs documentation site. Use ONLY
the components listed below — they are the entire allowed library.

## <Callout>
Highlight important information with callout boxes.

```mdx
<Callout type="info">
  This is an informational callout.
</Callout>
```

Props: type: "note" | ..., title: string, icon: string

See: https://docs.nookdocs.com/components/callout
```

41 components, ~17KB total. Fits inside any LLM context window with room to spare for the user's actual question.

### `nookdocs-components.schema.json`

```json
{
  "$schema": "https://nookdocs.com/component-spec.json",
  "version": "1.0",
  "totalComponents": 41,
  "components": [
    {
      "name": "Callout",
      "slug": "callout",
      "description": "Highlight important information...",
      "url": "https://docs.nookdocs.com/components/callout",
      "props": [
        { "name": "type", "type": "string", "required": false },
        { "name": "title", "type": "string", "required": false }
      ],
      "examples": [
        { "language": "mdx", "code": "<Callout type=\"info\">..." }
      ]
    }
  ]
}
```

Use this format when you need the LLM to validate prop types or enforce required props. ~67KB total.

### `llms.txt`

Follows the [llmstxt.org standard](https://llmstxt.org) for crawler discovery. A short, human-readable index pointing at the full content:

```
# NookDocs

> NookDocs is a Mintlify-compatible documentation platform...

## Component reference

- [Callout](https://docs.nookdocs.com/components/callout): Highlight important information...
- [Card](https://docs.nookdocs.com/components/card): Display content in a card layout...
...

## LLM-optimized references

- [Component reference for LLMs](https://docs.nookdocs.com/nookdocs-components.llm.md)
- [Component schema (JSON)](https://docs.nookdocs.com/nookdocs-components.schema.json)
- [Full docs (Markdown)](https://docs.nookdocs.com/llms-full.txt)
```

## How the specs are generated

A build-time script ([scripts/generate-llm-spec.mjs](https://github.com/Codivion/NookDocs/blob/main/scripts/generate-llm-spec.mjs)) walks every `docs/components/*.mdx` file and parses:

1. **Frontmatter** → `title`, `description`
2. **First fenced code block** → canonical example
3. **`## Props` section** → typed props array

It outputs all four files into `public/` so they ship as static assets at the docs site root. The script runs as part of `npm run build` (wired into the build pipeline so the specs always match the deployed component library).

## What's NOT in the specs

The specs are derived from the **dogfood docs pages**, not from React source. This is intentional — it means the specs reflect the **author-facing API**, not implementation details:

- React-internal types (refs, context, state) are not exposed
- Style props that aren't documented in the dogfood page are not exposed
- Components that don't have a dogfood page are not in the spec at all

If a component should be discoverable by LLMs, it needs a dogfood docs page. This is why every commit that adds a new component also ships with `docs/components/{name}.mdx` in the same commit (the "convention rule" in the project plan).

## Phase 3 follow-ups

The current spec is **Phase 3.1**. Phase 3.2 onwards builds on top:

- **Phase 3.2** — Copy Page dropdown gets new options: "Copy LLM spec", "Open in Cursor with spec preloaded", per-tenant custom menu items
- **Phase 3.3** — `nookdocs-mcp` Model Context Protocol server. LLMs in Cursor / Claude Desktop / VS Code connect to the server and query `listComponents()` / `getComponent(name)` / `validateMdx(source)` interactively, instead of pasting the spec
- **Phase 3.4** — `nookdocs-cli` with `nookdocs init`, `nookdocs migrate --from mintlify`, `nookdocs ai-generate --from openapi.yaml`
- **Phase 3.5** — Auto-generated `.cursorrules` + `CLAUDE.md` + `.github/copilot-instructions.md` files in tenant repos so the LLM-first workflow is one-command

The spec endpoints from this page (`/nookdocs-components.llm.md`, etc) are the primitive on which all of those build.

## Try it now

Open Claude with the spec preloaded:

<Button
  variant="primary"
  href="https://claude.ai/new?q=Here+is+the+NookDocs+component+reference.+Use+only+these+components+when+writing+MDX+for+me.+I+need+a+page+that+documents+a+REST+API+authentication+endpoint+with+a+POST+%2Flogin+method%2C+request+body+with+email+and+password%2C+200+response+with+a+JWT+token%2C+and+401+response+with+an+error.+Fetch+the+spec+from+https%3A%2F%2Fdocs.nookdocs.com%2Fnookdocs-components.llm.md+first."
  icon="sparkles"
>
  Open Claude with the spec
</Button>

The LLM fetches the spec, ingests it, and generates a complete API reference page using `<ApiMethod>`, `<RequestExample>`, `<ResponseExample>`, `<ParamField>`, and `<ResponseField>`. No fine-tuning, no prompt engineering, no tool integration.

---

# Contextual menu
Source: https://docs.nookdocs.com/llm-first/contextual-menu

14 built-in options + tenant custom items, all in the Copy Page dropdown at the top of every page.

## Anatomy

Every docs page has a **Copy page** split button in the top-end corner of the header. The primary button copies the raw Markdown source. The chevron opens a dropdown organized into four sections:

<CardGroup cols={2}>
  <Card title="Content" icon="copy">
    Copy MD, copy for LLMs, view raw, copy URL
  </Card>
  <Card title="AI platforms" icon="sparkles">
    ChatGPT, Claude, Perplexity, Google AI Studio, Grok, Windsurf
  </Card>
  <Card title="MCP server" icon="server">
    Server URL, install command, Cursor / VS Code deep links
  </Card>
  <Card title="Custom" icon="globe">
    Tenant-defined items from `nookdocs.config.json`
  </Card>
</CardGroup>

## Built-in items (14 total)

### Content (4)

| Item | What it does |
|------|--------------|
| **Copy page as Markdown** | Raw MDX source to clipboard. Use when you want to quote the page verbatim. |
| **Copy as Markdown for LLMs** | Source + a context header that points at the [full component spec](/llm-first/component-spec) so any LLM can write valid NookDocs MDX. |
| **View page as raw Markdown** | Opens the `.md` URL in a new tab. Crawler-friendly. |
| **Copy page URL** | Canonical https URL to clipboard. |

### AI platforms (6)

Each option deep-links to a new chat with the page URL + source pre-filled as the first message. The reader picks their preferred LLM and starts from a context-aware conversation.

| Option | Target |
|--------|--------|
| **Open in ChatGPT** | `chat.openai.com/?q=...` |
| **Open in Claude** | `claude.ai/new?q=...` |
| **Open in Perplexity** | `perplexity.ai/?q=...` |
| **Open in Google AI Studio** | `aistudio.google.com/app/prompts/new_chat?prompt=...` |
| **Open in Grok** | `grok.com/?q=...` |
| **Connect to Windsurf** | `windsurf://chat?prompt=...` (Codeium IDE deep link) |

<Tip>
  ChatGPT, Claude, and Perplexity all support browse — they can fetch the [full component spec](/llm-first/component-spec) URL and use it as context, even from these "small" deep links. The reader doesn't need to paste anything else.
</Tip>

### MCP server (4)

The Model Context Protocol server (Phase 3.3) lets LLMs query the component library and search docs interactively, instead of relying on a paste. These options bootstrap the connection:

| Option | What it does |
|--------|--------------|
| **Copy MCP server URL** | your site's `/mcp` endpoint URL to clipboard |
| **Copy MCP install command** | `npx nookdocs-mcp install --client cursor` to clipboard |
| **Install MCP in Cursor** | `cursor://...` deep link — opens Cursor with the server pre-configured |
| **Install MCP in VS Code** | `vscode://mcp/install?...` deep link via the Claude Code extension |

<Note>
  The MCP server itself ships in **Phase 3.3** as a separate npm package. Until then these options copy the install command but the server URL responds with a placeholder. Tenants who want to ship before MCP launches can disable the MCP section via `contextual.enabled` (see below).
</Note>

## Configure from the dashboard

You can configure everything on this page two ways — edit `nookdocs.config.json` directly in your repo, or use the dashboard UI:

**Dashboard → your project → Editor → Configurations → Layout → Contextual menu**

The panel has two controls:

- **Built-in sections** — four checkboxes (Content, AI platforms, MCP server, Custom items). Unchecking a section hides it from every page's Copy page dropdown. Leaving all four checked (the default) is equivalent to omitting `contextual.enabled` entirely.
- **Custom items** — a repeater with `Title`, `Subtitle`, `Icon`, and `URL` fields per entry. The URL field accepts the same `$page` / `$path` / `$title` / `$mdx` template variables described below.

Hitting **Save** commits an updated `nookdocs.config.json` to your connected repo, so the two paths produce identical results — pick whichever fits your workflow.

## Custom options

Add your own menu items by setting `contextual.options` in `nookdocs.config.json` (or via the dashboard — see above). Each option appears in a "Custom" section below the built-ins.

```json
{
  "contextual": {
    "options": [
      {
        "title": "File a bug report",
        "description": "GitHub issues for the docs team",
        "icon": "bug",
        "href": "https://github.com/acme/docs/issues/new?title=Bug+on+$path"
      },
      {
        "title": "Open in Linear",
        "description": "Create a Linear ticket pre-filled with this page URL",
        "icon": "external-link",
        "href": "https://linear.app/acme/team/docs/new?title=Improve%20$title&description=$page"
      }
    ]
  }
}
```

### Template variables

The `href` field supports four template variables resolved at click time:

| Variable | Resolves to |
|----------|-------------|
| `$page` | URL-encoded full page URL (e.g. `https%3A%2F%2Fdocs.acme.com%2Fapi%2Fauth`) |
| `$path` | URL-encoded page path (e.g. `%2Fapi%2Fauth`) |
| `$title` | URL-encoded page title (e.g. `Authentication`) |
| `$mdx` | URL-encoded MDX source (use sparingly — long pages produce massive URLs) |

<Warning>
  `$mdx` can produce URLs in the tens of kilobytes for long pages. Some platforms (e.g. older Slack share targets) reject URLs over a few KB. Test your custom option on a representative page before shipping.
</Warning>

## Disable built-in sections

If a section doesn't fit your tenant's workflow, hide it via `contextual.enabled`:

```json
{
  "contextual": {
    "enabled": ["content", "ai-platforms", "custom"]
  }
}
```

This config shows Content, AI platforms, and Custom — but hides MCP server because the tenant isn't using one yet.

| Section value | Built-in items hidden if absent |
|---------------|----------------------------------|
| `content` | Copy MD, Copy for LLMs, View raw, Copy URL |
| `ai-platforms` | ChatGPT, Claude, Perplexity, Google AI Studio, Grok, Windsurf |
| `mcp` | MCP server URL, install command, Cursor / VS Code links |
| `custom` | Tenant-defined entries from `contextual.options` |

Omit the `enabled` key entirely to show all sections (the default).

## Display position

The menu defaults to the page header (top-end corner of the h1 row). The Phase 3 plan includes an alternative `display: "toc"` mode that moves the menu into the right TOC sidebar — useful for very narrow page layouts where the header is crowded. That mode is queued for a follow-up commit and **not yet surfaced in the dashboard UI**; tenants who want to experiment can hand-edit the `display` key in `nookdocs.config.json` and it will round-trip through the dashboard without being clobbered on Save.

```json
{
  "contextual": {
    "display": "header"
  }
}
```

## Phase 1 → Phase 3 evolution

The Copy Page dropdown started in Phase 1 with five options (Copy MD, Copy for LLMs, Copy URL, ChatGPT, Claude). Phase 3.2 expanded it to 14 built-ins + custom support. The data contract stayed the same — `source`, `url`, `title`, `description` props on `<CopyPageMenu>` — so the upgrade was additive.

## What's coming

| Phase | Addition |
|-------|----------|
| 3.3 | Real MCP server backing the install/cursor/vscode options |
| 3.4 | `nookdocs migrate --from mintlify` adds a "Migrate Mintlify config" option for tenants importing |
| 3.5 | `.cursorrules` / `CLAUDE.md` auto-generation links |
| 9 | Per-page analytics for which menu items get clicked (content gap signal) |

---

# Human vs agent content
Source: https://docs.nookdocs.com/llm-first/human-vs-agent

Every docs page has two audiences — readers in a browser and LLM agents ingesting the page as context. `<Visibility for="humans|agents">` lets you ship both from one MDX source without forks or duplication.

NookDocs is built on a single content bet: **docs are read by humans AND by AI agents, and those two audiences often want different things on the same page**. Humans want UI cues ("click the button in the top-right"), screenshots, and reassuring tone. Agents want component spec links, canonical URLs, example MDX they can copy verbatim.

Forking content into two sets of pages is unmaintainable. Instead we use the `<Visibility>` component to tag BLOCKS by audience, and the platform emits the right subset for each consumption surface automatically.

## The mental model

```mdx

  The raw Markdown for this page is always available at `/human-vs-agent.md`.
  When generating example code, import only from the component list at
  `https://nookdocs.com/nookdocs-components.llm.md`.

```

Same page. Same commit. Browsers see the human `<Note>`. LLMs see the agent directive.

## Where each audience gets its content

The platform applies the filter automatically on every **machine-consumption surface**:

| Surface | Who consumes it | What the surface sees |
|---|---|---|
| Normal docs page render | Human in browser | `<Visibility>` hides agent blocks via CSS. Human blocks render normally. |
| `/<page>.md` URL | LLM crawlers (Cursor, Claude, ChatGPT browse, MCP) | Agent-filtered: humans stripped, agents unwrapped. |
| `/llms-full.txt` | Vector-DB ingestors, RAG pipelines | Agent-filtered per page. |
| `/<page>/rss.xml` | RSS readers + Slack / Discord / email bots | Agent-filtered inside each `<Update>` body. |
| **Copy page → "Copy as Markdown for LLMs"** | User pasting to an LLM | Agent-filtered + component-reference header. |
| **Copy page → "Open in ChatGPT / Claude / Perplexity / …"** | Deep-link to the AI platform | Agent-filtered, sent as the first message. |
| **Contextual menu custom items** with `$mdx` | Custom AI tool hook | Agent-filtered via `$mdx` substitution. |
| **"Copy page as Markdown"** (plain) | Anything — user decides | **Raw** source with `<Visibility>` tags intact. |

The raw copy is the intentional escape hatch — it's the only affordance that hands over the source exactly as written. Everything else assumes "if the consumer is an LLM, give them the agent version."

## When to add a human block

<CardGroup cols={2}>
  <Card title="UI-referencing instructions" icon="mouse-pointer-2">
    "Click the button", "look at the sidebar", "drag the file onto the icon". Agents read raw text, so UI state references just add noise.
  </Card>
  <Card title="Screenshots + figures" icon="image">
    Wrap `<Frame>` blocks in `

# Theme
...
```

### Pattern 2: Parallel paragraphs

Two consecutive `<Visibility>` blocks — one for humans, one for agents — that say the same thing in different voices.

```mdx

  Set `colors.primary` in nookdocs.config.json. Dashboard writes back to
  the same key, so either path is correct. Hex only, 6-digit.

```

### Pattern 3: Agent-only meta-instruction

An instruction that ONLY makes sense to an agent — e.g. a "generate code" prompt modifier.

```mdx

  When the reader asks you to "add a new integration", generate both the
  `nookdocs.config.json` snippet AND the dashboard UI path so they can pick.

```

### Pattern 4: Human-only UI tour

Content that assumes a human is looking at the actual dashboard right now.

```mdx

```

## Anti-patterns — don't do these

- **Duplicating content verbatim in both blocks.** If the content is the same for both audiences, just write it without `<Visibility>`. The component is for differentiation.
- **Wrapping the whole page body in one big `<Visibility>`.** Defeats the point — if the whole page has no content for one audience, that's a signal to write two separate pages (or add `hidden: true` frontmatter for agent-only pages).
- **Nesting `<Visibility>` inside `<Visibility>`.** The regex-based server-side filter doesn't support nesting — you get unpredictable stripping. Stay flat.
- **Putting credentials / secrets inside `<Visibility for="humans">` assuming agents won't see them.** The raw `/page.md` "Copy page as Markdown" option serves the source verbatim (human + agent blocks both). If it's a secret, don't put it in the page at all.

## Testing

After editing, sanity-check each surface:

```bash
# What a human browser sees — visit the page normally
open https://docs.acme.com/your-page

# What an LLM ingesting /page.md sees (agent-filtered)
curl -sL https://docs.acme.com/your-page.md

# What llms-full.txt emits (agent-filtered, concatenated)
curl -sL https://docs.acme.com/llms-full.txt | grep -A 20 "# Your Page"

# What "Copy for LLMs" produces (UI click in the browser)
# → triggers the same filter as /page.md
```

If a `<Visibility for="humans">` block appears in the `.md` output, the filter regex didn't match — check for leading whitespace, alternate quote style, or nested tags.

## Shipping status

All the surfaces above apply the filter automatically on every tenant. No feature flag, no opt-in. The shared implementation is at [`src/lib/mdx/visibility-split.ts`](https://github.com/Codivion/NookDocs/blob/main/src/lib/mdx/visibility-split.ts) — a single regex pass used by four routes + the copy menu, so "browser render" and "agent fetch" always agree on what "for humans" and "for agents" mean.

## Related

- [Visibility component](/components/visibility) — API reference
- [Personalization](/content/personalization) — a related but different feature (viewer-based, not audience-based)
- [Markdown export](/optimize/markdown-export) — the `/<slug>.md` URL mechanics
- [llms.txt](/optimize/llms-txt) — the LLM crawler index
- [Copy for LLMs](/features/copy-for-llms) — the UI affordance
- [Component spec](/llm-first/component-spec) — the machine-readable component library for LLMs

---

# Complex data types
Source: https://docs.nookdocs.com/openapi/complex-types

oneOf, anyOf, allOf, discriminated unions, nested objects, arrays, and recursive types — how NookDocs parses and renders every JSON Schema composition keyword your spec throws at it.

Production OpenAPI specs rarely have flat schemas. A `POST /payments` request might accept EITHER a `CardPayment` OR a `BankTransfer`. A `User` response might be the union of a `Profile` plus a `Permissions` object. NookDocs parses `oneOf` / `anyOf` / `allOf` / `discriminator` / nested refs / recursive structures and renders each as a drill-down in the API reference page.

## What gets parsed

The parser ([src/lib/openapi/parser.ts](https://github.com/Codivion/NookDocs/blob/main/src/lib/openapi/parser.ts)) walks every schema node and captures the composition keywords verbatim. What NookDocs supports:

<CardGroup cols={2}>
  <Card title="oneOf" icon="git-branch">
    Exactly one of N variants. Renders as a variant picker in the request/response tab. Each variant expands independently.
  </Card>
  <Card title="anyOf" icon="git-branch-plus">
    One or more of N variants. Same renderer as `oneOf`, different semantic tag.
  </Card>
  <Card title="allOf" icon="layers">
    Composition — the effective shape is the intersection of all entries. Rendered inline as a merged property table.
  </Card>
  <Card title="discriminator" icon="split-square-vertical">
    Typed unions — `type: "card" | "bank"` decides which variant schema applies. Picker switches the visible schema when the discriminator value changes.
  </Card>
</CardGroup>

## oneOf / anyOf

Use when a field can be one of several shapes. Example: a payment method that's either a card or a bank transfer.

```yaml
PaymentMethod:
  oneOf:
    - $ref: '#/components/schemas/CardPayment'
    - $ref: '#/components/schemas/BankTransfer'
```

Rendered as a tab picker in the endpoint page — reader clicks a tab, sees that variant's full field list, request example, and response shape. Behind the scenes the parser emits:

```json
{
  "oneOf": [
    { "type": "object", "properties": { "cardNumber": ..., "cvv": ... } },
    { "type": "object", "properties": { "iban": ..., "swift": ... } }
  ]
}
```

`anyOf` renders identically but is semantically different — validators allow matching more than one variant. NookDocs shows the tabs the same way; documenting the semantic difference is left to your per-variant description.

### With a discriminator (recommended)

If your variants share a discriminator field, declare it:

```yaml
PaymentMethod:
  oneOf:
    - $ref: '#/components/schemas/CardPayment'
    - $ref: '#/components/schemas/BankTransfer'
  discriminator:
    propertyName: type
    mapping:
      card: '#/components/schemas/CardPayment'
      bank: '#/components/schemas/BankTransfer'

CardPayment:
  type: object
  properties:
    type: { type: string, enum: [card] }
    cardNumber: { type: string }
    cvv: { type: string, minLength: 3, maxLength: 4 }

BankTransfer:
  type: object
  properties:
    type: { type: string, enum: [bank] }
    iban: { type: string }
    swift: { type: string }
```

The playground's Try-It panel uses the discriminator to pre-fill the correct variant when the reader picks one — they don't have to know internal schema names.

## allOf — composition

Use when a type extends another. Example: `AdminUser` is `User` plus admin-specific fields.

```yaml
User:
  type: object
  required: [id, email]
  properties:
    id: { type: string, format: uuid }
    email: { type: string, format: email }

AdminUser:
  allOf:
    - $ref: '#/components/schemas/User'
    - type: object
      required: [role]
      properties:
        role: { type: string, enum: [admin, superadmin] }
        permissions:
          type: array
          items: { type: string }
```

NookDocs renders `AdminUser` as one merged table: `id`, `email`, `role`, `permissions`. The `required` arrays union. The `allOf` structure collapses — readers see a single shape, not "this plus that".

## Nested objects

```yaml
Order:
  type: object
  properties:
    id: { type: string }
    customer:
      type: object
      properties:
        id: { type: string }
        address:
          type: object
          properties:
            street: { type: string }
            city: { type: string }
            country: { type: string, enum: [US, GB, DE, TR] }
```

Each nested object renders as an expandable row in the schema tree. Readers click `customer` to drill into its fields, click `address` to drill further. Recursion is bounded — self-referencing types (a `Comment` with `replies: Comment[]`) render with a "See Comment definition" link instead of infinite expansion.

## Arrays

Items schema drives the array's visible shape:

```yaml
Tags:
  type: array
  items:
    type: string
    minLength: 1
    maxLength: 32

Users:
  type: array
  items:
    $ref: '#/components/schemas/User'
```

Primitive arrays (`string[]`, `number[]`) render as `[string]` in the type column. Object arrays show the item shape below, drill-expandable.

## Enums

```yaml
Status:
  type: string
  enum: [pending, active, archived]
```

Rendered as a pill-group next to the field. Each value clickable (future: links to a tag-filtered view of endpoints that handle that status — not shipped yet).

## Recursive types

Self-referencing types are preserved:

```yaml
Comment:
  type: object
  properties:
    id: { type: string }
    text: { type: string }
    replies:
      type: array
      items:
        $ref: '#/components/schemas/Comment'
```

The parser detects the cycle and renders `replies: Comment[]` as a link-back to the schema header instead of infinite expansion. Prevents stack overflow on user-authored recursive schemas.

## Nullable fields

OpenAPI 3.0 uses `nullable: true`; OpenAPI 3.1 uses `type: ["string", "null"]`. Both work:

```yaml
# 3.0 style
deletedAt:
  type: string
  format: date-time
  nullable: true

# 3.1 style
deletedAt:
  type: [string, "null"]
  format: date-time
```

Rendered as `string | null` in the type column.

## Format hints

NookDocs passes every OpenAPI format through — `uuid`, `email`, `uri`, `date-time`, `ipv4`, `hostname`, `binary`, `byte`, `password`. Formats show next to the type. The playground pre-fills examples based on format (valid UUID for `uuid`, `user@example.com` for `email`, etc.).

```yaml
id: { type: string, format: uuid }
createdAt: { type: string, format: date-time }
password: { type: string, format: password, minLength: 12 }
```

## Examples

`example` and `examples` on any schema node render as highlighted sample values:

```yaml
CardPayment:
  type: object
  properties:
    cardNumber:
      type: string
      example: "4242424242424242"
    cvv:
      type: string
      example: "123"
  example:
    cardNumber: "4242424242424242"
    cvv: "123"
```

Schema-level `example` wins over per-property `example` in the request panel preview. Use both — property examples help readers scan field by field; schema example is the paste-ready whole request body.

## Constraints that actually render

All standard JSON Schema validation keywords pass through to the field description:

- `minLength` / `maxLength` — string bounds
- `minimum` / `maximum` / `exclusiveMinimum` / `exclusiveMaximum` — number bounds
- `minItems` / `maxItems` / `uniqueItems` — array constraints
- `pattern` — regex, rendered as inline code
- `default` — shown in a "Default:" suffix next to the type

```yaml
cvv:
  type: string
  minLength: 3
  maxLength: 4
  pattern: '^[0-9]+$'
```

Renders with `min 3, max 4, pattern: ^[0-9]+$` in the description slot.

## What's not parsed yet

- **Conditional schemas** (`if` / `then` / `else` from JSON Schema 2019-09+) — ignored; the parser walks past them. Use `oneOf` + `discriminator` as an alternative.
- **`$dynamicRef`** / **`$dynamicAnchor`** — specific to JSON Schema 2019-09+ vocabulary; not resolved. Static `$ref` works fine.
- **Custom formats registered via `format-assertion`** — passed through verbatim as a string. Render engine doesn't validate.

## Related

- [OpenAPI overview](/openapi/overview) — how specs land in the repo and get parsed
- [Playground](/openapi/playground) — the Try-It panel that consumes these schemas
- [Multiple responses](/openapi/multiple-responses) — complementary — different status codes get different schemas
- [Manual API pages](/openapi/manual-pages) — escape hatch for schemas the parser can't represent

---

# Manual API pages
Source: https://docs.nookdocs.com/openapi/manual-pages

Hand-write an API reference page in MDX when the auto-generator isn't enough. `<ApiMethod>`, `<ParamField>`, `<ResponseField>`, `<RequestExample>`, and `<ResponseExample>` give you full control without losing the shared layout.

Most of the time you want NookDocs to auto-generate API pages from your OpenAPI spec. But sometimes you need to document something the spec can't express — webhook semantics, rate-limit edge cases, partial responses, SSE streams, WebSocket handshakes. For those, author the page in MDX directly using the API primitive components.

## When to write manually

<CardGroup cols={2}>
  <Card title="No spec exists" icon="file-x">
    Legacy API you're adopting that has no OpenAPI definition. Ship docs first, reverse-engineer the spec later.
  </Card>
  <Card title="Semantics the spec can't express" icon="brain">
    Retry behaviour, idempotency keys, rate-limit burst vs sustained, eventual consistency windows. Prose > schema.
  </Card>
  <Card title="Custom response formats" icon="file-code">
    Server-sent events, newline-delimited JSON, WebSocket frames. `<ResponseExample>` accepts any body string.
  </Card>
  <Card title="Specific endpoints with special UX" icon="sparkles">
    Your `POST /payments` has a 3-step flow with customer redirects. Manual page can walk through each step with `<Steps>` + `<RequestExample>`.
  </Card>
</CardGroup>

## The five components

<ParamField path="<ApiMethod>" type="component">
  Renders the method + path header at the top of an endpoint page (`GET /users/{id}`). Colour-coded by method — GET green, POST blue, DELETE red, etc.
</ParamField>

<ParamField path="<ParamField>" type="component">
  One row per request parameter — path, query, header, or body field. Props: `path` (field name), `type` (TS-ish type), `required`, `default`. Children = description.
</ParamField>

<ParamField path="<ResponseField>" type="component">
  Same shape as ParamField but for response body fields. Renders in the response panel.
</ParamField>

<ParamField path="<RequestExample>" type="component">
  Tabbed code card for the request — cURL, fetch, SDK, whatever you want. Same layout as the auto-generated card.
</ParamField>

<ParamField path="<ResponseExample>" type="component">
  Tabbed code card for response examples. One tab per status code or scenario. Status-coloured like auto-gen.
</ParamField>

## Minimal example

Complete page documenting a `POST /payments` endpoint from scratch:

````mdx
---
title: Create payment
description: Charge a card or create a pending bank transfer.
---

<ApiMethod method="POST" path="/v1/payments" />

## Request body

<ParamField path="amount" type="integer" required>
  Amount in smallest currency unit (cents for USD). Min `100`.
</ParamField>

<ParamField path="currency" type="'usd' | 'eur' | 'gbp'" required>
  ISO 4217 currency code. Only these three are supported today.
</ParamField>

<ParamField path="source" type="string" required>
  Payment source token from the Elements SDK (`tok_...`) or a saved
  customer card (`card_...`).
</ParamField>

<ParamField path="description" type="string">
  Appears on the customer's statement. Max 22 characters.
</ParamField>

<ParamField path="idempotencyKey" type="string">
  Unique key to dedupe retries. Same key within 24 hours returns the
  original response without re-charging.
</ParamField>

<RequestExample>
```bash cURL
curl https://api.acme.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 1000,
    "currency": "usd",
    "source": "tok_visa",
    "description": "Monthly subscription"
  }'
```

```typescript TypeScript
import Acme from "@acme/sdk";
const acme = new Acme({ apiKey: process.env.ACME_KEY });

const payment = await acme.payments.create({
  amount: 1000,
  currency: "usd",
  source: "tok_visa",
  description: "Monthly subscription",
}, {
  idempotencyKey: crypto.randomUUID(),
});
```
</RequestExample>

## Response

<ResponseField name="id" type="string">
  Unique payment identifier. Always starts with `pay_`.
</ResponseField>

<ResponseField name="status" type="'succeeded' | 'pending' | 'failed'">
  `succeeded` — money moved. `pending` — waiting on bank rails (up to 3 business days). `failed` — reason in `failureReason`.
</ResponseField>

<ResponseField name="amount" type="integer">
  Same amount you passed in the request.
</ResponseField>

<ResponseField name="createdAt" type="string (ISO 8601)">
  Server timestamp when the payment was created.
</ResponseField>

<ResponseExample>
```json 200 OK
{
  "id": "pay_abc123",
  "status": "succeeded",
  "amount": 1000,
  "currency": "usd",
  "createdAt": "2026-04-20T10:30:00Z"
}
```

```json 400 Bad Request
{
  "code": "invalid_amount",
  "message": "Amount must be at least 100 for USD.",
  "statusCode": 400
}
```

```json 429 Too Many Requests
{
  "code": "rate_limited",
  "message": "Too many requests. Retry after 60 seconds.",
  "statusCode": 429
}
```
</ResponseExample>
````

The page renders with the same layout as auto-generated pages — method header, params table, request code card, response field table, response example tabs.

## When to use method + path

`<ApiMethod>` renders a one-line header. If you need the full endpoint treatment (Try-It playground, request tabs, response tabs, status-coloured), you can bind a manual page to an auto-gen'd operation via the `openapi` frontmatter:

```mdx
---
title: Create payment — detailed walkthrough
openapi: "POST /v1/payments"
---

This page still renders the Try-It panel + auto-gen'd tabs for
POST /v1/payments. Your prose renders between the method bar and
the generated reference — Callouts, plan banners, setup notes,
any component works here.

## When to use this endpoint

(Your custom narrative, full MDX freedom.)
```

This **hybrid** mode is described in the [OpenAPI overview](/openapi/overview). The manual-page-only approach (this page) skips the spec entirely.

## Organising manual endpoints

Put them under a sensible path that mirrors your API shape:

```
docs/
  api/
    payments/
      create.mdx       # <-- manual page
      capture.mdx      # <-- manual page
      refund.mdx       # <-- manual page
```

Add to nav as a group:

```json
{
  "group": "Payments",
  "pages": [
    "docs/api/payments/create",
    "docs/api/payments/capture",
    "docs/api/payments/refund"
  ]
}
```

Status badges (GET/POST/etc) appear automatically in the sidebar when the page starts with `<ApiMethod>`.

## Authentication sections

Shared auth blocks belong in a snippet. Today use inline `<Snippet>` children; Phase 4 file-based snippets will let you include from `_snippets/auth.mdx`:

```mdx
<Snippet>
  All endpoints require a `Bearer <api_key>` in the `Authorization`
  header. Test-mode keys start with `sk_test_`; live keys with `sk_live_`.
</Snippet>
```

See [reusable snippets](/content/reusable-snippets) for the full pattern.

## Paginated responses

Document cursor pagination with a dedicated field block:

```mdx
<ResponseField name="data" type="Payment[]">
  Current page of results. Always ordered newest first.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether more results exist. When `true`, include the last item's `id`
  as the `startingAfter` query parameter to fetch the next page.
</ResponseField>

<ResponseField name="startingAfter" type="string">
  Echoes the cursor from the request, or `null` for the first page.
</ResponseField>
```

Include a working paginated example in `<RequestExample>` showing two sequential calls.

## Streaming responses (SSE / NDJSON)

`<ResponseExample>` accepts any body string — use it for non-JSON formats:

````mdx
<ResponseExample>
```text Server-Sent Events
event: message
data: {"id":"msg_1","content":"Hello"}

event: message
data: {"id":"msg_2","content":"world"}

event: done
data: {"finishReason":"stop"}
```
</ResponseExample>
````

Document the content-type (`text/event-stream` / `application/x-ndjson`) in prose above the example.

## Page frontmatter for discovery

Set `description` so the LLM search + Copy-for-LLMs header has a one-sentence summary. Set `icon` to give the sidebar entry a glyph. Set `hidden: true` for internal-only endpoints that you still want routable.

```mdx
---
title: Rotate API key
description: Generate a new API key and invalidate the old one after a 5-minute grace period.
icon: key-round
---
```

## Related

- [Complex types](/openapi/complex-types) — composition keywords for spec-driven schemas
- [Multiple responses](/openapi/multiple-responses) — status-code tabs behaviour (manual pages get this for free via `<ResponseExample>`)
- [SDK examples](/openapi/sdk-examples) — `x-codeSamples` extension for spec-driven pages
- [Reusable snippets](/content/reusable-snippets) — share auth + intro blocks across manual pages
- [OpenAPI overview](/openapi/overview) — auto-gen + hybrid modes

---

# Multiple responses
Source: https://docs.nookdocs.com/openapi/multiple-responses

Document every response an endpoint can return — 200 success plus 400 / 401 / 404 / 429 / 500 — each with its own schema, example, and tab in the endpoint page.

Real APIs don't just return 200. They return 400 when the input's malformed, 401 when auth's missing, 404 when the resource doesn't exist, 429 when the reader's rate-limited. NookDocs renders every response declared in your OpenAPI spec as a tab in the endpoint page, each with its own schema and example, colour-coded by status class.

## How responses render

The endpoint page's response panel has a tab strip — one tab per status code in your spec, ordered numerically. Status tabs are semantically coloured:

| Status class | Tab colour | Examples |
|---|---|---|
| **2xx success** | Green | 200 OK, 201 Created, 204 No Content |
| **3xx redirect** | Blue (info) | 301, 302, 304 — rare in REST APIs |
| **4xx client error** | Red (danger) | 400, 401, 403, 404, 422, 429 |
| **5xx server error** | Amber (warning) | 500, 502, 503, 504 |

Reader clicks a tab → sees that status's description, content-type, response schema (full field table), and the example response body.

## Minimal shape

Every response needs `description` + `content` with a media-type and schema:

```yaml
paths:
  /users/{id}:
    get:
      operationId: getUser
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
```

Two tabs render: **200** (green) and **404** (red). Each with its schema field table + a synthesised example.

## Adding examples

Schemas auto-synthesise an example (from `example` / `examples` on the schema, or from `type` + `format` fallbacks). Override per response:

```yaml
responses:
  '200':
    description: Successful user lookup
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
        example:
          id: "usr_abc123"
          email: "jane@acme.com"
          createdAt: "2026-04-20T10:30:00Z"
  '404':
    description: No user with that ID
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'
        example:
          code: "user_not_found"
          message: "No user exists with id usr_doesnotexist"
          statusCode: 404
```

The example appears in the example-response tab strip alongside the schema tab. Readers flip between "what the shape is" and "what a real body looks like."

## Multiple examples per status

Sometimes 200 responses can vary by scenario — a `GET /search` returns different shapes for "found results" vs "no results". Declare with `examples`:

```yaml
responses:
  '200':
    description: Search completed
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SearchResults'
        examples:
          hasResults:
            summary: Results found
            value:
              query: "carbon"
              total: 42
              items:
                - { id: "r_1", title: "Carbon pricing" }
                - { id: "r_2", title: "Carbon capture methods" }
          empty:
            summary: No results
            value:
              query: "kdjhfksjdhf"
              total: 0
              items: []
```

Each named example appears as a sub-tab within the status tab. Reader clicks **200 → Results found** or **200 → No results**.

## Error response schema pattern

Centralise your error shape in a single `Error` schema and reference it everywhere:

```yaml
components:
  schemas:
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error slug (e.g. `user_not_found`, `rate_limited`).
          example: "user_not_found"
        message:
          type: string
          description: Human-readable explanation.
          example: "No user exists with that ID."
        statusCode:
          type: integer
          description: HTTP status code, mirroring the response status.
        requestId:
          type: string
          format: uuid
          description: Passthrough for our logs. Include in support tickets.
```

Then across every endpoint:

```yaml
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'404':
  description: Not found
  content:
    application/json:
      schema: { $ref: '#/components/schemas/Error' }
```

Response-level `$ref` (`#/components/responses/...`) lets you centralise not just the schema but the full description + example, so your error handling docs stay consistent endpoint to endpoint.

## Rate-limit + auth responses

Two responses every endpoint should document even if you don't enforce them globally:

```yaml
'401':
  description: Missing or invalid API key
  content:
    application/json:
      schema: { $ref: '#/components/schemas/Error' }
      example:
        code: "invalid_api_key"
        message: "API key is missing or invalid."
        statusCode: 401
'429':
  description: Rate limit exceeded
  headers:
    X-RateLimit-Limit:
      schema: { type: integer }
      description: Request quota per minute.
    X-RateLimit-Remaining:
      schema: { type: integer }
      description: Requests remaining in the current window.
    Retry-After:
      schema: { type: integer }
      description: Seconds to wait before retrying.
  content:
    application/json:
      schema: { $ref: '#/components/schemas/Error' }
      example:
        code: "rate_limited"
        message: "Too many requests. Retry after 60 seconds."
        statusCode: 429
```

Response headers declared via `headers:` render in the response panel below the body — readers see `X-RateLimit-Remaining` is a thing before they have to discover it the hard way.

## Default response

OpenAPI's `default` response catches everything not enumerated:

```yaml
responses:
  '200':
    description: Success
    content:
      application/json:
        schema: { $ref: '#/components/schemas/User' }
  default:
    description: Unexpected error
    content:
      application/json:
        schema: { $ref: '#/components/schemas/Error' }
```

Rendered as a **default** tab, neutral-coloured (no status number to classify). Useful for APIs where you don't want to enumerate every 5xx possibility but still want the error shape documented.

## Status descriptions

The `description` field is the tab's subtitle — readers scan these to figure out which tab they care about. Write them as "what happened" sentences, not just status name repetition:

```yaml
'200': { description: "User retrieved successfully" }          # Better
'200': { description: "OK" }                                    # Noise
'404': { description: "No user exists with the provided ID" }  # Better
'404': { description: "Not Found" }                             # Noise
```

## Content-type other than JSON

NookDocs handles multiple media types per response:

```yaml
responses:
  '200':
    description: Export completed
    content:
      application/json:
        schema: { $ref: '#/components/schemas/ExportJob' }
      application/pdf:
        schema:
          type: string
          format: binary
      text/csv:
        schema:
          type: string
```

The media-type appears below the status tab header. Schemas render independently per type.

## Limitations

- **No `links` rendering.** OpenAPI's `links` keyword (for describing how one response's ID feeds the next endpoint's request) is parsed but not yet rendered as a UI affordance. Useful for HATEOAS-style docs — on the roadmap.
- **No response callback docs for WebSockets.** `asyncapi.yaml` is the right format for event-driven APIs; we parse but don't fully render it yet — see [AsyncAPI setup](/openapi/overview#asyncapi) (roadmap).
- **No response-time SLA annotation.** `x-response-time-p99` and similar extensions pass through but aren't surfaced. If you need latency docs, put them in the endpoint description.

## Related

- [Complex types](/openapi/complex-types) — `oneOf` / `anyOf` / `allOf` response schemas
- [Playground](/openapi/playground) — Try-It panel where readers see real responses
- [SDK examples](/openapi/sdk-examples) — `x-codeSamples` for hand-written code snippets
- [Manual API pages](/openapi/manual-pages) — escape hatch with `<ResponseExample>` + `<ResponseField>`

---

# OpenAPI integration
Source: https://docs.nookdocs.com/openapi/overview

Auto-generated API reference pages from your openapi.json or openapi.yaml — push the spec, get a docs site.

## How it works

Drop an OpenAPI 2.0 / 3.0 / 3.1 spec into your repo, point `nookdocs.config.json` at it, and NookDocs auto-generates a full API reference for every endpoint. No template writing, no MDX per endpoint — the spec is the source of truth.

<Steps>
  <Step titleIcon="file-text" title="Add your spec to the repo">
    Commit `openapi.json` (or any path you prefer) alongside your existing docs files. The `api.openapi` path is relative to your docs base.
  </Step>
  <Step titleIcon="settings" title="Point config at it">
    Add the `api.openapi` field in `nookdocs.config.json`:

    ```json
    {
      "name": "Acme API",
      "api": {
        "openapi": "openapi.json",
        "playground": true
      },
      "navigation": [...]
    }
    ```
  </Step>
  <Step titleIcon="rocket" title="Push to GitHub">
    The sync job fetches the spec, parses it via `swagger-parser` (full `$ref` resolution), and stores the parsed endpoints in the database.
  </Step>
  <Step titleIcon="check" title="Endpoint pages live">
    Every operation is reachable at `/api-reference/{tag}/{operation-id}`. The platform renders the full page using the existing `<ApiMethod>`, `<ParamField>`, `<ResponseField>`, and `<Expandable>` components.
  </Step>
</Steps>

## URL pattern

Each endpoint becomes a page at:

```
/api-reference/{tag}/{operation-id}
```

The `tag` comes from the operation's `tags[0]` field (or `default` if none). The `operation-id` is the spec's `operationId` field (or a generated fallback like `get-users-id` if missing). Tags with spaces are slugified — `"User Management"` becomes `user-management` in the URL.

## What's auto-generated

For every operation, the rendered page includes:

<CardGroup cols={2}>
  <Card title="Method + URL" icon="code">
    Color-coded `<ApiMethod>` badge next to the path
  </Card>
  <Card title="Description" icon="file-text">
    Operation summary as the page h1, full description as the lead paragraph
  </Card>
  <Card title="Authorization" icon="lock">
    Security requirements section if the operation has any
  </Card>
  <Card title="Path parameters" icon="link">
    `<ParamField path="path">` per parameter, with type, required, and description
  </Card>
  <Card title="Query parameters" icon="search">
    `<ParamField path="query">` with default values and enum options surfaced
  </Card>
  <Card title="Headers" icon="server">
    Required headers as `<ParamField path="header">`
  </Card>
  <Card title="Request body" icon="upload">
    Top-level body properties as `<ParamField path="body">`. Nested objects expand via `<Expandable>`.
  </Card>
  <Card title="Responses" icon="download">
    One section per status code with the response schema as `<ResponseField>` entries
  </Card>
</CardGroup>

## Supported spec versions

| Version | Support |
|---------|---------|
| **OpenAPI 3.1** | ✅ Full |
| **OpenAPI 3.0** | ✅ Full |
| **Swagger 2.0** | ✅ Full (body params auto-promoted to requestBody) |

The parser uses [`@apidevtools/swagger-parser`](https://apitools.dev/swagger-parser/) under the hood, which validates the spec and dereferences every `$ref` before we touch it. Invalid specs surface in your build log so you can fix them on the next push.

## Schema features

| Feature | Support |
|---------|---------|
| `$ref` (local references) | ✅ Inlined at parse time |
| `oneOf`, `anyOf`, `allOf` | ✅ Stored, renderer flattening in Phase 4 follow-up |
| Nested object schemas | ✅ One level via `<Expandable>` |
| Enum values | ✅ Surfaced as inline pills under the param |
| Default values | ✅ Shown in the param metadata row |
| Deprecated flag | ✅ Strikethrough + warning badge |
| File uploads (`multipart/form-data`) | ⏳ Planned |
| Webhooks (3.1) | ⏳ Planned |
| Callbacks | ⏳ Planned |

## Mixing manual MDX with auto-generated pages

The auto-generation only kicks in when there's no MDX page at the requested path. So you can override any auto-generated page by writing a manual MDX file at the same URL:

```
docs/api-reference/users/get-user.mdx
```

This wins over the auto-generated `/api-reference/users/get-user`. Use it when you want to add prose explanations, custom code examples, or migration notes that the spec alone can't express.

The recommended pattern: let auto-generation handle the bulk of your endpoints, write manual MDX only for the 5-10% that need extra context.

## YAML and JSON

Both formats work. Point `api.openapi` at a `.json`, `.yaml`, or `.yml` spec and
NookDocs parses it either way — YAML is a JSON superset, so you can keep your spec
in whichever format your API framework emits (FastAPI, NestJS, Spring Boot, and
most others emit either). No conversion step.

## Configure once, deploy forever

After your first push with `api.openapi` configured, the sync job auto-runs on every subsequent push. Update your spec, commit, push — the API reference updates 30 seconds later. No manual rebuild step.

## Try it

If you have a working OpenAPI spec, drop it at your docs base (relative to the base), add `"api": { "openapi": "openapi.json" }` to your `nookdocs.config.json`, and push. You'll have a fully-rendered API reference at `/api-reference/{tag}/{operation-id}` for every endpoint in your spec.

## What's next

| Phase | Addition |
|-------|----------|
| 4.3 | Try-it playground modal — click "Try it" on any endpoint, fill the form, fire a real request from the browser |
| 4.4 | Versioning — `versions: ["v1", "v2"]` config + version selector in the navbar |
| 4.5 | Custom domain DNS verification (separate feature, lands in the same phase) |
| 4 follow-up | YAML spec support + Phase 4 follow-up: oneOf/anyOf rendering, file upload params |

---

# Try-it playground
Source: https://docs.nookdocs.com/openapi/playground

A live in-browser API request runner that auto-generates the form from your OpenAPI schema.

## What it is

Every auto-generated endpoint page (and any manual MDX page that wraps an endpoint) gets a **Try it** button next to the URL. Clicking it opens a two-pane modal:

- **Left pane** — Auto-generated form with one input per parameter, plus a body textarea pre-filled with a JSON template from the request body schema
- **Right pane** — Live cURL preview that updates as the form fills out, plus the response (status, headers, body) once the request completes

The reader fires a real `fetch()` from the browser, sees the actual response, and copies the cURL one-click to drop into their own terminal.

## How the form is built

The form is generated entirely from the parsed OpenAPI schema — no per-endpoint configuration needed:

<CardGroup cols={2}>
  <Card title="Path params" icon="link">
    One text input per `in: path` parameter. Required-marked params show a red asterisk.
  </Card>
  <Card title="Query params" icon="search">
    One input per `in: query` parameter. `default` values from the spec pre-fill on open.
  </Card>
  <Card title="Headers" icon="server">
    One input per `in: header` parameter. Authorization is its own dedicated input above the others.
  </Card>
  <Card title="Body" icon="upload">
    Plain JSON textarea pre-filled with a template walked from the request body schema (string → "", number → 0, enum → first value, date-time → now).
  </Card>
</CardGroup>

## Authorization

The auth input is separate from the headers section and supports three schemes:

| Scheme | Where the value goes |
|--------|----------------------|
| `bearer` | `Authorization: Bearer {value}` |
| `apiKey` | `{configurable header name}: {value}` |
| `basic` | `Authorization: Basic {value}` (base64-encoded) |

The reader's auth value is **never persisted** — it lives in the modal's local state only. Close the modal and the value is gone. This keeps API tokens out of localStorage and out of your tenant analytics.

## cURL preview

The right pane shows a live cURL command that mirrors the request the playground will fire. As the reader fills out the form, the cURL string updates in real time. One click on **Copy as cURL** ships it to the clipboard ready to paste into a terminal.

```bash
curl -X POST 'https://api.acme.com/v1/users' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","email":"alice@example.com"}'
```

## Sending the request

The **Send request** button calls `fetch()` directly from the browser. This means:

- **CORS must be configured** on your API for the docs site origin
- **Mixed content** rules apply — your API must be HTTPS if your docs site is HTTPS
- **Cookies / credentials** are NOT sent by default (the playground doesn't set `credentials: "include"`)

If your API has strict CORS or you don't want to expose it to the docs origin, the Phase 4 follow-up will add an optional server-side proxy at `/api/playground/proxy` that the playground can route through.

## Response viewer

The response panel shows:

- **Status badge** — green for 2xx, red for 4xx/5xx, with the HTTP status text
- **Duration** — milliseconds from button click to response
- **Body** — pretty-printed JSON if `Content-Type: application/json`, otherwise raw text
- **Network errors** — fall through with a friendly error message instead of a stack trace

The body viewer is plain `<pre>` for v1. JSON tree expansion ships in a Phase 4 follow-up.

## When the playground appears

The Try-It button is enabled by default on every auto-generated endpoint page. To hide it for a specific endpoint or for the entire site, you have two options:

1. **Per-spec disable** — set `playground: false` (or `playground: "none"`) in `nookdocs.config.json#api`:
   ```json
   {
     "api": {
       "openapi": "openapi.json",
       "playground": false
     }
   }
   ```
2. **Per-endpoint disable** — when writing manual MDX that uses `<ApiEndpoint>`, pass `playground={false}` (Phase 4 follow-up — not yet wired into MDX exposure)

## Differences from `<RequestExample>`

| | `<ApiPlayground>` | `<RequestExample>` |
|---|---|---|
| **Interactive** | Yes — fires real requests | No — static code samples |
| **Auto-generated** | Yes — from spec | Either author-written or auto-gen (Phase 4 follow-up) |
| **Multi-language** | cURL only (v1) | curl/js/python/go/etc. |
| **Use** | "Try this endpoint right now" | "Here's how the request looks" |

The two are complementary, not competing. Most endpoint pages use both: a `<RequestExample>` block at the top showing the canonical request shape, and a Try It modal for readers who want to experiment.

## Known limits (v1)

- **Single-language cURL output** — multi-language Copy buttons are queued
- **No JSON tree** for the response — pretty-printed text only
- **No streaming responses** — waits for the full body before rendering
- **No file uploads** — `multipart/form-data` is not yet supported
- **No save/share** — you can't link to a pre-filled form state
- **No history** — reload the modal and your previous request is gone

These are all v1 trade-offs. The most-asked items will land in Phase 4 follow-up commits.

## Try it

Find any auto-generated endpoint page on this site (e.g. `/api-reference/projects/create-project` once a tenant ships an OpenAPI spec) and click the **Try it** button next to the URL. The modal opens with the form pre-filled from the schema and you're ready to fire requests.

---

# Add SDK examples
Source: https://docs.nookdocs.com/openapi/sdk-examples

Drop `x-codeSamples` into your OpenAPI operations and NookDocs merges them into the endpoint's Try-It code card — auto-generated curl + real SDK snippets side by side in one tab strip.

Auto-generated curl / JS / Python examples are the bare minimum. Your users probably have an SDK. The `x-codeSamples` OpenAPI extension (a ReDoc convention, widely adopted) lets you attach hand-written or Speakeasy/Stainless-generated SDK examples directly to each operation, and NookDocs merges them into the endpoint code card automatically.

## Why this matters

The Try-It code card on every endpoint page ships three auto-generated tabs by default: **cURL**, **JavaScript (fetch)**, **Python (requests)**. These are fine for exploration but not what your users actually paste into their codebase — they paste SDK calls. `x-codeSamples` gives you that extra tab strip **with zero UI configuration** on our side. Drop the extension into your spec, redeploy, done.

## The extension

```yaml
paths:
  /payments:
    post:
      operationId: createPayment
      summary: Create a payment
      x-codeSamples:
        - lang: TypeScript
          label: "@acme/sdk"
          source: |
            import Acme from "@acme/sdk";
            const acme = new Acme({ apiKey: process.env.ACME_KEY });
            const payment = await acme.payments.create({
              amount: 1000,
              currency: "usd",
              source: "tok_visa",
            });
        - lang: Python
          label: "acme-python"
          source: |
            from acme import Acme
            acme = Acme(api_key="sk_...")
            payment = acme.payments.create(
                amount=1000,
                currency="usd",
                source="tok_visa",
            )
        - lang: Go
          label: "acme-go"
          source: |
            acme := acme.New("sk_...")
            payment, err := acme.Payments.Create(&acme.PaymentCreateParams{
                Amount: acme.Int64(1000),
                Currency: acme.String("usd"),
                Source: acme.String("tok_visa"),
            })
```

Each entry becomes a tab in the endpoint's code card. Tab labels come from `label` (fallback: `lang`). The tab content is the `source` string verbatim, syntax-highlighted via Prism based on `lang`.

## Field reference

<ParamField path="x-codeSamples[].lang" type="string" required>
  Language slug. Controls syntax highlighting. Common values: `typescript`, `javascript`, `python`, `ruby`, `go`, `rust`, `java`, `php`, `csharp`, `swift`, `kotlin`, `bash`, `curl`. Free-form — unknown slugs render as plain text without highlighting.
</ParamField>

<ParamField path="x-codeSamples[].label" type="string">
  Human-readable tab label. Falls back to `lang` when omitted. Use this to differentiate multiple entries of the same language (e.g. `"SDK"` vs `"REST (fetch)"` for two TypeScript samples).
</ParamField>

<ParamField path="x-codeSamples[].source" type="string" required>
  The code snippet. Multiline strings via YAML `|` block scalar are the cleanest — indentation is preserved exactly. Keep it under ~50 lines per tab so readers can scan without scrolling the whole page.
</ParamField>

## How NookDocs merges these

The endpoint code card renders tabs in this order:

1. **Auto-generated** — cURL + JS fetch + Python requests, synthesised from the spec.
2. **`x-codeSamples`** — appended after, in the order declared in the spec.

If `x-codeSamples` contains a language that conflicts with an auto-generated tab (e.g. you provided your own `curl`), your version wins — the auto-gen is dropped. This gives you full control when you need it.

Reader clicks a tab → the Try-It playground uses the **currently visible tab's language** as the base for its "Run request" call where applicable (for cURL, fetch, requests — SDK snippets are display-only).

## Generator tools

You don't have to hand-write these. Commercial and open-source tools generate `x-codeSamples` entries from your OpenAPI spec automatically:

<CardGroup cols={2}>
  <Card title="Speakeasy" icon="sparkles" href="https://speakeasy.com">
    Commercial. Generates idiomatic SDKs for 7+ languages and emits matching `x-codeSamples` entries back into the spec. Keeps SDK calls and docs in sync as your spec evolves.
  </Card>
  <Card title="Stainless" icon="zap" href="https://stainless.com">
    Commercial. Similar positioning — SDK gen + docs examples. Used by OpenAI, Anthropic, Cloudflare.
  </Card>
  <Card title="openapi-generator" icon="terminal" href="https://openapi-generator.tech">
    Open source. Generates client code but doesn't auto-emit `x-codeSamples`. You'd post-process the output.
  </Card>
  <Card title="Hand-written" icon="pen-line">
    Totally fine for small specs. Pay attention to authentication setup — readers will copy-paste, so make the snippets runnable after one env-var swap.
  </Card>
</CardGroup>

## Authoring guidance

### Keep them paste-runnable

The fastest path from "read the docs" to "first 200 response" is a snippet the reader can paste, swap the API key, and run. Include the import line. Include the env-var lookup. Omit everything else — no explanatory comments, no try/catch unless the point is the try/catch.

```typescript
// Good — copy, paste, swap key, run
import Acme from "@acme/sdk";
const acme = new Acme({ apiKey: process.env.ACME_KEY });
const payment = await acme.payments.create({ amount: 1000, currency: "usd" });
```

```typescript
// Bad — too much scaffolding, reader stops reading halfway through
async function createPaymentExample() {
  try {
    // First, initialize the SDK with your API key from env
    const acme = new Acme({
      apiKey: process.env.ACME_KEY ?? "fallback-value",
    });
    // Now call the payments.create method...
    const payment = await acme.payments.create({
      amount: 1000, // in cents
      currency: "usd",
      /* more options here */
    });
    console.log("Created payment", payment.id);
  } catch (err) {
    console.error("Payment failed:", err);
  }
}
```

### One variant per use case

Don't ship 6 TypeScript samples for the same endpoint. Pick one canonical example per SDK, per operation. Use the `label` field to differentiate if you truly need two (e.g. `"SDK (async)"` vs `"SDK (sync)"`).

### Keep labels short

Tab strips break layout when labels are long. Target ≤12 chars. `"@acme/sdk"` beats `"Acme TypeScript SDK (npm package)"`.

### Order by user preference

Tabs render in declared order. Put your users' most likely language first — for B2B SaaS that's usually TypeScript or Python. Not cURL — cURL is already auto-generated.

## Inspect the merged output

Every endpoint page serves the agent-filtered MDX at `/<endpoint-path>.md`. The `x-codeSamples` entries appear there too so LLMs helping users generate integration code can see what canonical SDK usage looks like:

```bash
curl -sL https://docs.acme.com/api-reference/payments/create-payment.md
```

The Copy-for-LLMs button in the endpoint page header emits the same view.

## Limitations

- **No inline execution.** Unlike cURL / fetch / requests tabs, SDK snippets are display-only. The Try-It playground doesn't execute arbitrary SDK calls.
- **No syntax validation.** We render whatever `source` string you provide. Broken snippets ship as broken snippets.
- **No Speakeasy/Stainless-specific field names.** Both tools emit standard `x-codeSamples`. If your generator uses a proprietary extension (e.g. `x-speakeasy-code-samples` or similar), rename to `x-codeSamples` or configure the generator to output the standard form.

## Related

- [Playground](/openapi/playground) — the Try-It code card where these tabs render
- [Manual API pages](/openapi/manual-pages) — escape hatch with `<RequestExample>` / `<ResponseExample>` components
- [OpenAPI overview](/openapi/overview) — how specs wire up
- [Complex types](/openapi/complex-types) — `oneOf` / `anyOf` / `allOf` handling

---

# Manage page visibility
Source: https://docs.nookdocs.com/openapi/visibility

Control which operations generate docs pages, which stay in the spec but hidden from the sidebar, and which get stripped entirely — today via MDX frontmatter, `x-hidden` / `x-excluded` extension support is roadmap.

Not every operation in your OpenAPI spec deserves a docs page. Internal endpoints, deprecated routes, partner-only APIs — they belong in the spec (for SDK codegen, for internal tooling) but shouldn't surface to public readers. Mintlify/ReDoc adopted two OpenAPI extensions for this: `x-hidden` (generate the page but hide from navigation) and `x-excluded` (don't generate at all). NookDocs supports the hide-from-sidebar side today via MDX frontmatter; the native OpenAPI extensions are on the roadmap.

<Banner variant="warning">
  **Shipping status.** Hide-from-sidebar works today via `hidden: true` frontmatter on hybrid MDX pages. Pure OpenAPI `x-hidden` / `x-excluded` extension parsing is not yet wired — auto-generated API pages from the spec always appear in the sidebar. Workarounds below.
</Banner>

## What ships today

### `hidden: true` on hybrid pages

If an operation is surfaced via a **hybrid MDX page** (`openapi: "METHOD /path"` in frontmatter), you can hide it:

```mdx
---
title: Rotate API key (internal)
openapi: "POST /internal/rotate-api-key"
hidden: true
---

Detailed walkthrough of the key-rotation flow for our CS team...
```

Effect:
- Page renders at `/api-reference/...` — URL works for anyone who has it.
- Sidebar drops the entry — no navigation path to the page.
- Search index excludes it — search doesn't surface it.
- Sitemap skips it — search engines don't crawl it.
- `llms.txt` / `llms-full.txt` exclude it — LLM crawlers don't ingest it.
- `seo.indexing` can still override if you want Google to skip even the URL: add `noindex: true` on the page frontmatter.

See [hidden pages](/configuration/schema-reference) and [SEO](/optimize/seo) for the mechanics.

### Per-group hiding in navigation

A whole nav group can be hidden by setting `hidden: true` on the group:

```json
{
  "navigation": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Internal APIs",
          "hidden": true,
          "pages": ["docs/api/internal/rotate-key", "docs/api/internal/force-sync"]
        }
      ]
    }
  ]
}
```

Every page in the group gets hidden — same effect as individual `hidden: true` on each page.

### `authGroups` (schema-scaffolded, runtime roadmap)

The schema accepts `authGroups: ["admin", "devrel"]` on groups and pages to gate behind auth. Runtime enforcement isn't wired yet — setting the field today has no effect. When the auth layer ships, these groups will only render for viewers in the matching `authGroups`. See [personalization](/content/personalization).

## What's on the roadmap

### `x-hidden` — generate but hide

ReDoc / Mintlify convention: add to any operation in your spec, and the generator creates the page but omits it from navigation.

```yaml
paths:
  /internal/rotate-key:
    post:
      operationId: rotateApiKey
      x-hidden: true
      summary: Rotate API key
      responses:
        '200':
          description: New key returned
```

**Status:** not parsed yet. Today the parser includes the operation in navigation regardless. Workaround: back the operation with a hybrid MDX page carrying `hidden: true` frontmatter.

### `x-excluded` — don't generate at all

Same convention, different semantic: the operation is present in the spec (SDK codegen picks it up) but NookDocs doesn't create a docs page.

```yaml
paths:
  /internal/purge-cache:
    delete:
      operationId: purgeCache
      x-excluded: true
```

**Status:** not parsed yet. Workaround: maintain a **secondary reduced spec** that omits excluded operations, point `api.openapi` at the reduced spec, keep the full spec for SDK codegen in a different path. Ugly but works.

### `x-internal` (OpenAPI 3.0 community convention)

Some teams use `x-internal: true` as a synonym for `x-hidden`. Parser treats it identically when shipped.

### Roadmap details

When these land, the parser will:

1. Walk every path + operation in the spec.
2. If `x-excluded: true` — skip the operation entirely. Don't emit a page, don't add to sidebar, don't include in sitemap.
3. If `x-hidden: true` (or `x-internal: true`) — emit the page, mark it hidden in `frontmatter.hidden = true` when syncing. Same effect as the manual `hidden: true` approach.

Tracking: [github.com/Codivion/NookDocs/issues?q=x-hidden](https://github.com/Codivion/NookDocs/issues?q=x-hidden). Drop a 👍 if you need this.

## Practical workarounds today

### Workaround 1: hybrid page per internal operation

Create an MDX page for each operation you want hidden, and bind it to the OpenAPI operation via frontmatter:

```mdx
---
title: Force cache purge
openapi: "DELETE /internal/purge-cache"
hidden: true
---

Operational-only endpoint for the CS team. Reach out in #cs-ops
before hitting this in production.
```

Effect: the Try-It playground + auto-generated schema still render on the page, but the page never appears in the sidebar, search, sitemap, or llms.txt.

### Workaround 2: split into two specs

Ship two OpenAPI files in your repo:

- `openapi-public.json` — operations you want documented. Point `api.openapi` at this.
- `openapi-full.json` — everything including internal operations. Feed this to your SDK codegen.

Only the public spec becomes docs pages. The internal spec stays in the repo for SDK generation without surfacing to readers.

### Workaround 3: nav-group exclusion

If you group internal operations under a single tag in your spec, the auto-generator puts them in a single sidebar group (named after the tag). Hide that whole group:

```yaml
# openapi.json
paths:
  /internal/purge-cache:
    delete:
      tags: [Internal]
      ...
  /internal/rotate-key:
    post:
      tags: [Internal]
      ...
```

```json
// nookdocs.config.json
{
  "navigation": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Internal",
          "hidden": true
        }
      ]
    }
  ]
}
```

Every operation tagged `Internal` hides from the sidebar via the group-level flag.

## Deprecated operations (adjacent)

OpenAPI's `deprecated: true` keyword IS parsed and renders with a strike-through + "Deprecated" badge in the sidebar. Keep the docs visible but signal users to migrate:

```yaml
paths:
  /v1/old-endpoint:
    get:
      deprecated: true
      summary: Old endpoint (use /v2/new-endpoint)
      x-sunset-date: "2026-12-01"
      ...
```

Custom `x-sunset-date` passes through but doesn't render specially — include it in the description if you want readers to see it.

## Related

- [Schema reference — `hidden`](/configuration/schema-reference) — the frontmatter field the workarounds use
- [Hidden pages](/configuration/schema-reference) — page-level hidden mechanics
- [Personalization](/content/personalization) — viewer-based gating (`authGroups`, roadmap)
- [OpenAPI overview](/openapi/overview) — parser + hybrid page mechanics

---

# llms.txt
Source: https://docs.nookdocs.com/optimize/llms-txt

Every NookDocs tenant ships an auto-generated llms.txt (sitemap-style index) and llms-full.txt (full content dump) for AI crawlers. No configuration — the files regenerate on every page sync.

`llms.txt` is the [llmstxt.org](https://llmstxt.org) standard for pointing LLM crawlers at the canonical, machine-readable version of a documentation site. NookDocs hosts two files on every tenant automatically:

- **`/llms.txt`** — sitemap-style index: H1 + tagline + list of `[title](url)` links to every docs page, grouped by section.
- **`/llms-full.txt`** — the entire MDX body of every page concatenated, ready to paste into a prompt or ingest into a vector DB.

Both regenerate whenever a page syncs from the repo. No `nookdocs.config.json` flag to set; no build step to run; no plugin to install.

## Where to find them

Every tenant exposes them at the docs root:

```text
https://{your-subdomain}.nookdocs.site/llms.txt
https://{your-subdomain}.nookdocs.site/llms-full.txt
```

Custom domains serve them from the same path:

```text
https://docs.yourcompany.com/llms.txt
https://docs.yourcompany.com/llms-full.txt
```

Try it on this very site: [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt).

## What's inside

### `llms.txt` format

Follows the llmstxt.org spec: Markdown H1 + blockquote tagline + grouped list of H2 sections with `[title](url)` links. Example:

```text
# Acme Documentation

> Build, deploy, and scale with Acme.

## Getting started

- [Introduction](https://docs.acme.com/introduction)
- [Quickstart](https://docs.acme.com/quickstart)

## API

- [Authentication](https://docs.acme.com/api/authentication)
- [Rate limits](https://docs.acme.com/api/rate-limits)
```

Hidden pages (`hidden: true` in frontmatter) are excluded. Section grouping comes from your `navigation` config.

### `llms-full.txt` format

Every page's MDX body, concatenated with `# {title}` headings as section markers:

```text
# Introduction

Acme Docs is the fastest way to ship API documentation...

# Quickstart

Sign up at acme.com, then...
```

Binary assets (images, PDFs) are skipped. Frontmatter is stripped. The file is plain UTF-8, no HTML escaping.

## How AI tools discover the file

Most LLM products that support documentation fetching will probe `/llms.txt` at the root of the domain you give them. Tested clients:

- **Claude.ai Projects** — paste your docs URL; Claude checks `/llms.txt` + `/llms-full.txt` automatically.
- **ChatGPT Custom GPTs** — set the `openapi_url` to your docs root; GPT Actions crawler follows `/llms.txt` links.
- **Cursor / Windsurf / Claude Code** — use the [contextual menu](/configuration/contextual) "Open in …" items, which deep-link these tools to your docs with `$path` / `$mdx` placeholders.
- **Perplexity** — indexes `/llms.txt` as a sitemap alongside `/sitemap.xml`.

## Customising with contextual menu

The **Copy page** dropdown that appears next to every page title exposes both files as one-click operations. See [contextual menu](/configuration/contextual) for how to enable additional items (Cursor, VS Code, Grok) and custom template variables.

## Limitations

- **No HTTP discovery headers yet.** Mintlify advertises `llms.txt` via an `X-Llms-Txt` response header and an HTML `<link rel="describedby">` tag. NookDocs ships the files but doesn't yet advertise them in headers — on the roadmap. Crawlers that probe `/llms.txt` directly work fine today.
- **No custom `llms.txt` override.** The generated file reflects your navigation. If you need a custom sort, drop a file at `public/llms.txt` in your repo and we'll start respecting it (planned).
- **Non-public pages excluded.** Pages with `seo.indexing: "noindex"` or frontmatter `hidden: true` are excluded from both files.

## Related

- [Markdown export](/optimize/markdown-export) — companion `/<slug>.md` URL convention for per-page raw MDX
- [Contextual menu](/configuration/contextual) — "Open in ChatGPT / Claude / Cursor" dropdown
- [SEO](/optimize/seo) — sitemap.xml + robots.txt + canonical URLs
- [Copy for LLMs](/features/copy-for-llms) — user-facing overview of the AI discovery stack

---

# Markdown export
Source: https://docs.nookdocs.com/optimize/markdown-export

Every docs page is also available as raw MDX at `/path.md`. Appends no `.mintlify/llms` magic — the URL convention is the API. Works with any LLM, any scraper, any clipboard.

NookDocs assumes you'll hand pages off to LLMs — to summarise, extend, translate, or regenerate. That handoff needs the **source**, not the rendered HTML. We expose the source at a stable `/path.md` URL on every page, plus a one-click clipboard affordance in the UI.

## The `.md` URL convention

Append `.md` to any docs page URL and the server returns the raw MDX source with `Content-Type: text/markdown`.

```text
# Rendered HTML
https://docs.acme.com/quickstart

# Raw MDX source (same content, different format)
https://docs.acme.com/quickstart.md
```

Works on any tenant, any custom domain, any path depth:

```text
https://docs.acme.com/api/authentication.md
https://docs.acme.com/configuration/theme.md
https://docs.acme.com/.md                    # root page
```

Try it on this page: [`/optimize/markdown-export.md`](/optimize/markdown-export.md).

## What you get back

Exact MDX source from your repo — frontmatter included, components intact, no HTML escaping. Example (abridged):

```text
---
title: Markdown export
description: Every docs page is also available as raw MDX...
icon: file-down
---

NookDocs assumes you'll hand pages off to LLMs...

<ParamField path="...">
  ...
</ParamField>
```

Headers:

- `Content-Type: text/markdown; charset=utf-8`
- `Cache-Control: public, max-age=300, s-maxage=300, stale-while-revalidate=3600`

No authentication required for public pages. Pages hidden via `hidden: true` frontmatter return a 404 at the `.md` URL too.

## Use cases

### Paste into any LLM

```text
Reader: "summarise this for me"
→ paste /my-page.md contents
→ LLM understands the component set + body + frontmatter
```

### Script-assisted content operations

```bash
# Pull a page, run a diff, open an issue when it drifts from your style guide
curl -sL https://docs.acme.com/quickstart.md | ./lint-style.py
```

```bash
# Export every page as MDX for a one-off migration
curl -sL https://docs.acme.com/sitemap.xml | \
  xmllint --xpath "//*[local-name()='loc']/text()" - | \
  xargs -I{} curl -sL "{}.md" -o "./export/$(basename {}).md"
```

### Claude Projects / ChatGPT Custom GPTs

Most LLM providers accept a docs-site URL and will fetch `/llms.txt` + per-page `.md` URLs automatically. See [llms.txt](/optimize/llms-txt) for the index file format.

## Copy from the UI

Every docs page also ships a **Copy page** split button in the top-end corner of the page header. The primary click copies the raw Markdown to your clipboard; the chevron opens the [contextual menu](/configuration/contextual) with deep-links to ChatGPT / Claude / Perplexity / Cursor / Windsurf / VS Code / MCP clients.

<Steps>
  <Step title="Click Copy page">
    Plain MDX source, no decoration. Same content as the `.md` URL returns.
  </Step>
  <Step title="Click Copy as Markdown for LLMs">
    Same source prefixed with a component-reference header so the LLM knows the NookDocs component library without fine-tuning.
  </Step>
  <Step title="Click Open in ChatGPT / Claude / Perplexity">
    Deep-links the provider with the page content pre-loaded as context.
  </Step>
</Steps>

The "Markdown for LLMs" variant wraps the source with an auto-generated component spec (see [copy for LLMs](/features/copy-for-llms) for the exact header format).

## Limitations

- **No `Accept: text/markdown` content negotiation yet.** Mintlify lets you send an `Accept: text/markdown` header to the HTML URL and get Markdown back; NookDocs only exposes the `.md` suffix for now. The `.md` URL always works.
- **No HTTP `Link` / `X-Llms-Txt` discovery headers yet.** Clients that auto-discover Markdown variants from response headers won't find them. Direct URL access works.
- **No `Cmd+C` → full-page-as-Markdown keyboard shortcut.** The Copy button is the only UI affordance right now; keyboard shortcut is on the roadmap.
- **Binary assets excluded.** Images and PDFs return a 404 at `.md`. Only MDX source pages respond.

## Related

- [llms.txt](/optimize/llms-txt) — sitemap-style index of every page's `.md` URL
- [Contextual menu](/configuration/contextual) — Copy-page dropdown + custom items (ChatGPT / Claude / Cursor deep-links)
- [Copy for LLMs](/features/copy-for-llms) — the UI variant with component-spec header
- [SEO](/optimize/seo) — sitemap.xml + robots.txt + canonical URLs

---

# SEO
Source: https://docs.nookdocs.com/optimize/seo

Auto-generated sitemap.xml + robots.txt + canonical URLs, plus per-page frontmatter controls for indexing, Open Graph, and Twitter cards. Zero plugins, zero build config.

NookDocs emits the entire on-page SEO surface by default: sitemap, robots, canonical URLs, Open Graph tags, Twitter cards, `<link rel="icon">`. You control crawler behaviour from `nookdocs.config.json#seo` globally, and from each page's frontmatter individually.

## What's auto-generated

Every tenant exposes these on the docs origin with zero configuration:

| URL | What it is |
|---|---|
| `/sitemap.xml` | XML sitemap with every non-hidden page, `lastmod` from last git commit |
| `/robots.txt` | `User-agent: *` rules honouring `seo.indexing`; references the sitemap |
| `/llms.txt` | LLM-crawler index (see [llms.txt](/optimize/llms-txt)) |
| `/favicon.ico` etc. | Served from `seo.favicon` or your brand config |
| Per-page `<link rel="canonical">` | Always the absolute tenant URL |
| Per-page Open Graph + Twitter tags | From page frontmatter with fallback to `seo.*` defaults |

Try it on this site: [`/sitemap.xml`](/sitemap.xml), [`/robots.txt`](/robots.txt), [`/llms.txt`](/llms.txt).

## Global `seo` configuration

<ParamField path="seo.title" type="string">
  Default site title. Page frontmatter `title` wins when present. Final format: `{page title} | {seo.title}`.
</ParamField>

<ParamField path="seo.description" type="string">
  Default meta description used when a page has no frontmatter `description`.
</ParamField>

<ParamField path="seo.keywords" type="string[]">
  Default meta keywords for the site. Per-page frontmatter `keywords` (an array) overrides. Emitted as `<meta name="keywords">`.
</ParamField>

<ParamField path="seo.author" type="string">
  Default content author. Emitted as `<meta name="author">` and the article author. Per-page frontmatter `author` overrides.
</ParamField>

<ParamField path="seo.ogImage" type="string">
  Default Open Graph image (1200×630 PNG recommended). Applied to `og:image` and `twitter:image`. Per-page `og.image` frontmatter wins.
</ParamField>

<ParamField path="seo.indexing" type="'default' | 'noindex'" default="default">
  `noindex` emits a `robots: noindex, nofollow` meta tag on every page + writes `Disallow: /` into `/robots.txt`. Use for staging sites and private docs.
</ParamField>

<ParamField path="seo.metatags" type="Record<string, string>">
  Free-form meta-tag map. Each key/value becomes `<meta name="KEY" content="VALUE">`. Common keys: `twitter:site`, `theme-color`, `color-scheme`, `robots`.
</ParamField>

<ParamField path="seo.favicon" type="string">
  Favicon path (SVG preferred). Renders as `<link rel="icon">` globally. Falls back to brand config favicon if unset.
</ParamField>

```json
{
  "seo": {
    "title": "Acme Documentation",
    "description": "Build, deploy, and scale with Acme.",
    "keywords": ["acme api", "acme sdk", "acme docs"],
    "author": "Acme, Inc.",
    "ogImage": "/og-default.png",
    "indexing": "default",
    "favicon": "/favicon.svg",
    "metatags": {
      "twitter:site": "@acme",
      "theme-color": "#0ea5e9"
    }
  }
}
```

## Per-page frontmatter controls

Every page's MDX frontmatter can override site-wide defaults or add richer metadata:

```mdx
---
title: Getting started with Acme
description: Create your first Acme workspace in under 2 minutes.
keywords: [acme, workspace, getting started]
hidden: false
sitemap: true
og:
  image: /images/getting-started-og.png
  title: Ship docs in 2 minutes
---
```

- `title` + `description` populate `<title>`, `<meta name="description">`, `og:title`, `og:description`, `twitter:title`, `twitter:description`.
- `keywords` adds `<meta name="keywords">` (low SEO impact but still honoured).
- `hidden: true` drops the page from sitemap, llms.txt, and search indexing. Page still renders at its URL — hiding it from discovery is intentional for gated flows.
- `sitemap: false` excludes the page from the sitemap while still rendering it.
- `og.image` / `og.title` — per-page Open Graph overrides for social link previews.

See [frontmatter reference](/content/frontmatter) for the full field list.

## Canonical URLs

Every page ships a `<link rel="canonical">` pointing at the absolute tenant URL. Custom domains (`docs.acme.com`) are preferred over the default subdomain (`acme.nookdocs.site`) when a primary domain is set. This prevents duplicate-content penalties when a tenant has multiple verified domains.

To override the canonical target per-page, use `seo.metatags.canonical` in your config or a page-level override (planned). For now the default is correct for 99% of cases.

## noindex strategy

Three levers, with increasing scope:

1. **Per-page** — frontmatter `hidden: true` drops the page from sitemap + llms.txt + search. Page still renders for anyone with the URL.
2. **Site-wide (staging)** — `seo.indexing: "noindex"` emits `<meta name="robots" content="noindex, nofollow">` site-wide and `Disallow: /` in `robots.txt`. Google and Bing respect within 24-48 hours.
3. **Protocol-level** — block crawlers entirely via reverse proxy / WAF. Only for truly private docs.

## Open Graph checklist

A sharable docs page needs:

- Page-specific `og:title` and `og:description` (frontmatter `title` + `description` give you both)
- 1200×630 PNG at `og:image` (per-page `og.image` or `seo.ogImage` default)
- `twitter:card: summary_large_image` — set via `seo.metatags` or defaults
- Canonical URL (automatic)

Test with Slack, Discord, Twitter, LinkedIn after your first deploy — each one caches for ~7 days so set it right before sharing widely.

## Limitations

- **No per-page canonical override in frontmatter yet.** Planned. For now, `seo.metatags.canonical` sets it site-wide (rarely what you want).
- **No structured-data / JSON-LD emission.** `BreadcrumbList`, `TechArticle`, and `FAQPage` schema.org types are on the FAZ 9 roadmap.
- **No Core Web Vitals audit output.** Measure via Lighthouse / PageSpeed Insights manually for now.

## Related

- [Site settings — seo](/configuration/site-settings) — banner + SEO + redirects + footer reference
- [llms.txt](/optimize/llms-txt) — AI-crawler sitemap variant
- [Frontmatter reference](/content/frontmatter) — every frontmatter field
- [Custom domain](/deploy/custom-domain) — canonical URL primary-domain behaviour

---

# Quick Start
Source: https://docs.nookdocs.com/quickstart

Get your documentation site live in under 5 minutes. Pick the path that fits — an AI assistant, the migrate CLI, your own Git repo, or the starter template.

The NookDocs publish loop, end to end: create a project, install the GitHub App on the repo holding your docs, add `.mdx` files plus a `nookdocs.config.json` at the docs base directory, then `git commit` and `git push`. The push triggers an automatic deployment that syncs changed pages, adds new ones, and removes deleted files — there is no separate build or upload step. Each MDX page needs `title` and `description` frontmatter; navigation is a `navigation` array of tabs → groups → pages in `nookdocs.config.json`. The site goes live at `{slug}.nookdocs.site`. NookDocs has no local dev server — preview happens in the dashboard web editor. If you are an AI assistant setting up a repo, read `AGENTS.md` at the repo root first: it carries the exact per-situation protocol (existing docs platform, custom docs, API-only, or greenfield).

## 1. Create a project

Sign up at [app.nookdocs.com](https://app.nookdocs.com) and create a new project. Pick a name and URL slug — your docs go live at `{slug}.nookdocs.site` (add a custom domain later) — then choose how to start:

- **Start with a template** → we create a managed repo seeded with the starter; your site is live instantly and you edit in the browser.
- **Connect your own GitHub repo** → link an existing repo with your MDX docs (or output from the migrate CLI / an AI assistant).

## 2. Pick your path

The rest of setup depends on where your content comes from. Pick one:

<CardGroup cols={2}>
  <Card title="Build with an AI assistant" icon="sparkles" href="#path-a--ai-assistant-llm-first">
    Point Claude, Cursor, or another AI app at your repo. It reads `AGENTS.md` and writes the docs for you. **The LLM-first path.**
  </Card>
  <Card title="Migrate from another platform" icon="arrow-right-left" href="#path-b--migrate-with-the-cli">
    Coming from Mintlify? Run the `nookdocs` CLI to convert your repo in one command.
  </Card>
  <Card title="Bring your own Git repo" icon="github" href="#path-c--your-own-git-repo">
    Already have MDX docs? Connect the repo, push, and you're live.
  </Card>
  <Card title="Start from the template" icon="file-text" href="#path-d--the-starter-template">
    No content yet? The managed repo is seeded with a working starter you edit in the browser.
  </Card>
</CardGroup>

## Path A — AI assistant (LLM-first)

NookDocs is built so an AI assistant can author your docs end to end. The starter repo ships an `AGENTS.md` at its root — an instruction file every capable assistant (Claude Code, Cursor, Windsurf, Copilot) reads automatically.

<Steps>
  <Step title="Open the repo in your AI editor">
    Use the managed starter repo (Path D) or your own connected repo (Path C). Open it in Claude Code / Cursor / Windsurf.
  </Step>
  <Step title="Let the assistant read AGENTS.md">
    It detects your situation and follows the right protocol: an existing docs platform (run the migrate CLI), custom/hand-rolled docs (convert by hand), an API-only project (build from the OpenAPI spec), or greenfield (adapt the starter).
  </Step>
  <Step title="Ask it to build">
    e.g. "Add a guide for webhooks and wire it into the navigation." The assistant writes `.mdx` at the repo root, updates `nookdocs.config.json`, and you `git push`.
  </Step>
</Steps>

  If you are the assistant: read `AGENTS.md` at the repo root before writing anything. Content lives flat at the repo root (`contentRoot: "/"`); every page needs `title` + `description` frontmatter and an entry in the `navigation` array, or its URL is live but hidden from the sidebar. Rewrite components to the NookDocs set (see [components](/components/callout)); most Mintlify tags keep the same name, only `<Latex>`→`<Math>` and `<Tree>`→`<FileTree>` are renamed. If the source is a competitor (Mintlify `docs.json`, Docusaurus `docusaurus.config.js`), detect it first and convert its structure into ours — you can read a competitor's own `/llms.txt` to learn its page tree, then map it onto our schema.

See the per-tool guides: [Claude Code](/guides/claude-code), [Cursor](/guides/cursor), [Windsurf](/guides/windsurf).

## Path B — migrate with the CLI

Moving an existing docs site? The `nookdocs` CLI converts it to NookDocs format in one command. Mintlify is fully supported today.

```bash
npx nookdocs migrate ./my-mintlify-docs -o ./nookdocs-output
```

It writes the flat NookDocs layout (`contentRoot: "/"`, `api-reference/openapi.json`, `global.anchors` preserved) and prints a report of what to review. Then commit the output to a repo and connect it (Path C).

See [Migrating from Mintlify](/cli/migrate-from-mintlify) for the full walkthrough, and [Migration playbooks](/guides/migration-playbooks) for the strategy around a cutover (redirects, SEO, timing).

## Path C — your own Git repo

Already have MDX docs, or output from Path A/B? Connect the repo and push.

<Steps>
  <Step title="Connect GitHub">
    On your project page, click **Install GitHub App** and select the repository holding your docs.
  </Step>
  <Step title="Lay out your content">
    MDX files sit flat at the docs base directory (the repo root), alongside `nookdocs.config.json`:

    ```
    my-repo/
    ├── nookdocs.config.json
    ├── index.mdx
    ├── quickstart.mdx
    └── api-reference/
        └── introduction.mdx
    ```

    Each page needs frontmatter:

    ```mdx
    ---
    title: My Page Title
    description: A brief description of this page.
    ---

    Your content here...
    ```
  </Step>
  <Step title="Configure navigation">
    `nookdocs.config.json` declares the sidebar as tabs → groups → pages:

    ```json
    {
      "$schema": "https://nookdocs.com/schema.json",
      "name": "My Docs",
      "contentRoot": "/",
      "navigation": [
        {
          "tab": "Documentation",
          "groups": [
            {
              "group": "Getting Started",
              "pages": ["index", "quickstart"]
            }
          ]
        }
      ]
    }
    ```
  </Step>
  <Step title="Push and deploy">
    ```bash
    git add .
    git commit -m "docs: add initial documentation"
    git push
    ```

    Every push triggers an automatic deploy — no separate build or upload step. Your docs are live at `{slug}.nookdocs.site`.
  </Step>
</Steps>

## Path D — the starter template

Picked **"Start with a template"** in the wizard? We create a private managed repo already seeded with a working starter — your site is live instantly. Edit pages in the dashboard **web editor** (live preview, no local setup), or open the repo in an AI assistant (Path A). There is no local dev server; preview is the editor.

## Next steps

<CardGroup cols={2}>
  <Card title="Write for LLMs" icon="sparkles" href="/guides/writing-for-llms">
    The habits that make your docs rank in AI answers — the core NookDocs advantage.
  </Card>
  <Card title="Components" icon="component" href="/components/callout">
    Callouts, cards, tabs, steps, API blocks — everything you can use in MDX.
  </Card>
  <Card title="Configuration" icon="settings" href="/configuration/config-file">
    Themes, navigation, branding, and every `nookdocs.config.json` field.
  </Card>
  <Card title="CLI" icon="terminal" href="/cli">
    Migrate from another platform, and the two ways to do it (CLI vs AI).
  </Card>
</CardGroup>

---

# Security overview
Source: https://docs.nookdocs.com/security

How NookDocs protects customer data, the controls we run, and what's available for vendor reviews.

NookDocs runs as a multi-tenant SaaS hosted on Vercel + Supabase + Cloudflare. This page summarises the security posture, the controls in place today, and the documents we share with enterprise procurement teams.

## Architecture overview

| Component | Provider | Region | Purpose |
|---|---|---|---|
| Application runtime | Vercel (Edge + Node) | Global | Next.js docs renderer + API |
| Database | Supabase (Postgres) | us-east-1 | Tenant data + auth + RLS |
| Custom domain edge | Cloudflare for SaaS | Global | TLS termination + SSL provisioning |
| Object storage | Supabase Storage | us-east-1 | Logos, images, generated assets |
| LLM gateway | Third-party LLM API gateway | Global | AI assistant + writing agent |

## Encryption

| Surface | Standard |
|---|---|
| In transit | TLS 1.2+, HTTP/2, HSTS preload |
| At rest (DB) | AES-256 (Supabase managed) |
| At rest (object storage) | AES-256 (Supabase managed) |
| API key storage | SHA-256 hashed (Settings → API Keys never re-displays the secret) |
| Access cookie | HMAC-SHA256 signed, password-hash-derived key (rotates on password change) |

## Access controls

- **Auth:** Supabase Auth (JWT-based session cookies, email + OAuth)
- **Authorization:** Postgres Row Level Security (RLS) on every tenant table
- **API auth:** Dual-mode — Supabase JWT or hashed API key
- **SSO:** SAML 2.0 + OIDC (Team+, see [SSO docs](/configuration/sso))
- **SCIM:** Read-only sync today, full lifecycle in next release ([SCIM docs](/configuration/scim))

## Compliance

| Standard | Status |
|---|---|
| GDPR | ✅ DPA template available — see [DPA](/security/dpa) |
| SOC 2 Type I | In progress (target Q1 2027) |
| SOC 2 Type II | Planned Q3 2027 |
| HIPAA | BAA available on Enterprise plan with PHI use case |
| PCI DSS | Not applicable — no payment data stored on our side (Stripe handles all of it) |

## Vendor questionnaire

Enterprise customers needing a vendor security review can use our pre-filled vendor questionnaire — see [Vendor questionnaire](/security/vendor-questionnaire).

## Reporting a vulnerability

Email `security@codivion.com` (PGP key available on request). We acknowledge within 48 hours and ship a fix within the timeline appropriate to the severity (Critical: 24h, High: 7d, Medium: 30d, Low: next release).

## Data residency

Today: us-east-1 only.

EU-region (eu-central-1) data residency is on the Enterprise roadmap. Contact sales if it's a hard requirement — early-access path is available.

## Backups + DR

- **Daily snapshots** of the Postgres database, retained 30 days
- **Point-in-time recovery** within the last 7 days
- RTO target: 4 hours
- RPO target: 1 hour

## What we never do

- Sell customer data to third parties
- Use customer docs content to train external models
- Share data across tenants without explicit consent (showcase opt-in)
- Read customer docs content in the course of normal support (we have RLS-immune service-role access only for incident response, audited)

---

# Report abuse
Source: https://docs.nookdocs.com/security/abuse

How to report phishing, malware, spam, or other abuse of a NookDocs-hosted documentation site.

The canonical abuse contact lives on the main site:
**[nookdocs.com/abuse](https://nookdocs.com/abuse)**.

If a NookDocs-hosted site is being used for **phishing, malware, spam, or any
other abuse**, email **abuse@codivion.com** with the full URL of the offending
page and a short description. We review every report and respond within five
business days; action is scoped to the offending site, so other customers'
documentation is unaffected.

<Note>
  This is the contact for abuse of content **hosted on** NookDocs. For a
  security vulnerability in the platform itself, see the
  [Security overview](/security) and email `security@codivion.com`.
</Note>

---

# Data Processing Agreement (DPA)
Source: https://docs.nookdocs.com/security/dpa

GDPR-compliant DPA template. Pre-signed by Codivion, ready for your legal team's review.

For customers processing personal data of EU/UK/Switzerland residents, NookDocs offers a Data Processing Agreement (DPA) that complies with GDPR Article 28 + UK GDPR + Swiss FADP.

## How to get the DPA

1. Email `accounts@codivion.com` from the address on file with your NookDocs org
2. Subject: `DPA request for <Your Company>`
3. We send back a pre-signed PDF DPA + Standard Contractual Clauses (SCCs) for international transfers
4. Your legal team reviews → countersign and return one copy
5. Effective date = the date both parties sign

Turnaround: 48-72 hours for the pre-signed copy.

## What the DPA covers

- Roles: NookDocs is the **data processor**; you are the **data controller**
- Subject matter: docs content, account metadata, usage telemetry, member identifiers
- Duration: term of your NookDocs subscription + 30 days post-termination
- Sub-processors: enumerated list (see below)
- Security: TLS 1.2+, AES-256 at rest, RLS-enforced isolation
- International transfers: SCCs (EU-approved 2021 set) + UK addendum + Swiss addendum
- Breach notification: within 72 hours of discovery
- Data subject rights: assistance with access / rectification / erasure / portability requests
- Audit rights: customer audit on reasonable notice (max 1/year)
- Sub-processor changes: 14-day notice + customer right to object

## Current sub-processors

| Sub-processor | Purpose | Region |
|---|---|---|
| Vercel Inc. | Application hosting + edge runtime | Global (request routing) |
| Supabase Inc. | Database + auth + object storage | us-east-1 |
| Cloudflare Inc. | TLS edge + SSL provisioning for custom domains | Global |
| Third-party LLM API gateway | AI assistant + writing-agent inference (plan-included AI) | Global |
| Stripe Inc. | Payment processing | us, eu (per customer location) |
| GitHub Inc. | Source repo storage (when using managed-repo flow) | us |

Adding a new sub-processor triggers a 14-day notice + the customer right to object. We never silently add sub-processors.

## What's outside the DPA

- Free-tier orgs use the same security controls but the DPA is a paid-tier deliverable. Free orgs operate under the standard Terms of Service.
- Marketing communications (newsletter, blog) are governed by our [Privacy Policy](https://nookdocs.com/privacy), not the DPA.

---

# Vendor security questionnaire
Source: https://docs.nookdocs.com/security/vendor-questionnaire

Pre-filled answers to the questions your security team will ask. Speeds up enterprise procurement.

Enterprise procurement always sends a vendor security questionnaire. Use the answers below as a starting point — we keep them current and accept supplementary questions in writing.

## Organisation

| Question | Answer |
|---|---|
| Legal entity | Codivion, LLC |
| Registered jurisdiction | United States (state on request) |
| Year founded | 2025 |
| Employee count | `<10` (early-stage) |
| Primary contact for security | `security@codivion.com` |
| Cyber liability insurance | In progress (target Q2 2027) |

## Architecture + hosting

| Question | Answer |
|---|---|
| Hosting provider | Vercel (compute), Supabase (data), Cloudflare (edge) |
| Primary region | us-east-1 |
| Multi-region replication | DB read replicas: roadmap. Active-active: not yet. |
| Tenant isolation | Postgres RLS on every tenant table |
| Network segmentation | Vercel-managed + Supabase VPC |
| Logical separation of customer data | Enforced at database level via Row Level Security policies |

## Authentication + access

| Question | Answer |
|---|---|
| End-user auth | Email/password, OAuth (Google, GitHub), SAML 2.0 SSO (Team+), OIDC (Team+) |
| Session storage | HttpOnly Secure SameSite=Lax cookies |
| Session TTL | 30 days, refreshable |
| Internal admin auth | Platform admin allowlist in DB (RLS-enforced) |
| MFA support | Via SSO IdP |
| Password policy | NIST 800-63B aligned (length-first, no forced rotation) |
| Password storage | PBKDF2-SHA256 with per-user salt + 100k iterations |
| API key storage | SHA-256 hashed; never re-displayable after creation |

## Encryption

| Question | Answer |
|---|---|
| In transit | TLS 1.2+, HTTP/2, HSTS preload |
| At rest (DB) | AES-256 (Supabase-managed) |
| At rest (object storage) | AES-256 (Supabase-managed) |
| Key management | Supabase-managed; BYOK on Enterprise roadmap |
| Customer data segregation key | Per-tenant cookie HMAC keyed by per-org password hash |

## Compliance

| Question | Answer |
|---|---|
| SOC 2 Type I | In progress (target Q1 2027) |
| SOC 2 Type II | Planned Q3 2027 |
| ISO 27001 | Not pursued |
| HIPAA | BAA available on Enterprise with PHI use case |
| GDPR | DPA available — see [DPA docs](/security/dpa) |
| CCPA | Compliant (no sale of personal data) |
| PCI DSS | Out of scope — Stripe handles all payment data |

## Operational security

| Question | Answer |
|---|---|
| Incident response plan | Documented; CSM-led on Enterprise tier |
| Vulnerability disclosure | `security@codivion.com`, 48h ack, severity-based SLA |
| Penetration testing | Scheduled annually (next: 2026 Q4) |
| Security training for staff | Mandatory annual review |
| Background checks | Standard for all employees with prod access |
| Source code review | All commits reviewed via GitHub PR before merge |

## Backups + recovery

| Question | Answer |
|---|---|
| Backup frequency | Daily snapshots, 30-day retention |
| Point-in-time recovery | 7 days |
| RTO | 4 hours |
| RPO | 1 hour |
| Backup encryption | AES-256 (Supabase-managed) |
| Backup access controls | Service-role only, audited |
| Disaster recovery test cadence | Annually |

## Sub-processors

See [DPA — current sub-processors](/security/dpa#current-sub-processors). 14-day notice on new sub-processor additions; customer right to object.

## Data subject rights

| Question | Answer |
|---|---|
| Access requests | Self-serve via dashboard + API export |
| Deletion requests | Self-serve project delete + admin-assisted full org delete on request |
| Data portability | Full DB export available on request (JSON dump) |
| Response SLA | 30 days max (GDPR-aligned) |

## Logging + monitoring

| Question | Answer |
|---|---|
| Audit log retention | Team: 90d, Enterprise: unlimited (with export) |
| Security event log | Vercel + Supabase platform logs, 30 days |
| Alerting | Sentry (errors) + uptime monitoring + PagerDuty oncall |
| Customer-facing audit log | Yes — see [Audit log docs](/configuration/audit-log) |

## Need something not on this list?

Email `security@codivion.com` with the specific question. We aim to respond within 5 business days.

---

# Components
Source: https://docs.nookdocs.com/showcase

Every component reads the same theme tokens. Nothing here is styled by hand.

<Columns cols={3}>
  <div>
    <Steps>
      <Step title="Install">
        Add the package.
      </Step>
      <Step title="Configure">
        Point at your content root.
      </Step>
    </Steps>
  </div>
  <div>
    <CodeGroup>
    ```bash npm
    npm install @yourorg/sdk
    ```

    ```bash pnpm
    pnpm add @yourorg/sdk
    ```
    </CodeGroup>
  </div>
  <div>
    <FileTree>
      <Folder name="docs" defaultOpen>
        <File name="index.mdx" />
        <File name="guides.mdx" />
      </Folder>
      <File name="docs.config.json" />
    </FileTree>
  </div>
</Columns>

<Columns cols={3}>
  <div>
    <Tip>Press <Kbd>⌘K</Kbd> to search.</Tip>
    <Warning>This cannot be undone.</Warning>
  </div>
  <div>
    <Note>Config changes apply on save.</Note>
    <Danger>Destructive action.</Danger>
  </div>
  <div>
    <p><Check /> Verified domain</p>
    <p><Uncheck /> SSL pending</p>
  </div>
</Columns>

<Columns cols={3}>
  <div>
    <ParamField name="slug" type="string" required path="path">
      Lowercase letters, numbers, hyphens.
    </ParamField>
  </div>
  <div>
    <ResponseField name="id" type="uuid">
      Unique project identifier.
    </ResponseField>
  </div>
  <div>
    <Accordion title="Does it collapse?">
      It does — content stays in the DOM.
    </Accordion>
  </div>
</Columns>

<Columns cols={3}>
  <div>
    <ColorPalette>
      <ColorSwatch name="Primary" hex="#F59E0B" description="CTAs" />
      <ColorSwatch name="Success" hex="#10B981" description="Positive" />
    </ColorPalette>
  </div>
  <div>
    <TerminalBlock title="bash">
    {`$ git push
✓ Synced 14 pages`}
    </TerminalBlock>
  </div>
  <div>
    <LinkCard
      title="API Reference"
      description="Generated from your spec"
      href="/api-reference"
      icon="code"
    />
  </div>
</Columns>

<Columns cols={3}>
  <div>
    <Badge variant="success">GA</Badge>&nbsp;
    <Badge variant="warning">Beta</Badge>&nbsp;
    <Badge variant="danger">Deprecated</Badge>
  </div>
  <div>
    <Tag>API</Tag>&nbsp;<Tag>Guide</Tag>&nbsp;<Pill>v2</Pill>
  </div>
  <div>
    <Icon name="rocket" />&nbsp;<Icon name="layers" />&nbsp;<Icon name="code" />&nbsp;<Kbd>Esc</Kbd>
  </div>
</Columns>

<Tiles cols={3}>
  <Tile title="Callout" description="Six variants" href="/components/callout" icon="message-square" />
  <Tile title="FileTree" description="Nested, collapsible" href="/components/file-tree" icon="folder" />
  <Tile title="ParamField" description="API reference fields" href="/components/param-field" icon="code" />
</Tiles>