bass 1.4.0

Static site generator

Bass

Bass is a static website generator (Bass=Build A Static Site), written in Python 3. It turns a collection of content pages, assets (PNG, CSS, JS etc.) and templates into a static website, i.e. a website consisting only of directories, HTML pages and the same assets. Bass is distributed under the MIT license (see the LICENSE file for more details).

The idea behind a static site generator is that you don't need a content-management system on the server to generate pages dynamically: you generate the content, upload it to the server, and repeat this process when something has changed. That way, there is no need to install complex software on the server, with the associated maintenance effort (software upgrade, backup) and security issues.

The design of Bass borrows ideas from Wok and other static site generators (see overview). Before I created Bass, I used Wok for about a year, created two websites with it, and also looked at alternatives. During that year I noticed several drawbacks, which led to the development of Bass.

The most important feature of Bass is that it gives the user complete freedom in organizing the input directory, considers this organization as meaningful, and therefore preserves it in the site tree. With organization of the input directory I mean: (1) the structure of the tree of files and sub-directories in the input directory, and (2) the names of files and sub-directories. This concept was borrowed from Wintersmith. Other static site generators are designed primarily for blog sites, and use an input directory with a fixed structure, or completely ignore the structure of the input directory, creating the structure of the site tree from metadata (Wok for example).

Other features that were added: extension through generic event mechanism (inspired by Pelican and Wok); use of template engines other than Jinja; ignoring specified files in the content directory (e.g. Emacs backup files); flexible pagination.

Documentation

Documentation is in the doc directory. An example site is in the test directory.

Installation

The recommended way to install Bass is from the Python Package Index with this command: sudo pip install bass.

Dependencies

All dependencies are available through pip. Although optional, you should at least install one of the following three tools:

• Markdown (Markdown2 is an alternative)
• Docutils
• Textile

If you install with pip, Markdown2 will be installed automatically.

Required

• pyyaml
• Chameleon

Optional

• Markdown or Markdown2, for rendering Markdown documents.
• Docutils, for rendering ReStructuredText documents.
• Textile, for rendering Textile documents.
• WebOb, for a more advanced web server.
• Waitress, for a faster web server.

Usage

To use Bass, go to the project directory (the directory where the input files and generated site will be located), and run the command bass -c or bass --create. This will create a basic directory structure and corresponding configuration file. You can change the names of the directories, provided you apply the changes in the configuration file as well.

Put your content in the input directory (default: input). Build the site with bass -b or bass --build. If you want to see debugging information, use bass -b -d or bass --build --debug.

If you add the option -s or --serve, Bass will generate the site as usual, and then start a simple web server on port 8080. This web server is intended solely for local testing of the site during the development phase.

If the Python package WebOb is available, a slightly more advanced server (WSGI) is made available. This server checks for changes in the input and layout directories (see the manual) whenever a page is requested. If it detects a change in either of these directories, the site is regenerated before the page is returned. If the Python package Waitress is also installed, this WSGI-based server is replaced with a faster one.

About

Bass is written by Nico Poppelier and licensed under the MIT license.

The name is just another acronym. Several other site generators (e.g. Wok, Wintersmith, Jekyll, Pelican, StrangeCase) inspired this project.