Jamdesk Documentation logo

Visão geral da CLI

Visualize a documentação localmente, valide a configuração, verifique links quebrados e migre de outras plataformas usando a CLI Jamdesk de código aberto.

A CLI Jamdesk permite visualizar sua documentação localmente, validar a configuração, verificar links quebrados e migrar de outras plataformas. Ela é de código aberto, sob a Licença Apache 2.0.

Instalação

Instale globalmente pelo npm para usar jamdesk de qualquer lugar:

npm install -g jamdesk

Verifique a instalação:

jamdesk --version

Requisitos

  • Node.js 22.18+ ou 24.11+ (Node.js 23 não é suportado)
  • npm v8 ou superior (recomendado)

Início rápido

1
Crie um projeto

Crie um novo projeto de documentação:

jamdesk init my-docs
cd my-docs
2
Inicie o servidor de desenvolvimento

Execute o servidor de desenvolvimento local com recarregamento automático:

jamdesk dev

Sua documentação roda em http://localhost:3000/docs

3
Valide antes de implantar

Verifique erros de configuração, links quebrados e ortografia:

jamdesk validate
jamdesk broken-links
jamdesk fix --dry-run
jamdesk fix
jamdesk spellcheck

Comandos

Execute jamdesk <command> --help para ver detalhes de qualquer comando.

Desenvolvimento

Inicie o servidor de desenvolvimento local com recarregamento automático.

jamdesk dev
jamdesk dev --port 3001

Recursos:

  • Validação automática na inicialização (schema do docs.json, sintaxe MDX e especificações OpenAPI referenciadas. Uma especificação inválida interrompe o servidor.)
  • Recarregamento automático ao alterar arquivos MDX
  • Reconstrução automática da navegação ao alterar docs.json
  • CSS personalizado (style.css) recarregado ao atualizar o navegador
  • Busca
  • Todos os temas e componentes

Opções:

FlagDescrição
-p, --port <port>Porta de execução (padrão: 3000)
-v, --verboseAtiva saída detalhada

Crie um novo projeto de documentação.

jamdesk init              # Interactive mode
jamdesk init my-docs      # Create in new directory

Isso cria um novo projeto com:

  • Arquivo de configuração docs.json
  • Páginas MDX de exemplo
  • Estrutura de pastas recomendada

Autenticação

Faça login no Jamdesk pelo navegador. Necessário antes de implantar.

jamdesk login

Abre o painel do Jamdesk no seu navegador. A CLI armazena as credenciais em ~/.jamdeskrc.

Guia de autenticação

Fluxo de autenticação pelo navegador, gerenciamento de sessão e solução de problemas

Remove as credenciais armazenadas.

jamdesk logout

Mostra o usuário conectado e verifica a sessão.

jamdesk whoami

Validação

Valide sua configuração docs.json, a sintaxe MDX e as especificações OpenAPI.

jamdesk validate
jamdesk validate --skip-mdx

Verifica:

  • Sintaxe JSON válida no docs.json
  • Campos obrigatórios (name, navigation)
  • Valores de tema válidos
  • Erros de sintaxe MDX (por exemplo, caracteres < não escapados)
  • Validação de especificação OpenAPI (se configurada)
  • Conformidade com o schema

Opções:

FlagDescrição
--skip-mdxIgnora a validação de sintaxe MDX
-v, --verboseMostra saída detalhada da validação

Execute isso antes de implantar para detectar erros cedo.

Verifique sua documentação em busca de links internos quebrados.

jamdesk broken-links

Exemplo de saída:

docs/getting-started.mdx:15 - /docs/quikstart
  Did you mean: /docs/quickstart

Found 1 broken link in 45 files.

Detecta links para páginas inexistentes e erros de digitação. Veja Links e navegação para mais detalhes.

Corrige automaticamente avisos de links internos quebrados que têm um destino inequívoco. Ele corrige dois tipos:

  • Âncoras com erro de digitação: um fragmento como #instalation que claramente deveria ser #installation
  • Desvio de âncora entre idiomas: uma página traduzida renomeou seus títulos, mas os links nesse idioma ainda apontam para o fragmento antigo em inglês
