Supporto monorepo
Configura la modalità monorepo nelle impostazioni del progetto Jamdesk indicando il percorso di docs, così Jamdesk compila solo la documentazione
Se docs.json si trova in una sottodirectory (docs/, packages/docs/ o un'altra), attiva la modalità monorepo nelle impostazioni del progetto e inserisci il percorso. Jamdesk compila solo quella directory.
Gli screenshot mostrano l'interfaccia in inglese.
Prerequisiti: prima di configurare il supporto monorepo, devi avere un progetto Jamdesk collegato a un repository GitHub.
Come Jamdesk limita la build
Configurazione rapida
Apri il progetto nella dashboard di Jamdesk e vai su Settings.
Nella sezione Git Repository, attiva Set up as monorepo.
Inserisci il percorso della directory che contiene il file docs.json.
L'anteprima mostra dove Jamdesk cerca il file di configurazione.
Fai clic su Save Changes. La build successiva userà il nuovo percorso.
Comprendere il percorso della documentazione
Inserisci solo il percorso della directory, non il nome del file. Usa docs, non docs/docs.json.
Esempi di percorsi
| Struttura del repository | Valore del percorso di 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 |
Cosa viene incluso
Jamdesk elabora solo i file all'interno del percorso di docs:
- I file di contenuto (
.mdx,.md) vengono compilati in pagine - Le risorse nelle sottodirectory (come
images/) vengono incluse - La configurazione (
docs.json) definisce il sito
Durante le build, i file al di fuori del percorso di docs vengono ignorati.
Strutture monorepo comuni
Documentazione in una directory di primo livello.
monorepo/
├── packages/
├── apps/
└── docs/ # Docs path: docs
├── docs.json
├── introduction.mdx
└── guides/Percorso di docs: docs
Lavorare con le risorse
I percorsi delle risorse in docs.json sono sempre relativi alla directory docs, non alla radice del repository.
Esempio
Per la documentazione in packages/docs/:
{
"logo": {
"light": "/images/logo.svg"
},
"favicon": "/images/favicon.svg"
}Questi percorsi fanno riferimento a:
packages/docs/images/logo.svgpackages/docs/images/favicon.svg
Non usare percorsi assoluti dalla radice del repository. Questo non funziona:
"favicon": "/packages/docs/images/favicon.svg"Nei file MDX
Le immagini nei file MDX seguono la stessa regola:
Questo fa riferimento a un'immagine in [docs-path]/images/tabs-preview.png.
Link interni
I link interni non dipendono dalla struttura del repository. Usa percorsi relativi alla radice di docs:
[See the quickstart guide](/quickstart)
[Installation steps](/quickstart#installation)Questi percorsi corrispondono alla struttura di navigazione, non al file system.
Comportamento delle build
Solo le modifiche all'interno del percorso di docs avviano una build:
- Le modifiche a
packages/docs/**avviano una build - Le modifiche a
packages/core/**non avviano una build
Devi avviare una build quando cambia altro codice?
Per la documentazione generata dal codice sorgente (ad esempio, la documentazione API ricavata dai commenti nel codice), avvia manualmente una nuova build dalla dashboard oppure configura un webhook nella pipeline CI.
Compatibilità con gli strumenti per workspace
Imposta il percorso di docs. Per questi strumenti monorepo non serve alcun'altra configurazione.
| Strumento | Supportato |
|---|---|
| npm workspaces | Sì |
| Yarn workspaces | Sì |
| pnpm workspaces | Sì |
| Turborepo | Sì |
| Nx | Sì |
| Lerna | Sì |
Risoluzione dei problemi
- Verifica che il percorso esatto nel repository corrisponda a quello inserito
- Assicurati che
docs.jsonesista in quella posizione - Controlla che non ci siano errori di battitura. I percorsi distinguono tra maiuscole e minuscole
- Ricorda: usa
docs, nondocs/docs.json
Verifica rapida: nel repository, il file deve trovarsi in [your-docs-path]/docs.json
I percorsi delle risorse devono essere relativi alla directory docs.
Corretto (relativo alla directory docs):
"favicon": "/images/favicon.svg"Errato (percorso assoluto dalla radice del repository):
"favicon": "/packages/docs/images/favicon.svg"Verifica che le immagini siano presenti in [docs-path]/images/.
Solo le modifiche all'interno del percorso di docs avviano build automatiche.
- Verifica di modificare file all'interno del percorso di docs
- Controlla di eseguire il push sul branch corretto
- Controlla lo stato di consegna dei webhook nelle impostazioni del repository GitHub
Per avviare una build quando cambiano file al di fuori del percorso di docs, usa le build manuali o i webhook CI.