Estrutura de diretórios

Esta página mostra como organizar os arquivos em um repositório de documentação Jamdesk, desde o mínimo de dois arquivos até um layout completo com vários diretórios.

Estrutura mínima

O projeto Jamdesk mais simples precisa de apenas dois arquivos:

my-docs/
├── docs.json           # Configuration
└── introduction.mdx    # Your first page

Estrutura recomendada

Para sites de documentação maiores, organize as páginas em diretórios:

my-docs/
├── docs.json
├── introduction.mdx
├── quickstart.mdx
│
├── guides/
│   ├── getting-started.mdx
│   ├── authentication.mdx
│   └── deployment.mdx
│
├── api-reference/
│   ├── overview.mdx
│   ├── endpoints/
│   │   ├── users.mdx
│   │   └── projects.mdx
│   └── webhooks.mdx
│
├── images/
│   ├── logo.svg
│   ├── favicon.svg
│   └── screenshots/
│       └── dashboard.png
│
└── snippets/
    └── api-base-url.mdx

Arquivos obrigatórios

docs.json

O arquivo de configuração que define seu site. Ele deve estar na raiz do diretório de documentação (ou no caminho especificado nas configurações do projeto).

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "My Documentation",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      }
    ]
  }
}

Consulte a referência de docs.json para ver todas as opções.

Organização das páginas

Estrutura plana vs. aninhada

Escolha com base no tamanho da sua documentação:

docs/
├── docs.json
├── introduction.mdx
├── installation.mdx
├── configuration.mdx
└── troubleshooting.mdx

"pages": ["introduction", "installation"]

Convenções de nomenclatura

Diretórios especiais

images/

Armazene imagens, logotipos e favicons:

images/
├── logo-light.webp     # Light mode logo
├── logo-dark.webp      # Dark mode logo
├── favicon.svg         # Browser favicon
└── screenshots/        # Documentation screenshots
    └── dashboard.png

Referencie-os em docs.json:

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "favicon": "/images/favicon.svg"
}

snippets/

Blocos de conteúdo reutilizáveis:

snippets/
├── api-base-url.mdx
└── auth-header.mdx

Inclua-os nas páginas:

<Snippet file="api-base-url.mdx" />

openapi/

Arquivos de especificação OpenAPI para a documentação da API:

openapi/
├── api.yaml
└── webhooks.yaml

Referencie-os em docs.json:

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

Para ver um exemplo funcional, consulte Exemplo de OpenAPI.

Arquivos de especificação específicos por linguagem

Para sites de documentação multilíngues, adicione arquivos de especificação traduzidos ao lado da origem, usando um infixo de código de idioma:

openapi/
├── api.yaml
├── api.fr.yaml
├── api.es.yaml
└── api.zh.yaml

O Jamdesk disponibiliza automaticamente a especificação correta quando uma página é renderizada com um prefixo de idioma (/fr/…, /es/…, etc.). Consulte Suporte a vários idiomas → Tradução de especificações OpenAPI para conhecer todas as regras sobre o que traduzir e o que manter idêntico.

Arquivos a ignorar

Crie um .gitignore para excluir artefatos de build:

.jamdesk/
node_modules/
.DS_Store
*.log

O diretório .jamdesk/ contém o cache de desenvolvimento local e não deve ser incluído no controle de versão.

O que vem a seguir?