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 se trouvent 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 avez besoin d'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.
Entrez 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 traite uniquement les fichiers dans ce répertoire :
- Les fichiers de contenu (
.mdx,.md) sont compilés en pages - Les assets dans les sous-répertoires (comme
images/) sont inclus - 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 monorepos
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 assets
Les chemins d'assets dans docs.json sont toujours relatifs à votre répertoire de docs, pas à 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 référencent :
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 référence une image à [docs-path]/images/tabs-preview.png.
Liens internes
Les liens internes fonctionnent de la même manière 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 surveille uniquement les modifications dans votre chemin de docs configuré :
- Les modifications dans
packages/docs/**déclenchent un build - Les modifications dans
packages/core/**ne déclenchent pas de build
Cela maintient des builds rapides et centrés sur les modifications de la documentation.
Besoin de déclencher des builds lors de modifications d'autre code ?
Si vous générez de la documentation à partir du code source (comme des docs API à partir de commentaires de code), déclenchez un rebuild manuel depuis le dashboard ou configurez un webhook dans votre pipeline CI.
Compatibilité avec les outils de workspace
Jamdesk fonctionne avec tous les principaux outils 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
- N'oubliez pas : utilisez
docset nondocs/docs.json
Vérification rapide : Dans votre dépôt, le fichier doit exister à [your-docs-path]/docs.json
Les chemins d'assets 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 le statut 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 rebuilds manuels ou des webhooks CI.