A simple static site generator written in Bash

BSSG processes Markdown files and builds a minimal, accessible website suitable for personal journals, daily writing, or introspective personal newspapers. Started in 2015 by Stefano Marinelli as a personal project and maintained privately for many years, it has grown to become what is likely the largest static site generator written in Bash.

Get Started BSSG Dev Blog Documentation View on Brew View Theme Gallery

📣 New BSSG Dev Blog

Stay updated with the latest BSSG news, development progress, and insights on our new project blog.

🛠️ Development Updates 🧪 Experiments 🎨 Theme Previews 📝 Release Notes 💬 Minimalism Thoughts
Visit the Blog

Features

Everything you need to create a personal website or blog

📝

Markdown & HTML Content

Generate HTML from Markdown using commonmark, pandoc or markdown.pl (configurable). Also supports plain HTML pages.

🏷️

Rich Post Metadata

Support for frontmatter (title, date, tags, slug, image, image_caption, description, secondary flag). Auto-generates excerpts if description is missing.

📸

Featured Images

Support for featured images (with optional captions) displayed in index, tag, and archive pages.

⏱️

Reading Time

Automatically calculates and displays estimated reading time for posts (configurable template string).

🔗

Customizable URLs

Define custom URL patterns for posts and pages using URL_SLUG_FORMAT and PAGE_URL_FORMAT.

📑

Dynamic Menu & Pages

Generates menus based on pages, distinguishing primary/secondary pages (via secondary: true). Creates a separate pages.html index for secondary pages.

🗂️

Tag & Archive Pages

Automatically creates tag index pages and archives by year and month (optional) for easy browsing.

📈

Advanced SEO

Generates detailed OpenGraph, Twitter Card, and Schema.org (JSON-LD: Article, WebPage, CollectionPage, WebSite) metadata.

📡

Sitemap & RSS

Generates sitemap.xml and RSS feed (with timezone support) for content discovery and syndication.

🌐

Built-in Development Server

Test your site locally with the integrated development server that automatically adjusts URLs for local preview.

🌓

Multiple Themes

Choose from over 50 built-in themes including modern, retro computing, OS-inspired, and more.

🌐

Internationalization (i18n)

Built-in support for multiple languages using locale files (e.g., en.sh) and MSG_ variables in templates.

⚙️

Flexible Configuration

Configure via config.sh, override with config.sh.local, and use command-line flags for fine-grained control.

🗓️

Date & Time Support

Full date/time support with configurable format (DATE_FORMAT) and timezone awareness (TIMEZONE).

💻

Cross-Platform

Works on Linux, macOS, and BSD systems with automatic OS detection for commands like `date` and `stat`.

⚡

Performance Optimized

Incremental builds, metadata/content caching, parallel processing (with fallback), file locking, and absolute URL post-processing.

📋

Draft Posts

Draft post support with editing capabilities and easy publishing workflow.

💾

Backup & Restore

Built-in backup and restore functionality for all your posts, pages, and config.

Getting Started

Create your site in minutes with these simple steps

✨ Recommended Setup: Separating Content from Core

BSSG now provides a streamlined way to organize your projects by separating your website's content (posts, pages, static files) from the BSSG core scripts. This makes it much easier to update BSSG itself without affecting your site content.

Recommended Setup (New)
Traditional Setup

1. Clone the BSSG core repository

git clone https://brew.bsd.cafe/stefano/BSSG.git
cd BSSG

2. Initialize your site directory

./bssg.sh init /path/to/your/new/website

This command creates a new, separate site directory with all necessary folders (src, pages, drafts, static) and a config.sh.local file. The script will ask if you want to automatically configure the core scripts to use your new site.

3. Create your first post

./bssg.sh post

If you chose to automatically configure the core scripts in step 2, this command will create a post in your new site directory. Otherwise, you'll need to specify the config file:

./bssg.sh post --config /path/to/your/new/website/config.sh.local

4. Build the site

./bssg.sh build

Again, if you chose automatic configuration, this builds your site using the settings in your new site directory. Otherwise, specify the config:

./bssg.sh build --config /path/to/your/new/website/config.sh.local

5. View your site locally

./bssg.sh server

This will build your site and start a local development server. Your site will be available at http://localhost:8000 for preview.

Benefits of this approach

  • Your content is completely separate from the BSSG core scripts
  • You can easily update BSSG without affecting your content (just git pull in the core directory)
  • Multiple sites can be managed with a single BSSG core installation
  • Cleaner organization of your projects

1. Clone the repository

git clone https://brew.bsd.cafe/stefano/BSSG.git
cd BSSG

2. Create your first post

./bssg.sh post

3. Build the site

