CLI Reference

• 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.
• 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.
• 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.
• 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.

Text Formatting 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

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.

Snippets are great to use when you want to share some HTML content in all three of the page templates (home, page, and post); e.g. a header, a footer, or a link tree.

File Structure

A site is expected to be a folder containing:

• config.ini - key/value pairs, no sections (yet)
• feed.xslt - XSLT stylesheet so users can open the generated feed in a browser and get something that looks nice
• 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
• snippets/ - HTML snippets

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.

Site Generation Notes

Any additional files inside of the post and pages structure will be copied wholesale to the corresponding location in the built site. This allows you to add images or other files specific to a post or page directly adjacent to the index.html and easily reference them rather than putting them into the files/ subdirectory.

When a site contains posts, an archive page and a feed.xml RSS feed will be created at the root of the site.

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.

Feel free to define your own key-value pairs. They can be accessed through text templates (see below). The values can even contain more templates, though be careful about the maximum nesting constraint — templates currently support 10 levels of nesting.

Template Reference

Parameterized templates in Ream can be nested, mostly to allow using CFG templates to centralize settings. There's also nothing particularly “hygenic” about them as they're implemented using basic text replacement.

• [[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's 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.