Konfiguration

Jeder Konfigurationsschlüssel, sein Standardwert und was er bewirkt.

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). Hat ein Projekt aus irgendeinem Grund mehr als eine, gewinnt bxsites.yaml, dann bxsites.yml, dann 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: []
assets:
  fingerprint: true
  bundle: true
  images: { enabled: true, widths: [400, 800, 1200, 1600], formats: [original, webp] }
plugins: []
i18n:
  defaultLocale: { code: en, label: English }
  locales: []
blog:
  postsPerPage: 10
  feed: true
variables: {}

{
	"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": [],
	"assets": {
		"fingerprint": true,
		"bundle": true,
		"images": { "enabled": true, "widths": [400, 800, 1200, 1600], "formats": ["original", "webp"] }
	},
	"plugins": [],
	"i18n": {
		"defaultLocale": { "code": "en", "label": "English" },
		"locales": []
	},
	"blog": {
		"postsPerPage": 10,
		"feed": true
	},
	"variables": {}
}

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 unten heißt in beiden Formaten gleich und hat dieselbe Form - wechsle bei jedem Beispiel unten einfach den Tab, um es in der jeweils anderen Form zu sehen.

name

Der Name der Website, angezeigt in der Kopfzeile/Marke und in Seitentiteln. Erforderlich.

description

Eine optionale Website-Beschreibung, verwendet als Fallback für <meta name="description"> und og:description für jede Seite, die keine eigene description-Frontmatter setzt (siehe Erste Schritte).

baseURL

Steuert, wie jeder interne Link, Asset-Pfad und Navigationseintrag vorangestellt wird, und dient zugleich als kanonische URL der Website für sitemap.xml, robots.txt, llms.txt und das eigene <link rel="canonical">-Tag jeder Seite.

• Leer gelassen oder "/" (Standard) - Links bleiben root-relativ (/page/), und weder sitemap.xml, eine Sitemap:-Zeile in robots.txt, eine llms.txt mit absoluten URLs, noch ein <link rel="canonical">-Tag 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/ Canonical-Tags, 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, robots.txt erhält eine Sitemap:-Zeile, die darauf zeigt, und jede Seite bekommt ihr eigenes korrektes <link rel="canonical"> (die eigene Seite eines Versions-/Locale-Baums zeigt weiterhin auf die URL dieses Baums selbst, nicht auf die der Haupt-Website).

llms.txt (siehe unten) 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-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-Protokoll auf.

robots.txt

Jeder Build schreibt eine robots.txt in die Wurzel der Website - kein Konfigurationsschlüssel nötig, es sei denn, du möchtest ihr standardmäßig erlaubendes Verhalten ändern:

robots: false

{ "robots": false }

• true (Standard) - Allow: / für jeden Crawler, plus eine Sitemap:-Zeile, die auf sitemap.xml zeigt, wenn baseURL eine vollständige URL ist (siehe oben).
• false - stattdessen Disallow: / für jeden Crawler, und keine Sitemap:-Zeile - der übliche Bedarf "dieses Staging-/internes Deploy überhaupt nicht indexieren lassen". Das ist nur ein Crawler-Opt-out, keine Zugriffskontrolle - die Website bleibt für jeden, der die URL hat, weiterhin vollständig erreichbar; siehe Deployment, falls du tatsächlich einschränken musst, wer überhaupt darauf zugreifen kann.

Brauchst du mehr als den Ein-/Aus-Schalter - bestimmte gesperrte Pfade, mehrere Sitemap:-Zeilen, ein Crawl-delay, Regeln pro User-Agent? Lege deine eigene robots.txt direkt neben index.md ab (docs/robots.txt, oder src/robots.txt für ein src/-basiertes Projekt - siehe docs/ oder src/), und sie wird byte-für-byte durchgereicht statt der generierten, bei jedem Build - der robots-Schlüssel oben wird vollständig ignoriert, sobald diese Datei existiert.

theme

