Docs site

Docs site

These docs are built with bxSites from the docs folder and published to bxlens.boxlang.io.

Build locally

install-bx-module bx-sites bx-markdown bx-esapi bx-yaml bx-image
bxSites lint      # lint issues fail the publish
bxSites build     # writes site/
bxSites audit     # broken links and missing alt text fail the publish
bxSites serve     # preview with live reload

The theme

The site uses its own theme in docs/.theme, based on the bxSites bootstrap theme. assets/style.css carries the Lens palette (deep navy, cyan and mint) for every page. home.bxm is the homepage (layout: home in docs/index.md) and assets/lens-home.css its look. The homepage is a template, so its text is in home.bxm and not in index.md. Colors, the logo, the favicon and the social image are set in bxsites.yaml and docs/assets.

Publish

The workflow .github/workflows/docs.yml builds the site on every push to development or main that changes docs/**, bxsites.yaml, tools/docs/** or the workflow, runs the lint and audit gates, and publishes site/ to the gh-pages branch with the custom domain bxlens.boxlang.io. It can also be started by hand from the Actions tab.

Versions: 1.0.0 and next

The site has two versions, and for now they are the same docs:

The version switcher is in the header. Until the first release is cut, tools/docs/sync-version.sh copies docs/ into docs/versions/1.0.0/ before every build (the docs workflow does it for you, and you run it by hand for a local preview). That folder is generated and is not committed. Edit docs/ only.

To cut the release: delete the sync step in docs.yml, delete the docs/versions/ line in .gitignore, run tools/docs/sync-version.sh 1.0.0 once and commit docs/versions/1.0.0/. From then on 1.0.0 is edited on its own and docs/ keeps moving as next. A later minor release is bxSites version:new --name=1.1.0 and a new versions.default.

One time setup, by a repository admin:

1. Settings, Pages: serve from the gh-pages branch, root folder. Pages for a private repository needs a plan that includes it.
2. DNS: a CNAME record for bxlens.boxlang.io pointing to the GitHub Pages host of the organization.
3. Pages: set the custom domain to bxlens.boxlang.io and turn on Enforce HTTPS once the certificate is ready.

What publishes and what builds

The docs workflow runs only when docs/**, bxsites.yaml or the workflow itself changes. The module workflows (pr.yml, snapshot.yml, release.yml) ignore those same paths and tools/videos/**, so a docs only change builds no module and makes no release. A required status check on a docs only pull request stays pending: make an admin merge it, or add a no-op check.

The homepage hero and the trailer

The hero is an animated GIF (assets/videos/bxlens-hero.gif) that uses the bxSites image gallery: click it to enlarge. The Watch the trailer button plays bxlens-trailer.mp4 and .webm (the MP4 is listed first because Safari and some phones fail on the WebM, which has no duration) (52 seconds, original music). Both are built by tools/videos/trailer. The Gallery page uses the gallery block for the screenshots.

Videos

tools/videos holds a recording script for each major area of Lens. Each scene can be recorded as a short video or printed as a narration script (tools/videos/SCRIPTS.md). See tools/videos/README.md. The videos are not recorded in CI yet.

The three Lensy loops on the homepage and on the Lensy page are scenes 15 to 17, cropped to the chat panel and saved as WebM and MP4 in docs/assets/videos (about 150 KB each).