Erste Schritte

Installiere das Modul, erstelle ein Projekt und baue deine erste Website.

Erste Schritte

Voraussetzung: BoxLang installieren

Alles Folgende setzt voraus, dass die BoxLang-Laufzeitumgebung selbst bereits auf deinem Rechner vorhanden ist - install-bx-module ist BoxLangs eigener CLI-Befehl zum Installieren eines Moduls in eine bestehende Installation, und CommandBox' box install benötigt ebenfalls eine bereits vorhandene BoxLang-Engine, gegen die es laufen kann. Falls du BoxLang noch nicht installiert hast, installiere es zuerst mit einer der beiden Methoden:

• dem Quick Installer (eine einzelne Version, am einfachsten für den Einstieg):

  curl -fsSL https://install.boxlang.io/ | bash

• oder BVM, dem BoxLang Version Manager (installiert mehrere BoxLang-Versionen nebeneinander und lässt dich zwischen ihnen wechseln):

  curl -fsSL https://install-bvm.boxlang.io/ | bash
  bvm install latest && bvm use latest

Windows- und Homebrew-Installer sowie die vollständige BVM-Befehlsreferenz findest du in BoxLangs eigener Installationsdokumentation.

Installation

BxSites benötigt bx-markdown für das Rendern von Markdown, bx-esapi für die HTML-Kodierung, bx-yaml zum Lesen von bxsites.yaml, und bx-image für die responsive Bilder-Pipeline (siehe Responsive Bilder) - alle vier werden automatisch als box.json-Abhängigkeiten mitinstalliert, sodass die Installation von bx-sites selbst der einzige nötige Befehl ist, entweder über BoxLangs eigenen OS-Binary-Installer:

install-bx-module bx-sites

oder über CommandBox:

box install bx-sites

Beide lesen boxlang.executable aus box.json und legen ein bxSites-Skript in deinem PATH ab (in ~/.boxlang/bin), sodass jeder Befehl unten entweder als kurzer, eigenständiger Befehl funktioniert:

bxSites <verb> [options]

oder überall dort, wo BoxLang zwar verfügbar ist, dieser PATH-Shim aber nicht (ein CI-Runner, ein von Hand statt per Installation registriertes Modul) - beide Formen führen genau dasselbe aus:

boxlang bxSites <verb> [options]

Der Rest dieser Anleitung verwendet die Kurzform.

Ein Projekt aufsetzen

bxSites new my-docs
cd my-docs

Das erzeugt:

my-docs/
├── docs/
│   ├── assets/
│   └── index.md
└── bxsites.yaml

Übergib --theme=material oder --theme=tailwind, um mit einem anderen Standard-Theme zu starten, und --name="My Project Docs", um den Website-Namen direkt festzulegen - andernfalls leitet new ihn aus dem Namen des Zielverzeichnisses ab.

Format der Konfigurationsdatei

bxsites.yaml ist das Standard- und bevorzugte Format - es ist das, was new erzeugt, sofern nichts anderes angegeben wird, und jedes Beispiel in dieser Anleitung und in Konfiguration zeigt es zuerst. bxsites.json wird ebenfalls vollständig unterstützt, für ein Projekt, das es bevorzugt: übergib --format=json, um stattdessen eines zu erzeugen, oder schreibe/benenne eines einfach selbst von Hand um - der ConfigLoader löst auf, welche von bxsites.yaml/.yml/.json tatsächlich vorhanden ist, in dieser Reihenfolge, ohne dass etwas anderes konfiguriert werden muss, um zu wechseln. Siehe Konfiguration für die vollständige Schlüsselreferenz in beiden Formaten.

Hast du bereits Inhalte in GitBook? bxSites migrate --source=/path/to/export wandelt einen GitBook-Export direkt in docs/ um - siehe Migration von GitBook - und du kannst direkt zu Build springen.

Seiten hinzufügen

Jede .md-Datei unter docs/ wird zu einer Seite. Ordnerverschachtelung wird automatisch zu Navigationsverschachtelung:

docs/
├── index.md              -> /
├── guides/
│   ├── index.md          -> /guides/
│   └── deployment.md     -> /guides/deployment/

(Eine große Website kann diese abgeleitete Reihenfolge/Gruppierung vollständig durch eine explizite Navigation ersetzen - siehe nav.)

Zwischen Seiten verlinken

Verlinke eine andere Seite auf die übliche mkdocs-Art - ein dateirelativer Pfad zu ihrer .md-Quelldatei, genau als lägen die beiden Dateien nebeneinander auf der Festplatte (denn genau das tun sie):

