sbl

sbl is a Go-based static blog builder.

It reads a site folder, discovers Markdown content under content/posts/<slug>/index.md and content/pages/<slug>/index.md, validates content, renders HTML, fingerprints assets, and writes a static site that can be served from public/.

The shipped sbl binary is self-contained. Default templates, CSS, client render bootstrap, vendored KaTeX and Mermaid assets, and the base SWS config are compiled into the executable. To build a site, only the site folder itself needs to be present on disk.

Generated output includes:

• home page
• archive page
• post pages
• standalone pages
• 404.html
• 50x.html
• feed.xml
• sitemap.xml
• robots.txt
• deploy/sws.toml

Commands

Build a site:

sbl build <site-root> [--out <dir>] [--base-url <url>] [--include-drafts] [--clean] [--timings]

Watch source files and rebuild on change:

sbl live <site-root> [--out <dir>] [--base-url <url>] [--include-drafts] [--timings]

Validate content without writing output:

sbl validate <site-root> [--base-url <url>] [--include-drafts] [--timings]

Print the CLI version:

sbl --version
sbl version [--timings]

Options

Global options

• --version, -v: print the current CLI version string

build

• --out <dir>: write output to a custom directory instead of <site-root>/public
• --base-url <url>: override config/site.yaml base_url
• --include-drafts: include draft posts in validation and build output
• --clean: remove the output directory before building
• --timings: print a timing breakdown after the build completes

live

• --out <dir>: write output to a custom directory instead of <site-root>/public
• --base-url <url>: override config/site.yaml base_url
• --include-drafts: include draft posts in validation and build output
• --timings: print an aggregated timing breakdown when live mode exits

validate

• --base-url <url>: override config/site.yaml base_url
• --include-drafts: include draft posts in validation
• --timings: print a timing breakdown after validation completes

version

• --timings: print the total execution time for the version command

Site Layout

Minimum expected input:

<site-root>/
  config/
    site.yaml
  content/
    posts/
      <slug>/
        index.md
        assets/
    pages/
      <slug>/
        index.md
        assets/

site.yaml should define at least:

title: "My Blog"
base_url: "https://example.com"

Optional Prism syntax highlighting theme:

prism_theme: okaidia

Supported Prism themes are prism, coy, dark, funky, okaidia, solarizedlight, tomorrow, and twilight.

Tooling

KaTeX, Mermaid, and Prism ship as self-hosted browser assets committed in the repo.

Pages that contain math, Mermaid fences, or fenced code blocks with a language identifier load those assets client-side from /assets/vendor/.... When code highlighting is used, only the configured Prism theme stylesheet and required language components are published.

Builds do not require Node, npm, or a browser install. Builds do not require checked-out repo templates, static assets, or deploy defaults next to the executable.

Quick Start

1. Build the sbl binary:

go build ./cmd/sbl

2. Create a new site folder:

my-site/
  config/
    site.yaml
  content/
    posts/
      hello-world/
        index.md

3. Add config/site.yaml:

title: "My Blog"
base_url: "https://example.com"
description: "My static site built with sbl."
language: "en"
navigation:
  - label: "Archive"
    url: "/archive/"

4. Add content/posts/hello-world/index.md:

---
title: "Hello World"
date: 2026-04-12
summary: "My first post."
---

## Welcome

This site was built with `sbl`.

5. Validate and build the site:

./sbl validate ./my-site
./sbl build ./my-site --clean

Flags may appear before or after <site-root>.

6. The generated site will be written to:

my-site/public/

7. Preview it with Static Web Server:

static-web-server -w ./my-site/deploy/sws.toml

8. Rebuild automatically while editing:

./sbl live ./my-site

live watches config/, content/, templates/, static/, and deploy/sws.base.toml, then reruns the normal build when those inputs change. It does not start a preview server or auto-refresh the browser.

Usage

1. Create a site folder with config/site.yaml, posts under content/posts/, and optional standalone pages under content/pages/.
2. Run:

sbl validate ./my-site
sbl build ./my-site --clean

3. Serve the generated public/ directory with any static file server.
4. If you use Static Web Server, use the generated deploy/sws.toml.

Example:

static-web-server -w ./my-site/deploy/sws.toml

Releases

CI runs on pushes to main and on pull requests targeting main.

Release publishing runs when you push a tag that starts with v, for example:

git tag v0.0.3
git push origin v0.0.3

The release workflow only publishes if the tagged commit is reachable from main.

Each release uploads one compressed archive per target platform:

• Windows x64: sbl-windows-x86_64-vX.Y.Z.zip
• Linux x64: sbl-linux-x86_64-vX.Y.Z.tar.gz
• macOS arm64: sbl-macos-arm64-vX.Y.Z.tar.gz