./bssg.sh build

4. View your site locally

./bssg.sh server

This will build your site and start a local development server. Your site will be available at http://localhost:8000 for preview.

Note: While simpler, this approach mixes your content with the BSSG core files, making it more challenging to update BSSG without affecting your content.

Requirements

BSSG requires the following tools:

  • Bash
  • Markdown Processor: cmark (default and recommended), pandoc, or markdown.pl (configurable via MARKDOWN_PROCESSOR in config.sh.local)
  • Standard Unix utilities (e.g., awk, sed, grep, find, date)
  • socat for the built-in development server
  • (Optional) GNU parallel for faster builds

Install the necessary dependencies for your system:

Installation on Debian/Ubuntu:

sudo apt-get update
sudo apt-get install cmark
# Optional:
# sudo apt-get install socat
# sudo apt-get install pandoc
# sudo apt-get install parallel

Installation on macOS (using Homebrew):

⚠️ Important note for macOS users

The default version of bash included with macOS is too old and not compatible with BSSG. You must install a newer version of bash using Homebrew.

# First, install a newer version of bash
brew install bash

# Then install other dependencies
brew install cmark
# Optional:
# brew install socat
# brew install pandoc
# brew install parallel

After installing the newer bash version, you may need to add it to your allowed shells list and set it as your default shell:

# Add the new bash to allowed shells
echo $(brew --prefix)/bin/bash | sudo tee -a /etc/shells

# Change your default shell (optional)
chsh -s $(brew --prefix)/bin/bash

Installation on FreeBSD:

pkg install bash cmark
# Optional:
# pkg install socat
# pkg install hs-pandoc
# pkg install parallel

Installation on OpenBSD:

pkg_add bash cmark
# Optional:
# pkg_add socat
# pkg_add pandoc
# pkg_add parallel

Installation on NetBSD:

pkgin in bash cmark
# Optional: pandoc and parallel might be available via pkgin
# pkgin in socat
# pkgin in pandoc
# pkgin in parallel

Remember to set the MARKDOWN_PROCESSOR variable in your config.sh.local if you choose to use pandoc or markdown.pl instead of the default cmark. For markdown.pl, ensure the script is downloaded and available in your PATH.

For complete documentation on installation and configuration, please refer to our comprehensive documentation (the README.md in the repository). Leverage config.sh.local for persistent personal overrides and command-line flags (e.g., --theme minimal) for temporary settings changes during builds.

Usage

Simple commands to manage your site

Available Commands

Usage: ./bssg.sh [--config ] command [options]

Global Options:
  --config             Specify a custom configuration file. Overrides BSSG_LCONF
                             and the default config.sh.local.

Commands:
  post [-html] [draft_file]    Create a new post or continue editing a draft
                               Use -html to edit in HTML instead of Markdown
  page [-html] [draft_file]    Create a new page or continue editing a draft
                               Use -html to edit in HTML instead of Markdown
  edit [-n]         Edit an existing post
                               Use -n to give the post a new name if title changes
  delete [-f]       Delete a post
                               Use -f to skip confirmation
  list                         List all posts
  tags [-n]                    List all tags
                               Use -n to sort by number of posts
  drafts                       List all draft posts
  backup                       Create a backup of all posts, pages, drafts, and config
  restore [backup_file|ID]     Restore from a backup (all content by default)
                               Options: --no-content, --no-config
  backups                      List all available backups
  build [-f] [more...]         Build the site (use 'build --help' for all options)
  server [-h] [options]        Build & run local server (use 'server --help' for options)
                               Options: --port  (default from config: 8000)
                                        --host  (default from config: localhost)
  init       Initialize a new site in the specified directory
  help                         Show this help message

Creating Content

Create posts and pages in Markdown or HTML with powerful frontmatter options for metadata.

Learn More

Managing Posts

List, edit, and organize your content with easy commands for content management.

Learn More

Backup & Restore

Keep your content safe with built-in backup and restore functionality.

Learn More

Local Development Server

Preview your site locally with the built-in web server

BSSG includes a simple but powerful built-in web server to help you preview your site locally during development. This eliminates the need for setting up a separate web server for testing.

Starting the Server

./bssg.sh server

