Configuration File

Blogofile looks for a file called in the root of your source directory; this is your site’s main configuration file. Blogofile tries to use sensible default values for anything you don’t configure explicitly in this file. Although every site must have a, it can start out completely blank. is just regular Python source code. If you don’t know any Python, don’t worry, there’s actually very little you need to change in this file to get started.

Context of is run within a context that is prepared by Blogofile before executing. This context includes the following objects:

  • controllers - Settings for each controller (See Controllers).
  • filters - Settings for each filter (See Filters).
  • site - General Settings pertaining to your site, eg: site.url.

All of these are instances of the HierarchicalCache class. HierarchicalCache objects behave a bit differently than typical Python objects: accessed attributes that do not exist, do not raise an AttributeError. Instead, they instantiate the non-existing attribute as a nested HierarchicalCache object.

This style of configuration provides a seperate namespace for each feature of your blogofile site, and also allows for Blogofile to contain configuration settings for controllers or filters that may or may not be currently installed. For example, your might have the following setting for a photo gallery controller:

controllers.photo_gallery.albums.photos_per_page = 5

In the above example, controllers, photo_gallery, and albums, are all instances of HierarchicalCache. photos_per_page is an integer that is an attribute on the albums HierarchicalCache.

Because this setting is contained in a HierarchicalCache object, if the photo gallery controller is not installed, the setting will simply be ignored.

Site Configuration

In Blogofile, the “site” corresponds with the _site directory that blogofile builds. Even if your site is primarily used as a blog, think of the “site” as the parent of the blog. The site has it’s own namespace within called site.



This is the root URL for your website. This is the URL that your blogofile site will be hosted at:

site.url = ""



This is a list of regular expressions that describe paths to ignore when processing your source directory. The most important one (and one you should not remove) is ".*/_.*" which ignores all files and directories that start with an underscore (like and _posts):

site.file_ignore_patterns = [
# All files that start with an underscore
# Emacs temporary files
# Emacs/Vim temporary files
# Vim swap files
# VCS directories
# Git and Mercurial ignored files definitions
# CVS dir

Blog Configuration

The core of Blogofile actually does not know what a blog is. Blogofile itself just provides a runtime environment for templates, controllers and filters. A Blogofile blog is actually built by creating a blog controller (see Controllers.) A default implementation of a blog controller is provided with the Blogofile simple_blog template and should be sufficient for most users.

All controllers in Blogofile have their own seperate namespace in under controllers. For convenience, you would usually reference the blog controller like so in

blog =



This turns on/off the blog feature. Blogofile is obviously geared toward sites that have blogs, but you don’t need to have one. If this is set to True, Blogofile requires several blog specific templates to exist in the _templates directory as described in Template Environment:

blog.enabled = True



This is the path of the blog off of the site.url. For example, if site.url is and blog.path is /blag your full URL to your blog will be

blog.path = "/blag"


This is the name of your blog: = "xkcd - The blag of the webcomic"



This is a (short) description of your blog. Many RSS readers support/expect a description for feeds:

blog.description = "A Webcomic of Romance, Sarcasm, Math, and Language"



This is the timezone that you normally post to your blog from:

blog.timezone = "US/Eastern"

You can see all of the appropriate values by running:

python -c "import pytz, pprint; pprint.pprint(pytz.all_timezones)" | less



This is the number of blog posts you want to display per page:

blog.posts_per_page = 5



Turns on/off Disqus comment system integration:

blog.disqus.enabled = False


The Disqus website ‘short name’: = "your_disqus_name"



When you configure blog.path, Blogofile by default writes a chronological listing of the latest blog entries at that location. With this option you can turn that behaviour off and your index.html.mako file in that same location will be your own custom template:

blog.custom_index = False



Post objects have a .content attribute that contains the full content of the blog post. Some blog authors choose to only show an excerpt of the post except for on the permalink page. If you turn this feature on, post objects will also have a .excerpt attribute that contains the first blog.post_excerpts.word_length words:

blog.post_excerpts.enabled = True

If you don’t use post excerpts, you can turn this off to decrease render times.



The number of words to have in post excerpts:

blog.post_excerpts.word_length = 25



The name of the directory that contains more pages of posts than can be shown on the first page.

Defaults to page, as in

blog.pagination_dir = "page"



This is a dictionary of file extensions to default filter chains (see Filters) to be applied to blog posts. A default filter chain is applied to a blog post only if no filter attribute is specified in the blog post YAML header:

blog.post_default_filters = {
    "markdown": "syntax_highlight, markdown",
    "textile": "syntax_highlight, textile",
    "org": "syntax_highlight, org",
    "rst": "syntax_highlight, rst",
    "html": "syntax_highlight"

Build Hooks



This is a function that gets run before the _site directory is built



This is a function that gets run after the _site directory is built .. _config-post-build:



This is a function that gets run after the _site directory is built OR whenever a fatal error occurs. You could use this function to perform a cleanup function after building, or to notify you when a build fails.

Read the Docs v: latest
On Read the Docs
Project Home

Free document hosting provided by Read the Docs.