---
title: Configurazione
order: 4
icon: phosphor-duotone:gear-six
summary: Ogni chiave della configurazione del sito, il suo valore predefinito e cosa fa.
tags: [riferimento, configurazione]
---
# 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](getting-started.md#formato-del-file-di-configurazione)). Se
un progetto ne ha in qualche modo più di uno, vince `bxsites.yaml`, poi
`bxsites.yml`, poi `bxsites.json`.
=== "YAML"
```yaml
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: []
variables: {}
```
=== "JSON"
```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": []
},
"variables": {}
}
```
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 - cambia scheda in
qualsiasi esempio qui sotto per vederlo nell'altra forma.
## `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 ``
e `og:description` di riserva per qualsiasi pagina che non imposti una
propria `description` nel frontmatter (vedi [Per iniziare](getting-started.md#add-pages)).
## `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`,
`robots.txt`, `llms.txt` e per il tag `` di ogni
pagina.
- Lasciato vuoto o `"/"` (il valore predefinito) - i link restano relativi
alla radice (`/page/`), e non viene generato né `sitemap.xml`, né una
riga `Sitemap:` in `robots.txt`, né un `llms.txt` con URL assoluti, né un
tag `` (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`/tag canonici, 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, `robots.txt`
guadagna una riga `Sitemap:` che vi punta, e ogni pagina ottiene il
proprio `` corretto (la pagina di un albero di
versione/locale punta comunque all'URL *di quello stesso albero*, non a
quello del sito principale).
`llms.txt` (vedi [sotto](#llmstxt)) viene sempre scritto; preferisce
semplicemente un URL assoluto quando `baseURL` ne fornisce uno.
## `robots.txt`
Ogni build scrive un `robots.txt` alla radice del sito - nessuna chiave di
configurazione necessaria, a meno che tu non voglia cambiarne il
comportamento predefinito, permissivo:
=== "YAML"
```yaml title="bxsites.yaml"
robots: false
```
=== "JSON"
```json title="bxsites.json"
{ "robots": false }
```
- `true` (il valore predefinito) - `Allow: /` per ogni crawler, più una
riga `Sitemap:` che punta a `sitemap.xml` quando `baseURL` è un URL
completo (vedi sopra).
- `false` - `Disallow: /` per ogni crawler al suo posto, e nessuna riga
`Sitemap:` - la comune esigenza di "non indicizzare affatto questo
deploy di staging/interno". Questa è solo un'esclusione per i
*crawler*, non un controllo degli accessi - il sito resta comunque
pienamente raggiungibile da chiunque ne abbia l'URL; vedi
[Distribuzione](guides/deployment.md#limitare-chi-può-raggiungere-il-tuo-sito)
se hai davvero bisogno di limitare chi può raggiungerlo.
Ti serve più del semplice interruttore on/off - percorsi specifici da
escludere, più righe `Sitemap:`, un `Crawl-delay`, regole per singolo
user-agent? Metti il tuo `robots.txt` proprio accanto a `index.md`
(`docs/robots.txt`, o `src/robots.txt` per un progetto basato su `src/` -
vedi [`docs/` o `src/`](getting-started.md#aggiungere-pagine)) e viene copiato
byte per byte al posto di quello generato, a ogni build - la chiave
`robots` sopra viene del tutto ignorata una volta che questo file esiste.
## `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](https://llmstxt.org) 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](https://www.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](guides/themes.md))
- `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 `` (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.
=== "YAML"
```yaml
theme: { options: { colorMode: dark } }
```
=== "JSON"
```json
{ "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 ``/`` 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.
=== "YAML"
```yaml
theme: { options: { navCollapsible: true, navExpandAll: false } }
```
=== "JSON"
```json
{ "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](guides/search.md).
## `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](guides/search.md#local-the-default)). `"algolia"` attiva
invece [Algolia DocSearch](guides/search.md#algolia), e `"pagefind"`
attiva [Pagefind](guides/search.md#pagefind). Qualsiasi altro valore è un
provider personalizzato del progetto, collegato tramite una
sovrascrittura `theme/` - vedi
[Ricerca](guides/search.md#other-search-providers).
- `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.
=== "YAML"
```yaml title="bxsites.yaml" linenums="1"
search: true
searchProvider:
provider: algolia
algolia:
appId: ABC123
apiKey: a1b2c3d4e5f6...
indexName: my-docs
```
=== "JSON"
```json title="bxsites.json" linenums="1"
{
"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` - BxSites
ci esegue uno shell out (come `git` per `lastUpdated`/`gh-deploy`), non
la installa al posto tuo.
=== "YAML"
```yaml title="bxsites.yaml" linenums="1"
search: true
searchProvider:
provider: pagefind
pagefind: { bin: pagefind, options: [] }
```
=== "JSON"
```json title="bxsites.json" linenums="1"
{
"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'`