CLI-Referenz

Jedes bxSites-Verb und seine Optionen.

CLI-Referenz

bxSites <verb> [options]

box install bx-sites legt ein eigenständiges bxSites-Skript in deinem PATH ab (über boxlang.executable in box.json), sodass jedes Verb unten entweder auf diese kurze Art ausgeführt werden kann, oder als boxlang bxSites <verb> - beide führen genau dasselbe aus; nutze die längere Form überall dort, wo der PATH-Shim nicht eingerichtet ist (ein CI-Runner, ein von Hand registriertes Modul):

boxlang bxSites <verb> [options]

Jedes Verb akzeptiert --projectRoot=<path> (oder einen einfachen positionalen Pfad), um ein anderes Projekt als das aktuelle Verzeichnis anzusprechen, und die beiden globalen Flags unten können vor jedem Verb stehen.

Jedes unten erwähnte docs/ gilt genauso für ein Projekt, das stattdessen src/ verwendet - siehe Erste Schritte für die docs/-oder-src/-Konvention. new erzeugt immer ein Gerüst mit docs/.

Globale Optionen

new

Ein Docs-Projekt aufsetzen.

bxSites new [path] [--name=...] [--theme=<siehe guides/themes.md für alle 10>] [--description=...] [--format=yaml|json]

• --name - der in die Website-Konfiguration geschriebene Website-Name (Standard: der Name des Zielverzeichnisses)
• --theme - Standard ist bootstrap
• --description - die in die Website-Konfiguration geschriebene Website-Beschreibung
• --format - yaml (Standard, erzeugt bxsites.yaml) oder json (erzeugt bxsites.json) - siehe Konfiguration

build

