Origine del contenuto

Origine del contenuto

Ogni progetto ha esattamente una content root - la cartella che bxSites analizza alla ricerca di pagine .md, assets/, blog/, i18n/, versions/, e tutto il resto trattato altrove in questi documenti. Questa guida copre come viene trovata quella cartella, come puntarla altrove con source, come tenere fuori dalla scansione i file estranei con exclude, e dove vive la sovrascrittura di tema propria di un progetto rispetto ad essa.

Rilevamento automatico (il comportamento predefinito)

Senza alcuna chiave source impostata, bxSites cerca prima docs/, poi src/, e usa qualunque delle due esista davvero sul disco - la stessa convenzione di lunga data trattata in Per iniziare. Va bene per la maggior parte dei progetti e non richiede alcuna configurazione.

La chiave di configurazione source

Imposta source in bxsites.yaml per saltare il rilevamento automatico e indicare esplicitamente dove vive il tuo contenuto:

source: docs

{ "source": "docs" }

source = "docs"

source accetta:

• docs o src - gli stessi due nomi convenzionali che il rilevamento automatico già controlla, semplicemente indicati in modo esplicito invece che dedotti.
• Qualsiasi altro nome di cartella - content, pages, website, qualunque cosa si adatti al tuo progetto. Il rilevamento automatico cerca solo docs/src; un nome personalizzato richiede sempre un source esplicito.
• . - la radice del progetto stessa è la content root, senza alcuna sottocartella. Utile per un progetto che è soltanto un sito di documentazione - nient'altro nel repository - dove aggiungere uno strato docs/ sopra sarebbe solo un'altra cartella da attraversare. build/serve/ogni altro verbo analizza allora l'intera radice del progetto alla ricerca di pagine .md, esattamente come farebbe con docs/ altrimenti.

bxSites new scrive sempre un source: esplicito nel bxsites.yaml che genera (docs per impostazione predefinita, o qualunque --source=... tu abbia passato) - vedi Per iniziare - così un progetto appena creato non è mai ambiguo su dove vive il suo contenuto, anche prima che il rilevamento automatico entri in gioco.

Un nome resta comunque vietato: source: site fallisce sempre, dato che site/ è l'output di build generato proprio di bxSites - ogni build lo rimuove e lo ricrea, quindi lasciarlo fungere anche da cartella sorgente significherebbe una build che cancella il proprio stesso contenuto.

L'errore BxSites.SourceNotConfigured

Se source viene lasciata non impostata e né docs/ né src/ esistono sul disco, la build fallisce in modo esplicito invece di ricadere silenziosamente sulla radice del progetto:

BxSites.SourceNotConfigured: No docs/ or src/ folder found, and no
[source] set in bxsites.yaml - set source: docs, source: src, or
source: . (if your whole repo is the content) to tell bxSites where
your content lives

Questo è voluto - indovinare "la radice del progetto deve essere il contenuto" ogni volta che nessuna delle due cartelle convenzionali esiste finirebbe per raccogliere silenziosamente cose come README.md, un CHANGELOG.md, la configurazione CI, o il codice sorgente proprio di un repository in una build, nel momento in cui qualcuno rinominasse docs/ in qualcos'altro, o eseguisse bxSites contro un repository che non è mai stato pensato per essere un sito di documentazione. La correzione è sempre una riga in bxsites.yaml:

source: .

{ "source": "." }

source = "."

(oppure source: docs/source: src se intendevi una di quelle e la cartella semplicemente non esiste ancora - creala, o punta source dove il contenuto vive realmente).

Escludere file e cartelle

bxSites esclude sempre da sé una manciata di nomi dalla scansione del contenuto - .git, .github, node_modules, boxlang_modules, site, .theme, .themes, e il proprio file di configurazione (bxsites.yaml/.yml/.toml/.json, box.json) - allo stesso modo in cui esclude già assets/, versions/, i18n/, blog/ e includes/ dall'essere scansionati come pagine normali. exclude aggiunge i tuoi nomi sopra a quell'elenco:

source: .
exclude:
  - tests
  - build
  - CONTRIBUTING.md

{
	"source": ".",
	"exclude": ["tests", "build", "CONTRIBUTING.md"]
}

source = "."
exclude = [ "tests", "build", "CONTRIBUTING.md" ]

Ogni voce è un nome nudo, confrontato allo stesso modo delle esclusioni integrate - alla radice della cartella di contenuto, o ovunque al suo interno.

Questo è più utile in coppia con source: .. Una volta che l'intero repository è la content root, tutto ciò che contiene e non è di per sé una pagina va nominato esplicitamente - una cartella tests/, una directory di output build/, la configurazione del tooling, o qualsiasi altra cosa che altrimenti verrebbe scansionata e pubblicata come se fosse una pagina di documentazione. exclude non è deliberatamente pre-popolato con README.md/LICENSE.md/CHANGELOG.md, però - un progetto è libero di avere una vera pagina di contenuto esattamente a uno di questi nomi (il docs/license.md proprio di questo modulo, ad esempio), quindi se il tuo progetto source: . non vuole che il proprio README.md/LICENSE.md/CHANGELOG.md alla radice venga pubblicato come pagina, escludilo per nome tramite exclude invece di contare su un comportamento automatico.

Vedi Configurazione: exclude per il riferimento completo.

Dove vive una sovrascrittura di tema

La sovrascrittura di tema propria di un progetto - un .theme/ scritto a mano (vedi Temi: Sovrascrivere un tema) oppure un .themes/<name>/ installato con install:theme (vedi Temi: Installare un tema pubblicato) - vive dentro la content root risolta, non alla radice nuda del progetto: <contentRoot>/.theme/ e <contentRoot>/.themes/<name>/, dove <contentRoot> è qualunque cosa risolva source (o il rilevamento automatico) - docs/, src/, un nome di cartella personalizzato, oppure la radice del progetto stessa per source: ..

my-project/
├── bxsites.yaml          ← source: docs
└── docs/                 ← la content root risolta
    ├── index.md
    ├── assets/
    └── .theme/            ← vive dentro docs/, non alla radice del progetto
        ├── layout.bxm
        └── page.bxm

Tenere .theme/.themes dentro la content root invece che alla radice nuda del progetto conta soprattutto una volta che un repository ha più di una content root al suo interno - vedi Monorepo multi-dominio per questo schema. La sovrascrittura di tema propria di ogni content root vive allora senza ambiguità accanto al contenuto che tematizza, senza alcuna domanda su a quale dominio apparterrebbe una cartella theme/ nuda alla radice.