# Preview what would change without touching any files
jamdesk fix --dry-run

# Apply fixes (prompts for confirmation)
jamdesk fix

Exemplo de saída do dry-run:

Planned fixes:

  fr/ai/overview.mdx:9
    /fr/ai/selectors#ai-strategies  →  /fr/ai/selectors#stratégies-ia

(dry run — no files written)

jamdesk fix grava uma correção somente quando a âncora corrigida resolve para um título real na página de destino. Casos ambíguos são deixados para revisão manual.

Opções:

FlagDescrição
--dry-runVisualiza as correções planejadas sem gravar arquivos
-y, --yesAplica as correções sem pedir confirmação
--types <list>Tipos de aviso separados por vírgula a corrigir (padrão: todos os suportados)
--no-aiIgnora as correções por IA e usa apenas as correções que o Jamdesk consegue determinar sem IA
--project <id>ID do projeto para correções por IA (padrão: projectId em docs.json)
--jsonImprime o plano de correção e os problemas que não pode corrigir em JSON, para um agente de IA. Não grava arquivos nem pergunta nada. Requer CLI 1.1.229 ou superior
Guia de correção de links quebrados

Passo a passo: visualizar, aplicar, revisar e fazer commit

Mostra ou altera a configuração AI Fixes do projeto, a mesma das Configurações no painel.

# Show the current setting
jamdesk ai-fix

# Commit fixes to your build branch after each build
jamdesk ai-fix auto

# Suggest fixes for you to review in the dashboard
jamdesk ai-fix review

# Turn off dashboard scans
jamdesk ai-fix off

Exemplo de saída:

✓ AI Fixes set to Auto-fix
Jamdesk commits fixes to main after the next build. Pull before you push. Undo runs from the dashboard.

Execute jamdesk login antes. O comando usa o projectId em docs.json, ou o projeto que você passar com --project. Requer CLI 1.1.229 ou superior.

FlagDescrição
--project <id>ID do projeto (padrão: projectId em docs.json)
Corrigir com IA

O que cada modo faz e como desfazer uma correção automática

Verifique sua documentação em busca de erros ortográficos.

jamdesk spellcheck

Exemplo de saída:

getting-started.mdx:14 - "recieve"
  └─ Did you mean: receive

Found 3 misspellings across 24 pages.
Tip: Run "jamdesk spellcheck --fix" to interactively fix or ignore words.

Usa um dicionário de inglês com mais de 150 termos técnicos integrados (API, GraphQL, Kubernetes, React etc.). Ignora blocos de código, código inline, frontmatter, JSX, URLs e caminhos de arquivo. Por enquanto, apenas inglês. Dicionários em outros idiomas estão previstos.

Opções:

FlagDescrição
--fixCorrige erros ortográficos de forma interativa ou adiciona à lista de ignorados
--jsonSaída em JSON (para pipelines de CI)
-v, --verboseMostra cada arquivo enquanto é verificado

Modo de correção interativo (--fix) percorre cada palavra com erro ortográfico única:

1/10  "recieve" — found in 3 files
      intro.mdx:14, setup.mdx:7, guide.mdx:22

? What do you want to do?
❯ Fix → receive (recommended)
  Fix → relieve
  Ignore in the future (add to docs.json)
  Skip
  • Fix substitui a palavra por uma sugestão em todos os arquivos. Nunca altera blocos de código nem atributos JSX. O prompt mostra até 3 sugestões e marca a melhor como recomendada.
  • Ignore adiciona a palavra a spellcheck.ignore no seu docs.json. Ela não será mais sinalizada.
  • Skip não faz nada para esta execução

Você visualiza e confirma as alterações antes de serem aplicadas.

Lista de ignorados personalizada: adicione termos específicos do projeto ao seu docs.json:

docs.json
{
  "spellcheck": {
    "ignore": ["YourProduct", "kubectl", "Terraform"]
  }
}

O spellcheck ignora o nome do seu projeto em docs.json.

Valide um único arquivo de especificação OpenAPI.

jamdesk openapi-check openapi.yaml
jamdesk openapi-check api/spec.json

