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
blogtree_rst
¶
Path to custom rST template for blog index page. Example:
blogtree_rst: templates/blogtree.rst
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