• theme.name - eines der integrierten Themes (bootstrap, material, tailwind, docsy, slate, docusaurus, justthedocs, vuepress, gitbook, notion) oder der Name eines eigenen Themes, das du über einen theme/-Ordner im Projekt-Wurzelverzeichnis bereitstellst (siehe Themes)
• 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 <link rel="icon"> 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.

    theme: { options: { colorMode: dark } }
    ```

=== "JSON"
    ```json
    { "theme": { "options": { "colorMode": "dark" } } }
    ```

• theme.options.navCollapsible - false (Standard) rendert jeden Navigationsabschnitt stets ausgeklappt, wie bisher. true gibt jedem Abschnitt mit Kindern eine Umschalt-Schaltfläche, mit der der Besucher ihn ein-/ausklappen kann - egal, ob dieser Abschnitt eine reine Gruppenüberschrift ist (ein Ordner ohne index.md) oder auf eine eigene Seite verlinkt. Der Abschnitt, der die gerade angezeigte Seite enthält, startet immer geöffnet, unabhängig von navExpandAll, damit das Navigieren dorthin nie den eigenen Link verdeckt, auf dem man gerade steht.
• theme.options.navExpandAll - nur relevant, wenn navCollapsible true ist. true (Standard) startet jeden Abschnitt geöffnet; false startet jeden Abschnitt eingeklappt, außer dem, der die aktuelle Seite enthält.

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

=== "JSON"
    ```json
    { "theme": { "options": { "navCollapsible": true, "navExpandAll": false } } }
    ```

• theme.options.tocPosition - wo das eigene Inhaltsverzeichnis ("Auf dieser Seite") einer Seite gerendert wird. "top" (Standard) rendert es inline, oben im Artikel, wie bisher. "sticky" verschiebt es in eine eigene rechte Spalte, die beim Scrollen des darunterliegenden Artikels sichtbar bleibt - dieselbe "Auf dieser Seite"-Liste, nur fixiert, was bei langen Seiten hilft. Die fixierte Spalte passt nur auf breite Viewports (sie ist unterhalb des Punkts ausgeblendet, an dem ein dreispaltiges Layout zu eng würde); unterhalb dieser Breite rendert der sticky-Modus stattdessen eine einklappbare "Auf dieser Seite"-Leiste, die beim Scrollen oben am Viewport fixiert bleibt - antippen, um die Liste auszuklappen, dieselbe Behandlung, die auch VitePress/GitBook auf Mobilgeräten verwenden - sodass das Inhaltsverzeichnis bei jeder Viewport-Breite erreichbar bleibt, nur seine Form ändert sich je nach verfügbarem Platz.

    theme: { options: { tocPosition: sticky } }
    ```

=== "JSON"
    ```json
    { "theme": { "options": { "tocPosition": "sticky" } } }
    ```

