Jamdesk Documentation logo

Estrutura de diretórios

Como organizar os arquivos em um repositório de documentação Jamdesk: arquivos obrigatórios, diretórios de páginas, imagens, snippets e especificações OpenAPI.

Organize os arquivos de 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

O repositório de documentação da Jamdesk é um exemplo de produção dessa estrutura: duas abas, mais de 120 páginas, especificações OpenAPI e scripts personalizados.

Arquivos obrigatórios

docs.json

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

docs.json
{
  "$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 do docs.json para todas as opções.

Organização das páginas

Estrutura plana vs. aninhada

Escolha de acordo com o tamanho da sua documentação:

Mantenha todas as páginas na raiz:

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

Referencie as páginas diretamente na navegação:

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

Convenções de nomenclatura

ConvençãoExemploURL
Minúsculasgetting-started.mdx/getting-started
Kebab-caseapi-reference.mdx/api-reference
Diretóriosguides/auth.mdx/guides/auth

Evite espaços e caracteres especiais nos nomes de arquivos. Use hífens para separar palavras.

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 no docs.json:

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 nas páginas:

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

openapi/

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

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

Referencie no docs.json:

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

Para um exemplo real, consulte o Exemplo de OpenAPI.

Arquivos de especificação específicos por linguagem

Para sites de documentação multilíngue, adicione arquivos de especificação traduzidos ao lado do original, com um infixo de código de idioma:

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

A Jamdesk serve automaticamente a especificação correta quando uma página é renderizada sob um prefixo de idioma (/fr/…, /es/…, etc.). Consulte Suporte a múltiplos idiomas → Traduzindo especificações OpenAPI para as regras completas 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. Não o inclua no commit.

O que vem a seguir?

Suporte a monorepos

Configure o caminho da documentação para monorepos

Referência do docs.json

Todas as opções de configuração