# Bx Sites Getting Started

> Install bx-sites (ortus-boxlang/bx-sites) and scaffold a new site, or bring an existing GitBook/mkdocs/Notion project into one - project layout, page frontmatter, linking between pages, and the basic build/serve/clean loop. Use this whenever a user wants to start a new bx-sites project, add/move a plain docs page, or migrate an existing docs project in. For advanced Markdown/content-block syntax, use bx-sites-content-blocks/bx-sites-markdown; for bxsites.yaml keys, themes, or deployment, use bx-sites-configuration/bx-sites-themes/bx-sites-deployment; for the blog/versions/i18n, use bx-sites-blog-versioning-i18n.

- Skill: `ortus-boxlang/bx-sites-getting-started` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ortus-boxlang/bx-sites-getting-started`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ortus-boxlang/bx-sites-getting-started/raw
- Safety review: WARNING
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: ortus-boxlang (https://skillmd.com/u/ortus-boxlang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ortus-boxlang/bx-sites-getting-started

---


# BxSites Getting Started

BxSites (`ortus-boxlang/bx-sites`) is a BoxLang-based static site generator in
the spirit of mkdocs/GitBook: point it at a `docs/` (or `src/`) folder of
Markdown and it builds a themed, searchable static site - not just for docs,
also blogs/marketing sites/knowledge bases.

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>`. **CLI flags
always use `--flag=value`, never a bare positional value**, for a verb's
primary argument.

## Prerequisites

BxSites needs the BoxLang runtime plus `bx-markdown`, `bx-esapi`, `bx-yaml`,
`bx-image` (all installed automatically as `box.json` dependencies):

```bash
# Install BoxLang itself first, if not already present
curl -fsSL https://install.boxlang.io/ | bash
# or BVM (side-by-side version management):
curl -fsSL https://install-bvm.boxlang.io/ | bash && bvm install latest && bvm use latest

# Then install bx-sites
install-bx-module bx-sites   # OS binary installer
# or
box install bx-sites          # CommandBox
```

Either installer drops a `bxSites` script on `PATH`.

## Scaffold a new project

```bash
bxSites new my-docs [--name="My Project Docs"] [--theme=material] [--description=...] [--format=yaml|json]
cd my-docs
```

Creates:

```text
my-docs/
├── docs/
│   ├── assets/
│   └── index.md
└── bxsites.yaml
```

- `--theme` defaults to `bootstrap` - see the `bx-sites-themes` skill for
  all 10 built-in options.
- `--format` defaults to `yaml` (scaffolds `bxsites.yaml`, the
  default/preferred format); `json` scaffolds `bxsites.json` instead. Both
  are fully supported and equivalent - see the `bx-sites-configuration`
  skill for the full key reference.

## Bringing an existing project in

```bash
bxSites migrate --source=<path> [--from=gitbook|mkdocs|markdown-zip|notion]
```

Converts an existing project into `docs/` + `nav.json`:

- `--from=gitbook` (default) - needs a `SUMMARY.md`-rooted GitBook export.
  `{% block %}` syntax becomes its bx-sites equivalent (`::: name`
  directives - see `bx-sites-content-blocks`).
- `--from=mkdocs` - needs `mkdocs.yml`; most syntax carries over unchanged
  since mkdocs-material's own admonition/tabs/math conventions already
  *are* bx-sites' native syntax.
- `--from=markdown-zip` - a plain `.zip` of Markdown files, no proprietary
  format to translate.
- `--from=notion` - a Notion "Export as Markdown & CSV" archive (`.zip` or
  an extracted folder); strips Notion's id-suffixed filenames and turns
  the duplicated leading `# Heading` into real `title` frontmatter.

All four print a conversion summary and a list of anything that needs a
manual look - nothing is silently dropped, but an existing
`bxsites.yaml`/`docs/nav.json` at the destination is overwritten, so review
before committing.

## Project layout

