Writing docs with Cursor

Cursor 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

The .cursor/rules/nookdocs.mdc template

Cursor rules files use a YAML frontmatter + Markdown body. This file targets every .mdx file in the repo:

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

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:

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:

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

.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 — CLI agent sibling guide

• Windsurf — alternative editor-based agent

• Writing for LLMs — broader authoring theory

• Component spec — the URL you share with the agent

• Style and tone — the authoring rubric Cursor enforces