Support des monorepos
Gardez la documentation aux côtés de votre code. Jamdesk prend en charge les monorepos et tout dépôt où les docs ne sont pas à la racine.
Si votre docs.json se trouve dans un sous-répertoire -- docs/, packages/docs/, ou ailleurs -- activez le mode monorepo dans les paramètres du projet et spécifiez le chemin. Jamdesk limitera les builds à ce répertoire et ignorera tout ce qui se trouve en dehors.
Les captures d'écran montrent l'interface en anglais.
Prérequis : Vous devez avoir un projet Jamdesk connecté à un dépôt GitHub avant de configurer le support des monorepos.
Comment Jamdesk délimite votre build
Configuration rapide
Accédez à votre projet dans le dashboard Jamdesk et naviguez vers Settings.
Dans la section Git Repository, activez Set up as monorepo.
Spécifiez le chemin vers le répertoire contenant votre fichier docs.json.
Le preview indique où Jamdesk cherchera votre fichier de configuration.
Cliquez sur Save Changes pour appliquer. Votre prochain build utilisera le nouveau chemin.
Comprendre le chemin des docs
Le chemin des docs indique à Jamdesk où trouver votre fichier de configuration docs.json dans le dépôt.
Saisissez uniquement le chemin du répertoire, pas le nom du fichier. Utilisez docs et non docs/docs.json.
Exemples de chemins
| Structure du dépôt | Valeur du chemin des docs |
|---|---|
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 |
Ce qui est inclus
Lorsque vous définissez un chemin de docs, Jamdesk ne traite que les fichiers dans ce répertoire :
- Les fichiers de contenu (
.mdx,.md) sont compilés en pages - Les ressources dans les sous-répertoires (comme
images/) sont incluses - La configuration (
docs.json) définit votre site
Les fichiers en dehors du chemin des docs sont ignorés lors des builds.
Structures courantes de monorepo
Choisissez la structure qui correspond à votre projet :
Documentation dans un répertoire de premier niveau.
monorepo/
├── packages/
├── apps/
└── docs/ # Docs path: docs
├── docs.json
├── introduction.mdx
└── guides/Chemin des docs : docs
Travailler avec les ressources
Les chemins des ressources dans docs.json sont toujours relatifs à votre répertoire de docs, et non à la racine du dépôt.
Exemple
Si vos docs se trouvent dans packages/docs/ :
{
"logo": {
"light": "/images/logo.svg"
},
"favicon": "/images/favicon.svg"
}Ces chemins font référence à :
packages/docs/images/logo.svgpackages/docs/images/favicon.svg
N'utilisez pas de chemins absolus depuis la racine du dépôt. Ceci ne fonctionnera pas :
"favicon": "/packages/docs/images/favicon.svg"Dans les fichiers MDX
La même règle s'applique aux images dans votre contenu :
Ceci fait référence à une image à [docs-path]/images/tabs-preview.png.
Liens internes
Les liens internes fonctionnent de la même façon quelle que soit la structure de votre dépôt. Utilisez des chemins relatifs à la racine de vos docs :
[See the quickstart guide](/quickstart)
[Installation steps](/quickstart#installation)Ces chemins correspondent à votre structure de navigation, pas à votre système de fichiers.
Comportement des builds
Jamdesk ne surveille que les modifications dans votre chemin de docs configuré :
- Les modifications apportées à
packages/docs/**déclenchent un build - Les modifications apportées à
packages/core/**ne déclenchent pas de build
Cela permet de maintenir des builds rapides et ciblés sur les modifications de la documentation.
Besoin de reconstruire lorsque d'autre code change ?
Si vous générez de la documentation à partir du code source (comme des docs API issues de commentaires de code), déclenchez une reconstruction manuelle depuis le dashboard ou configurez un webhook dans votre pipeline CI.
Compatibilité avec les outils de workspace
Jamdesk fonctionne avec tous les principaux outils de monorepo. Aucune configuration spéciale n'est nécessaire au-delà de la définition du chemin des docs.
| Outil | Pris en charge |
|---|---|
| npm workspaces | Oui |
| Yarn workspaces | Oui |
| pnpm workspaces | Oui |
| Turborepo | Oui |
| Nx | Oui |
| Lerna | Oui |
Dépannage
- Vérifiez que le chemin exact dans votre dépôt correspond à ce que vous avez saisi
- Assurez-vous que
docs.jsonexiste à cet emplacement - Vérifiez les fautes de frappe — les chemins sont sensibles à la casse
- Rappel : utilisez
docset nondocs/docs.json
Vérification rapide : Dans votre dépôt, le fichier doit exister à [your-docs-path]/docs.json
Les chemins des ressources doivent être relatifs à votre répertoire de docs.
Correct - relatif au répertoire de docs :
"favicon": "/images/favicon.svg"Incorrect - absolu depuis la racine du dépôt :
"favicon": "/packages/docs/images/favicon.svg"Vérifiez que vos images existent bien dans [docs-path]/images/.
Seules les modifications dans votre chemin de docs configuré déclenchent des builds automatiques.
- Vérifiez que vous modifiez des fichiers à l'intérieur du chemin de docs
- Vérifiez que vous poussez vers la bonne branche
- Consultez l'état de livraison des webhooks dans les paramètres du dépôt GitHub
Si vous avez besoin que des builds soient déclenchés par des modifications en dehors du chemin de docs, utilisez des reconstructions manuelles ou des webhooks CI.