Getting Started with bserver

What is bserver?

bserver is a simple web server written in Go that generates HTML pages from YAML definitions. Instead of writing HTML directly, you define your page structure using YAML files, and bserver renders them into complete HTML pages with proper DOCTYPE, head, body, and all the trimmings.

Installation

Build from source:

go build
./bserver

By default, bserver listens on port 80 (HTTP) and serves content from the current working directory. Subdirectories matching domain names are used as virtual host roots.

How It Works

bserver serves virtual hosts from subdirectories. For example, if you run bserver in /var/www/, it will serve example.com from /var/www/example.com/.

The default/ directory is used as a fallback for any host that doesn't have its own directory. This documentation site itself is the default site.

Directory Structure

A typical bserver site looks like this:

mysite.com/
├── index.yaml          # Homepage content
├── about.yaml          # About page
├── navlinks.yaml       # Navigation links
├── header.yaml         # Header section (usually loads navbar)
├── footer.yaml         # Footer section
└── style.yaml          # Custom CSS styles (optional)

The root bserver directory contains shared definitions (html.yaml, head.yaml, body.yaml, navbar.yaml, etc.) that are inherited by all sites.

Your First Page

The simplest page needs only an index.yaml file with a main: definition:

main:
  - h1: "Hello World"
  - p: "This is my first bserver page."

This renders inside the full HTML structure. bserver automatically provides:

The Rendering Pipeline

  1. bserver loads html.yaml as the starting point
  2. html.yaml references head and body
  3. body.yaml references header, main, and footer
  4. Each name is resolved by searching for name.yaml files
  5. Your index.yaml defines main: to set the page content

The pipeline looks like:

html.yaml
├── head.yaml → title, meta, headlink, style
└── body.yaml
    ├── header.yaml → navbar
    ├── main ← YOUR CONTENT (from index.yaml)
    └── footer.yaml → muted text

Name Resolution

When bserver encounters a name reference like footer, it searches for footer.yaml:

  1. First in the current request directory (e.g., mysite.com/)
  2. Then upward through parent directories
  3. Up to the document root and one level above

This cascading search allows shared definitions (like the navbar) to live in the bserver root directory while site-specific content lives in the site directory. Your site's navlinks.yaml overrides the default navigation, but the navbar structure itself is inherited.

Creating Multiple Pages

Each .yaml file that defines main: becomes a page. For example:

about.yaml:

main:
  - h1: "About Us"
  - p: "Welcome to our company."

This page is accessible at /about (bserver strips the .yaml extension).

You can also use Markdown files - any .md file is automatically rendered with the same site structure (navbar, footer, etc.). See the Definitions page for more on how content is defined.

Setting Up Navigation

Create a navlinks.yaml file in your site directory:

navlinks:
  "/": Home
  "/about": About
  "/contact": Contact

Each key is the URL path, and the value is the display text. The navbar automatically highlights the current page using server-side Python scripting.

Adding Styles

Create a style.yaml file for custom CSS:

style:
  body:
    font-family: sans-serif
  .custom-header:
    background-color: "#2c3e50"
    color: white

Or include Bootstrap 5 (already included in the default navbar) for a full CSS framework.

Environment Variables

bserver can be configured with environment variables:

Variable Default Description
HTTP :80 HTTP listen address
HTTPS :443 HTTPS listen address
INDEX index.yaml,index.md,... Index file search order
DEBUG (unset) Enable debug HTML comments

Next Steps