BxSites Build & Diagnostics
Every command runs as bxSites <verb> [options] (or boxlang bxSites <verb> [options] where the PATH shim isn't installed - e.g. a CI runner). Every verb accepts --projectRoot=<path>.
build
bxSites build
Renders docs/.md (or src/) into a static site in site/ - also builds the search index (unless search: false, or searchProvider is set to a provider like algolia/pagefind that doesn't use it - see bx-sites-search), runs the pagefind CLI against the finished site/ when that provider is active, and copies theme + docs/assets/ into site/.
serve
bxSites serve [--port=8080] [--host=127.0.0.1]
Builds and serves site/ locally with live reload. Runs in the foreground until interrupted (Ctrl+C). A native BoxLang file watcher (not a poll loop) reacts to a saved change immediately, and only reconverts the page(s) that actually changed rather than the whole site.
search-index
bxSites search-index
Rebuilds site/search-index.json standalone, without re-rendering pages or copying assets - build already runs this automatically; this verb exists for when only the index needs refreshing. Only ever covers the main docs/ tree, even on a project with docs/versions//docs/i18n/ - a real build writes each tree's own scoped index instead. No-op for the algolia/ pagefind search providers (neither uses a local index) - see bx-sites-search.
clean
bxSites clean
Removes site/ and any build cache, leaving docs/ and the site config alone.
doctor
bxSites doctor
A one-shot environment/config health check - the "run this before filing a bug report" verb. Checks the JVM version, that docs/ exists, that bxsites.yaml/.json actually parses and validates, that the required BoxLang modules (bx-markdown, bx-esapi, bx-yaml, bx-image) are installed and activated, and - if a project-level theme/ override exists
- that it satisfies the
layout.bxm/page.bxm contract (see
bx-sites-themes). Exits 1 if any check fails, 0 otherwise. Nothing here mutates a project.
stats
bxSites build
bxSites stats
A read-only summary report of an already-built site/ (run build first). Reports:
- Total page/word counts, plus a per-tree breakdown once there's more than
one tree (a version, or a non-default locale)
- Version/locale names present
- Blog post/category/author/year-active counts (
none if no blog)
- Distinct tag count across the whole site
- Search-index entry count and file size (
none if search is off or a
non-local provider is active)
- Total file count and on-disk size of the built
site/
Always exits 0 - purely informational, not a pass/fail gate (that's audit's job).
audit
bxSites build
bxSites audit
A CI-grade content quality gate over an already-built site/ (run build first). Checks for:
- Broken internal links/images - any
<a href>/<img src> pointing at
a page or asset that doesn't exist in site/. Fails the check.
- Missing alt text - any
<img> with no alt attribute at all. An
empty alt="" (correct markup for a purely decorative image) is not flagged. Fails the check.
- Orphaned pages - pages in
site/ not reachable by following links
from any tree's own homepage. Informational only, never fails the check - a page deliberately left out of nav (frontmatter hidden: true) is supposed to only be reachable by direct link.
Exits 1 when there are broken links/images or missing-alt images, 0 otherwise (orphaned pages never affect the exit code). Deliberately internal-links-only - no HTTP requests to check external URLs.
A CI-grade pre-publish gate
bxSites build
bxSites audit
bxSites stats
audit catches broken content; stats gives a sanity-check summary before handing off to bx-sites-deployment. See bx-sites-content-quality for lint/blog:drafts/blog:find/search:query, which check raw docs/ source without needing a build first.
A build can report success while producing broken output
A crashed BoxLang process's exit code doesn't always propagate reliably through every calling shell script. When a fix doesn't appear to take effect after a "successful" build, don't trust a green exit code alone - confirm site/ was actually (re)written with the expected content, and run doctor/audit to catch a config or content problem the build step itself didn't surface.
