The Makeup of a Blogofile Site

Blogofile is a website compiler, but instead of translating something like C++ source code into an executable program, Blogofile takes Mako templates, and other Blogofile features, and compiles HTML for viewing in a web browser. This chapter introduces the basic building blocks of a Blogofile directory containing such source code.

An Example

The best way to understand how Blogofile works is to look at an example. Create a new directory and inside it run:

blogofile init simple_blog

This command creates a very simple blog that you can use to learn how Blogofile works as well as to provide a clean base from which you can create your own Blogofile based website.

For a more complete example, you can checkout the code for the same website you’re reading right now,

blogofile init

This command downloads the very latest website source code, which requires that you have git installed on your system. If you don’t have it, you can just download the zip file instead.

The rest of this document will assume that you’re using the simple_blog template. It is the defacto reference platform for Blogofile.

Directory Structure

Inside the source directory are the following files (abbreviated):

|-- _controllers
|   |-- blog
|   |   |--
|   |   |--
|   |   |--
|   |   |--
|   |   |--
|   |   |--
|   |   `--
|-- _filters
|   |--
|   |--
|-- index.html.mako
|-- _posts
|   |-- 001 - post 1.markdown
|   |-- 002 - post 2.markdown
`-- _templates
    |-- atom.mako
    |-- base.mako
    |-- chronological.mako
    |-- footer.mako
    |-- header.mako
    |-- head.mako
    |-- permapage.mako
    |-- post_excerpt.mako
    |-- post.mako
    |-- rss.mako
    `-- site.mako

The basic building blocks of a Blogofile site are:

  • - Your main Blogofile configuration file. See Configuration File
  • Templates - Templates dynamically create pages on your site. index.html.mako along with the entire _templates directory are examples. See Templates
  • Posts - Your blog posts, contained in the _posts directory. See Posts
  • Filters - contained in the _filters directory, filters can process textual data like syntax highlighters, translators, swear word censors etc. See Filters
  • Controllers - contained in the _controllers directory, controllers create dynamic sections of your site, like blogs. See Controllers

Any file or directory not starting with an underscore, and not ending in ”.mako”, are considered regular files (eg. css/site.css and js/site.js). These files are copied directly to your compiled site.

Building the Site

Now that you have an example site initialized, we can compile the source to create a functioning website.

Run the following to compile the source in the current directory:

blogofile build

Blogofile should run without printing anything to the screen. If this is the case, you know that it ran successfully. Inside the _site directory you have now built a complete website based on the source code in the current directory. You can now upload the contents of the _site directory to your webserver or you can test it out in the embedded webserver included with Blogofile:

blogofile serve 8080

Go to http://localhost:8080 to see the site served from the embedded webserver. You can quit the server by pressing Control-C.

Understanding the Build Process

When the Blogofile build process is invoked, it follows this conceptual order of events:

  • A file is loaded with your custom settings. See Configuration File.
  • If the blog feature is enabled (blog.enabled), the blog posts in the _posts directory are processed and made available to templates. See Posts.
  • Filters in the _filters directory are made available to templates. See Filters.
  • Files and sub-directories are recursively processed and copied over to the _site directory which becomes the compiled HTML version of the site:
    • If the filename ends in .mako, it is considered a page template. It is rendered via Mako, then copied to the _site directory stripped of the .mako extension. See Templates.
    • If the filename or directory starts with an underscore, it is ignored and not copied to the _site directory (other ignore patterns may be setup using site.file_ignore_patterns in
  • Controllers from the _controllers directory are run to build dynamic sections of your site, for example, all of the blog features: permalinks, archives, categories etc. See Controllers.

Build Process Flowchart

digraph {
     start [shape=circle, label="Blogofile build starts"];
     default_config [shape=box, label="Default configuration is loaded"]
     filters_read [shape=box, label="Filters are discovered in the _filters directory,\nimported, and placed on bf.config.filters cache"]
     controllers_read [shape=box, label="Controllers are discovered in the _controllers\ndirectory, imported, and placed on\nbf.config.controllers cache"]
     user_config [shape=box, label="User's is loaded"]
     user_pre_build [shape=box, label="User's pre_build function is run\n(if present in"]
     site_dir_created [shape=box, label="The _site directory is created.\n(contents cleared out first if necessary)"]
     fatal_error [shape=box, label="A fatal error occurs, and the\n_site directory is incomplete"]
     filter_init [shape=box, label="Filter's init methods run\n(optional; sets up context before running)"]
     controller_init [shape=box, label="Controller's init methods run\n(optional; sets up context before running)"]
     controllers_run [shape=box, label="Controllers run in order of configured priority."]
     files_processed [shape=diamond, label="Rest of files in source\ndirectory are processed:"]
     files_are_ignored [shape=box, label="The file or directory name matches one of the\nsite.file_ignore_patterns and is not copied"]
     files_end_in_mako [shape=box, label="The filename ends in .mako; it's rendered as a\nMako template into the _site directory"]
     files_are_other [shape=box, label="All other files and directories are\ncopied into the _site directory"]
     user_post_build [shape=box, label="User's post_build function is run\n(if present in"]
     site_dir_success [shape=circle, label="User's _site directory\nbuilt successfully"];
     user_build_finally [shape=box, label="User's build_finally function is run\n(if present in"]
     start -> default_config;
     default_config -> filters_read;
     filters_read -> controllers_read;
     controllers_read -> user_config;
     user_config -> user_pre_build;
     user_pre_build -> site_dir_created;
     site_dir_created -> filter_init;
     filter_init -> controller_init;
     controller_init -> controllers_run;
     controllers_run -> files_processed;
     files_processed -> fatal_error;
     files_processed -> files_are_ignored;
     files_processed -> files_end_in_mako;
     files_processed -> files_are_other;
     files_end_in_mako -> site_dir_success;
     files_are_other -> site_dir_success;
     site_dir_success -> user_post_build;
     user_post_build -> user_build_finally;
     site_dir_created -> fatal_error;
     filter_init -> fatal_error;
     controller_init -> fatal_error;
     controllers_run -> fatal_error;
     fatal_error -> user_build_finally;