Codex

# Jamdesk Documentation Project

Jamdesk docs project. Pages are MDX (Markdown + React components). Config is in `docs.json`.

## How This Project Works

- `docs.json`: navigation structure, theme, colors, branding. Pages must be listed here to appear in the sidebar.
- `*.mdx` files: documentation pages. Every page needs `title` and `description` frontmatter.
- `images/`: static assets. Always use `.webp` format.
- `snippets/`: reusable MDX fragments. Import with `<Snippet file="name.mdx" />`.

## Page Template

Every page follows this structure:

    ---
    title: Clear, Specific Title
    description: One sentence. Used in search results and social previews.
    ---

    Opening paragraph: what this page covers and who it's for. No heading needed.

    ## First Section

    Content. Use components where they help, not for decoration.

    ## What's Next?

    <Columns cols={2}>
      <Card title="Related Page" icon="arrow-right" href="/path">

        Why the reader would go here next

</Card>
</Columns>

The opening paragraph comes right after frontmatter with no heading. "What's Next?" is always the last section. Card descriptions explain why, not what.

## Writing Style

Start with why. What problem does this solve? Show the answer first, then unpack the how.

Use progressive disclosure: simple example up top, advanced options tucked into Accordions or later sections.

Active voice. "Run this command", not "This command should be run".

One idea per paragraph. If you find yourself reaching for "also" or "additionally", that's the cue to start a new paragraph instead.

Code examples have to actually work. Every block should be complete and copy-pasteable, never partial or pseudocode.

And write like a person. No filler ("It's important to note that", "This allows you to"). No hedging ("you might want to consider"). If a paragraph reads like a chatbot wrote it, rewrite it shorter.

## 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 | Don't use for |
|-----|-----|---------------|
| Tabs | Mutually exclusive choices (npm/yarn, OS) | Sequential content |
| Steps | Ordered procedures | Unordered lists |
| Accordion | Optional/advanced detail | Core content |
| Card + Columns | Navigation links, feature grids | Inline content |
| Note/Tip/Warning | Important context | Every other paragraph |

Cards always go inside Columns:

    <Columns cols={2}>
      <Card title="Page Title" icon="icon-name" href="/path">

        Brief description

</Card>
</Columns>

Icons are Font Awesome Light names: "rocket", "code", "terminal", "book-open", "gear"

## Adding Pages

1. Create the `.mdx` file
2. Add the page path (no `.mdx` extension) to `docs.json` in the right navigation group
3. Link to it from related pages via "What's Next?" cards

If you skip step 2, the page won't show up in the sidebar. Read `docs.json` before creating pages so you understand the navigation structure.

## Common Mistakes

- Inventing components like `<CodeBlock>`, `<Alert>`, `<Section>`. They don't exist.
- Using `<Card>` without a `<Columns>` wrapper.
- Skipping `description` in frontmatter, which breaks search results and link previews.
- Using raw HTML tags instead of MDX components.
- Writing "click here" links instead of descriptive link text.

[mcp_servers.my-docs]
url = "https://your-project.jamdesk.app/_mcp"