Cursor

---
description: Rules for writing Jamdesk documentation in MDX
globs: "**/*.mdx"
---

# Jamdesk MDX Rules

## Page Structure

Every page follows this pattern — no exceptions:

1. Frontmatter with `title` and `description`
2. Opening paragraph (no heading before it)
3. Content sections with ## headings
4. "What's Next?" section at the end with Card links inside Columns

## Components

Only use these — do not invent others:

Layout: Card, Columns, Tabs, Tab, Accordion, AccordionGroup, Steps, Step, Expandable, Frame, CodeGroup
Callouts: Note, Info, Warning, Tip, Check, Danger

| Use | For |
|-----|-----|
| Tabs | Mutually exclusive choices (npm/yarn, OS variants) |
| Steps | Ordered procedures the reader follows |
| Accordion | Optional detail that would clutter the page |
| Card + Columns | Navigation links and feature grids |
| Note/Tip/Warning | Important context — use sparingly |

Cards always go inside Columns: `<Columns cols={2}><Card ... /></Columns>`
Icons are Font Awesome Light names: "rocket", "code", "terminal", "book-open"

## Style

- Active voice: "Run this command" not "This command should be run"
- Start with why, then how
- One idea per paragraph
- Code examples must be complete and copy-pasteable
- Write like a person — no filler ("It's important to note"), no hedging ("you might want to consider"). If it sounds like a chatbot, rewrite it shorter.

## Common Mistakes

- `<CodeBlock>`, `<Alert>`, `<Section>` don't exist — use the components listed above
- `<Card>` without `<Columns>` wrapper won't render correctly
- Missing `description` in frontmatter breaks search and link previews
- Raw HTML tags should be MDX components instead

## New Pages

When creating a page, add it to `docs.json` navigation. Without this, the page won't appear in the sidebar. Read `docs.json` first to understand the group structure.

{
  "mcpServers": {
    "my-docs": {
      "url": "https://your-project.jamdesk.app/_mcp"
    }
  }
}