https://bssg.dragas.net/ Skip to main content $_ BSSG Bash Static Site Generator * Features * Getting Started * Usage * Themes * Theme Previews * Performance * BSSG Dev Blog * Documentation 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. 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 cd /path/to/your/new/website/output python3 -m http.server 8000 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 cd output python3 -m http.server 8000 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) * (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) init Initialize a new site structure in the specified directory This separates your site content from the BSSG core scripts 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. 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 BSSG A simple static site generator written in Bash for personal journals and blogs. Links * Features * Getting Started * Usage * Themes * Theme Previews * Performance Resources * BSSG Dev Blog * Documentation * Repository * Release Notes * Contributing * Troubleshooting * Theme Gallery Support * FAQ * Issues * Contact (c) 2015-2025 Stefano Marinelli Released under the BSD 3-clause License. []