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.
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.com:
blogofile init blogofile.com
The rest of this document will assume that you're using the simple_blog template. It is the defacto reference platform for Blogofile.
Inside the source directory are the following files (abbreviated):
|-- _config.py |-- _controllers | |-- blog | | |-- archives.py | | |-- categories.py | | |-- chronological.py | | |-- feed.py | | |-- __init__.py | | |-- permapage.py | | `-- post.py |-- _filters | |-- markdown_template.py | |-- syntax_highlight.py |-- 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:
- _config.py - Your main Blogofile configuration file. See :ref:`config-file`
- Templates - Templates dynamically create pages on your site.
index.html.makoalong with the entire
_templatesdirectory are examples. See :ref:`templates`
- Posts - Your blog posts, contained in the
_postsdirectory. See :ref:`posts`
- Filters - contained in the
_filtersdirectory, filters can process textual data like syntax highlighters, translators, swear word censors etc. See :ref:`filters`
- Controllers - contained in the
_controllersdirectory, controllers create dynamic sections of your site, like blogs. See :ref:`controllers`
Any file or directory not starting with an underscore, and not ending in ".mako", are considered regular files (eg.
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 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
Understanding the Build Process
When the Blogofile build process is invoked, it follows this conceptual order of events:
_config.pyfile is loaded with your custom settings. See :ref:`config-file`.
- If the blog feature is enabled (:ref:`config-blog-enabled`), the blog posts in the
_postsdirectory are processed and made available to templates. See :ref:`Posts`.
- Filters in the
_filtersdirectory are made available to templates. See :ref:`filters`.
- Files and sub-directories are recursively processed and copied over to the
_sitedirectory 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
_sitedirectory stripped of the
.makoextension. See :ref:`templates`.
- If the filename or directory starts with an underscore, it is ignored and not copied to the
_sitedirectory (other ignore patterns may be setup using :ref:`config-file-ignore-patterns` in
- If the filename ends in
- Controllers from the
_controllersdirectory are run to build dynamic sections of your site, for example, all of the blog features: permalinks, archives, categories etc. See :ref:`controllers`.
Build Process Flowchart
Click for larger SVG view