Valida:

  • Sintaxe YAML/JSON válida
  • Conformidade com o schema OpenAPI 3.x
  • Definições de endpoints
  • Referências $ref resolvidas corretamente

O Jamdesk valida especificações OpenAPI em três lugares. jamdesk dev interrompe a inicialização se uma especificação referenciada for inválida. jamdesk validate e jamdesk openapi-check verificam especificações sob demanda. O build na nuvem verifica as especificações referenciadas ao implantar, onde uma especificação inválida é um aviso não fatal. O restante da sua documentação continua sendo publicado. O e-mail e a lista de builds no painel indicam o problema: um erro de análise com linha e coluna, um $ref não resolvido ou um operationId duplicado. Corrija a especificação e envie novamente para limpar o aviso.

Gerenciamento de arquivos

Renomeie uma página e atualize todas as referências a ela.

jamdesk rename docs/old-name.mdx docs/new-name.mdx

Isso irá:

  • Renomear o arquivo
  • Atualizar a navegação do docs.json
  • Atualizar links em todos os outros arquivos MDX
  • Atualizar referências a snippets

Use isso em vez de renomear manualmente. As referências permanecem sincronizadas.

Migração

Migre a documentação do Mintlify para o Jamdesk.

jamdesk migrate

Detecta sua configuração do Mintlify e a converte para o formato Jamdesk. A mesma etapa também:

  • Renomeia componentes obsoletos (por exemplo, CardGroup → Columns)
  • Move arquivos MDX de snippets órfãos para /snippets/ e reescreve importações relativas ao diretório pai
  • Extrai componentes inline que usam hooks do React para /snippets/<name>.tsx com 'use client'
  • Corrige problemas mecânicos de sintaxe MDX

O comando é idempotente. Executá-lo novamente é seguro.

Guia de migração

Guia completo de migração com instruções passo a passo para Mintlify e outras plataformas

Implantação

Baixe um projeto cuja documentação o Jamdesk hospeda (sem GitHub) como um repositório git, ou mescle novas alterações do Jamdesk em uma cópia que você já baixou.

jamdesk pull
jamdesk pull --project your-project
jamdesk pull --dir ./docs-copy

Edite os arquivos e depois execute jamdesk deploy nessa pasta para publicá-los. Requer CLI 1.1.227 ou superior e git.

FlagDescrição
--project <id-or-slug>Baixa um projeto específico (pula a seleção interativa)
--dir <path>Pasta de destino (padrão: ./<slug>)
--forceTransforma uma pasta que já tem arquivos, como uma cópia antiga somente leitura, em uma cópia git. Seus arquivos continuam como alterações não commitadas
Edite no seu computador

Publicação, mesclagem de alterações do Jamdesk, conflitos e arquivos que o deploy recusa

Envie sua documentação e dispare um build pelo terminal.

jamdesk deploy
jamdesk deploy --detach
jamdesk deploy --full-rebuild

A CLI mostra cada fase do build conforme ela é concluída. Também disponível como jamdesk push.

FlagDescrição
--detachEnfileira e encerra imediatamente
--full-rebuildForça um build completo (sem cache)
--project <id>Implanta em um projeto específico
--allow-emptyPermite implantar com zero páginas de conteúdo .mdx (recusado por padrão)
-m, --message <text>Mensagem de commit em uma pasta criada por jamdesk pull
--allow-secret-filesPublica arquivos com aparência de segredo de uma pasta criada por jamdesk pull
Guia de deploy pela CLI

Pipeline completo de implantação, fases do build, referência de erros e solução de problemas

Gere a estrutura e implante um Cloudflare Worker que faz proxy de /docs no seu próprio domínio para o seu site Jamdesk.

jamdesk deploy-proxy cloudflare
jamdesk deploy-proxy cloudflare --slug myproject --domain example.com --yes

O comando é interativo por padrão. Ele verifica o Wrangler, valida sua conta Cloudflare, detecta seu slug em docs.json, gera os arquivos do Worker e oferece a opção de implantar. --yes apenas gera os arquivos e para. Implante-os com npx wrangler deploy a partir do diretório de saída.

