Graaf - static sites generator¶

Config file format¶

By default, Graaf will read graaf.yml for settings.

The layout is as follows, with default values provided:

paths:
  source: pages/
  dest: assets/
  templates: templates/

generators:
  - name: graaf.simple_md.SimpleMarkdown
  - name: graaf.scss.SassGenerator

The generators section lists configurations for the Generators to use, in order. Any other values beyond ‘name’ will be passed to the class when it’s instantiated.

graaf package¶

Submodules¶

graaf.base module¶

class graaf.base.Generator¶

Bases: object

Base Generator class

can_process(filename)¶: Determine if this instance will attempt to process the file.

enter_dir(src_dir, dirs, files)¶: Hook to allow Generators to react to start of processing a dir.

extensions = []¶

finish(processor)¶: Hook to allow Generators to react to end of processing.

leave_dir(src_dir, dirs, files)¶: Hook to allow Generators to react to end of processing a dir.

process(src_dir, dest_dir, filename, processor)¶: Called by the Processor for any file that can_process returns True for.

read_file(src_dir, filename)¶

start(processor)¶: Hook to alow Generators to react to start of processing.

write_file(dest_dir, filename, content)¶

class graaf.base.Processor(srcdir, destdir, templatedir, generators=None)¶

Bases: object

Site Processor class.

Given directories for source documents, destination, and templates, as well as a list of generators, will process all files.

Will apply _.yml to the context in each directory.

render(template_name, extra_context)¶: Helper function to render a template with the current context, and extra context.

run()¶: Trigger to process...

graaf.base.get_yaml(src)¶

Try to read a YAML document from the provided file.

If it doesn’t exist, return an empty dict instead.

graaf.scss module¶

graaf.simple_md module¶

class graaf.simple_md.SimpleMarkdown¶

Bases: graaf.base.Generator

Generator for processing plain Markdown files

Will try to read {filename}.yml for additional context. Processes content as a Template first, allowing variables, etc. Will use context[‘template’] for the template name.

extensions = ['.md']¶

process(src_dir, dest_dir, filename, processor)¶

graaf.verbatim module¶

class graaf.verbatim.VerbatimGenerator¶

Bases: graaf.base.Generator

Copy _any_ file verbatim to the destination.

Useful for static content like images and fonts.

can_process(filename)¶

process(src_dir, dest_dir, filename, processor)¶

Module contents¶

graaf.get_version()¶

Why Graaf?¶

This project is named after Van de Graaf.

Why did you build it?¶

Recently I’ve built a number of sites backed by AWS API Gateway, and needed a way to build their static pages, but remain consistent with the templates and styles of the rest of the site.

How it works¶

Put your source content in a directory. By default this is called pages.
You create a target directory to generate the content in. By default this is called assets.
Write templates for your content. By default these go in a directory called templates.
You run graaf

It will find every file in your sirce directory, and check if any of its configured Generators will work on it. If so, they will be invoked, and (typically) generate an output file.
PROFIT!

Configuration¶

The main configuration file is called graaf.yml and contains two main sections:

paths¶

Here you can override any of three directories

paths:
  srcdir:
  destdir:
  templates:

generators¶

This is a list of generator classes to use, in order.

Each item in the list is a map with at least the import name of a Generator class. It may also include arguments to pass to the Generator for configuration.

generators:
  - name: 'graaf.simple_md.SimpleMarkdown'
  - name: 'graaf.scss.SassGenerator'