Jamdesk Documentation logo

Claude Code

Configure o Claude Code para escrever e manter a documentação Jamdesk. Inclui modelo de CLAUDE.md e conexão com o servidor MCP.

Claude Code é a CLI da Anthropic para o Claude. Ele lê o diretório completo do seu projeto e aprende o estilo de escrita e a estrutura do docs.json a partir dos arquivos. As páginas que ele escreve se encaixam junto às suas existentes.

Mantemos a documentação da Jamdesk com esta configuração. O modelo de CLAUDE.md abaixo é próximo do que usamos. Personalize-o para o seu projeto. Recomendamos manter as regras de estrutura de página, a convenção de cards "O que vem a seguir?" e a lista estrita de componentes.

O Claude Code é melhor que o Codex para iteração interativa. Você rascunha uma página, lê o resultado, questiona uma seção e pede ao Claude para reescrevê-la na mesma sessão. Ele mantém o contexto completo do projeto o tempo todo. O Codex é a melhor escolha para tarefas em lote com vários arquivos, sem acompanhamento.

Configuração rápida

1
Instale o Claude Code

Instale a partir de claude.ai/code.

2
Conecte sua documentação via MCP

Adicione sua documentação como fonte de dados MCP:

claude mcp add --transport http my-docs https://your-project.jamdesk.app/_mcp

Substitua your-project pelo seu subdomínio Jamdesk. Se você tiver um domínio personalizado ativo, use-o em vez disso: https://docs.acme.com/_mcp. O Claude agora pode pesquisar e ler sua documentação publicada. Veja Servidor MCP para mais detalhes.

3
Adicione um arquivo CLAUDE.md

Crie um CLAUDE.md na raiz do seu projeto de documentação. Isso dá ao Claude um contexto consistente sobre seus padrões de documentação, componentes disponíveis e estilo de escrita.

Modelo de CLAUDE.md

Adicione este arquivo à raiz do seu projeto de documentação Jamdesk:

CLAUDE.md
# 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).

Adicione o nome do seu produto, convenções de API, terminologia e quaisquer diretrizes de conteúdo específicas da sua documentação.

Prompts de exemplo

Prompts curtos funcionam melhor que longos depois que o CLAUDE.md e a conexão MCP estão configurados. O Claude já tem o contexto do projeto.

Um ponto de partida comum: "Escreva um guia de primeiros passos para [recurso]". O Claude já leu suas outras páginas e capta seu tom sem que você precise dizer. Peça para revisar uma página em comparação com o restante do site para identificar desvios. O Claude tende a encontrar pequenas inconsistências (um componente usado de forma diferente aqui e ali, uma mudança de tom entre seções) que autores costumam deixar passar na autorrevisão.

Prompts de limpeza também funcionam bem. "Converta este README em páginas de documentação" transforma um arquivo em um conjunto estruturado de páginas com navegação. Aponte para uma página existente e peça um FAQ baseado em Accordion. Ele também puxa issues do seu repositório, que se aproximam mais das perguntas dos leitores do que qualquer coisa que você escreveria a partir de um documento em branco.

A skill /update-jamdesk

Instale a skill /update-jamdesk para atualizar a documentação automaticamente quando o código mudar:

npx skills add jamdesk/skills --skill update-jamdesk

Execute /update-jamdesk depois de implementar um recurso voltado ao usuário. O Claude encontra as páginas de documentação a criar ou editar. Veja Atualizações automatizadas para o guia completo.

Próximos passos

Plugin do Claude Code

Instale o plugin Jamdesk para referência de componentes, configuração e CLI

Cursor

Arquivo de regras do Cursor e atalhos de edição inline

Servidor MCP

Referência de endpoints, limites de taxa e exemplos com curl