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 Documentation View on Brew View Theme Gallery

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.

🌓

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

1. Clone the repository

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

2. Create your first post

./bssg.sh post

3. (Optional) Customize Configuration

Copy config.sh to config.sh.local and edit settings like SITE_TITLE, SITE_URL, or THEME. You can also configure your preferred Markdown processor here.

cp config.sh config.sh.local
# Edit config.sh.local with your favorite editor
# Example: Set MARKDOWN_PROCESSOR="pandoc" or MARKDOWN_PROCESSOR="markdown.pl"

4. Build the site

./bssg.sh build

5. View your site locally (if you have Python installed)

cd output
python3 -m http.server 8000

Your site will be available at http://localhost:8000 for preview.

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)
  • (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 pandoc
# sudo apt-get install parallel

Installation on macOS (using Homebrew):

brew install cmark
# Optional:
# brew install pandoc
# brew install parallel

Installation on FreeBSD:

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

Installation on OpenBSD:

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

Installation on NetBSD:

pkgin in bash cmark
# Optional: pandoc and parallel might be available via pkgin
# 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 command [options]

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|-f]      Edit an existing post
                               Use -n to give the post a new name if title changes
                               Use -f to edit the full HTML file (advanced)
  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, and config
  restore [backup_file|ID]     Restore from a backup
  build [build_options]        Build the site (see Build Options below)
  help                         Show this help message

Build Options (passed to 'build' command):
  --config FILE           Configuration file (default: config.sh)
  --src DIR               Source directory (default: src)
  --output DIR            Output directory (default: output)
  --templates DIR         Templates directory (default: templates)
  --theme NAME            Theme to use (overrides config)
  --static DIR            Static directory (default: static)
  --clean-output [true|false] Clean output before building
  --force-rebuild         Force rebuild all files
  --site-url URL          Override site URL
  --posts-per-page NUM    Override posts per page
  --local-config FILE     Load specific local config file
  (See build script or docs for more...)

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

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. Stay tuned for updates!

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

Brew Documentation Theme Gallery Report Issues