• theme.options.pageMetaPosition - wo die Zeile mit Bearbeiten-diese-Seite/Markdown-herunterladen/Zuletzt-aktualisiert relativ zum eigenen Inhalt einer Seite gerendert wird. "bottom" (Standard) rendert sie als kleine Fußnotiz kurz vor Ende des Artikels. "top" rendert sie stattdessen oben in der Nähe des Titels, an derselben Stelle, an der sie immer gerendert wurde, bevor es diese Option gab.

    theme: { options: { pageMetaPosition: top } }
    ```

=== "JSON"
    ```json
    { "theme": { "options": { "pageMetaPosition": "top" } } }
    ```

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.

searchProvider

Welche Such-UI search: true verdrahtet:

• provider - "local" (Standard) ist bx-sites' eigene statische/ clientseitige Suche (search-index.json + lunr.js, siehe Suche). "algolia" verdrahtet stattdessen Algolia DocSearch, und "pagefind" verdrahtet Pagefind. Jeder andere Wert ist ein eigener, projektspezifischer Provider, verdrahtet über ein theme/-Override - siehe Suche.
• algolia - erforderlich, wenn provider "algolia" ist: appId, apiKey (der reine Such-öffentliche API-Schlüssel, kein Administrator-Schlüssel) und indexName, genau wie es Algolias eigener DocSearch-Client erwartet. insights (standardmäßig false) schaltet DocSearchs Klick-/Konversions-Analytics ein.

  search: true
  searchProvider:
    provider: algolia
    algolia:
      appId: ABC123
      apiKey: a1b2c3d4e5f6...
      indexName: my-docs

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

• pagefind - beide Schlüssel optional, wenn provider "pagefind" ist: bin (Standard "pagefind") ist der Name/Pfad der CLI-Binary, aufgelöst gegen PATH, wenn es ein reiner Name ist; options ist ein Array zusätzlicher, roher CLI-Flags, die direkt durchgereicht werden. Die pagefind-CLI selbst muss bereits installiert und im PATH vorhanden sein - BxSites ruft sie extern auf (wie git für lastUpdated/gh-deploy), es installiert sie nicht für dich.

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

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

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 <h1>/<title> der Seite bleibt unangetastet - nur das Navigations-Label/-Icon ändert sich) - siehe Icons dafür, was ein icon-Wert sein kann

Ein Eintrag nur mit title, mit children und ohne path ist genau ein Menü-Container/Abschnitts-Label - eine nicht klickbare Überschrift, die nur ihre Kinder gruppiert, dieselbe Rolle, die "MAIN COMPONENTS" in GitBooks eigener Seitenleiste spielt:

nav:
  - index.md
  - title: Main Components
    children:
      - title: Quick Start
        path: guides/setup.md
      - guides/deployment.md

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

Gib demselben Gruppeneintrag stattdessen einen path, und er wird zu einem normal verlinkten Abschnitt (mit eigener Landingpage plus Kindern) statt eines reinen Labels - beide Formen verschachteln sich unter theme.options.navCollapsible auf dieselbe Weise (siehe oben).

Für eine Navigation, die groß genug ist, um bxsites.yaml zu überladen, verschiebe sie in eine eigene docs/nav.json-Datei - dieselbe Array-Form, nur als kompletter Top-Level-Inhalt der Datei:

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

Das eigene nav von bxsites.yaml gewinnt, wenn es nicht leer ist, immer gegenüber docs/nav.json. Nur der Hauptbaum berücksichtigt eines von beiden - ein docs/versions/<name>/-Baum leitet seine Navigation immer aus seiner eigenen Ordnerstruktur ab, selbst wenn der Hauptbaum eine explizite Navigation hat.

redirects

[] (Standard) - websiteweite from/to-Weiterleitungen für alte URLs, nur auf den Hauptbaum angewendet:

redirects:
  - from: old-guide
    to: guides/new-guide/

{
	"redirects": [
		{ "from": "old-guide", "to": "guides/new-guide/" }
	]
}

• redirects[].from - das alte hübsche URL-Segment, an dem eine statische Weiterleitungs-Stub-Datei geschrieben wird (kein führender/abschließender Schrägstrich, keine Dateiendung)
• redirects[].to - ein root-relativer Pfad (aufgelöst gegen baseURL) oder eine vollständige https://-URL

Die eigene Frontmatter redirect_from einer Seite ist die Alternative pro Seite/pro Baum (funktioniert auch innerhalb eines Versions-/Locale-Baums) - siehe Weiterleitungen für das vollständige Bild, einschließlich wie page:rename sie automatisch setzt.

markdown

Wird unverändert an bx-markdowns eigene Modul-Einstellungen weitergereicht, bevor jede Seite gerendert wird. BxSites definiert oder validiert diese Schlüssel nicht neu; was auch immer du hier einträgst, ist direkt bx-markdowns eigenes Optionsset - diese Liste kann sich also im Lauf der Zeit von bx-markdowns eigener unterscheiden. Tabellen, ~~Durchgestrichen~~, - [ ]-Task-List-Checkboxen und das Inhaltsverzeichnis innerhalb der Seite sind immer aktiv, ohne Umschaltmöglichkeit. Die eine Ausnahme ist enableAdmonition - bx-markdown selbst setzt es standardmäßig auf false, aber BxSites setzt es standardmäßig auf true (siehe die Markdown-Erweiterungen-Anleitung).

Jede gerenderte Tabelle erhält außerdem automatisch einen Wrapper für responsives Scrollen und einen fixierten Kopfbereich, ohne eigenen Konfigurationsschlüssel - siehe Tabellen.

markdown:
  enableFootnotes: true
  enableDefinitionLists: true
  anchorLinks: false
  enableYouTubeTransformer: true

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

repo

Fügt der Kopfzeile (in jedem integrierten Theme) einen Repository-Icon-Link hinzu und, wenn beide Schlüssel gesetzt sind, jeder Seite einen "Diese Seite bearbeiten"-Link.

• repo.url - die URL deines Repos, z. B. "https://github.com/acme/docs". Rendert für sich genommen bereits den Icon-Link in der Kopfzeile; leer lassen, um ihn ganz wegzulassen.
• repo.editUri - das Pfadsegment zwischen der Repo-URL und dem eigenen Quellpfad einer Seite, z. B. "edit/main/docs/" (GitHubs eigene "edit"-URL-Konvention). Wird mit repo.url und dem docs/-relativen Quellpfad einer Seite kombiniert, um ihren Bearbeiten-Link zu bauen - z. B. mit dem Beispiel oben ergibt docs/guides/setup.md https://github.com/acme/docs/edit/main/docs/guides/setup.md. Erfordert ebenfalls repo.url; leer lassen, um Bearbeiten-Links wegzulassen und trotzdem das Icon in der Kopfzeile zu zeigen.

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

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

social

Ein Array von Social-/externen Links, die in der Fußzeile gerendert werden (siehe footer - hat ohne diesen keine Wirkung). Jeder Eintrag braucht eine url; icon wählt aus einem kleinen integrierten Icon-Set (github, twitter/x, youtube, linkedin, facebook, bluesky, threads, slack, patreon, rss, email, mit einem generischen Link-Symbol als Fallback für alles andere), und label setzt den barrierefreien Namen/Tooltip des Links (Standard ist icon, dann "Link").

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

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

footer

false (Standard) - überhaupt keine Fußzeile. true fügt jeder Seite eine hinzu: eine Copyright-Zeile (© <Jahr> <Website-Name>), die social-Links (falls vorhanden) und einen "Built with BxSites"-Hinweis.

footer: true

{ "footer": true }

lastUpdated

false (Standard) - kein Datum der letzten Aktualisierung. true fügt eine "Zuletzt aktualisiert"-Zeile neben dem Bearbeiten-Link hinzu (oder für sich allein, wenn repo.editUri nicht gesetzt ist), ermittelt aus dem git log der eigenen Markdown-Datei jeder Seite zur Build-Zeit. Wird stillschweigend ausgelassen für eine Seite, für die Git keine Historie hat - ein frisches git init ohne bisherige Commits, ein Build aus einem heruntergeladenen ZIP ohne .git überhaupt, oder Git ist auf der Build-Maschine nicht installiert - statt den Build abzubrechen.

lastUpdated: true

{ "lastUpdated": true }

analytics

Bindet Pageview-Analytics ein. Unterstützt derzeit nur Google Analytics (gtag.js):

• analytics.provider - "google", um es zu aktivieren; leer gelassen (Standard), wird gar kein Analytics-Skript ausgeliefert.
• analytics.id - die Google-Analytics-Measurement-ID (z. B. "G-ABC123"). Erforderlich, wenn provider "google" ist.

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

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

ogImage

Pfad/URL zu einem Standard-Social-Card-Bild, gerendert als og:image (gepaart mit einem twitter:card von summary_large_image) auf jeder Seite, die es nicht überschreibt - aufgelöst auf dieselbe Weise wie theme.logo (relative Pfade werden mit baseURL vorangestellt, absolute URLs unverändert verwendet). Leer gelassen (Standard) und generateOgImages deaktiviert, werden gar keine og:image/twitter:card-Tags gerendert.

ogImage: assets/social-card.png

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

Die eigene ogImage-Frontmatter einer Seite (siehe Erste Schritte) gewinnt für diese eine Seite immer gegenüber diesem websiteweiten Standard.

generateOgImages

false (Standard) - keine seitenweisen Cards. true rendert für jede Seite, die noch keine eigene ogImage-Frontmatter hat, eine echte 1200x630-PNG-Social-Card - den Seitentitel auf dem Marken-Gradienten, geschrieben nach site/assets/og/<page>.png - statt dass sich alle Seiten ein generisches, websiteweites Bild teilen. Rein java.awt/javax.imageio unter der Haube (Teil jeder JVM, auf der BoxLang läuft), sodass dafür kein Headless-Browser, kein externer Dienst und kein Netzwerkzugriff zur Build-Zeit nötig ist.

generateOgImages: true

{ "generateOgImages": true }

extraCss / extraJs

Arrays zusätzlicher Stylesheet-/Skript-URLs, die auf jeder Seite eingebunden werden, nach den eigenen Assets des Themes - jeder Eintrag wird auf dieselbe Weise aufgelöst wie theme.logo (ein relativer Pfad wird mit baseURL vorangestellt; eine absolute URL wird unverändert verwendet). extraJs-Einträge werden mit defer geladen.

extraCss: [ assets/custom.css ]
extraJs: [ assets/custom.js ]

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

Wenn assets.bundle aktiv ist (Standard), wird eine lokale extraCss/extraJs-Liste wie die obige jeweils zu einer fingerprinted Datei gebündelt, statt einem <link>/<script>-Tag pro Eintrag - siehe assets unten.

assets

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

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

Die Asset-Pipeline - Bildskalierung/WebP über bx-image (eine erforderliche Abhängigkeit, mitinstalliert neben bx-markdown/bx-esapi) und CSS/JS-Bundling. Hier ist standardmäßig alles mit sinnvollen Einstellungen aktiv - ein frisches bxSites new-Projekt muss davon nichts anfassen. Siehe Responsive Bilder für das vollständige Bild, einschließlich dessen, was bewusst nicht abgedeckt wird (AVIF, animierte GIFs, SVGs).

• assets.fingerprint - true (Standard). Benennt jede erzeugte Bildvariante und jedes CSS/JS-Bundle nach einem Inhalts-Hash (z. B. screenshot-800w.a3f9c2e1.webp, bundle.a3f9c2e1.css), sodass sie mit sicheren, weit in der Zukunft liegenden Cache-Headern ausgeliefert werden können - der Build eines Projekts ändert den eigenen Dateinamen nur, wenn sich dessen Inhalt tatsächlich ändert. Benennt die eigenen Originaldateien eines Projekts unter docs/assets/ nicht um - nur von der Pipeline erzeugte Ausgabe wird fingerprinted, sodass alles andere, was ein Asset über seinen einfachen Dateinamen referenziert (eine ::: file-Download-Card, ein roher Markdown-Link), unverändert weiterfunktioniert.
• assets.bundle - true (Standard). Verkettet extraCss/extraJs je zu einer fingerprinted Datei - reines BoxLang/JVM, keine Node/esbuild-Toolchain. Fällt exakt auf das heutige Pro-URL- <link>/<script>-Verhalten zurück, unverändert, sobald irgendein Eintrag in der Liste eine externe URL (ein CDN-Link) ist oder eine nicht existierende Datei benennt - siehe Responsive Bilder.
• assets.images.enabled - true (Standard). Jedes geeignete docs/assets/**-Bild (.png/.jpg/.jpeg) erhält über bx-image erzeugte Skalierungs-/WebP-Varianten, und jedes passende <img> wird zu einem <picture> mit srcset umgeschrieben. Auf false setzen, um auf einfaches, unverarbeitetes Kopieren von Bildern zurückzufallen, genau wie vor Einführung dieser Funktion.
• assets.images.widths - zu erzeugende Breakpoints, in Pixeln. Eine Breite, die der eigenen Breite eines Bildes entspricht oder darüber liegt, wird für dieses Bild automatisch übersprungen - nichts wird jemals hochskaliert.
• assets.images.formats - "original" behält das Quellformat als <img>-Fallback bei; "webp" fügt eine gleich große <source type="image/webp">-Variante hinzu. Beide standardmäßig aktiv.

mermaid

false (Standard) - überhaupt keine Mermaid-Diagrammunterstützung ausgeliefert. true lädt mermaid.js clientseitig und rendert jeden mit ```mermaid eingezäunten Codeblock als Diagramm. Siehe Markdown-Erweiterungen für die Syntax.

