---
title: Configuración
order: 4
icon: phosphor-duotone:gear-six
summary: Cada clave de la configuración del sitio, su valor por defecto y qué hace.
tags: [referencia, configuración]
---
# Configuración
Cada proyecto tiene una configuración de sitio única en su raíz -
`bxsites.yaml` (o `.yml`), el formato por defecto y preferido, o
`bxsites.json` para un proyecto que prefiera quedarse con él. Ambos son
totalmente compatibles y producen exactamente el mismo resultado;
`bxSites new` genera `bxsites.yaml` a menos que se pase `--format=json`
(consulta [Primeros Pasos](getting-started.md#formato-del-archivo-de-configuración)).
Si un proyecto de algún modo tiene más de uno, `bxsites.yaml` prevalece,
luego `bxsites.yml`, luego `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: []
blog:
postsPerPage: 10
feed: true
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": []
},
"blog": {
"postsPerPage": 10,
"feed": true
},
"variables": {}
}
```
Solo `name` es obligatorio - todo lo demás recurre a los valores por
defecto mostrados arriba. Un objeto `theme` parcial se combina un nivel
de profundidad, así que `{theme: {name: material}}` por sí solo conserva
las `options` por defecto (vacías). Cada clave de abajo se llama y tiene
la misma forma en ambos formatos - cambia de pestaña en cualquier ejemplo
de abajo para verlo en la otra forma.
## `name`
El nombre del sitio, mostrado en la marca de la cabecera y en los títulos
de página. Obligatorio.
## `description`
Una descripción de sitio opcional, usada como ``
y `og:description` de reserva para cualquier página que no defina su
propio frontmatter `description` (consulta
[Primeros Pasos](getting-started.md#añadir-páginas)).
## `baseURL`
Controla cómo se antepone el prefijo a cada enlace interno, ruta de
recurso y entrada de navegación, y también actúa como la URL canónica
del sitio para `sitemap.xml`, `robots.txt`, `llms.txt`, y la propia
etiqueta `` de cada página.
- Dejado en blanco o `"/"` (el valor por defecto) - los enlaces
permanecen relativos a la raíz (`/page/`), y no se genera ni
`sitemap.xml`, ni una línea `Sitemap:` en `robots.txt`, ni un
`llms.txt` con URL absoluta, ni una etiqueta
`` (no hay un dominio canónico a partir del
cual construirlos).
- Una ruta simple, por ejemplo `"my-docs"` o `"/my-docs/"` - se asume que
el sitio se sirve desde esa subruta, y cada enlace interno, entrada de
navegación y recurso lleva ese prefijo (`/my-docs/page/`). Siguen sin
generarse `sitemap.xml`/etiquetas canónicas, ya que todavía no hay un
dominio absoluto.
- Una URL completa, por ejemplo `"https://docs.example.com/"` - la parte
de la ruta (`/` aquí) se usa de la misma forma que lo haría una ruta
simple, **y** `sitemap.xml` se escribe en el momento de la construcción
con la URL absoluta de cada página no oculta bajo ese dominio,
`robots.txt` obtiene una línea `Sitemap:` que apunta a él, y cada
página obtiene su propia `` correcta (la propia
página de un árbol de versión/idioma sigue apuntando a la URL *de ese
mismo árbol*, no a la del sitio principal).
`llms.txt` (consulta [más abajo](#llmstxt)) siempre se escribe; simplemente
prefiere una URL absoluta cuando `baseURL` la proporciona.
## `llms.txt`
Cada construcción escribe un `llms.txt` en la raíz del sitio - un índice
en Markdown simple de cada página no oculta, siguiendo la convención
emergente de [llms.txt](https://llmstxt.org) para ayudar a las
herramientas basadas en LLM a navegar un sitio sin rastrear su HTML
renderizado. No hay clave de configuración para esto; se genera
automáticamente, usando una URL absoluta por enlace cuando `baseURL` es
una URL completa, o una relativa a `basePath` en caso contrario.
## `sitemap.xml`
Se escribe en la raíz del sitio, pero solo cuando `baseURL` es una URL
completa (ver arriba) - un sitemap necesita un dominio absoluto para
tener sentido. Enumera cada página no oculta según el protocolo de
[sitemaps.org](https://www.sitemaps.org/).
## `robots.txt`
Cada construcción escribe un `robots.txt` en la raíz del sitio - no hace
falta ninguna clave de configuración a menos que quieras cambiar su
comportamiento por defecto, permisivo:
=== "YAML"
```yaml title="bxsites.yaml"
robots: false
```
=== "JSON"
```json title="bxsites.json"
{ "robots": false }
```
- `true` (el valor por defecto) - `Allow: /` para cada rastreador, además
de una línea `Sitemap:` que apunta a `sitemap.xml` cuando `baseURL` es
una URL completa (ver arriba).
- `false` - `Disallow: /` para cada rastreador en su lugar, y sin línea
`Sitemap:` - la necesidad habitual de "no indexes en absoluto este
despliegue de staging/interno". Esto es solo una exclusión de
*rastreadores*, no un control de acceso - el sitio sigue siendo
totalmente alcanzable por cualquiera que tenga la URL; consulta
[Despliegue](guides/deployment.md#restringir-quién-puede-acceder-a-tu-sitio)
si de verdad necesitas restringir quién puede acceder a él.
¿Necesitas más que el simple interruptor de activar/desactivar - rutas
específicas no permitidas, varias líneas `Sitemap:`, un `Crawl-delay`,
reglas por agente de usuario? Coloca tu propio `robots.txt` justo al lado
de `index.md` (`docs/robots.txt`, o `src/robots.txt` para un proyecto
basado en `src/` - consulta
[`docs/` o `src/`](getting-started.md#añadir-páginas)) y se copia tal
cual, byte a byte, en lugar del generado, en cada construcción - la clave
`robots` de arriba se ignora por completo en cuanto existe este archivo.
## `theme`
- `theme.name` - uno de los temas incorporados (`bootstrap`, `material`,
`tailwind`), o el nombre de un tema personalizado que proporciones
mediante una carpeta `theme/` en la raíz del proyecto (consulta
[Temas](guides/themes.md))
- `theme.logo` - ruta/URL a una imagen mostrada junto al nombre del sitio
en la marca de la cabecera (en lugar del glifo "⚡" por defecto) - una
ruta relativa (por ejemplo `"assets/logo.svg"`, resuelta contra
`docs/assets/`) lleva el prefijo `baseURL` como cualquier otro recurso
interno; una URL absoluta se usa tal cual. Dejado en blanco (el valor
por defecto), la cabecera muestra "⚡ <nombre del sitio>".
- `theme.favicon` - ruta/URL a un favicon, resuelta de la misma forma que
`theme.logo`. Dejado en blanco (el valor por defecto), no se renderiza
ningún `` en absoluto (recurriendo al comportamiento
por defecto propio del navegador).
- `theme.options` - opciones específicas del tema, leídas por todos los
temas incorporados:
- `theme.options.colorMode` - `"auto"` (el valor por defecto), `"light"`
o `"dark"`. Controla qué modo ve un visitante por primera vez antes de
haber elegido uno propio mediante el interruptor claro/oscuro de la
cabecera - `"auto"` sigue la preferencia de su sistema operativo,
`"light"`/`"dark"` fija un valor por defecto. Una vez que un visitante
activa el interruptor, su propia elección (guardada en `localStorage`)
siempre prevalece en visitas posteriores, independientemente de este
valor.
=== "YAML"
```yaml
theme: { options: { colorMode: dark } }
```
=== "JSON"
```json
{ "theme": { "options": { "colorMode": "dark" } } }
```
- `theme.options.navCollapsible` - `false` (el valor por defecto)
renderiza cada sección de navegación siempre expandida, como hoy.
`true` da a cada sección con hijos un botón de alternancia que el
visitante puede pulsar para colapsarla/expandirla - ya sea que esa
sección sea un simple encabezado de grupo (una carpeta sin
`index.md`) o que enlace a su propia página. La sección que contiene
la página en la que estás actualmente siempre empieza abierta,
independientemente de `navExpandAll`, así que navegar hasta ahí nunca
entierra el propio enlace en el que te encuentras.
- `theme.options.navExpandAll` - solo relevante cuando `navCollapsible`
es `true`. `true` (el valor por defecto) inicia cada sección abierta;
`false` inicia cada sección colapsada, excepto la que contiene la
página actual.
=== "YAML"
```yaml
theme: { options: { navCollapsible: true, navExpandAll: false } }
```
=== "JSON"
```json
{ "theme": { "options": { "navCollapsible": true, "navExpandAll": false } } }
```
- `theme.options.tocPosition` - dónde se renderiza la propia tabla de
contenido "En esta página" de una página. `"top"` (el valor por
defecto) la renderiza en línea, en la parte superior del artículo,
como hoy. `"sticky"` la traslada a su propia columna a la derecha que
permanece visible mientras el artículo se desplaza por debajo de
ella - la misma lista "En esta página", solo que fija, lo cual ayuda
en páginas largas. La columna fija solo cabe en viewports anchos (se
oculta por debajo del punto en el que un diseño de 3 columnas
resultaría apretado); por debajo de ese ancho, el modo `sticky`
renderiza en su lugar una barra colapsable "En esta página" fijada en
la parte superior del viewport mientras se hace scroll - toca para
expandir la lista, el mismo tratamiento que usan VitePress/GitBook en
móvil - así que la tabla de contenido sigue siendo accesible en
cualquier ancho de viewport, solo cambia de forma según el espacio
disponible.
=== "YAML"
```yaml
theme: { options: { tocPosition: sticky } }
```
=== "JSON"
```json
{ "theme": { "options": { "tocPosition": "sticky" } } }
```
- `theme.options.pageMetaPosition` - dónde se renderiza la fila de
editar-esta-página/descargar-markdown/última-actualización en
relación con el propio contenido de la página. `"bottom"` (el valor
por defecto) la renderiza como una pequeña nota de pie justo antes de
que termine el artículo. `"top"` la renderiza en su lugar cerca del
título, el mismo lugar donde siempre se renderizaba antes de que
existiera esta opción.
=== "YAML"
```yaml
theme: { options: { pageMetaPosition: top } }
```
=== "JSON"
```json
{ "theme": { "options": { "pageMetaPosition": "top" } } }
```
## `search`
`true` (el valor por defecto) construye un índice de búsqueda estático y
conecta el cuadro de búsqueda; `false` omite ambos por completo - sin
`search-index.json`, sin interfaz de búsqueda, sin JS adicional enviado.
Consulta [Búsqueda](guides/search.md).
## `searchProvider`
Qué interfaz de búsqueda conecta `search: true`:
- `provider` - `"local"` (el valor por defecto) es la propia búsqueda
estática/del lado del cliente de bx-sites (`search-index.json` +
lunr.js, consulta [Búsqueda](guides/search.md#local-el-predeterminado)).
`"algolia"` conecta en su lugar
[Algolia DocSearch](guides/search.md#algolia), y `"pagefind"` conecta
[Pagefind](guides/search.md#pagefind). Cualquier otro valor es un
proveedor personalizado propio de un proyecto, conectado mediante una
sobrescritura `theme/` - consulta
[Búsqueda](guides/search.md#otros-proveedores-de-búsqueda).
- `algolia` - obligatorio cuando `provider` es `"algolia"`: `appId`,
`apiKey` (la clave API pública *solo de búsqueda*, no una clave de
administrador) e `indexName`, exactamente como los espera el propio
cliente DocSearch de Algolia. `insights` (`false` por defecto) activa la
analítica de clics/conversión de 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` - ambas claves opcionales cuando `provider` es `"pagefind"`:
`bin` (por defecto `"pagefind"`) es el nombre/ruta del ejecutable de la
CLI, resuelto contra `PATH` cuando es un nombre simple; `options` es un
array de flags de CLI adicionales en bruto que se pasan tal cual. La
propia CLI de `pagefind` debe estar ya instalada y en el `PATH` - BX
Sites la invoca externamente (como hace con `git` para
`lastUpdated`/`gh-deploy`), no la instala por ti.
=== "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`
Por defecto, la navegación se infiere de la propia estructura de
carpetas/archivos de `docs/` (con el frontmatter `order`/`hidden`) - bien
para sitios pequeños, pero uno grande puede superarla: una navegación
explícita te permite titular, agrupar y ordenar las páginas como quieras,
independientemente de dónde vivan realmente sus archivos.
Un array vacío (el valor por defecto) significa "inferir de la estructura
de carpetas". Un array no vacío reemplaza esa inferencia por completo -
el orden del array se convierte en el orden de la navegación, y una
página no referenciada en ningún lugar de él igualmente se construye,
solo que no se enlaza desde la navegación (igual que `hidden: true`).
Cada entrada es o bien:
- una cadena con una ruta simple relativa a docs/, por ejemplo
`"guides/setup.md"` - el título proviene del propio frontmatter/nombre
de archivo de esa página, igual que daría la inferencia por carpetas
- un objeto `{ "title", "path", "icon", "children" }` - `path`, `icon` y
`children` son todos opcionales; una entrada solo con `title` y sin
`path` es un encabezado de grupo sin enlace (como una carpeta sin
`index.md` hoy en día), y un `title`/`icon` explícito siempre sobrescribe
el título/icono propio de la página enlazada en la navegación (el
`