Supporto monorepo
Mantieni la documentazione accanto al codice. Jamdesk supporta i monorepo e qualsiasi repository in cui la documentazione non si trovi nella root.
Se il tuo docs.json si trova in una sottodirectory — docs/, packages/docs/ o in qualsiasi altra posizione — attiva la modalità monorepo nelle impostazioni del progetto e specifica il percorso. Jamdesk limiterà le build a quella directory e ignorerà tutto ciò che si trova al di fuori.
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
Vai al tuo progetto nel dashboard di Jamdesk e apri Settings.
Nella sezione Git Repository, attiva Set up as monorepo.
Specifica il percorso della directory che contiene il file docs.json.
L'anteprima mostra dove Jamdesk cercherà il file di configurazione.
Fai clic su Save Changes per applicare le modifiche. La build successiva utilizzerà il nuovo percorso.
Comprendere il percorso della documentazione
Il percorso della documentazione indica a Jamdesk dove trovare il file di configurazione docs.json all'interno del repository.
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 della documentazione |
|---|---|
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
Quando imposti un percorso per la documentazione, Jamdesk elabora solo i file all'interno di quella directory:
- File di contenuto (
.mdx,.md) vengono compilati nelle pagine - Risorse nelle sottodirectory, come
images/, vengono incluse - Configurazione (
docs.json) definisce il sito
I file al di fuori del percorso della documentazione vengono ignorati durante le build.
Strutture monorepo comuni
Scegli il modello che corrisponde alla struttura del tuo progetto:
Documentazione in una directory di primo livello.
monorepo/
├── packages/
├── apps/
└── docs/ # Docs path: docs
├── docs.json
├── introduction.mdx
└── guides/Docs path: docs
Lavorare con le risorse
I percorsi delle risorse in docs.json sono sempre relativi alla directory della documentazione, non alla root del repository.
Esempio
Se la documentazione si trova 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 root del repository. Questo non funzionerà:
"favicon": "/packages/docs/images/favicon.svg"Nei file MDX
La stessa regola si applica alle immagini nei contenuti:
Questo fa riferimento a un'immagine in [docs-path]/images/tabs-preview.png.
Link interni
I link interni funzionano allo stesso modo indipendentemente dalla struttura del repository. Usa percorsi relativi alla root della documentazione:
[See the quickstart guide](/quickstart)
[Installation steps](/quickstart#installation)Questi percorsi corrispondono alla struttura della navigazione, non al file system.
Comportamento delle build
Jamdesk monitora le modifiche solo all'interno del percorso della documentazione configurato:
- Le modifiche a
packages/docs/**attivano una build - Le modifiche a
packages/core/**non attivano una build
In questo modo le build sono rapide e si concentrano sulle modifiche alla documentazione.
Devi ricreare la build quando cambia altro codice?
Se generi la documentazione dal codice sorgente, ad esempio la documentazione API dai commenti del codice, avvia una ricreazione manuale della build dal dashboard oppure configura un webhook nella pipeline CI.
Compatibilità con gli strumenti per workspace
Jamdesk funziona con tutti i principali strumenti per monorepo. Non è necessaria alcuna configurazione speciale oltre all'impostazione del percorso della documentazione.
| 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
Controllo rapido: nel repository, il file dovrebbe trovarsi in [your-docs-path]/docs.json
I percorsi delle risorse devono essere relativi alla directory della documentazione.
Corretto — relativo alla directory della documentazione:
"favicon": "/images/favicon.svg"Errato — assoluto dalla root del repository:
"favicon": "/packages/docs/images/favicon.svg"Verifica che le immagini si trovino effettivamente in [docs-path]/images/.
Solo le modifiche all'interno del percorso della documentazione configurato attivano le build automatiche.
- Verifica di modificare file all'interno del percorso della documentazione
- Controlla di eseguire il push sul branch corretto
- Visualizza lo stato della consegna del webhook nelle impostazioni del repository GitHub
Se devi attivare build in seguito a modifiche al di fuori del percorso della documentazione, usa le ricreazioni manuali o i webhook CI.