Documentation

Colophon

Bade mostly leans on other things.

  • Docutils / rST: Bade uses Docutils to process plaintext rST documents into markup, which will be familiar to Python developers. Probably the most useful resource is their quick reference, but there is full documentation available on the Docutils homepage.
  • Mako: Templates are rendered with Mako, a templating engine written by zzzeek. It has inheritance, is fast and lets your do whatever.

Templates

Bade uses a bunch of templates which are pretty empty and intended to be simple to customise to the specific applications. The best way to get an idea of how things are laid out is to look at the markup and see how the <%block> elements are arranged in the base.html template on GitHub.

Context

Another interesting template to look at would be the header.html template that lists links to pages. The pages and blogtree context variable

Blogtree

The way that Bade tells where posts appear chronologically is rather manual. It’s the responsibility of the user to place the content of their pose in a tree of directories where the first level denotes year, the second month and the third day. It’s covered in the Posts section of the Tutorial.

Configuration

Bade has a few options which can be configured through keys in a YAML file. Their effects are detailed below.

assetpaths

A list of directory paths containing any assets to be copied to the build directory. Directory will be preserved. Example:

assetpaths:
  - assets/images
  - assets/js
  - assets/fonts

blogroot

The directory where the tree of Posts_ will appear. Example:

blogroot: blog

blogtree_rst

Path to custom rST template for blog index page. Example:

blogtree_rst: templates/blogtree.rst

build

Directory to build in. Example:

build: _build

debug

Just asks Mako for debugging output. Override with --debug on the command line. Example:

debug: true

index_template

The template to look up to render the front page of the site. Example:

index_template: index.html

pages

Pages and external links, string is a page, dict is an external link. Example:

pages:
  - pages/about
  - pages/projects
  - github: https://github.com/johndoe

template_dirs

Directories to add to Mako TemplateLookup used by Bade (ie. the most preferred templates come first). The packaged templates are always part of this lookup, so if a required template isn’t found in a directory listed here, it will be available. Example:

template_dirs:
  - templates
  - summer_templates
  - winter_templates