Content-Blöcke

Content-Blöcke

Zusätzlich zu allem in Markdown-Erweiterungen unterstützt BxSites 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.yaml-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 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"
:::

Buttons

Eine GitBook-artige Call-to-Action-Schaltfläche - ::: button für sich allein, oder mehrere nebeneinander in einer Reihe innerhalb eines ::: buttons-Wrappers. Das führende "Label" und href sind die einzigen Angaben, die die meisten Schaltflächen brauchen:

::: button "Get Started" href="../getting-started.md" style="primary"
:::

Ein paar optionale Attribute verleihen jeder Schaltfläche ihre eigenen Fähigkeiten:

• style="primary" oder style="secondary" (der Standard) - voll ausgefüllt in Akzentfarbe vs. Outline.
• size="small", "medium" (der Standard) oder "large".
• icon="..." - wird auf dieselbe Weise aufgelöst wie das eigene icon einer Card (ein reines Emoji, oder ein benanntes Icon wie icon="phosphor-duotone:rocket-launch" - siehe Themes: Icons).
• target="_blank" - öffnet den Link in einem neuen Tab statt im selben (rel="noopener noreferrer" wird automatisch hinzugefügt).
• disabled="true" - rendert eine inaktive, nicht klickbare Schaltfläche (kein href nötig) für einen "Demnächst verfügbar"-Aufruf.

::: buttons
::: button "Read the docs" href="../getting-started.md" icon="phosphor-duotone:book-open" size="large"
:::
::: button "Star on GitHub" href="https://github.com/ortus-boxlang/bx-sites" style="secondary" target="_blank"
:::
::: button "Coming soon" disabled="true"
:::
:::

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

Prompt

Ein gestalteter Container für einen wiederverwendbaren KI-Prompt - bx-sites' eigenes Gegenstück zu GitBooks Prompt-Block. Der Inhalt des Blocks ist der Prompt-Text, geschrieben als gewöhnliches Markdown (sodass Überschriften, Listen und Code darin weiterhin ihre eigene Formatierung erhalten); jeder Prompt bekommt eine "Copy"-Schaltfläche, die genau diesen Quelltext kopiert, Formatierungs-Markup inklusive, bereit zum Einfügen in das jeweilige KI-Tool, mit dem du gerade arbeitest. description (eine optionale, einzeilige Zusammenfassung) und icon (aufgelöst auf dieselbe Weise wie das eigene icon von ::: card - fällt bei Weglassen standardmäßig auf ein Glitzer-Icon zurück) sind beide optional:

::: prompt description="Summarizes a pull request for a changelog entry" icon="phosphor-duotone:git-pull-request"
Summarize the following pull request diff as a single changelog entry,
written for an end user rather than a developer. Group related changes
together and skip anything purely internal (refactors, tests, CI).
:::

Füge expanded="preview" hinzu, um einen langen Prompt auf eine kurze, ausblendende Vorschau zu klemmen, bis die Leserin auf "Show more" klickt, oder expanded="hidden", um ihn vollständig eingeklappt hinter einer "Show prompt"-Schaltfläche zu starten - praktisch für eine Seite, die mehrere Prompts hintereinander auflistet. Lasse expanded weg (oder setze es auf "full", den Standard), um immer den gesamten Prompt anzuzeigen:

::: prompt description="A longer, multi-step prompt" expanded="preview"
1. Read the attached error log line by line.
2. For each stack trace, identify the failing module.
3. Group failures by root cause, not by timestamp.
4. Propose one fix per root cause, not per failure.
5. Skip anything that already has an open issue - list those separately.
:::

Anders als GitBooks eigener Prompt-Block gibt es hier kein "Open in AI providers"-Menü - bx-sites spricht nie mit einem KI-Anbieter eines Drittanbieters, daher hat dieser Teil von GitBooks eigenem Block hier kein Gegenstück.

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.yaml 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).

Conditional content

Zeigt eine von mehreren Varianten eines Blocks, je nach der eigenen Wahl der Leserin - "Free" vs. "Pro"-Anleitung auf derselben Seite, zum Beispiel. Das hier ist eine vollständig statische Website ohne jede Art von Besucher-Identität, also gibt es, anders als bei einer Plattform mit echtem Backend, kein serverseitig ausgewertetes "wer ist diese Leserin" - die Leserin trifft die Wahl selbst, und ihre Wahl wird einfach im eigenen Browser (localStorage) gemerkt, auch für jede spätere Seite:

::: audience-switcher key="plan" options="free:Free,pro:Pro"
:::

::: conditional key="plan" value="free"
The Free plan includes basic search.
:::

::: conditional key="plan" value="pro"
The Pro plan adds AI-assisted search and unlimited team seats.
:::

::: conditional key="..." value="..." kennzeichnet eine Variante; key ist der jeweilige Präferenzname, auf den umgeschaltet wird ("plan" oben, es könnte aber genauso gut "os", "language", was auch immer sein), und value ist die eine Einstellung, für die dieser bestimmte Block angezeigt werden soll. Jede Variante wird immer im HTML gerendert

• clientseitig nur versteckt, niemals weggelassen - sodass eine Leserin mit deaktiviertem JavaScript (oder ein Such-Crawler) weiterhin jede Variante sieht statt keine.

::: audience-switcher key="..." options="value:Label,value:Label,..." ist ein optionales, fertiges Steuerelement - eine Schaltfläche pro Option, die sofort jeden ::: conditional-Block mit demselben key umschaltet, überall auf der Seite. Du brauchst es überhaupt nicht: ein Link, der auf ?plan=pro endet, setzt beim Laden automatisch dieselbe Präferenz (praktisch, um einen direkten Link zu "der Pro-Version dieser Seite" zu teilen), und das eigene Theme-Override eines Projekts kann stattdessen direkt window.bxSitesSetPreference( key, value ) aufrufen, um es von einer eigenen UI aus zu steuern.