Content-Blöcke

Content-Blöcke

Zusätzlich zu allem in Markdown-Erweiterungen unterstützt BX Sites eine Familie von GitBook-artigen Content-Blöcken - für sich genommen praktisch, und der Grund, warum sich der Inhalt einer GitBook-Website unkompliziert migrieren lässt: jeder dieser Blöcke bildet direkt auf einen gleichnamigen GitBook-Block ab. Jeder verwendet dieselbe Container-Syntax ::: name ... ::: (ein einzelnes ::: in seiner eigenen Zeile schließt den jeweils gerade offenen Block) - keine bxsites.json-Konfiguration nötig, immer verfügbar. Ein Block kann in einem anderen verschachtelt sein (etwa ein Expandable mit einer Cards-Gruppe darin) - jeder wird erneut nach weiteren Blöcken in seinem eigenen Inhalt durchsucht.

Expandable

Ein einfacher einklappbarer Bereich - kein Callout-Icon/keine Farbe, im Gegensatz zu einer einklappbaren Admonition (???, siehe Admonitions):

::: expandable "Is this different from a collapsible admonition?"
Yes - this has no type/icon/color, just a plain expand/collapse section.
Add `open="true"` to start it expanded.
:::

Cards

Ein Raster aus Link-Cards, jede ihr eigenes ::: card innerhalb eines ::: cards-Wrappers - title, icon, image und href sind alle optional (eine Card ohne href wird als schlichte, nicht klickbare Card gerendert). icon wird auf dieselbe Weise aufgelöst wie Frontmatter-/Nav-icon-Werte - ein reines Emoji, oder ein benanntes Icon aus einer mitgelieferten Bibliothek (icon="phosphor-duotone:rocket-launch", icon="lucide:rocket", ...) - siehe Themes: Icons:

::: cards
::: card title="Getting Started" icon="phosphor-duotone:rocket-launch" href="../getting-started.md"
Install, scaffold and build your first site.
:::
::: card title="Themes" icon="phosphor-duotone:palette" href="themes.md"
Customize a built-in theme or write your own.
:::
:::

Columns

Ein nebeneinanderliegendes Layout - ::: column akzeptiert ein optionales width (eine reine CSS-Länge/-Prozentangabe, z. B. "40%"); Spalten ohne explizite Breite teilen sich die Reihe gleichmäßig:

::: columns
::: column width="60%"
The wider column.
:::
::: column
The narrower one.
:::
:::

Stepper

Eine nummerierte, verbundene Abfolge von Schritten:

::: stepper
::: step "Install"
`install-bx-module bx-sites`
:::
::: step "Scaffold"
`bxSites new`
:::
:::

Das eigene, optionale color-Attribut eines Schritts markiert seinen Marker mit einer von vier semantischen Farben - dem Standard (kein color), success, warning oder danger - unabhängig von der Position des Schritts in der Abfolge:

::: stepper
::: step "Back up your data" color="success"
Routine, safe to run any time.
:::
::: step "Optional: enable telemetry" color="warning"
Skip this one if you're not sure.
:::
::: step "Delete the old install" color="danger"
Irreversible - make sure the backup above finished first.
:::
:::

Der nummerierte Marker, die Verbindungslinie und jede der drei color-Paletten oben lassen sich unabhängig von der restlichen Palette der Website themen, über CSS-Custom-Properties - siehe Farben anpassen.

File

Eine Download-Card für ein PDF, ein Video oder ein beliebiges anderes Projekt-Asset - src wird auf dieselbe Weise aufgelöst wie theme.logo/die Frontmatter-ogImage (relativ zu docs/assets/):

::: file src="assets/spec.pdf" title="API Specification"
:::

Embed

Ein responsives iframe-Embed für einen erkannten Anbieter - derzeit YouTube, Vimeo, CodePen, Spotify, Loom und Figma. Eine URL von woanders fällt stattdessen auf eine schlichte "visit ↗"-Link-Card zurück, statt auf ein iframe, das ohnehin nicht rendern würde (die meisten Websites blockieren das Einbetten in Frames):

::: embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="A demo"
:::

Page Link

Eine ausführliche Vorschau-Card, die zu einer anderen Seite verlinkt - href folgt derselben dateirelativen Konvention wie ein gewöhnlicher Seiten-Link. Anders als eine Card werden Titel/Icon/Zusammenfassung automatisch aus der eigenen Frontmatter der Zielseite gezogen, sodass sie synchron bleibt, wenn diese Seite umbenannt wird oder sich ihre Zusammenfassung ändert:

