Suporte a monorepo
Mantenha a documentação junto ao código. O Jamdesk oferece suporte a monorepos e a qualquer repositório em que a documentação não esteja na raiz.
Se o seu docs.json estiver em um subdiretório — docs/, packages/docs/ ou qualquer outro local — ative o modo monorepo nas configurações do projeto e especifique o caminho. O Jamdesk limitará os builds a esse diretório e ignorará tudo o que estiver fora dele.
As capturas de tela mostram a interface em inglês.
Pré-requisitos: você precisa ter um projeto do Jamdesk conectado a um repositório do GitHub antes de configurar o suporte a monorepo.
Como o Jamdesk limita seu build
Configuração rápida
Acesse seu projeto no dashboard do Jamdesk e navegue até Settings.
Na seção Git Repository, ative Set up as monorepo.
Especifique o caminho para o diretório que contém seu arquivo docs.json.
A prévia mostra onde o Jamdesk procurará seu arquivo de configuração.
Clique em Save Changes para aplicar. Seu próximo build usará o novo caminho.
Entenda o caminho da documentação
O caminho da documentação informa ao Jamdesk onde encontrar seu arquivo de configuração docs.json dentro do repositório.
Insira apenas o caminho do diretório, não o nome do arquivo. Use docs, não docs/docs.json.
Exemplos de caminhos
| Estrutura do repositório | Valor do caminho da documentação |
|---|---|
my-repo/docs/docs.json | docs |
my-repo/packages/docs/docs.json | packages/docs |
my-repo/apps/website/docs/docs.json | apps/website/docs |
my-repo/documentation/docs.json | documentation |
O que é incluído
Quando você define um caminho para a documentação, o Jamdesk processa apenas os arquivos dentro desse diretório:
- Arquivos de conteúdo (
.mdx,.md) são compilados em páginas - Assets em subdiretórios (como
images/) são incluídos - Configuração (
docs.json) define seu site
Os arquivos fora do caminho da documentação são ignorados durante os builds.
Padrões comuns de monorepo
Escolha o padrão que corresponde à estrutura do seu projeto:
Documentação em um diretório de nível superior.
monorepo/
├── packages/
├── apps/
└── docs/ # Docs path: docs
├── docs.json
├── introduction.mdx
└── guides/Caminho da documentação: docs
Trabalhando com assets
Os caminhos dos assets em docs.json são sempre relativos ao diretório da documentação, não à raiz do repositório.
Exemplo
Se sua documentação estiver em packages/docs/:
{
"logo": {
"light": "/images/logo.svg"
},
"favicon": "/images/favicon.svg"
}Esses caminhos fazem referência a:
packages/docs/images/logo.svgpackages/docs/images/favicon.svg
Não use caminhos absolutos a partir da raiz do repositório. Isto não funcionará:
"favicon": "/packages/docs/images/favicon.svg"Em arquivos MDX
A mesma regra se aplica às imagens do seu conteúdo:
Isso faz referência a uma imagem em [docs-path]/images/tabs-preview.png.
Links internos
Os links internos funcionam da mesma forma, independentemente da estrutura do repositório. Use caminhos relativos à raiz da documentação:
[See the quickstart guide](/quickstart)
[Installation steps](/quickstart#installation)Esses caminhos correspondem à estrutura de navegação, não ao sistema de arquivos.
Comportamento dos builds
O Jamdesk monitora alterações apenas dentro do caminho configurado para a documentação:
- Alterações em
packages/docs/**acionam um build - Alterações em
packages/core/**não acionam um build
Isso mantém os builds rápidos e concentrados nas alterações da documentação.
Precisa refazer o build quando outro código for alterado?
Se você gera documentação a partir do código-fonte (como documentação de API a partir de comentários no código), acione manualmente um novo build no dashboard ou configure um Webhook no seu pipeline de CI.
Compatibilidade com ferramentas de workspace
O Jamdesk funciona com todas as principais ferramentas de monorepo. Não é necessária nenhuma configuração especial além de definir o caminho da documentação.
| Ferramenta | Compatível |
|---|---|
| npm workspaces | Sim |
| Yarn workspaces | Sim |
| pnpm workspaces | Sim |
| Turborepo | Sim |
| Nx | Sim |
| Lerna | Sim |
Solução de problemas
- Verifique se o caminho exato no repositório corresponde ao que você inseriu
- Confirme se
docs.jsonexiste nesse local - Verifique se há erros de digitação — os caminhos diferenciam maiúsculas de minúsculas
- Lembre-se: use
docs, nãodocs/docs.json
Verificação rápida: no seu repositório, o arquivo deve existir em [your-docs-path]/docs.json
Os caminhos dos assets devem ser relativos ao diretório da documentação.
Correto — relativo ao diretório da documentação:
"favicon": "/images/favicon.svg"Incorreto — absoluto a partir da raiz do repositório:
"favicon": "/packages/docs/images/favicon.svg"Verifique se as imagens realmente existem em [docs-path]/images/.
Apenas alterações dentro do caminho configurado para a documentação acionam builds automáticos.
- Verifique se você está modificando arquivos dentro do caminho da documentação
- Confirme se está enviando alterações para a branch correta
- Consulte o status de entrega do Webhook nas configurações do repositório do GitHub
Se precisar que alterações fora do caminho da documentação acionem builds, use novos builds manuais ou Webhooks de CI.