Configurazione

Ogni chiave della configurazione del sito, il suo valore predefinito e cosa fa.

Configurazione

Ogni progetto ha un'unica configurazione del sito alla radice - bxsites.yaml (o .yml), il formato predefinito e preferito, oppure bxsites.json per un progetto che desidera restare su di esso. Entrambi sono pienamente supportati e producono esattamente lo stesso risultato; bxSites new genera lo scheletro di bxsites.yaml a meno che non venga passato --format=json (vedi Per iniziare). Se un progetto ne ha in qualche modo più di uno, vince bxsites.yaml, poi bxsites.yml, poi bxsites.json.

name: "My Docs"
description: ""
baseURL: "/"
theme:
  name: bootstrap
  options: {}
  logo: ""
  favicon: ""
search: true
searchProvider:
  provider: local
  algolia: { appId: "", apiKey: "", indexName: "", insights: false }
nav: []
markdown:
  enableAdmonition: true
repo:
  url: ""
  editUri: ""
social: []
footer: false
lastUpdated: false
mermaid: false
math: false
analytics:
  provider: ""
  id: ""
ogImage: ""
generateOgImages: false
extraCss: []
extraJs: []
plugins: []
i18n:
  defaultLocale: { code: en, label: English }
  locales: []

L'equivalente bxsites.json, per un progetto che lo preferisce:

{
	"name": "My Docs",
	"description": "",
	"baseURL": "/",
	"theme": {
		"name": "bootstrap",
		"options": {},
		"logo": "",
		"favicon": ""
	},
	"search": true,
	"searchProvider": {
		"provider": "local",
		"algolia": { "appId": "", "apiKey": "", "indexName": "", "insights": false }
	},
	"nav": [],
	"markdown": { "enableAdmonition": true },
	"repo": {
		"url": "",
		"editUri": ""
	},
	"social": [],
	"footer": false,
	"lastUpdated": false,
	"mermaid": false,
	"math": false,
	"analytics": {
		"provider": "",
		"id": ""
	},
	"ogImage": "",
	"generateOgImages": false,
	"extraCss": [],
	"extraJs": [],
	"plugins": [],
	"i18n": {
		"defaultLocale": { "code": "en", "label": "English" },
		"locales": []
	}
}

Solo name è obbligatorio - tutto il resto ricade sui valori predefiniti mostrati sopra. Un oggetto theme parziale viene unito con quello di default per un livello, quindi {"theme":{"name":"material"}} da solo mantiene comunque le options predefinite (vuote). Ogni chiave ha lo stesso nome e la stessa forma in entrambi i formati; il resto di questa pagina mostra solo JSON per brevità, ma si legge allo stesso modo in YAML.

name

Il nome del sito, mostrato nel marchio dell'header/brand e nei titoli delle pagine. Obbligatorio.

description

Una descrizione opzionale del sito, usata come <meta name="description"> e og:description di riserva per qualsiasi pagina che non imposti una propria description nel frontmatter (vedi Per iniziare).

baseURL

Controlla come viene prefissato ogni link interno, percorso di asset e voce di nav, e funge anche da URL canonico del sito per sitemap.xml e llms.txt.

