The first static site generator to matter

After installing, copy and modify the example site.ini with your appropriate values:

• In a section called [roxy]
  • timezone should be the name of an IANA Database entry, like America/Los_Angeles
• In a section labeled [site:site-identifier] where site-identifier can pretty much be anything
  • name the name of your site
  • url the URL for your site (purely for cosmetic purposes)
  • url_base the base URL from which absolute URLs will be generated
  • generator the qualified name of a Python module which will act as the generator for this site, see below
  • content_source_path the location of source documents
  • asset_source_path the location of source assets
  • template_path the location of Jinja2 templates
  • build_path the location where generated documents will be written

Then run:

roxy initialize site-identifier

Repeating the same site-identifier from the site.ini

Documents are formatted according to Markdown syntax, with one addition. Until an empty line is encountered, lines are interpreted as metadata, for example:

title: The Title of the Document
slug: super-cool-thoughts
date: 2014-05-12
tags: this
      that
      the other thing
mood: cheerful
eating: A sandwich

The metadata is a place to describe the document and attach arbitrary values to your content. These values will be accessible from the Content object, which is primarily how you interact with documents. You can filter documents on these criteria when describing how to generate your site, and also access these metadata from templates used to render these documents.

After the metadata, insert a blank line and then begin the body of your document.

Assets should exist in the directory specified by asset_source_path. Their path, relative to that directory, will be preserved when writing them out to build_path -- e.g., an image at images/dogs/happy.jpg would, when processed, cause the same directory structure to be written beneath build_path.

Generators are a way to describe how to take in source contents and assets, and write out result documents. I'm lazy, so just look at roxy/generators/blog.py for now. I'll write this up later.