Get Your Docs Live in 10 Minutes
Install BX Sites, scaffold a project, add a page, and have a real static site built and served locally before your coffee gets cold.
I've written a lot of documentation tools over the years, and the thing I keep coming back to with BX Sites is how little ceremony is involved in going from nothing to a real, browsable static site. No config wizard, no plugin marketplace to shop through first - just a folder of Markdown and one command.
Install
BX Sites is a BoxLang module, so it installs the same way any other BoxLang module does. Its dependencies (bx-markdown for Markdown rendering, bx-esapi for HTML-encoding, bx-yaml for reading your bxsites.yaml, and bx-image for the responsive-image pipeline) are all installed automatically as box.json dependencies, so installing bx-sites itself is the only command needed:
# OS Binary
install-bx-module bx-sites
# CommandBox
box install bx-sites
Either path drops a bxSites script on your PATH, so every command from here on is just bxSites <verb> [options].
Scaffold a project
bxSites new my-docs
cd my-docs
That's it - you now have a docs/index.md and a bxsites.yaml sitting next to it. Pass --theme=material or --theme=tailwind if you don't want the bootstrap default, and --name="My Project Docs" if you don't want the site name derived from your folder name.
Add pages
Every .md file under docs/ becomes a page, and folder nesting becomes nav nesting automatically - no separate nav config to maintain for a normal-sized project:
docs/
├── index.md -> /
├── guides/
│ ├── index.md -> /guides/
│ └── deployment.md -> /guides/deployment/
Link between pages the way you'd expect if the files were just sitting next to each other on disk, because they are:
See [Deployment](guides/deployment.md) for the full picture.
BX Sites rewrites that at build time into the real built URL, resolved relative to the linking page's own folder. It also means the link still works if someone reads the raw file on GitHub instead of the built site - it's a genuinely valid relative path either way.
A page can carry a small frontmatter block up top - title, order, tags, icon, summary, and a few others - all optional. Skip it entirely and BX Sites derives a sensible title from the filename.
Build and serve
bxSites build
renders everything in docs/ into site/, ready to host anywhere that serves static files. While you're actively writing:
bxSites serve
builds the project, serves site/ at http://127.0.0.1:8080/, and rebuilds automatically the moment you save a change under docs/ or bxsites.yaml - your browser reloads on its own, no manual refresh loop.
From here, the obvious next moves are picking a theme that fits your project (see Pick Your Theme) and deciding whether you want search wired up beyond the default (it already is - see Search That Just Works). Both work with zero extra setup beyond what new already scaffolded.
Which part of this took you the longest the first time - install, or picking your first page structure? I'd genuinely like to know.