Claude Code
Set up Claude Code to write and maintain Jamdesk documentation. Includes CLAUDE.md template and MCP server connection.
Claude Code is Anthropic's CLI for Claude. Because it reads your full project directory, it picks up your existing writing style and your docs.json layout from the files themselves, then writes pages that fit alongside what you already have.
We maintain Jamdesk's own documentation in this exact setup. The CLAUDE.md template below is close to the one we use ourselves. Customize it for your project, but the page-structure rules, the "What's Next?" cards convention, and the strict component list are conventions we'd recommend keeping.
Compared to Codex, Claude Code's strength is interactive iteration. You can draft a page, read the result, push back on a section, and have it rewrite the section in the same session, with full project context the whole time. Codex is the better choice for hands-off multi-file batch jobs; this page covers the workflow for everything else.
Quick Setup
Install from claude.ai/code.
Add your documentation as an MCP data source:
claude mcp add --transport http my-docs https://your-project.jamdesk.app/_mcpReplace your-project with your Jamdesk subdomain. Claude can now search and read your published docs directly. See MCP Server for details.
Create a CLAUDE.md in your docs project root. This gives Claude consistent context about your documentation standards, available components, and writing style.
CLAUDE.md Template
Add this file to the root of your Jamdesk docs project:
# 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 before it. "What's Next?" is always the last section. Card descriptions explain why, not what ("Set up search for your docs", not "Search configuration page").
## Writing Style
Start with why. What problem does this page solve? Show that first, then walk through how to use the feature.
Use progressive disclosure: a simple example near the 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 reach for "also" or "additionally", start a new paragraph instead.
Code examples must actually work. Never show partial code or pseudocode. Every block should be complete and copy-pasteable.
Write like a person. Skip filler like "It's important to note that", "This allows you to", or "seamlessly". Drop the hedging ("you might want to consider"). Read your output back, and if it sounds like a chatbot wrote it, rewrite it shorter and more direct.
## Components
Layout: Card, Columns, Tabs, Tab, Accordion, AccordionGroup, Steps, Step, Expandable, Frame, CodeGroup
Callouts: Note, Info, Warning, Tip, Check, Danger
When to use each:
| Component | Use for | Don't use for |
|-----------|---------|---------------|
| Tabs | Mutually exclusive choices (npm/yarn, languages) | Sequential content |
| Steps | Ordered procedures | Unordered lists of features |
| Accordion | Optional/advanced detail | Core content readers need |
| Card (in Columns) | Navigation links, feature grids | Inline content |
| Note/Tip/Warning | Important context the reader might miss | 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.
## Before You're Done
Check your work:
- [ ] Frontmatter has both `title` and `description`
- [ ] Opening paragraph exists (no heading before it)
- [ ] Page ends with "What's Next?" cards
- [ ] New pages are added to `docs.json` navigation
- [ ] Code examples are complete and copy-pasteable
- [ ] No invented components; only the ones listed above
- [ ] No raw HTML tags; use MDX components
- [ ] Images use `.webp` format
## Common Mistakes
- Inventing components like `<CodeBlock>`, `<Alert>`, or `<Section>`. They don't exist. Use the components listed above.
- Wrapping code in components. Code blocks are standard Markdown triple backticks. Don't wrap them in `<CodeGroup>` unless you're showing multiple language alternatives.
- Skipping description frontmatter. Every page needs it; it appears in search results and link previews.
- Using `<Card>` without `<Columns>`. Cards must be inside a `<Columns>` wrapper.
- Writing "click here" links. Use descriptive link text: [Migration guide](/setup/migration), not [click here](/setup/migration).Customize the template for your project. Add your product name, API conventions, terminology, and any content guidelines unique to your docs.
Sample Prompts
Once your CLAUDE.md and MCP connection are wired up, you don't need to over-explain things. Claude already has the project context, so short prompts work better than long ones.
A common starting point: "Write a getting started guide for [feature]". Because Claude has already read your other pages, it picks up your tone without being told. For drift detection, ask it to review a single page against the rest of the site. Claude tends to catch the small inconsistencies (a component used differently here than there, a tone shift between sections) that authors miss in self-review.
The prompts that surprise people the most are the cleanup ones. "Convert this README into documentation pages" turns a single file into a properly structured set with navigation. Pointing it at an existing page and asking for an Accordion-based FAQ pulls in real issues from your repo — far closer to actual reader questions than anything you'd write from a blank doc.
The /update-jamdesk Skill
For automated documentation updates when code changes, install the /update-jamdesk skill:
npx skills add jamdesk/skills --skill update-jamdeskAfter implementing a user-facing feature, run /update-jamdesk and Claude will figure out which doc pages need creating or editing. See Automated Updates for the full guide.