Ream Static Site Generator

Ream (named for the quantity of paper, not the action) is a very simple static site generator that is designed to allow for easy management of a personal website with zero hosting overhead. All that is required to deploy a site made with Ream is a webhost that can serve static content.

Features

• Handles both blog posts and loose pages
• Generated output has a clean, hierarchical structure
• Templates and posts are written in raw HTML
  • Templating insertion is handled through simple text replacement
  • Posts and pages are nearly HTML -- the first two lines are raw text that are the title and author, respectively
  • Supports snippets to reduce template copy-paste
• Generates output that can be hosted anywhere, not just at the root of a server
• Commands for easily generating new pages and posts in a site

Non-Features

• Does not resize/re-encode images
• Does not support popular, non-HTML document markup formats
• Does not pre-process CSS files
• Does not have any facilities for live rebuilding and serving a debug version of a site
• Does not support conditional templating
• Does not support complex data management and referencing
• Does not currently do blog post pagination and unlikely to ever support it

Usage

Initialize a new site

ream init <site-path>

This will create a new folder and pre-populate it with the minimum set of default templates and config data necessary to make a working site.

Build a site

ream build <site-path> [<output-path>]

Processes a site into either the provided output path (if any), or a directory adjacent to the site directory but with _built appended. i.e. my_site would build into my_site_built.

Add a page

ream add-page <site-path> <page-name>

Adds a page with the given name to a site (if one of the same name doesn't already exist), and then attempts to launch $VISUAL or $EDITOR (in that order) to immediately start editing the new page.

Add a post

ream add-post <site-path>

Adds a post for today's date to a site (if one of the same date doesn't already exist), and then attempts to launch $VISUAL or $EDITOR (in that order) to immediately start editing the new post.

Specifications

Pages and posts are expected to be HTML snippets with a two-line header.

1. Title
2. Author

The HTML content starts on the third line and is the rest of the file.

The <!--SHORT-BREAK--> token provided exactly as-is on its own line can be used to demarcate the boundary between the "short" text and the rest of a post. The short text will be used as the description for the post in RSS. If this token is missing then the entire contents of the post will be used.

Snippets are HTML fragments that live in the snippets/ directory. They are referenced by their name minus the .html extension. Snippets can contain templates, but extra care must be taken not to create infinite loops. Ream will abort processing with an error if nesting exceeds 10 levels.

File Structure

A site is expected to be a folder containing:

• config.ini - key/value pairs, no sections (yet)
• home.html - page which will become the root index.html. Does not support body template and should be a complete page
• page_template.html - template for pages
• post_template.html - template for pages
• style.css - the site stylesheet
• files/ - a place to store any extra, unprocessed files
• pages/ - the root of the page structure
• posts/ - the root of the post structure

Page/Post

Pages are expected to be in subdirectories directly inside the pages/ directory.

Posts are expected to be in a directory hierarchy that looks like posts/<year>/<month>/<day>. Only a single post per day is supported. Month and day are expected to be two-digit numbers (i.e. leading zeroes).

Pages and posts will have the first path component (either pages/ or posts/) removed when output to help beautify the generated URL. For this reason you should avoid naming pages archive or a four-digit year that conflicts with the generated posts.

Config

The required keys are:

• site - The name/title of the site
• url - The URL where the site will reside. Required for RSS to function.
• feed-description - The description of the site for RSS. No HTML.

Template Reference

• [[SITE]] - The site name, shortcut for [[CFG:site]]
• [[TITLE]] - The page/post title
• [[AUTHOR]] - The page/post author
• [[DAY]] - The post date's day.
• [[MONTH]] - The post date month name.
• [[MONTH_NUM]] - The post date's month number 1-12.
• [[YEAR]] - The post date's year.
• [[CSS]] - CSS header declaration. Shortcut for using writing an HTML <link> tag using [[REL:style.css]].
• [[BODY]] - The body text
• [[ARCHIVE]] - Link to the post archive. Shortcut for [[LINK:archive/:Archive]].
• [[PREV_ENTRY]] - Link to the previous blog entry chronologically, only valid in posts
• [[NEXT_ENTRY]] - Link to the next blog entry chronologically, only valid in posts
• [[HOME]] - Link to the homepage. Shortcut for [[LINK::Home]].
• [[CFG:<key>]] - Returns the value of <key> from config.ini
• [[PAGE:<page-name>]] - Makes a link to the page of the given name. Shortcut for [[LINK:<page-path>:<page-title>]].
• [[LINK:<path-from-root>:<link-text>]] - Makes a relative link with the given text.
• [[REL:<path-from-root>]] - Returns the raw, relative path to something. Does not insert any HTML elements.
• [[FEED:<max-posts>:<snippet>]] - Formats up to <max-posts> most recent posts' short text and titles as a reverse-chronological feed using <snippet> as a template.
• [[SNIPPET:<snippet-name>]] - Inserts the contents of snippets/<snippet-name>.html.