Rendert docs/**.md zu einer statischen Website in site/. Baut außerdem den Suchindex (sofern search in der Website-Konfiguration nicht false ist, oder searchProvider nicht auf einen Provider gesetzt ist - wie algolia/pagefind -, der ihn nicht nutzt, siehe Suche), führt die pagefind-CLI gegen die fertige site/ aus, wenn searchProvider.provider auf "pagefind" steht, und kopiert Theme + docs/assets/** nach site/.

bxSites build

serve

Baut und liefert die Website lokal mit Live-Reload aus.

bxSites serve [--port=8080] [--host=127.0.0.1]

Läuft im Vordergrund, bis es unterbrochen wird (Strg+C).

search-index

Baut site/search-index.json eigenständig neu, ohne Seiten neu zu rendern oder Assets zu kopieren. build führt diesen Schritt bereits automatisch mit aus - dieses Verb existiert für den Fall, dass du nur den Index auffrischen musst. Deckt immer nur den Haupt-docs/-Baum ab, auch bei einem Projekt mit docs/versions//docs/i18n/ - ein echter build schreibt stattdessen den eigenen, begrenzten Index jedes Baums (siehe Versionierung).

bxSites search-index

clean

Entfernt site/ und jeglichen Build-Cache, lässt docs/ und die Website-Konfiguration unangetastet.

bxSites clean

gh-deploy

Baut die Website und pusht sie dann per Force-Push in einen gh-pages-artigen Branch - ein Commit pro Deploy, keine angesammelte Historie auf diesem Branch, passend zu mkdocs' eigener mkdocs gh-deploy-Konvention. Erfordert, dass das Projekt ein Git-Repository mit konfiguriertem Remote ist; rührt niemals deinen eigenen aktuellen Branch oder dein Arbeitsverzeichnis an (der Push erfolgt aus einem temporären git worktree).

bxSites gh-deploy [--branch=gh-pages] [--remote=origin] [--message="..."]

• --branch - Standard ist gh-pages
• --remote - Standard ist origin
• --message - die einzelne Commit-Nachricht des Branches, Standard ist "Deploy site via bxSites gh-deploy"

Siehe Deployment für die vollständige GitHub-Pages-Einrichtung (Pages für den Branch aktivieren, baseURL usw.).

deploy

Baut die Website und liefert sie dann an ein echtes Deployment-Ziel aus - S3 (und jeden S3-kompatiblen Dienst - DigitalOcean Spaces, Cloudflare R2, Backblaze B2, MinIO), Azure Blob Storage, Google Cloud Storage, Firebase Hosting, FTP, SFTP, rsync über SSH, Netlify, Vercel, Cloudflare Pages, ein lokales Verzeichnis oder GitHub Pages (derselbe Push, den auch gh-deploy macht, nur eben auch über diesen einen einheitlichen Befehl erreichbar).

bxSites deploy --entry=<name> [--verbose]
bxSites deploy [--target=local|github-pages] [target-specific flags] [--verbose]
bxSites deploy [--verbose]

Drei Arten, es aufzurufen:

1. --entry=<name> - leitet an das Ziel weiter, das eine deployments/<name>.json-Datei deklariert (siehe unten). Jedes Ziel außer local/github-pages braucht das - es gibt mehr Konfiguration, als ein paar Flags sinnvoll tragen könnten.
2. --target=<name> mit seinen eigenen Flags - eine reine Flag-Kurzform für die beiden einfachsten Ziele, die überhaupt keinen deployments/-Ordner brauchen: local (--destination=<path>) und github-pages ([--branch] [--remote] [--message], jedes Feld optional, dieselben Standardwerte wie bei gh-deploy).
3. Kein Flag - alles deployen. Jeder deployments/*.json-Eintrag wird der Reihe nach deployt, ausgehend von einem einzigen gemeinsamen Build (die Website wird einmal gebaut, nicht einmal pro Ziel). Setzt voraus, dass mindestens ein deployments/*.json-Eintrag existiert. Schlägt ein Ziel fehl, stoppt das die übrigen nicht - jeder Eintrag wird versucht, und der Befehl liefert nur dann einen von null verschiedenen Exit-Code, wenn mindestens einer davon fehlgeschlagen ist; die abschließende Zusammenfassung meldet, wie viele erfolgreich waren (z. B. Deployed to 2/3 target(s) (1 failed)).

--verbose gibt eine Fortschrittszeile aus, wenn der Build startet/endet und wenn jedes Ziel startet/endet, statt nur der abschließenden einzeiligen Zusammenfassung.

Siehe Deployment für die eigene Konfigurationsform jedes Ziels und ein echtes deployments/*.json-Beispiel für jedes davon.

package

Baut die Website und packt sie dann in ein einziges, verteilbares Archiv - ein einfaches Zip, dessen Wurzel der Inhalt der gebauten Website selbst ist (kein umschließender site/-Ordner), bereit zum Anhängen an ein Release oder zur Übergabe an jeden Host, der nur einen Zip-Upload akzeptiert.

bxSites package [--output=<path>]

--output ist standardmäßig <projectRoot>/site.zip (ein relativer Wert wird gegenüber dem Projekt-Root aufgelöst); die übergeordneten Verzeichnisse eines verschachtelten Ziels werden automatisch angelegt.

migrate

Wandelt ein bestehendes Docs-Projekt in dieses um - --from wählt das Quellformat: gitbook (Standard), mkdocs, markdown-zip oder notion.

bxSites migrate --source=/path/to/gitbook-export
bxSites migrate --source=/path/to/mkdocs-project --from=mkdocs
bxSites migrate --source=/path/to/export.zip --from=markdown-zip
bxSites migrate --source=/path/to/notion-export --from=notion

• --source (erforderlich) - Pfad zum Wurzelverzeichnis des Exports/Projekts (SUMMARY.md für gitbook, mkdocs.yml für mkdocs), oder eine .zip-Datei (markdown-zip; notion akzeptiert sowohl eine .zip als auch einen bereits entpackten Ordner)
• --from - gitbook (Standard), mkdocs, markdown-zip oder notion

--from=gitbook (Standard)

Ein GitBook-Export - ein SUMMARY.md-Inhaltsverzeichnis plus dessen .md-Dateien, GitBooks eigenes Sync-Format auf der Festplatte - wird in den docs/-Baum dieses Projekts umgewandelt: SUMMARY.md wird zu docs/nav.json, {% block %}-Syntax wird zu ihrem bx-sites-Äquivalent (::: name-Direktiven, oder die native === "Title"-Tab- bzw. !!! type-Admonition-Syntax, wo bereits eine treffendere Entsprechung existiert - siehe Content-Blöcke), README.md-Dateien werden zu index.md, und .gitbook/assets/** wird nach docs/assets/gitbook/ kopiert.

--from=mkdocs

Ein mkdocs-Projekt - mkdocs.yml plus dessen docs/-Ordner - wird in ein vollständiges bx-sites-Projekt umgewandelt: mkdocs.yml wird zu bxsites.yaml + docs/nav.json, und jede Seite wird weitgehend unverändert übernommen, da mkdocs-materials eigene Admonition-/Tabs-/ Mathematik-/Code-Annotation-Syntax bereits bx-sites' eigene native Syntax ist - siehe Migration von mkdocs. Nicht-.md-Assets (Bilder, die bei mkdocs meist direkt neben der Seite liegen, die sie verwendet, da mkdocs keine einheitliche Asset-Ordner-Konvention hat) werden nach docs/assets/mkdocs/ verschoben und ihre Referenzen entsprechend umgeschrieben.

--from=markdown-zip

Ein schlichtes .zip aus Markdown-Dateien - kein proprietäres Exportformat zu übersetzen, da die eigene Verschachtelung eines Ordners bereits genau bx-sites' eigener Nav-Konvention entspricht und ein Seite-zu-Seite-relativer .md-Link bereits so aufgelöst wird, wie bx-sites es erwartet. Meist eine reine Kopie: jede Nicht-.md-Datei (etwa ein Bild) wird nach docs/assets/imported/ verschoben und jede Referenz einer Seite darauf entsprechend umgeschrieben. Es wird keine bxsites.yaml/docs/nav.json geschrieben - ein reines Zip bringt weder einen eigenen Website-Namen noch eine eigene Nav-Struktur mit, die übersetzt werden könnten.

--from=notion

Ein Notion-"Export as Markdown & CSV"-Archiv (eine .zip, oder ein bereits entpackter Ordner) - behandelt Notions eigene zwei Eigenheiten, die sonst nichts hier Migriertes betreffen: jeder Seiten-/Unterseiten- Ordner trägt ein angehängtes Leerzeichen plus eine 32-stellige ID (zur Unterscheidung gleichnamiger Seiten, nie zum Lesen gedacht), und der Titel einer Seite wird als literale, führende # Überschrift wiederholt, statt in der Frontmatter zu stehen. Beides wird bereinigt: das ID-Suffix wird entfernt und der verbleibende Name für den Ausgabe-Dateinamen slugifiziert, die führende Überschrift wird zu einem echten title-Frontmatter-Feld statt einer doppelten ersten Zeile, und jedes Link-/Bild-Ziel (das Notion URL-kodiert schreibt, weiterhin auf die ursprünglichen ID-Suffix-Namen zeigend) wird entsprechend umgeschrieben. Nicht-.md-Dateien werden nach docs/assets/imported/ verschoben, genau wie bei markdown-zip oben.

Alle vier

Gibt eine Zusammenfassung der konvertierten Seiten (und, bei mkdocs/ markdown-zip/notion, der Assets) aus, und - wenn etwas nicht automatisch konvertiert werden konnte - eine Liste dessen, was manuell geprüft werden muss - nichts wird stillschweigend verworfen. Eine bereits existierende Zieldatei, bxsites.yaml, oder docs/nav.json wird überschrieben (ebenfalls gemeldet), prüfe daher die migrierte Ausgabe, bevor du sie committest.

check

Ein CI-taugliches Qualitäts-Gate über eine bereits gebaute site/ - führe zuerst build aus. Prüft:

• Defekte interne Links/Bilder - jedes <a href>/<img src>, das auf eine Seite oder ein Asset zeigt, das in site/ nicht existiert. Lässt die Prüfung fehlschlagen.
• Fehlender Alt-Text - jedes <img> ganz ohne alt-Attribut. Ein leeres alt="" (die korrekte Auszeichnung für ein rein dekoratives Bild) wird nicht bemängelt. Lässt die Prüfung fehlschlagen.
• Verwaiste Seiten - Seiten, die in site/ existieren, aber von keiner Baum-eigenen Startseite aus über Links erreichbar sind (die index.html der Hauptseite, sowie die jeder Version/jedes Locale). Rein informativ - lässt die Prüfung nie fehlschlagen, da eine Seite, die ein Projekt bewusst aus der eigenen Navigation ausgeschlossen hat (z. B. per Frontmatter hidden: true), soll nur über einen direkten Link erreichbar sein.

bxSites build
bxSites check

Beendet sich mit 1, wenn es defekte Links/Bilder oder Bilder ohne Alt-Text gibt, sonst mit 0 (verwaiste Seiten beeinflussen den Exit-Code nie). Bewusst nur auf interne Links beschränkt - es werden keine HTTP-Anfragen zur Prüfung externer URLs gestellt, das gehört in ein dediziertes Link-Checking-Tool als eigener Job.

stats

Ein rein lesender Zusammenfassungsbericht über eine bereits gebaute site/ - führe zuerst build aus. Meldet:

• Seiten und Wörter - Gesamtanzahl der Seiten und eine grobe Wortanzahl (Tags entfernt, derselbe "für eine Schätzung ausreichende" Standard wie bei der Lesezeit des Blogs), plus eine Aufschlüsselung pro Baum, sobald es mehr als einen Baum gibt (eine Version oder ein Nicht-Standard-Locale).
• Versionen und Locales - Namen jedes docs/versions/-/ Nicht-Standard-docs/i18n/-Ordners.
• Blog - Anzahl an Beiträgen/Kategorien/Autoren/aktiven Jahren, direkt aus der eigenen Ordnerstruktur von site/blog/ (entspricht daher immer dem, was tatsächlich veröffentlicht wurde, Entwürfe ausgeschlossen) - none, wenn es keinen Blog gibt.
• Tags - die Anzahl unterschiedlicher Tags über die gesamte Website.
• Suchindex - Anzahl der Einträge und Dateigröße von search-index.json, oder none, wenn Suche deaktiviert ist oder ein Nicht-lokaler Provider aktiv ist.
• Website-Ausgabe - Gesamtanzahl der Dateien und Größe auf der Festplatte der gebauten site/.

bxSites build
bxSites stats

Beendet sich immer mit 0 - rein informativ, hier gibt es kein Bestehen/Durchfallen-Gate (das ist die Aufgabe von check).

doctor

Eine einmalige Umgebungs-/Konfigurations-Gesundheitsprüfung - das Verb, das man "vor dem Melden eines Bugs ausführt". Prüft die JVM-Version, dass docs/ existiert, dass bxsites.yaml/.json tatsächlich geparst wird und gültig ist, dass die erforderlichen BoxLang-Module (bx-markdown, bx-esapi, bx-yaml, bx-image) installiert und aktiviert sind, und - falls ein projektweites theme/-Override existiert - dass es den Zwei-Pflichtdateien-Vertrag (layout.bxm/page.bxm) erfüllt.

bxSites doctor

Beendet sich mit 1, wenn eine Prüfung fehlschlägt, sonst mit 0. Nichts hier verändert ein Projekt - rein diagnostisch.

post:new

Einen neuen Blogbeitrag unter docs/blog/posts/<slug>.md als Gerüst anlegen.

bxSites post:new --title="My New Post" [--slug=...] [--date=...] [--authors=...] [--categories=...] [--tags=...] [--draft]

• --title (erforderlich) - wird auch zum Frontmatter-title des Beitrags
• --slug - Standard ist ein aus --title erzeugter Slug
• --date - Standard ist heute (yyyy-MM-dd)
• --authors, --categories, --tags - kommagetrennt
• --draft - Standard ist true (übergib --!draft, um sofort zu veröffentlichen)

Siehe Blog für die vollständige Frontmatter-Referenz.

version:new

Erstellt einen Snapshot des aktuellen docs/-Baums nach docs/versions/<name>/, ausgenommen assets/, versions/, i18n/ und blog/ (jeder davon ist ein eigener, separat geladener Baum, nicht Teil des Snapshots).

bxSites version:new --name=1.0

• --name (erforderlich) - der Versionsordner/-name, z. B. 1.0

Siehe Konfiguration, Abschnitt "Versionierung".

i18n:status

Meldet die Übersetzungsabdeckung pro Locale - für jedes konfigurierte Locale, wie viele Seiten des Standard-Baums (unter demselben relativen Pfad) unter docs/i18n/<code>/ existieren, und welche noch fehlen.

bxSites i18n:status

Beendet sich immer mit 0 - rein informativ.

i18n:new

Erzeugt das Gerüst eines neuen docs/i18n/<code>/-Locale-Ordners und sät dabei eine index.md, kopiert von der index.md des Standard-Locale, sofern eine existiert.

bxSites i18n:new --code=es

• --code (erforderlich) - der Locale-Code, z. B. es, fr, pt-BR

Siehe Internationalisierung, um das neue Locale in bxsites.yamls i18n.locales einzubinden.

page:new

Erzeugt das Gerüst einer einzelnen Docs-Seite an einem beliebigen Pfad unter docs/, mit bereits ausgefülltem angefordertem Frontmatter.

bxSites page:new --path=guides/setup.md [--title=...] [--description=...] [--icon=...] [--tags=...] [--order=...]

• --path (erforderlich) - relativ zu docs/, muss auf .md enden
• --title, --description, --icon, --order - werden ins Frontmatter geschrieben
• --tags - kommagetrennt

plugin:new

Erzeugt das Gerüst eines Plugin-Moduls (box.json, ModuleConfig.bx, ein models/BxSitesPlugin.bx mit jedem Hook als Stub), nach dem Vorbild von examples/hello-plugin/.

bxSites plugin:new --name=my-analytics-plugin [--dest=...]

• --name (erforderlich) - der Modulname/Slug des Plugins
• --dest - Standard ist <projectRoot>/<name>

Siehe Plugins für die Hook-Referenz und wie das fertige Plugin in bxsites.yamls plugins-Array eingebunden wird.

install:plugin

Lädt ein veröffentlichtes Plugin von ForgeBox herunter und legt es direkt in die eigenen boxlang_modules/ des Projekts - BoxLangs eigene automatisch geladene lokale-Modul-Konvention, sodass außer der bxSites-Binary selbst nichts weiter benötigt wird (kein box/CommandBox beteiligt).

bxSites install:plugin --name=bx-sites-plugin-analytics [--version=1.2.0]

• --name (erforderlich) - der zu installierende ForgeBox-Slug
• --version - eine bestimmte Version; weglassen für die neueste

Gibt den echten registrierten Mapping-Namen des Moduls aus, sobald es geladen ist - füge diesen Namen zu bxsites.yamls plugins-Array hinzu, um es zu aktivieren (die reine Installation aktiviert ein Plugin nie - siehe Plugins).

theme:new

Wirft eines der integrierten Themes in den eigenen theme/-Ordner des Projekts zum Anpassen aus, passend zu mkdocs' --theme-Eject-Workflow.

bxSites theme:new --theme=material

• --theme (erforderlich) - bootstrap, material, tailwind, docsy, slate, docusaurus, justthedocs, vuepress, gitbook oder notion - siehe Themes

Schlägt fehl, statt ein bestehendes theme/ zu überschreiben. Siehe Themes für den Override-Vertrag (layout.bxm + page.bxm).

install:theme

Lädt ein veröffentlichtes Theme von ForgeBox in die eigenen themes/<name>/ des Projekts herunter - nichts außer der bxSites-Binary benötigt, genau wie bei install:plugin.

bxSites install:theme --name=bx-sites-theme-blog1 [--version=1.0.0]

• --name (erforderlich) - der zu installierende ForgeBox-Slug
• --version - eine bestimmte Version; weglassen für die neueste

Validiert das heruntergeladene Paket vor Abschluss gegen den ThemeProvider-Vertrag (layout.bxm + page.bxm), sodass ein defektes Paket bereits bei der Installation fehlschlägt statt erst beim nächsten build. Setze bxsites.yamls theme.name auf den installierten Namen, um es zu verwenden - siehe Themes.

theme:import

Bestmögliche Konvertierung eines Themes aus dem Ökosystem eines anderen statischen Site-Generators (mkdocs/jekyll/hugo) in ein bx-sites-Theme-Gerüst unter themes/<name>/ - ein Ausgangspunkt, kein verlustfreier Ein-Befehl-Port.

bxSites theme:import --source=mkdocs --path=/path/to/theme --name=my-imported-theme

• --source (erforderlich) - mkdocs, jekyll oder hugo
• --path (erforderlich) - der Wurzelordner des Quell-Themes
• --name (erforderlich) - der Zielname, geschrieben nach themes/<name>/

Sicher, gegen denselben --name erneut auszuführen - layout.bxm/page.bxm werden überschrieben und neu gefundene Asset-Ordner werden zusammengeführt. Siehe Ein Theme importieren für genau das, was übersetzt wird und was nicht, und was danach zu prüfen ist.

page:rename

Verschiebt eine Docs-Seite von einem Pfad zu einem anderen und schreibt dabei jeden relativen Markdown-Link über docs/** um, der auf den alten Pfad zeigte - dasselbe Link-Rot-Problem, das die gebaute HTML-Seite bereits löst (check), hier angewendet auf rohen Markdown-Quelltext zur Zeit der Umbenennung.

bxSites page:rename --from=guides/old-name.md --to=guides/new-name.md

• --from (erforderlich) - der aktuelle, relativ zu docs/ angegebene Pfad der Seite
• --to (erforderlich) - ihr neuer, relativ zu docs/ angegebener Pfad

Nur einfache [text](relative/path.md)-artige Links werden umgeschrieben

• absolute URLs, mailto: und reine In-Page-Anker bleiben unangetastet. docs/assets/** wird nie durchsucht.

Stempelt außerdem das Frontmatter redirect_from der verschobenen Seite mit ihrer alten URL, sodass ein Build (Weiterleitungen) weiterhin darauf antwortet, statt die Umbenennung jeden externen Link, dessen Quelle dieses Projekt nicht kontrolliert, ins Leere laufen zu lassen (404).

blog:drafts

Listet jeden Blogbeitrag auf, dessen Frontmatter draft: true setzt - build überspringt Entwürfe immer, daher ist dies die einzige Stelle, an der ihre Existenz sichtbar wird.

bxSites blog:drafts

Beendet sich immer mit 0.

blog:find

Filtert Blogbeiträge nach Autor/Kategorie/Tag/Datumsbereich, ohne einen vollständigen build auszuführen.

bxSites blog:find [--author=...] [--category=...] [--tag=...] [--since=...] [--until=...] [--drafts]

• --author, --category, --tag - Groß-/Kleinschreibung ignorierend, exakte Übereinstimmung mit einem der eigenen Werte des Beitrags
• --since, --until - ein Datum; nur Beiträge am/nach --since und/oder am/vor --until passen
• --drafts - auch Entwürfe einbeziehen (standardmäßig ausgeschlossen)

Jeder Filter ist optional und unabhängig - werden keine übergeben, wird jeder veröffentlichte Beitrag aufgelistet.

search:query

Führt eine Stichwortsuche gegen eine bereits gebaute site/search-index.json aus - führe zuerst build oder search-index aus. Bewertet Ergebnisse mit derselben relativen Feldgewichtung, die auch das clientseitige Such-Widget verwendet (Titel, dann Tags, dann Überschriften, dann Fließtext), sodass du prüfen kannst, was die Suche eines echten Besuchers liefern würde, ohne einen Browser zu öffnen.

bxSites search:query --query="getting started" [--limit=10]

• --query (erforderlich) - durch Leerzeichen getrennte Suchbegriffe
• --limit - maximale Anzahl an Ergebnissen, Standard ist 10

lint

Ein Qualitäts-Durchlauf über den rohen docs/-Markdown-Quelltext vor dem Build, getrennt von check (das nur eine bereits gebaute site/ untersucht). Prüft:

• Übersprungene Überschriftenebenen - ein Seitentext, der direkt von ## zu #### springt, ohne dazwischenliegendes ### (verwirrende Struktur und schlecht für Barrierefreiheit). Zeilen innerhalb eines eingezäunten Code-Blocks werden nie fälschlich als Überschriften erkannt.
• Probleme mit Blogbeitrag-Daten - ein Beitrag unter docs/blog/posts/** mit fehlendem oder ungültigem Frontmatter-date (build selbst wirft hierbei bereits einen Fehler, sobald es Beiträge lädt - lint macht es stattdessen als Befund sichtbar).

bxSites lint

Beendet sich mit 1, wenn eine der beiden Prüfungen etwas findet, sonst mit 0.