mermaid: true

{ "mermaid": true }

math

false (Standard) - kein KaTeX ausgeliefert. true lädt es clientseitig und setzt $...$/$$...$$ direkt aus dem Markdown einer Seite. Siehe Markdown-Erweiterungen für die Syntax.

math: true

{ "math": true }

Admonitions (Hinweis-/Warnungs-/Tipp-artige Callout-Boxen), Content-Tabs und die Fenced-Code-Annotationen hl_lines/linenums/title sind im Markdown jeder Seite immer verfügbar, ohne Konfiguration nötig - siehe Markdown-Erweiterungen.

openapi

false (Standard) - kein Swagger UI ausgeliefert. true lädt es clientseitig und rendert jeden ::: openapi src="..."-Content-Block als interaktives Widget für die referenzierte OpenAPI-/Swagger-Spezifikation (JSON oder YAML). Siehe OpenAPI / Swagger für die Syntax.

openapi: true

{ "openapi": true }

plugins

[] (Standard) - ein Array von BoxLang-Modulnamen, die als Plugins aktiviert werden. Das Installieren eines Plugin-Moduls (box install) aktiviert es niemals von selbst als Plugin; es muss auch hier benannt werden. Siehe Plugins dafür, wie man eines schreibt.

plugins: [ myBxSitesPlugin ]