FlagDescrição
--slug <slug>Slug do projeto Jamdesk
--domain <domain>Domínio de destino (por exemplo, example.com)
--path <path>Prefixo de caminho (padrão: /docs)
--output-dir <dir>Diretório de saída (padrão: cloudflare-worker/)
--skip-deployIgnora o prompt "implantar agora?" em uma execução interativa
--forceSobrescreve o diretório de saída caso ele já exista
--yesResponde a todos os prompts com o padrão (modo CI). Nunca implanta e nunca sobrescreve um diretório existente
Guia do Cloudflare Workers

Configuração do Worker, padrões de rota e configuração de cache

Manutenção

Verifique seu ambiente e diagnostique problemas.

jamdesk doctor

Verifica:

  • Versão do Node.js (requer 22.18+ ou 24.11+)
  • O Node.js que vem primeiro no seu PATH, no qual o jamdesk dev é executado
  • Versão do npm
  • docs.json existe e é válido
  • Status do cache ~/.jamdesk
  • Permissões de escrita

Execute isso quando a CLI apresentar mau funcionamento.

Limpa o diretório de cache ~/.jamdesk.

jamdesk clean

Isso remove dependências em cache e artefatos de build. Use para:

  • Liberar espaço em disco
  • Corrigir um cache corrompido
  • Forçar a reinstalação limpa das dependências

O próximo jamdesk dev reinstala as dependências.

Atualiza a CLI para a versão mais recente.

jamdesk update

Você também pode atualizar manualmente:

npm update -g jamdesk

Configuração

Crie ~/.jamdeskrc para definir opções padrão:

{
  "defaultPort": 3001,
  "verbose": false,
  "checkUpdates": true
}
OpçãoTipoPadrãoDescrição
defaultPortnumber3000Porta padrão do servidor de desenvolvimento
verbosebooleanfalseAtiva saída detalhada por padrão
checkUpdatesbooleantrueVerifica atualizações da CLI na inicialização

Solução de problemas

MDX é interpretado como JSX. Alguns caracteres têm significado especial.

Problema comum: o caractere < é interpretado como o início de uma tag JSX.

✗ Found 1 MDX syntax error(s)

  getting-started.mdx:42
    Unexpected character `5` (U+0035) before name
    Fix: A < character is being parsed as JSX. Use &lt; or rewrite

Soluções:

  • Use &lt; para o sinal de menor literal: Values &lt;50% are low
  • Reescreva para evitar o caractere: "Below 50%" em vez de "<50%"
  • Execute jamdesk validate para mensagens de erro detalhadas com números de linha

Execute o comando a partir de um diretório com um arquivo docs.json.

Soluções:

  • Execute jamdesk init para criar um novo projeto
  • Verifique se você está no diretório correto
  • Confirme que o arquivo se chama exatamente docs.json (não doc.json ou similar)

Tente estes passos:

  1. Execute jamdesk doctor para verificar seu ambiente
  2. Execute jamdesk clean para limpar o cache
  3. Use jamdesk dev --verbose para saída de erro detalhada
  4. Verifique se o Node.js 22.18+ ou 24.11+ está instalado: node --version

A primeira execução instala as dependências em ~/.jamdesk/node_modules.

Isso acontece apenas uma vez. As execuções seguintes são mais rápidas.

Outro processo está usando a porta padrão.

Soluções:

# Use a different port
jamdesk dev --port 3001

# Or set a default in ~/.jamdeskrc
{ "defaultPort": 3001 }

Você pode não ter permissões de escrita no diretório de cache.

Soluções:

  1. Verifique as permissões de ~/.jamdesk: ls -la ~/.jamdesk
  2. Corrija a propriedade: sudo chown -R $(whoami) ~/.jamdesk
  3. Execute jamdesk clean e tente novamente

Ainda com problemas? Consulte o guia de solução de problemas da CLI ou abra uma issue no GitHub.

Próximos passos

Autenticação

Fluxo de login, sessões e solução de problemas

Deploy pela CLI

Implante pelo terminal

Visualização local

Opções avançadas de desenvolvimento local

Guia de migração

Migre do Mintlify ou de outras plataformas