See [Deployment](guides/deployment.md) or, from that same guide,
[back to Getting Started](../getting-started.md#seiten-hinzufügen).

BxSites schreibt jeden solchen Link zur Build-Zeit auf seine gebaute Pretty-URL um (guides/deployment.md -> /guides/deployment/index.html, Anker und Query-Strings bleiben erhalten), aufgelöst relativ zum eigenen Ordner der verlinkenden Seite - ../- und Geschwister-Referenzen funktionieren genau wie bei der Auflösung jedes anderen relativen Pfads. Das ist auch der Grund, warum der Link weiterhin funktioniert, wenn du die Datei direkt auf GitHub liest statt auf der gebauten Website: Es ist so oder so ein echter, gültiger relativer Pfad zu einer echten Datei. Absolute URLs, mailto: sowie Links, die bereits mit / beginnen, bleiben unangetastet.

Eine Seite als Markdown herunterladen

Zu jeder gebauten Seite wird auch ihre ursprüngliche .md-Quelldatei direkt mit veröffentlicht - docs/guides/deployment.md landet als site/guides/deployment.md, direkt neben site/guides/deployment/index.html - mit einem "Markdown herunterladen"-Link auf der Seite selbst, neben "Diese Seite bearbeiten". Keine Konfiguration nötig, immer aktiv.

Das folgt derselben Motivation wie llms.txt - ein Mensch (oder eine KI) kann die rohe Markdown-Quelle einer Seite direkt abrufen, statt gerendertes HTML zu scrapen - und da der gesamte docs/-Baum 1:1 gespiegelt wird, funktionieren auch die relativen Links einer Seite weiterhin, wenn sie so gelesen wird.

Jede Seite kann mit einem kleinen Frontmatter-Block beginnen:

---
title: Deployment
order: 2
hidden: false
description: How to deploy a built BxSites site.
tags: [guides, deployment]
icon: 🚀
summary: Everything you need to publish a built site.
ogImage: assets/deployment-card.png
toc: true
---

# Deployment

Your content here.

• title - überschreibt den Navigations-/Seitentitel (andernfalls aus dem Dateinamen abgeleitet)
• order - steuert die Reihenfolge unter Geschwisterelementen in der Navigation (kleinere Werte zuerst; Seiten ohne Angabe sortieren zuletzt, alphabetisch)
• hidden - true schließt die Seite aus der Navigation (und der Suche) aus, ohne sie vom Build auszuschließen
• description - die Social-Card-/Meta-Beschreibung dieser Seite (siehe ogImage); fällt, wenn nicht gesetzt, auf die websiteweite description in der Website-Konfiguration zurück
• tags - ein Array von Tags für diese Seite, dargestellt als klickbare Badges unter dem Titel und gesammelt in einer websiteweiten /tags/-Indexseite (wird erst gebaut, sobald mindestens eine Seite Tags hat); erhöht außerdem die Suchrelevanz bei passenden Anfragen
• icon - wird neben dem Seitentitel und ihrem Navigationseintrag angezeigt - ein reines Emoji oder ein benannter Icon-Verweis aus einer mitgelieferten Bibliothek (rocket, lucide:rocket, tabler:rocket, oder ein eigenes custom:my-icon eines Projekts) - siehe Icons
• summary - eine einzeilige Einleitung, die unter dem Titel angezeigt wird (zu unterscheiden von description, die nur für Meta-Tags gedacht ist und nie auf der Seite selbst gerendert wird)
• ogImage - überschreibt das Social-Card-Bild nur für diese eine Seite - siehe ogImage
• toc - false blendet das eigene Inhaltsverzeichnis ("Auf dieser Seite") dieser Seite aus, selbst bei 2+ Überschriften (dem üblichen Auslöser für dessen Anzeige) - praktisch für eine Landing-/Hero-Seite, die kein schwebendes Inhaltsverzeichnis neben ihrem eigenen Inhalt haben möchte; Standard ist true

Frontmatter-Werte können Inline-Listen (tags: [a, b, c]), YAML-artige Blocklisten (tags: gefolgt von eingerückten - item-Zeilen) oder >/|-Block-Skalare für einen mehrzeiligen Wert sein - es handelt sich allerdings um einen kleinen, selbst geschriebenen Parser, nicht um vollständiges YAML, verschachtelte Objekte/Maps werden also nicht unterstützt.

Build

bxSites build

Rendert jede Seite in docs/ zu einer statischen Website in site/, bereit zum Hosten überall dort, wo statische Dateien ausgeliefert werden können.

Lokal ausliefern

bxSites serve

Baut das Projekt, liefert site/ unter http://127.0.0.1:8080/ aus und baut automatisch neu, sobald du eine Änderung unter docs/, deiner bxsites.yaml/.json-Website-Konfiguration oder einem projektweiten theme/-Override speicherst - dein Browser lädt von selbst neu. Übergib --port=3000 oder --host=0.0.0.0, um zu ändern, woran gebunden wird.

Clean

bxSites clean

Entfernt site/ und jeglichen Build-Cache, ohne deine docs/-Quelle anzurühren.