A YAML-driven web server written in Go that generates complete HTML pages from structured YAML and Markdown definitions. Write YAML, get HTML — with virtual hosting, automatic HTTPS, and zero boilerplate.
Website: bserver.info
bserver uses a pipeline of YAML definitions to build complete HTML pages. You only define main: — everything else is inherited:
html.yaml ← starting point (provides <html lang="en">)
├── head.yaml ← <head> with meta, title, styles
└── body.yaml ← <body> wrapping:
├── header.yaml ← navbar
├── main ← YOUR CONTENT (from index.yaml)
└── footer.yaml ← footer text
Names resolve by searching upward through directories — your site's navlinks.yaml overrides the default, but inherited definitions like navbar.yaml are shared across all sites. Files are read on every request, so changes take effect immediately with no restart.
- YAML page generation — Define pages as structured YAML; bserver renders clean, indented HTML5
- Markdown support —
.mdfiles render with full site chrome (navbar, header, footer, styles) - Format definitions — Reusable HTML templates via the
^nameprefix, with variable substitution - Cascading name resolution — Definitions resolve upward through directories, child overrides parent
- Proxy mode — Reverse-proxy a vhost to a backend server with a one-line
index.yaml - Virtual hosting — Serve multiple domains from subdirectories, with a
default/fallback - Automatic HTTPS — Let's Encrypt certificates with self-signed fallback for local development
- Bootstrap 5 — Pre-configured CSS and Font Awesome out of the box
- Server-side scripting — Dynamic content via Python, JavaScript (Node.js), or PHP
- Privilege dropping — Binds ports 80/443 as root, then drops to
nobody - Merge definitions — Extend inherited definitions with the
+nameprefix - Style rendering — YAML-defined CSS with selector keys and property maps
- Debug mode — Add
?debugto any URL (e.g.,http://localhost/?debug) for HTML comment tracing - Hot reload — YAML/Markdown files are read per-request; no server restart needed
- Access logging — Every request is logged with method, path, status, and duration
- Graceful shutdown — Clean shutdown on SIGINT/SIGTERM for systemd compatibility
Requires Go 1.24 or later.
git clone https://github.com/stgnet/bserver.git
cd bserver
go build
./bserverThen visit localhost (port 80 or as shown on startup) to see the built-in documentation site.
A minimal page needs just an index.yaml in www/example.com:
main:
- h1: "Hello World"
- p: "Welcome to my site."This produces:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>bserver</title>
...
</head>
<body>
<header>...</header>
<main>
<h1>Hello World</h1>
<p>Welcome to my site.</p>
</main>
<footer>...</footer>
</body>
</html>Go source files live in the project root. Web content lives in www/, mirroring the /var/www convention:
bserver/
├── *.go # Go source code
├── www/ # Web content root (-base flag)
│ ├── default/ # Fallback for unmapped hosts
│ │ ├── index.yaml # Home page
│ │ ├── header.yaml # Site header
│ │ ├── footer.yaml # Site footer
│ │ └── style.yaml # Site styles
│ ├── example.com/ # Virtual host
│ │ ├── index.yaml
│ │ └── about.md
│ ├── html.yaml # Base document structure (inherited)
│ ├── bootstrap5.yaml # Bootstrap 5 CDN (inherited)
│ ├── navbar.yaml # Navigation component (inherited)
│ └── cert-cache/ # TLS certificates (auto-created)
└── ...
The shared YAML definitions in www/ are readable and can be copied into any virtual host directory to customize behavior.
git clone https://github.com/stgnet/bserver.git
cd bserver
go build
sudo ./install-service.shInstalls and starts bserver as a system 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
sudo ./install-service.sh restartTo uninstall:
sudo ./install-service.sh remove- Getting Started — Installation, directory layout, first page
- Content Definitions — How
main:and named definitions work - Format Definitions — Custom HTML templates with
^nameprefix - Built-in Components — Pre-defined YAML files (html, head, body, navbar, etc.)
- Server-Side Scripts — Dynamic content via Python, JavaScript, PHP, Shell
- Error Handling — Custom error pages
- Server Features — Caching, security headers, rate limiting, TLS, and more
- Proxy Mode — Reverse-proxy a vhost to a backend
- Advanced Features — Virtual hosting, HTTPS, debug mode
- Tips & Recipes — Common patterns and practical examples
Licensed under the Apache License 2.0. See LICENSE for details.