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 jamdeskVerifique 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
Crie um novo projeto de documentação:
jamdesk init my-docs
cd my-docsExecute o servidor de desenvolvimento local com recarregamento automático:
jamdesk devSua documentação roda em http://localhost:3000/docs
Verifique erros de configuração, links quebrados e ortografia:
jamdesk validate
jamdesk broken-links
jamdesk fix --dry-run
jamdesk fix
jamdesk spellcheckComandos
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 3001Recursos:
- 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:
| Flag | Descrição |
|---|---|
-p, --port <port> | Porta de execução (padrão: 3000) |
-v, --verbose | Ativa saída detalhada |
Crie um novo projeto de documentação.
jamdesk init # Interactive mode
jamdesk init my-docs # Create in new directoryIsso 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 loginAbre o painel do Jamdesk no seu navegador. A CLI armazena as credenciais em ~/.jamdeskrc.
Remove as credenciais armazenadas.
jamdesk logoutMostra o usuário conectado e verifica a sessão.
jamdesk whoamiValidação
Valide sua configuração docs.json, a sintaxe MDX e as especificações OpenAPI.
jamdesk validate
jamdesk validate --skip-mdxVerifica:
- 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:
| Flag | Descrição |
|---|---|
--skip-mdx | Ignora a validação de sintaxe MDX |
-v, --verbose | Mostra 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-linksExemplo 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
#instalationque 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 fixExemplo 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:
| Flag | Descrição |
|---|---|
--dry-run | Visualiza as correções planejadas sem gravar arquivos |
-y, --yes | Aplica as correções sem pedir confirmação |
--types <list> | Tipos de aviso separados por vírgula a corrigir (padrão: todos os suportados) |
--no-ai | Ignora 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) |
--json | Imprime 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 |
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 offExemplo 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.
| Flag | Descrição |
|---|---|
--project <id> | ID do projeto (padrão: projectId em docs.json) |
Verifique sua documentação em busca de erros ortográficos.
jamdesk spellcheckExemplo 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:
| Flag | Descrição |
|---|---|
--fix | Corrige erros ortográficos de forma interativa ou adiciona à lista de ignorados |
--json | Saída em JSON (para pipelines de CI) |
-v, --verbose | Mostra 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.ignoreno 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:
{
"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.jsonValida:
- Sintaxe YAML/JSON válida
- Conformidade com o schema OpenAPI 3.x
- Definições de endpoints
- Referências
$refresolvidas 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.mdxIsso 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 migrateDetecta 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>.tsxcom'use client' - Corrige problemas mecânicos de sintaxe MDX
O comando é idempotente. Executá-lo novamente é seguro.
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-copyEdite os arquivos e depois execute jamdesk deploy nessa pasta para publicá-los. Requer CLI 1.1.227 ou superior e git.
| Flag | Descrição |
|---|---|
--project <id-or-slug> | Baixa um projeto específico (pula a seleção interativa) |
--dir <path> | Pasta de destino (padrão: ./<slug>) |
--force | Transforma 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 |
Envie sua documentação e dispare um build pelo terminal.
jamdesk deploy
jamdesk deploy --detach
jamdesk deploy --full-rebuildA CLI mostra cada fase do build conforme ela é concluída. Também disponível como jamdesk push.
| Flag | Descrição |
|---|---|
--detach | Enfileira e encerra imediatamente |
--full-rebuild | Força um build completo (sem cache) |
--project <id> | Implanta em um projeto específico |
--allow-empty | Permite 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-files | Publica arquivos com aparência de segredo de uma pasta criada por jamdesk pull |
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 --yesO 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.
| Flag | Descriçã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-deploy | Ignora o prompt "implantar agora?" em uma execução interativa |
--force | Sobrescreve o diretório de saída caso ele já exista |
--yes | Responde a todos os prompts com o padrão (modo CI). Nunca implanta e nunca sobrescreve um diretório existente |
Manutenção
Verifique seu ambiente e diagnostique problemas.
jamdesk doctorVerifica:
- 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 cleanIsso 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 updateVocê também pode atualizar manualmente:
npm update -g jamdeskConfiguração
Crie ~/.jamdeskrc para definir opções padrão:
{
"defaultPort": 3001,
"verbose": false,
"checkUpdates": true
}
| Opção | Tipo | Padrão | Descrição |
|---|---|---|---|
defaultPort | number | 3000 | Porta padrão do servidor de desenvolvimento |
verbose | boolean | false | Ativa saída detalhada por padrão |
checkUpdates | boolean | true | Verifica 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 < or rewriteSoluções:
- Use
<para o sinal de menor literal:Values <50% are low - Reescreva para evitar o caractere:
"Below 50%"em vez de"<50%" - Execute
jamdesk validatepara 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 initpara criar um novo projeto - Verifique se você está no diretório correto
- Confirme que o arquivo se chama exatamente
docs.json(nãodoc.jsonou similar)
Tente estes passos:
- Execute
jamdesk doctorpara verificar seu ambiente - Execute
jamdesk cleanpara limpar o cache - Use
jamdesk dev --verbosepara saída de erro detalhada - 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:
- Verifique as permissões de
~/.jamdesk:ls -la ~/.jamdesk - Corrija a propriedade:
sudo chown -R $(whoami) ~/.jamdesk - Execute
jamdesk cleane tente novamente
Ainda com problemas? Consulte o guia de solução de problemas da CLI ou abra uma issue no GitHub.
