Struttura delle directory

Questa pagina mostra come organizzare i file in un repository di documentazione Jamdesk, dalla configurazione minima a due file fino a una struttura completa con più directory.

Struttura minima

Un progetto Jamdesk semplice richiede solo due file:

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

Struttura consigliata

Per siti di documentazione più grandi, organizza le pagine in directory:

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

File obbligatori

docs.json

Il file di configurazione che definisce il sito. Deve trovarsi nella directory principale della documentazione (o nel percorso specificato nelle impostazioni del progetto).

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

Consulta il riferimento di docs.json per tutte le opzioni.

Organizzazione delle pagine

Struttura piatta o annidata

Scegli in base alle dimensioni della documentazione:

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

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

Convenzioni di denominazione

Directory speciali

images/

Archivia immagini, loghi e favicon:

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

Fai riferimento a questi file in docs.json:

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

snippets/

Blocchi di contenuto riutilizzabili:

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

Includili nelle pagine:

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

openapi/

File delle specifiche OpenAPI per la documentazione delle API:

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

Fai riferimento alle specifiche in docs.json:

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

Per un esempio reale, consulta Esempio OpenAPI.

File delle specifiche specifici per lingua

Per i siti di documentazione multilingue, aggiungi i file delle specifiche tradotti accanto a quello originale, usando un codice lingua nel nome:

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

Jamdesk fornisce automaticamente la specifica corretta quando una pagina viene visualizzata con un prefisso di lingua (/fr/…, /es/… e così via). Consulta Supporto multilingue → Traduzione delle specifiche OpenAPI per le regole complete su cosa tradurre e cosa mantenere identico.

File da ignorare

Crea un .gitignore per escludere gli artefatti di build:

.jamdesk/
node_modules/
.DS_Store
*.log

La directory .jamdesk/ contiene la cache dello sviluppo locale e non deve essere inclusa nel commit.

Qual è il prossimo passo?