---
title: Docs site
order: 4
description: How the docs site at bxlens.boxlang.io is built, themed and published, and where the video scripts live.
icon: lucide:globe
---

# Docs site

These docs are built with [bxSites](https://bxsites.io) from the `docs` folder and published to **bxlens.boxlang.io**.

## Build locally

```bash
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:

| URL | What it is |
|---|---|
| `bxlens.boxlang.io/` | Version **1.0.0**, the default (`versions.default` in `bxsites.yaml`) |
| `bxlens.boxlang.io/next/` | **Next**, the working docs in `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](../gallery.md) 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](../console/ai.md) are scenes `15` to `17`, cropped to the chat panel and saved as WebM and MP4 in `docs/assets/videos` (about 150 KB each).