Structure des répertoires

Une structure de répertoires claire facilite la navigation, les builds et la collaboration.

Structure minimale

Le projet Jamdesk le plus simple nécessite seulement deux fichiers :

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

Structure recommandée

Pour les sites de documentation plus importants, organisez les pages en répertoires :

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

Fichiers requis

docs.json

Le fichier de configuration qui définit votre site. Il doit se trouver à la racine de votre répertoire de documentation (ou dans le chemin spécifié dans les paramètres du projet).

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

Consultez la Référence docs.json pour toutes les options.

Organisation des pages

Plat vs imbriqué

Choisissez en fonction de la taille de votre documentation :

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

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

Conventions de nommage

Répertoires spéciaux

images/

Stockez les images, logos et favicons :

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

Référencez dans docs.json :

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

snippets/

Blocs de contenu réutilisables :

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

Incluez dans les pages :

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

openapi/

Fichiers de spécification OpenAPI pour la documentation API :

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

Référencez dans docs.json :

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

Pour un exemple en production, consultez Exemple OpenAPI.

Fichiers de spécification spécifiques à une langue

Pour les sites de documentation multilingues, ajoutez des fichiers de spécification traduits à côté de la source avec un infixe de code de langue :

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

Jamdesk sert automatiquement la spécification correcte lorsqu'une page est rendue sous un préfixe de langue (/fr/…, /es/…, etc.). Consultez Support multilingue → Traduction des spécifications OpenAPI pour les règles complètes sur ce qu'il faut traduire et ce qu'il faut conserver à l'identique.

Fichiers à ignorer

Créez un .gitignore pour exclure les artefacts de build :

.jamdesk/
node_modules/
.DS_Store
*.log

Le répertoire .jamdesk/ contient le cache de développement local et ne doit pas être inclus dans les commits.

Et ensuite ?