::: page-link href="../getting-started.md"
:::

Link Preview

Eine ausführliche Vorschau-Card für eine externe URL - dieselbe Card-Form wie ::: page-link, aber für einen Link, der keine der eigenen Seiten dieser Website ist, es also keine Seite gibt, aus der sich Titel/Zusammenfassung automatisch ziehen ließen. Jedes Feld kommt aus den eigenen Attributen der Direktive: nur url ist erforderlich, title fällt, wenn weggelassen, auf die reine URL zurück, und description/image sind beide optional. Es gibt keinen Build-Zeit-Abruf der Ziel-URL, um diese automatisch zu befüllen - dieselbe Überlegung, die check auf interne Links beschränkt, gilt auch hier, sodass eine langsame oder nicht erreichbare externe Website die Build-Zeit niemals beeinflusst:

::: link-preview url="https://boxlang.io" title="BoxLang" description="A dynamic, multi-paradigm JVM language." image="https://boxlang.io/og.png"
:::

BoxLang

A dynamic, multi-paradigm JVM language.

boxlang.io

Updates (Changelog)

Eine datierte, taggbare Changelog-Liste - ::: update akzeptiert date="YYYY-MM-DD" und optional durch Kommas getrennte tags:

::: updates
::: update date="2026-01-15" tags="feature,fix"
Added dark mode and fixed a footer alignment bug.
:::
::: update date="2026-01-01"
Initial release.
:::
:::

Eine Seite mit einem ::: updates-Block erhält außerdem ihre eigene feed.xml (RSS 2.0), die daneben geschrieben wird, sobald baseURL in bxsites.json eine vollständige URL ist - dieselbe Voraussetzung wie bei sitemap.xml - sodass Leser genau den Changelog dieser einen Seite abonnieren können.

Wiederverwendbare Inhalte (Includes)

::: include src="..." fügt an dieser Stelle das rohe Markdown einer anderen Datei ein. Anders als jeder Block oben wird daraus echter Seiteninhalt (Überschriften, Absätze, seine eigenen verschachtelten Blöcke), nicht etwas, das in ein Widget verpackt wird - nützlich für einen Warn-/Hinweistext, der sich über mehrere Seiten wiederholt. Lege das Partial selbst unter docs/includes/ ab - dieselbe reservierte Ordner-Konvention wie assets//versions//i18n//blog/. Eine Datei unter includes/ wird nie als eigene Seite gebaut und erscheint nie in Navigation/Suche/Sitemap/Tags - sie existiert nur, um in andere Seiten eingefügt zu werden:

docs/
├── index.md
├── includes/
│   ├── beta-notice.md
│   └── legal/
│       └── terms.md
└── guides/
    └── deep/
        └── setup.md

Ein bloßer src (ohne führendes ./ oder ../) wird immer gegen das eigene docs/includes/ des aktuellen Baums aufgelöst, egal wie tief die einbindende Seite selbst verschachtelt ist - guides/deep/setup.md oben erreicht dieselbe Datei wie index.md, beide mit exakt demselben src:

::: include src="beta-notice.md"

Ein bloßer src kann auch in einen Unterordner von includes/ selbst zeigen:

::: include src="legal/terms.md"

Stelle stattdessen ./ oder ../ vor src, um ein seitennahes Fragment zu erreichen, das nicht im zentralen includes/-Ordner leben soll - diese Form löst dateirelativ zum eigenen Verzeichnis der einbindenden Seite auf, dieselbe Konvention wie ein gewöhnlicher Seiten-Link:

::: include src="../local-note.md"

Ein Versions-/Locale-Baum erhält sein eigenes includes/ auf dieselbe Weise - eine Seite unter docs/versions/2.0/ löst einen bloßen src gegen docs/versions/2.0/includes/ auf, und eine unter docs/i18n/es/ gegen docs/i18n/es/includes/ - die Partials jedes Baums gehören ihm selbst, sie werden nicht mit dem docs/includes/ des Hauptbaums geteilt.

Eine eingebundene Datei kann selbst eine weitere einbinden (eine zirkuläre Kette wirft zur Build-Zeit BxSites.CircularInclude, statt endlos zu laufen).