Component spec for LLMs

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

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:

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 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) 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:

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.