⚡︎ BX Docs

|:------------------------------------------------------: |
| ⚡︎ B o x L a n g ⚡︎
| Dynamic : Modular : Productive |
| :----------------------------:  |

Copyright Since 2023 by Ortus Solutions, Corp
www.boxlang.io | www.ortussolutions.com

Static documentation site generator for BoxLang, built on bx-markdown - in the spirit of mkdocs: write Markdown in docs/, get a themed, searchable static site out. Already on GitBook? bxDocs migrate --source=... converts an export straight into a bx-docs project - see Migrating from GitBook.

Quick Start

# Install this module and its dependencies, via CommandBox
box install bx-docs
box install bx-markdown
box install bx-esapi

# ...or, without CommandBox, BoxLang's own installer takes all three at once:
# install-bx-module bx-docs bx-markdown bx-esapi

# Scaffold a new docs project (docs/ + bxdocs.json)
bxDocs new my-docs
cd my-docs

# Build the static site to site/
bxDocs build

# Or build and serve locally with live reload while you write
bxDocs serve

See Getting Started for the full walkthrough.

Usage

box install drops a standalone bxDocs script on your PATH (via box.json's boxlang.executable), so every verb can be run either that short way, or as boxlang module:bxdocs <verb> - both run the exact same thing; use the longer form anywhere the PATH shim isn't set up (a CI runner, a module registered by hand):

bxDocs <verb> [options]
# or, equivalently:
boxlang module:bxdocs <verb> [options]

Verb	Purpose
`new`	Scaffold a docs project (`docs/` + `bxdocs.json`, defaulting to the `bootstrap` theme)
`build`	Render `docs/**.md` into a static site in `site/`, including the search index, `sitemap.xml`, `llms.txt` and assets. Needs bx-markdown and bx-esapi installed
`serve`	Build and serve the site locally with live reload (needs bx-markdown and bx-esapi too)
`search-index`	Rebuild `site/search-index.json` standalone (also runs automatically during `build`)
`clean`	Remove `site/` and any build cache
`migrate`	Convert a GitBook export (`SUMMARY.md` + `.md` files) into `docs/` + `nav.json`

Every verb accepts --projectRoot=<path> (or a bare positional path) to target a project other than the current directory. Run bxDocs --help for full usage.

Documentation

This repository documents itself with BX Docs - see bxdocs.json and docs/ at the repo root, published at:

ortus-boxlang.github.io/bx-docs - stable docs, built from main
ortus-boxlang.github.io/bx-docs/development - latest/unreleased docs, built from development

Both are built with all three built-in themes side by side (bootstrap at the root, material/tailwind under theme/material//theme/tailwind/) via buildMultiTheme.sh - use the switcher next to the dark-mode toggle to flip between them on any page.

Or read the source directly:

Getting Started
CLI Reference
Configuration - the full bxdocs.json reference
Guides: Themes · Search · Deploying to GitHub Pages · Migrating from GitBook
Releases - versioning policy and what's new per release

See MODULE_SPEC.md for the design spec driving this module's development.

Directory Structure

.github/workflows - CI: tests (tests.yml), PR checks (pr.yml), snapshot/release builds (snapshot.yml, release.yml), and publishing this repo's own docs to GitHub Pages (pages.yml)
models - the module's own source: models/cli (one dispatcher per bxDocs verb), models/config (bxdocs.json loader/validator), models/build (project scaffolding + the docs/nav/markdown/theme/search/sitemap build pipeline)
resources/themes - built-in themes (native BoxLang .bxm templates + assets): bootstrap (default), material, tailwind - all with the BoxLang brand palette, dark mode, breadcrumbs and code-copy buttons applied out of the box. A project can override any of them via its own theme/ folder (same layout.bxm + page.bxm contract - see Themes)
resources/assets - module-wide shared client-side assets: the search widget (search.js) and the copy-code button (copy-code.js)
docs / bxdocs.json - this repository's own docs, built by BX Docs itself (boxlang module:bxDocs build)
tests/specs - TestBox specs, one bundle per class under models/
bifs, components, interceptors - unused by this module today, kept for BoxLang module convention
box.json - package metadata used to publish to ForgeBox
ModuleConfig.bx - this module's configuration/CLI entry point

Local Building

Build.bx packages this module for distribution to ForgeBox: it produces a zip in build/ containing everything needed to run the module (box.json, ModuleConfig.bx, and the rest of the module's own files).

boxlang Build.bx --version=1.1.0

Option	Required	Default Value	Description
`version`	No	`1.0.0`	The version of the module.
`branch`	No	`development`	The branch being built.
`buildId`	No	UUID (generated)	A unique identifier for the build.

Running Tests

With CommandBox installed, install TestBox: box install
Register the module so BoxLang can resolve its bxdocs.* source classes: symlink this repo into your BoxLang home's modules/ folder - that's ~/.boxlang/modules unless $BOXLANG_HOME is set to something else (CI pins it to the checkout's own .boxlang/, per .github/workflows/tests.yml):
```
mkdir -p "${BOXLANG_HOME:-$HOME/.boxlang}/modules"
ln -s "$(pwd)" "${BOXLANG_HOME:-$HOME/.boxlang}/modules/$(basename "$(pwd)")"
```
With the BoxLang CLI installed, run tests using ./testbox/run

Version Management

This module uses SemVer for versioning. The version is stored in box.json, used to publish to ForgeBox, and bumped automatically by the release workflow, which also tags the repo for each release.

GitHub Actions Automation

pr.yml - runs the test suite against every pull request
tests.yml - the reusable test-suite workflow (./testbox/run), called by both pr.yml and snapshot.yml
snapshot.yml - on every push to development: runs tests, then builds and publishes a snapshot release
release.yml - builds and publishes a release to ForgeBox (a stable release from main, or a snapshot when called from snapshot.yml); requires a FORGEBOX_API_TOKEN secret
pages.yml - builds and publishes this repo's own dogfooded docs to GitHub Pages (see Deploying to GitHub Pages)
cron.yml - runs the test suite daily against development

Ortus Sponsors

BoxLang is a professional open-source project and it is completely funded by the community and Ortus Solutions, Corp. Ortus Patreons get many benefits like a cfcasts account, a FORGEBOX Pro account and so much more. If you are interested in becoming a sponsor, please visit our patronage page: https://patreon.com/ortussolutions