bserver Documentation

bserver is a YAML-driven web server that generates HTML pages from structured definitions. Write YAML, get HTML.

At a high level, bserver is using YAML as a content + composition DSL for full-page generation, not just a template variable file. The key purpose is to let users define site pages declaratively with inheritance and shared structure so they can avoid repetitive HTML boilerplate. That intent is explicit in the pipeline/inheritance model.

The current architecture supports that purpose in several strong ways:

• Composable page skeletons and inheritance (html/head/body pipeline + upward name resolution).
• Two-pass resolution/render so definitions and merges settle before output generation.
• Name-level extension model with ^name formats and +name merges, which is effectively a component and override mechanism.
• Unified Markdown integration by injecting converted markdown into main, then rendering the same chrome as YAML pages.
• Script and data-source hooks that make the content model dynamic.
• YAML-defined CSS generation for style declarations.

Key Features

• YAML-driven page generation with automatic HTML rendering
• Reusable format definitions with the ^ prefix
• Bootstrap 5 integration out of the box
• Markdown page support with full site chrome
• Server-side scripting in Python, JavaScript, PHP, and Shell
• Virtual hosting with automatic Let's Encrypt
• Cascading name resolution across directories

How It Works

Every page starts from html.yaml, which references head and body. The body references header, main, and footer. Your page defines main to set its content. Names are resolved by searching for matching YAML files, starting in the current directory and walking upward.

Quick Example

A minimal page needs just an index.yaml file:

main:
  - h1: "Hello World"
  - p: "Welcome to my site."

This produces a complete HTML page with doctype, head, body, navbar, and footer - all from a few lines of YAML.

Installation

Requires Go 1.24 or later. Clone the repository, build, and install as a service:

git clone https://github.com/stgnet/bserver.git
cd bserver
go build -o bserver
sudo ./install-service.sh

This compiles bserver and installs it as a service using systemd (Linux) or launchd (macOS). The service starts automatically and is enabled on boot.

To update and restart after pulling new changes:

git pull
go build -o bserver
sudo ./install-service.sh restart

To uninstall the service:

sudo ./install-service.sh remove

Documentation

Use the navigation above to explore, or choose a topic:

Getting Started Content Definitions Format Definitions Built-in Components Server-Side Scripts Error Handling Server Features Advanced Features