Running the server command will:

  1. Automatically build your site: The command runs the build process first, ensuring you're always previewing the latest version.
  2. Temporarily adjust SITE_URL: During the build, it sets SITE_URL to match the local server address (e.g., http://localhost:8000), ensuring all links work correctly in the preview. Your configuration files remain unchanged.
  3. Start the server: It serves files from your configured OUTPUT_DIR and provides a URL for local access.

Server Options

⚙️

Available Options

The server command provides several options to customize your local development experience:

  • --port <PORT> - Specify a custom port (default from config: 8000)
  • --host <HOST> - Specify a custom host/IP address (default from config: localhost)
  • --no-build - Skip the build step and serve existing content
# Examples:
./bssg.sh server --port 8080
./bssg.sh server --host 192.168.0.2
./bssg.sh server --no-build

You can run server --help for detailed information about all available options.

Example Workflow

# Create a new post
./bssg.sh post

# Start the development server to preview changes
./bssg.sh server

# In a different terminal, edit your post
./bssg.sh edit src/your-post.md

# Stop the server with Ctrl+C and restart with changes
./bssg.sh server

💡 Configuration Options

You can set default server host and port in your config.sh.local file:

BSSG_SERVER_PORT_DEFAULT=8080
BSSG_SERVER_HOST_DEFAULT="0.0.0.0"  # Accessible from any device on network

Themes

Customize the look of your site with over 50 built-in themes

BSSG includes a variety of themes to customize the look of your site. Set your chosen theme in the config.sh.local file:

# Example config.sh.local entry
THEME="your-theme-name"

Or override it temporarily during build:

./bssg.sh build --theme minimal

Theme Categories

Modern Themes

Clean, contemporary designs including default, minimal, dark, flat, material, art-deco, bauhaus, mid-century, swiss-design, nordic-clean, braun, and mondrian.

Retro Computing

Nostalgic themes inspired by classic computers: amiga500, apple2, atarist, c64, msdos, terminal, zxspectrum, nes, gameboy, mario and tty.

OS-Inspired

Themes based on operating systems: beos, macclassic, macos9, nextstep, osx, win311, win95, win7, and winxp.

Web Era Themes

Capture the aesthetic of different web eras: web1, web2, vaporwave, y2k, and bbs.

Content-Focused

Optimized for reading: docs, longform, reader-mode, and text-only.

Special Themes

Unique designs: brutalist, newspaper, diary, and random (selects a different theme each build).

Want to see all themes in action?

Visit our Theme Gallery to explore all available themes with real content.

View Theme Gallery

Theme Preview Generator

Generate examples of all available themes with your content

BSSG includes a script to generate previews of all available themes. This helps you see how each theme looks with your content before deciding which one to use.

Generate Theme Previews

./generate_theme_previews.sh

This will create a directory called example/ containing subdirectories for each theme, along with an index.html file that allows you to navigate between them.

Custom Site URL

Set a custom base URL for the previews, useful if hosting the example gallery in a subdirectory.

./generate_theme_previews.sh --site-url "https://example.com/blog/example"

Each theme preview will be accessible relative to this URL (e.g., https://example.com/blog/example/dark).

The script pulls the SITE_URL from these sources in order of precedence:

  1. Command line argument (--site-url)
  2. Local config file (config.sh.local)
  3. Main config file (config.sh)
  4. Default value (http://localhost)

Performance Features

Built for efficiency even with large sites

⚡

Incremental Builds

Intelligently rebuilds only what changed, checking source files, templates, config (config.sh, config.sh.local), locale files, and theme files.

💾

Caching System

Maintains caches for extracted metadata, rendered content, config state, and theme files to minimize redundant work.

⚙️

Parallel Processing

Uses GNU parallel (if available) to process multiple files simultaneously. Includes a built-in fallback using background jobs if parallel is not found.

🔒

File Locking

Implements basic file locking for safer concurrent operations when multiple processes access cache files (especially during parallel builds).

🔗

Absolute URL Generation

Automatically post-processes generated HTML, CSS, and XML files to ensure all internal links use the absolute SITE_URL defined in config.

🧹

Stale Cache Cleaning

Automatically removes cache entries for source files that have been deleted to keep the cache relevant.

Enable Parallel Processing

For the fastest builds, especially on multi-core systems, install GNU parallel:

# Debian/Ubuntu
sudo apt-get install parallel

# macOS (Homebrew)
brew install parallel

# FreeBSD
pkg install parallel

BSSG automatically detects and utilizes parallel if present, falling back gracefully otherwise.

Admin Interface

Manage your blog with a user-friendly interface

Coming Soon!

The admin interface is currently under development and has not been released yet. Follow the BSSG Dev Blog for updates on this and other features!

BSSG will include an admin interface for managing your blog with these planned features:

✏️

WYSIWYG Editor

Create and edit posts with a user-friendly Markdown editor.

📅

Post Scheduling

Schedule posts for future publication with an easy-to-use calendar interface.

📊

Statistics

View statistics about your blog including post count, tag usage, and more.

Get Involved

Join the community, contribute, and stay updated

BSSG Dev Blog Brew Documentation Theme Gallery Report Issues