{ "plugins": ["myBxSitesPlugin"] }

i18n

Metadaten für die Locale-Ordner-Konvention docs/i18n/<code>/ - eine Locale wird automatisch gebaut, sobald ihr Ordner existiert; i18n liefert nur ihr Anzeige-Label/ihre Schreibrichtung für den Sprachumschalter.

• i18n.defaultLocale - { "code", "label", "flag", "strings" } für den eigenen regulären docs/-Baum des Projekts, standardmäßig { "code": "en", "label": "English" }. Muss nur gesetzt werden, wenn deine Standard-Locale nicht Englisch ist.
• i18n.locales - [] (Standard) - ein Array aus { "code", "label", "dir", "flag", "strings" } für jede andere Locale. code dient zugleich als Ordnername in docs/i18n/<code>/ und als gebautes URL-Präfix - nur Buchstaben/Ziffern/Bindestriche (es, pt-BR, zh-Hans). dir ist "ltr" (Standard) oder "rtl". flag ist ein optionales Emoji-Override für das Flaggen-Icon des Sprachumschalters - die meisten gängigen Codes lösen bereits von selbst in eine sinnvolle Flagge auf. strings überschreibt die eigenen Theme-Chrome-UI-Texte dieser Locale (Suchplatzhalter, "Auf dieser Seite", die 404-Seite, ...) - siehe Internationalisierung für die vollständige Liste der Schlüssel; de/es/it/ja bringen bereits eine eingebaute Übersetzung mit, strings wird also nur zum Überschreiben eines Schlüssels oder für eine weitere Locale gebraucht.

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

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

