---
title: Konfiguration
order: 4
icon: phosphor-duotone:gear-six
summary: Jeder Konfigurationsschlüssel, sein Standardwert und was er bewirkt.
tags: [referenz, konfiguration]
---
# Konfiguration
Jedes Projekt hat eine Website-Konfiguration in seinem Wurzelverzeichnis -
`bxsites.yaml` (oder `.yml`), das Standard- und bevorzugte Format, oder
`bxsites.json` für ein Projekt, das dabei bleiben möchte. Beide werden
vollständig unterstützt und liefern exakt dasselbe Ergebnis; `bxSites new`
erzeugt `bxsites.yaml`, sofern nicht `--format=json` übergeben wird (siehe
[Erste Schritte](getting-started.md#format-der-konfigurationsdatei)). Hat
ein Projekt aus irgendeinem Grund mehr als eine, gewinnt `bxsites.yaml`,
dann `bxsites.yml`, dann `bxsites.json`.
```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: []
```
Die äquivalente `bxsites.json`, für ein Projekt, das sie bevorzugt:
```json
{
"name": "My Docs",
"description": "",
"baseURL": "/",
"theme": {
"name": "bootstrap",
"options": {},
"logo": "",
"favicon": ""
},
"search": true,
"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": []
}
}
```
Nur `name` ist erforderlich - alles andere fällt auf die oben gezeigten
Standardwerte zurück. Ein teilweise angegebenes `theme`-Objekt wird eine
Ebene tief zusammengeführt, sodass `{"theme":{"name":"material"}}` allein
weiterhin die Standard-(leeren)-`options` behält. Jeder Schlüssel heißt in
beiden Formaten gleich und hat dieselbe Form; der Rest dieser Seite zeigt
der Kürze halber nur JSON, liest sich in YAML aber genauso.
## `name`
Der Name der Website, angezeigt in der Kopfzeile/Marke und in Seitentiteln.
Erforderlich.
## `description`
Eine optionale Website-Beschreibung, verwendet als Fallback für
`` und `og:description` für jede Seite, die keine
eigene `description`-Frontmatter setzt (siehe
[Erste Schritte](getting-started.md#seiten-hinzufügen)).
## `baseURL`
Steuert, wie jeder interne Link, Asset-Pfad und Navigationseintrag
vorangestellt wird, und dient zugleich als kanonische URL der Website für
`sitemap.xml` und `llms.txt`.
- Leer gelassen oder `"/"` (Standard) - Links bleiben root-relativ
(`/page/`), und weder `sitemap.xml` noch eine `llms.txt` mit absoluten
URLs wird erzeugt (es gibt keine kanonische Domain, aus der sie gebaut
werden könnten).
- Ein reiner Pfad, z. B. `"my-docs"` oder `"/my-docs/"` - es wird
angenommen, dass die Website unter diesem Unterpfad ausgeliefert wird,
und jeder interne Link, Navigationseintrag und jedes Asset wird damit
vorangestellt (`/my-docs/page/`). Immer noch keine `sitemap.xml`, da es
weiterhin keine absolute Domain gibt.
- Eine vollständige URL, z. B. `"https://docs.example.com/"` - der
Pfadanteil (hier `/`) wird genauso verwendet wie ein reiner Pfad, **und**
`sitemap.xml` wird zur Build-Zeit mit der absoluten URL jeder nicht
versteckten Seite unter dieser Domain geschrieben.
`llms.txt` (siehe [unten](#llmstxt)) wird immer geschrieben; sie bevorzugt
lediglich eine absolute URL, wenn `baseURL` eine solche liefert.
## `llms.txt`
Jeder Build schreibt eine `llms.txt` in die Wurzel der Website - ein
einfacher Markdown-Index jeder nicht versteckten Seite, gemäß der
aufkommenden [llms.txt](https://llmstxt.org)-Konvention, die
LLM-basierten Tools hilft, sich auf einer Website zurechtzufinden, ohne
deren gerendertes HTML zu crawlen. Es gibt dafür keinen Konfigurationsschlüssel;
sie wird automatisch erzeugt, mit einer absoluten URL pro Link, wenn
`baseURL` eine vollständige URL ist, andernfalls relativ zum `basePath`.
## `sitemap.xml`
Wird in der Wurzel der Website geschrieben, aber nur, wenn `baseURL` eine
vollständige URL ist (siehe oben) - eine Sitemap braucht eine absolute
Domain, um sinnvoll zu sein. Listet jede nicht versteckte Seite gemäß dem
[sitemaps.org](https://www.sitemaps.org/)-Protokoll auf.
## `theme`
- `theme.name` - eines der integrierten Themes (`bootstrap`, `material`,
`tailwind`) oder der Name eines eigenen Themes, das du über einen
`theme/`-Ordner im Projekt-Wurzelverzeichnis bereitstellst (siehe
[Themes](guides/themes.md))
- `theme.logo` - Pfad/URL zu einem Bild, das neben dem Website-Namen in der
Kopfzeilen-Marke angezeigt wird (anstelle des standardmäßigen
"⚡"-Symbols) - ein relativer Pfad (z. B. `"assets/logo.svg"`, aufgelöst
relativ zu `docs/assets/`) wird mit `baseURL` vorangestellt, wie jedes
andere interne Asset auch; eine absolute URL wird unverändert verwendet.
Leer gelassen (Standard), zeigt die Kopfzeile "⚡ <Website-Name>".
- `theme.favicon` - Pfad/URL zu einem Favicon, aufgelöst auf dieselbe Weise
wie `theme.logo`. Leer gelassen (Standard), wird gar kein
`` gerendert (es greift dann das Standardverhalten des
Browsers).
- `theme.options` - themenspezifische Optionen, von jedem integrierten
Theme gelesen:
- `theme.options.colorMode` - `"auto"` (Standard), `"light"` oder
`"dark"`. Steuert, welchen Modus ein Erstbesucher sieht, bevor er
selbst über den Dunkel-/Hell-Umschalter in der Kopfzeile eine Wahl
getroffen hat - `"auto"` folgt der Betriebssystem-Präferenz,
`"light"`/`"dark"` legt einen festen Standard fest. Sobald ein Besucher
den Schalter umlegt, gewinnt seine eigene Wahl (in `localStorage`
gespeichert) bei späteren Besuchen immer, unabhängig von dieser
Einstellung.
```json
{ "theme": { "options": { "colorMode": "dark" } } }
```
- `theme.options.navCollapsible` - `false` (Standard) rendert jede
Navigationsabschnitts-Überschrift stets ausgeklappt, wie bisher. `true`
rendert jeden Navigationsabschnitt (einen Ordner ohne `index.md`) als
natives ``/``-Element, das der Besucher einklappen
kann - kein JS-Framework nötig.
- `theme.options.navExpandAll` - nur relevant, wenn `navCollapsible`
`true` ist. `true` (Standard) startet jeden Abschnitt geöffnet;
`false` startet jeden Abschnitt eingeklappt.
```json
{ "theme": { "options": { "navCollapsible": true, "navExpandAll": false } } }
```
## `search`
`true` (Standard) baut einen statischen Suchindex und verdrahtet die
Suchbox; `false` überspringt beides vollständig - keine
`search-index.json`, keine Such-UI, kein zusätzliches JS ausgeliefert.
Siehe [Suche](guides/search.md).
## `nav`
Standardmäßig wird die Navigation aus der eigenen Ordner-/Dateistruktur von
`docs/` abgeleitet (mit `order`/`hidden`-Frontmatter) - für kleine
Websites ausreichend, aber eine große Website kann daraus herauswachsen:
eine explizite Navigation erlaubt es dir, Seiten zu betiteln, zu gruppieren
und zu ordnen, ganz unabhängig davon, wo ihre Dateien tatsächlich liegen.
Ein leeres Array (Standard) bedeutet "aus der Ordnerstruktur ableiten". Ein
nicht leeres Array ersetzt diese Ableitung vollständig - die Array-Reihenfolge
wird zur Navigationsreihenfolge, und eine Seite, auf die darin nirgendwo
verwiesen wird, wird trotzdem gebaut, nur nicht aus der Navigation
verlinkt (wie bei `hidden: true`). Jeder Eintrag ist entweder:
- eine reine, docs/-relative Pfad-Zeichenkette, z. B. `"guides/setup.md"` -
der Titel stammt aus der eigenen Frontmatter/dem Dateinamen dieser Seite,
genau wie bei der Ordner-Ableitung
- ein Objekt `{ "title", "path", "icon", "children" }` - `path`, `icon`
und `children` sind alle optional; ein Eintrag nur mit `title` und ohne
`path` ist eine unverlinkte Gruppenüberschrift (wie ein Ordner ohne
`index.md` heute), und ein explizites `title`/`icon` überschreibt immer
den eigenen Titel/das eigene Icon der verlinkten Seite in der Navigation
(das echte `