• Lasciato vuoto o "/" (il valore predefinito) - i link restano relativi alla radice (/page/), e non viene generato né sitemap.xml né un llms.txt con URL assoluti (non c'è un dominio canonico da cui costruirli).
• Un percorso semplice, ad es. "my-docs" o "/my-docs/" - si assume che il sito venga servito da quel sotto-percorso, e ogni link interno, voce di nav e asset viene prefissato con esso (/my-docs/page/). Ancora nessun sitemap.xml, dato che manca comunque un dominio assoluto.
• Un URL completo, ad es. "https://docs.example.com/" - la parte del percorso (qui /) viene usata allo stesso modo di un percorso semplice, e sitemap.xml viene scritto al momento del build con l'URL assoluto di ogni pagina non nascosta sotto quel dominio.

llms.txt (vedi sotto) viene sempre scritto; preferisce semplicemente un URL assoluto quando baseURL ne fornisce uno.

llms.txt

Ogni build scrive un llms.txt alla radice del sito - un indice Markdown semplice di ogni pagina non nascosta, seguendo la convenzione emergente di llms.txt per aiutare gli strumenti basati su LLM a orientarsi in un sito senza doverne effettuare la scansione dell'HTML renderizzato. Non c'è una chiave di configurazione per questo; viene generato automaticamente, usando un URL assoluto per link quando baseURL è un URL completo, oppure uno relativo a basePath in caso contrario.

sitemap.xml

Scritto alla radice del sito, ma solo quando baseURL è un URL completo (vedi sopra) - una sitemap ha bisogno di un dominio assoluto per avere senso. Elenca ogni pagina non nascosta secondo il protocollo sitemaps.org.

theme

• theme.name - uno dei temi integrati (bootstrap, material, tailwind), oppure il nome di un tema personalizzato che fornisci tu tramite una cartella theme/ alla radice del progetto (vedi Temi)
• theme.logo - percorso/URL a un'immagine mostrata accanto al nome del sito nel marchio dell'header (al posto del glifo predefinito "⚡") - un percorso relativo (ad es. "assets/logo.svg", risolto rispetto a docs/assets/) viene prefissato con baseURL come qualsiasi altro asset interno; un URL assoluto viene usato così com'è. Lasciato vuoto (il valore predefinito), l'header mostra "⚡ <nome del sito>".
• theme.favicon - percorso/URL a una favicon, risolto allo stesso modo di theme.logo. Lasciato vuoto (il valore predefinito), non viene reso alcun <link rel="icon"> (ricadendo sul comportamento predefinito del browser).
• theme.options - opzioni specifiche del tema, lette da ogni tema integrato:

  • theme.options.colorMode - "auto" (il valore predefinito), "light" o "dark". Controlla quale modalità vede un visitatore alla prima visita, prima che ne scelga una propria tramite l'interruttore scuro/chiaro nell'header - "auto" segue la preferenza del suo sistema operativo, "light"/"dark" fissa un default fisso. Una volta che un visitatore attiva l'interruttore, la sua scelta (memorizzata in localStorage) prevale sempre nelle visite successive, indipendentemente da questa impostazione.

    { "theme": { "options": { "colorMode": "dark" } } }
    

  • theme.options.navCollapsible - false (il valore predefinito) mostra ogni intestazione di sezione della nav sempre espansa, come oggi. true mostra ogni sezione della nav (una cartella senza index.md) come un elemento nativo <details>/<summary> che il visitatore può comprimere - nessun framework JS coinvolto.

  • theme.options.navExpandAll - rilevante solo quando navCollapsible è true. true (il valore predefinito) avvia ogni sezione aperta; false avvia ogni sezione compressa.

    { "theme": { "options": { "navCollapsible": true, "navExpandAll": false } } }
    

search

true (il valore predefinito) compila un indice di ricerca statico e attiva il box di ricerca; false salta entrambi del tutto - nessun search-index.json, nessuna UI di ricerca, nessun JS extra distribuito. Vedi Ricerca.

searchProvider

Quale UI di ricerca search: true attiva:

• provider - "local" (il valore predefinito) è la ricerca statica/lato client propria di bx-sites (search-index.json + lunr.js, vedi Ricerca). "algolia" attiva invece Algolia DocSearch, e "pagefind" attiva Pagefind. Qualsiasi altro valore è un provider personalizzato del progetto, collegato tramite una sovrascrittura theme/ - vedi Ricerca.
• algolia - obbligatorio quando provider è "algolia": appId, apiKey (la chiave API pubblica solo per la ricerca, non una chiave da amministratore) e indexName, esattamente come li richiede il client DocSearch di Algolia stesso. insights (false di default) attiva l'analytics di click/conversione proprio di DocSearch.

  {
    "search": true,
    "searchProvider": {
      "provider": "algolia",
      "algolia": {
        "appId": "ABC123",
        "apiKey": "a1b2c3d4e5f6...",
        "indexName": "my-docs"
      }
    }
  }

• pagefind - entrambe le chiavi opzionali quando provider è "pagefind": bin (predefinito "pagefind") è il nome/percorso dell'eseguibile CLI, risolto rispetto a PATH quando è un nome nudo; options è un array di flag CLI grezzi extra passati direttamente. La CLI pagefind stessa deve essere già installata e su PATH - BX Sites ci esegue uno shell out (come git per lastUpdated/gh-deploy), non la installa al posto tuo.

  {
    "search": true,
    "searchProvider": {
      "provider": "pagefind",
      "pagefind": { "bin": "pagefind", "options": [] }
    }
  }

nav

Per impostazione predefinita, la nav viene dedotta dalla struttura stessa di cartelle/file di docs/ (con il frontmatter order/hidden) - va bene per siti piccoli, ma un sito grande può superarla: una nav esplicita ti permette di dare titolo, raggruppare e ordinare le pagine come vuoi, indipendentemente da dove si trovino effettivamente i loro file.

Un array vuoto (il valore predefinito) significa "deduci dalla struttura delle cartelle". Un array non vuoto sostituisce del tutto quella deduzione - l'ordine dell'array diventa l'ordine della nav, e una pagina non referenziata da nessuna parte al suo interno viene comunque compilata, solo non collegata dalla nav (come hidden: true). Ogni voce è una delle seguenti:

• una semplice stringa di percorso relativa a docs/, ad es. "guides/setup.md" - il titolo proviene dal frontmatter/nome del file di quella pagina, lo stesso che darebbe la deduzione dalla struttura delle cartelle
• un oggetto { "title", "path", "icon", "children" } - path, icon e children sono tutti opzionali; una voce con solo title e senza path è un'intestazione di gruppo senza link (come una cartella senza index.md oggi), e un title/icon esplicito sovrascrive sempre il titolo/icona propri della pagina collegata nella nav (l'<h1>/<title> reale della pagina resta intatto - cambia solo l'etichetta/icona nella nav) - vedi Temi: Icone per cosa può essere un valore icon

{
	"nav": [
		"index.md",
		{
			"title": "Guides",
			"children": [
				{ "title": "Quick Start", "path": "guides/setup.md" },
				"guides/deployment.md"
			]
		}
	]
}

Per una nav abbastanza grande da appesantire bxsites.json, spostala nel proprio file docs/nav.json - stessa forma di array, solo come contenuto principale dell'intero file:

[
	"index.md",
	{ "title": "Guides", "children": [ "guides/setup.md" ] }
]

Il nav proprio di bxsites.json, quando non vuoto, prevale sempre su docs/nav.json. Solo l'albero principale rispetta l'uno o l'altro - un albero docs/versions/<name>/ deduce sempre la propria nav dalla propria struttura di cartelle, anche quando l'albero principale ne ha una esplicita.

markdown

Inoltrato così com'è alle opzioni del modulo bx-markdown prima della compilazione di ogni pagina. BX Sites non ridefinisce né valida queste chiavi; qualunque cosa metti qui è il set di opzioni proprio di bx-markdown, passato direttamente - quindi questo elenco può divergere da quello di bx-markdown man mano che si evolve. Tabelle, ~~barrato~~, checkbox - [ ] per le liste di attività e il sommario in pagina sono sempre attivi, senza alcun interruttore. L'unica eccezione è enableAdmonition - bx-markdown stesso lo imposta a false di default, ma BX Sites lo imposta a true di default (vedi la guida alle Estensioni Markdown).

{
	"markdown": {
		"enableFootnotes": true,
		"enableDefinitionLists": true,
		"anchorLinks": false,
		"enableYouTubeTransformer": true
	}
}

repo

Aggiunge un link con icona del repository nell'header (in tutti e tre i temi integrati) e, quando entrambe le chiavi sono impostate, un link "Modifica questa pagina" su ogni pagina.

• repo.url - l'URL del tuo repository, ad es. "https://github.com/acme/docs". Da solo, mostra il link con icona nell'header; lascialo vuoto per ometterlo del tutto.
• repo.editUri - il segmento di percorso tra l'URL del repository e il percorso sorgente proprio di una pagina, ad es. "edit/main/docs/" (la convenzione URL di "edit" propria di GitHub). Combinato con repo.url e il percorso sorgente di una pagina relativo a docs/ per costruirne il link di modifica - ad es. con l'esempio sopra, docs/guides/setup.md ottiene https://github.com/acme/docs/edit/main/docs/guides/setup.md. Richiede anche repo.url; lascialo vuoto per omettere i link di modifica pur mostrando l'icona nell'header.

{ "repo": { "url": "https://github.com/acme/docs", "editUri": "edit/main/docs/" } }

social

Un array di link social/esterni renderizzati nel footer (vedi footer - non ha effetto a meno che non sia anch'esso attivato). Ogni voce richiede un url; icon seleziona da un piccolo set di icone integrato (github, twitter/x, youtube, linkedin, facebook, bluesky, threads, slack, patreon, rss, email, con un glifo di link generico come ripiego per qualsiasi altra cosa), e label imposta il nome accessibile/tooltip del link (predefinito su icon, poi "Link").

{
	"social": [
		{ "url": "https://twitter.com/acme", "icon": "twitter", "label": "Twitter" },
		{ "url": "https://acme.com/rss.xml", "icon": "rss", "label": "RSS" }
	]
}

footer

false (il valore predefinito) - nessun footer. true ne aggiunge uno a ogni pagina: una riga di copyright (© <anno> <nome del sito>), i link social (se presenti), e un credito "Built with BX Sites".

{ "footer": true }

lastUpdated

false (il valore predefinito) - nessuna data di ultimo aggiornamento. true aggiunge una riga "Last updated" accanto al link di modifica (o da sola, se repo.editUri non è impostato), ricavata dal git log del file Markdown proprio di ogni pagina al momento del build. Omessa silenziosamente per una pagina di cui git non ha storia - un git init appena fatto senza ancora commit, un build eseguito da uno zip scaricato senza alcun .git, oppure git non installato sulla macchina di build - piuttosto che interrompere il build.

{ "lastUpdated": true }

analytics

Attiva l'analisi delle visualizzazioni di pagina. Attualmente supporta solo Google Analytics (gtag.js):

• analytics.provider - "google" per attivarlo; lasciato vuoto (il valore predefinito), non viene distribuito alcuno script di analytics.
• analytics.id - l'ID di misurazione di Google Analytics (ad es. "G-ABC123"). Obbligatorio quando provider è "google".

{ "analytics": { "provider": "google", "id": "G-ABC123" } }

ogImage

Percorso/URL a un'immagine social-card predefinita, renderizzata come og:image (abbinata a un twitter:card di tipo summary_large_image) su ogni pagina che non la sovrascrive - risolta allo stesso modo di theme.logo (i percorsi relativi vengono prefissati con baseURL, gli URL assoluti vengono usati così come sono). Lasciato vuoto (il valore predefinito) e con generateOgImages disattivato, non viene renderizzato alcun tag og:image/twitter:card.

{ "ogImage": "assets/social-card.png" }

Un ogImage proprio del frontmatter di una pagina (vedi Per iniziare) prevale sempre su questo valore predefinito a livello di sito per quella singola pagina.

generateOgImages

false (il valore predefinito) - nessuna card per singola pagina. true renderizza una vera immagine PNG 1200x630 come social card per ogni pagina che non ha già un proprio ogImage nel frontmatter - il titolo della pagina sul gradiente del brand, scritto in site/assets/og/<page>.png - invece di condividere tutte le pagine un'unica immagine generica a livello di sito. Solo java.awt/ javax.imageio dietro le quinte (parte di qualsiasi JVM su cui gira BoxLang), quindi non serve alcun browser headless, servizio esterno, o accesso alla rete al momento del build.

{ "generateOgImages": true }

extraCss / extraJs

Array di URL di fogli di stile/script extra da includere in ogni pagina, aggiunti dopo gli asset propri del tema - ogni voce viene risolta allo stesso modo di theme.logo (un percorso relativo viene prefissato con baseURL; un URL assoluto viene usato così com'è). Le voci di extraJs vengono caricate con defer.

{
	"extraCss": [ "assets/custom.css" ],
	"extraJs": [ "assets/custom.js" ]
}

Quando assets.bundle è attivo (il valore predefinito), un elenco locale di extraCss/extraJs come quello sopra viene raggruppato in un unico file con impronta digitale ciascuno, invece di un tag <link>/<script> per ogni voce - vedi assets sotto.

assets

{
	"assets": {
		"fingerprint": true,
		"bundle": true,
		"images": {
			"enabled": true,
			"widths": [ 400, 800, 1200, 1600 ],
			"formats": [ "original", "webp" ]
		}
	}
}

La pipeline degli asset - ridimensionamento immagini/WebP tramite bx-image (una dipendenza obbligatoria, installata insieme a bx-markdown/bx-esapi) e bundling CSS/JS. Tutto qui è attivo di default con impostazioni ragionevoli - un progetto appena generato con bxSites new non deve toccare nulla di questo. Vedi Immagini Responsive per il quadro completo, incluso ciò che deliberatamente non è coperto (AVIF, GIF animate, SVG).

• assets.fingerprint - true (il valore predefinito). Assegna un nome basato sull'hash del contenuto a ogni variante di immagine generata e a ogni bundle CSS/JS (ad es. screenshot-800w.a3f9c2e1.webp, bundle.a3f9c2e1.css) così possono essere serviti con header di cache sicuri a lunghissima scadenza - un build cambia il nome proprio del file solo quando il suo contenuto cambia davvero. Non rinomina i file originali di un progetto sotto docs/assets/ - solo l'output generato dalla pipeline ottiene l'impronta digitale, quindi qualsiasi altra cosa che fa riferimento a un asset con il proprio nome file semplice (una card di download ::: file, un link markdown grezzo) continua a funzionare senza modifiche.
• assets.bundle - true (il valore predefinito). Concatena extraCss/extraJs in un unico file con impronta digitale ciascuno - puro BoxLang/JVM, nessuna toolchain Node/esbuild. Ricade sull'esatto comportamento odierno per-URL con <link>/<script>, senza modifiche, nel momento in cui una qualsiasi voce dell'elenco è un URL esterno (un link CDN) o nomina un file che non esiste - vedi Immagini Responsive.
• assets.images.enabled - true (il valore predefinito). Ogni immagine idonea sotto docs/assets/** (.png/.jpg/.jpeg) ottiene varianti ridimensionate/WebP generate tramite bx-image, e ogni <img> corrispondente viene riscritto in un <picture> con srcset. Imposta false per ricadere sulla semplice copia non elaborata delle immagini, esattamente come prima che questa funzionalità esistesse.
• assets.images.widths - i breakpoint da generare, in pixel. Una larghezza pari o superiore a quella propria di una data immagine viene saltata automaticamente per quell'immagine - niente viene mai ingrandito.
• assets.images.formats - "original" mantiene il formato sorgente come ripiego dell'<img>; "webp" aggiunge una variante <source type="image/webp"> alla stessa dimensione. Entrambi attivi di default.

mermaid

false (il valore predefinito) - nessun supporto per i diagrammi Mermaid distribuito. true carica mermaid.js lato client e renderizza ogni blocco di codice delimitato ```mermaid come un diagramma. Vedi Estensioni Markdown per la sintassi.

{ "mermaid": true }

math

false (il valore predefinito) - nessun KaTeX distribuito. true lo carica lato client e compone $...$/$$...$$ scritti direttamente nel markdown di una pagina. Vedi Estensioni Markdown per la sintassi.

{ "math": true }

Le ammonizioni (box di richiamo in stile nota/avviso/suggerimento), le schede di contenuto e le annotazioni hl_lines/linenums/title sui blocchi di codice delimitati sono sempre disponibili nel markdown di ogni pagina, senza bisogno di configurazione - vedi Estensioni Markdown.

plugins

[] (il valore predefinito) - un array di nomi di moduli BoxLang da attivare come plugin. Installare un modulo plugin (box install) non lo attiva mai da solo; deve essere nominato anche qui. Vedi Plugin per come scriverne uno.

{ "plugins": [ "myBxSitesPlugin" ] }

i18n

Metadati per la convenzione delle cartelle-locale docs/i18n/<code>/ - una locale si compila automaticamente una volta che la sua cartella esiste; i18n fornisce solo la sua etichetta di visualizzazione/direzione per il selettore di lingua.

• i18n.defaultLocale - { "code", "label" } per l'albero docs/ regolare del progetto, con valore predefinito { "code": "en", "label": "English" }. Va impostato solo quando la tua locale predefinita non è l'inglese.
• i18n.locales - [] (il valore predefinito) - un array di { "code", "label", "dir" } per ogni altra locale. code funge sia da nome della cartella docs/i18n/<code>/ sia da prefisso dell'URL compilato - solo lettere/cifre/trattini (es, pt-BR, zh-Hans). dir è "ltr" (il valore predefinito) oppure "rtl".

{
	"i18n": {
		"defaultLocale": { "code": "en", "label": "English" },
		"locales": [
			{ "code": "es", "label": "Español" },
			{ "code": "ar", "label": "العربية", "dir": "rtl" }
		]
	}
}

Vedi Internazionalizzazione per il quadro completo - il fallback per le pagine non tradotte, il selettore di lingua, e cosa non è ancora tradotto.

Versionamento

I documenti versionati sono convenzione più che configurazione - non c'è una chiave di bxsites.json per questo. Aggiungi una cartella docs/versions/, e ogni sottocartella diretta al suo interno viene compilata come un proprio albero di documenti completamente autonomo, accanto al tuo docs/ regolare (che si compila sempre come "Latest"):

docs/
├── index.md
├── guides/
└── versions/
    ├── 1.0/
    │   ├── index.md
    │   └── guides/
    └── 2.0/
        ├── index.md
        └── guides/

Ogni cartella di versione è un albero normale a forma di docs/ - il proprio index.md, la propria nav, le proprie pagine - compilato in site/versions/<name>/ con ogni link interno prefissato di conseguenza, e condividendo l'unico bxsites.json di configurazione/tema del progetto. I nomi delle versioni si ordinano dal più recente, numericamente piuttosto che alfabeticamente (quindi 2.0 si ordina prima di 10.0), e ogni tema renderizza automaticamente un menu a discesa per il cambio versione nell'header non appena esiste più di una versione - niente da attivare esplicitamente. Un file sciolto posizionato direttamente sotto docs/versions/ (non dentro una sottocartella) viene ignorato.

sitemap.xml e llms.txt includono le pagine di ogni versione insieme a quelle del sito principale.