```text
my-docs/
├── bxsites.yaml            # site config (bxsites.json also supported)
├── deployments/*.json      # deploy targets (see bx-sites-deployment)
├── theme/                  # optional project theme override (see bx-sites-themes)
└── docs/                   # or src/ - every .md file here is a page
    ├── index.md
    ├── functions.bxs       # magic functions, see bx-sites-variables-functions
    ├── nav.json            # optional explicit nav (alternative to bxsites.yaml's nav key)
    ├── 404.md               # optional custom 404 page
    ├── robots.txt           # optional hand-authored robots.txt (overrides generated one)
    ├── assets/              # images, downloads, icons - copied to site/assets/
    ├── includes/            # reusable content fragments, spliced via ::: include
    ├── blog/                # see bx-sites-blog-versioning-i18n
    ├── versions/            # see bx-sites-blog-versioning-i18n
    └── i18n/                # see bx-sites-blog-versioning-i18n
```

Folder nesting under `docs/` becomes nav nesting automatically (override
with an explicit `nav` - see `bx-sites-configuration`). `assets/`, `blog/`,
`versions/`, and `i18n/` are reserved folder names with special meaning -
don't repurpose them for ordinary content. A project that isn't really
"docs" in spirit (a marketing site, a portfolio) can use `src/` instead of
`docs/` with zero other changes - every verb looks for `docs/` first and
falls back to `src/`.

## Adding and scaffolding pages

```bash
bxSites page:new --path=guides/setup.md [--title=] [--description=] [--icon=] [--tags=] [--order=]
```

Scaffolds a single page at an arbitrary `docs/`-relative path with
frontmatter pre-filled. Every `.md` file under `docs/` becomes a page.

```bash
bxSites page:rename --from=guides/old.md --to=guides/new.md
```

Moves a page, rewrites every relative Markdown link across `docs/**` that
pointed at it, and stamps `redirect_from` on the moved page automatically
(see `bx-sites-blog-versioning-i18n` for redirects). Always prefer this
over hand-moving a file.

### Page frontmatter

```markdown
---
title: Deployment
order: 2
hidden: false
description: How to deploy a built BxSites site.
tags: [guides, deployment]
icon: 🚀
summary: Everything you need to publish a built site.
ogImage: assets/deployment-card.png
toc: true
redirect_from: [guides/old-deploy-guide]
---

# Deployment
Your content here.
```

- `title` - nav/page title (defaults to filename)
- `order` - sibling sort order in nav (lower first; omitted sorts last, alphabetically)
- `hidden: true` - excludes from nav and search, still built
- `description` - meta description / social card (falls back to site-wide `description`)
- `tags` - array; renders as badges and feeds the site-wide `/tags/` index; boosts search relevance
- `icon` - emoji or a named icon (`rocket`, `lucide:rocket`, `phosphor-bold:rocket`, `tabler:rocket`, `custom:my-icon` from `docs/assets/icons/my-icon.svg`) - see `bx-sites-markdown`
- `summary` - a one-line lead-in rendered under the title (distinct from `description`, which is meta-only)
- `ogImage` - per-page social card image, overrides the site-wide one
- `toc: false` - hides the page's own "On this page" TOC even with 2+ headings
- `redirect_from` - array of old pretty-URL segments that should redirect here; `page:rename` stamps this automatically

It's a small hand-rolled parser, not full YAML: inline lists (`tags: [a, b]`),
block lists (`- item`), and `>`/`|` block scalars work; nested
objects/maps do not.

## Linking between pages

Link with a file-relative path to the target's `.md` source, exactly as if
browsing the repo on disk - `[Deployment](guides/deployment.md)`,
`[back](../getting-started.md#add-pages)`. BxSites rewrites it to the built
pretty-URL at build time, resolved against the *linking* page's own folder.
Absolute URLs, `mailto:`, and links already starting with `/` are left alone.

## Downloading a page as Markdown

Every built page also gets its own original `.md` source published
alongside it (`docs/guides/deployment.md` → `site/guides/deployment.md`,
next to `site/guides/deployment/index.html`) - a "Download Markdown" link
appears on the page itself, next to "Edit this page." Always on, no config.

## Build, serve, clean

```bash
bxSites build           # render docs/**.md into site/
bxSites serve           # build and serve locally with live reload
bxSites clean           # remove site/ and build cache
```

`serve` builds, serves `site/` at `http://127.0.0.1:8080/` by default
(`--port=`/`--host=` to change), and rebuilds automatically on any saved
change under `docs/`, the site config, or a project `theme/` override - a
native file watcher, only reconverting what changed, so it stays fast even
on a large site. See `bx-sites-build` for `doctor`/`stats`/`audit` and a
CI-grade pre-publish gate, and `bx-sites-deployment` for shipping the
result.