Siehe Internationalisierung für das vollständige Bild - Fallback bei nicht übersetzten Seiten, den Sprachumschalter und was noch nicht übersetzt wird.

blog

Optionen für den Blog - selbst eine Convention-over-Configuration-Funktion (docs/blog/posts/), dafür ist kein Schlüssel hier nötig, um ihn einzuschalten.

• blog.postsPerPage - 10 (Standard) - wie viele Beiträge pro Seite auf /blog/, jeder Kategorieseite und jeder /blog/archive/<year>/-Seite angezeigt werden, bevor es zu .../page/2/ weitergeht.
• blog.feed - true (Standard) - ob /blog/feed.xml (RSS 2.0) geschrieben wird. Nur sinnvoll mit einer absoluten baseURL, dieselbe Voraussetzung wie bei sitemap.xml.
• blog.feedLimit - 25 (Standard) - begrenzt /blog/feed.xml auf so viele der neuesten Beiträge. 0 bedeutet unbegrenzt (jeder Beitrag, vollständig). Die meisten Feed-Reader interessieren sich nur für das Neueste, daher verschwendet ein unbegrenzter Feed bei einem Blog mit Hunderten Beiträgen bei jedem Abruf nur Bandbreite - siehe Blog: Feed.

blog: { postsPerPage: 10, feed: true, feedLimit: 25 }

{ "blog": { "postsPerPage": 10, "feed": true, "feedLimit": 25 } }

Siehe Blog für Beitrags-/Autoren-Frontmatter, Kategorien, Featured Images und SEO-/Social-Metadaten.

variables

{} (Standard) - ein Objekt wiederverwendbarer Werte, in beliebiger Form, referenziert von jeder Markdown-Seite aus als {{ dotted.path }}. Siehe Variablen & Magische Funktionen.

variables:
  company: "Ortus Solutions"
  product: { name: "BoxLang", supportEmail: "support@example.com" }

{
	"variables": {
		"company": "Ortus Solutions",
		"product": { "name": "BoxLang", "supportEmail": "support@example.com" }
	}
}

Welcome to {{ company }}! We build {{ product.name }}.

Eine Datei docs/functions.bxs (kein eigener Konfigurationsschlüssel - per Konvention, genau wie docs/nav.json/docs/blog/authors.yml) fügt neben variables BoxLang-"magische Funktionen" hinzu - aufrufbar auf dieselbe Weise, als {{ $name(...) }}. Siehe Variablen & Magische Funktionen.

Versionierung

Versionierte Docs sind Convention over Configuration - dafür gibt es keinen bxsites.yaml-Schlüssel. Füge einen docs/versions/<name>/-Ordner hinzu, und er wird automatisch als eigener Doc-Baum gebaut, mit einem Versionsumschalter, den jedes Theme kostenlos rendert, sobald mehr als eine Version existiert. Siehe Versionierung für das vollständige Bild - eine neue Version mit version:new anlegen, wie Versionen sortieren und bauen, und was außen vor bleibt (Suche pro Baum begrenzt, kein Deprecated-/EOL-Flag).