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][wok] and other static site
generators (see [overview][static]). 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][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][pelican] and Wok); use of template engines other than
Jinja; ignoring specified files in the content directory (e.g. Emacs backup
files); flexible pagination.

[wok]: https://github.com/mythmon/wok
[static]: https://www.staticgen.com/
[wintersmith]: https://github.com/jnordberg/wintersmith
[pelican]: https://github.com/getpelican/pelican

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][pypi]
with this command: `sudo pip install bass`.

[pypi]: http://pypi.python.org/pypi

### 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.
