SmallCage Manual

gommmmmm edited this page Sep 13, 2010 · 4 revisions

What is SmallCage?

SmallCage is a software to generate and update a static website.

After several products of similar kind, we kicked off our brand new engine in ruby at 2007.

Directory layout

These directories under the working directory have special meaning to SmallCage.

  • /_smc/ — contains files used by SmallCage.
  • /_smc/templates/ — contains template files.
  • /_smc/helpers/ — contains helper classes.
  • /_smc/filters/ — contains filter classes.
  • /_smc/ tmp/ — SmallCage creates temporary files under this directory.

Outside _smc directory, files with these names will be handled or referred to by SmallCage.

  • *.smc — will be converted into artifact page. Written in YAML.
  • _dir.smc — contains information on the directory it is placed. Also written in YAML.
  • _local.smc — overwrites values defined in _dir.smc. Put values specific for local environment.

All the files and directories are optional, except for _smc directory placed right under the document root. Once invoked, SmallCage will search for _smc directory, and the parent directory of _smc directory will be considered as document root (note: _smc directory itself must exsist, but SmallCage runs fine with empty _smc directory).

$ mkdir htdocs
$ mkdir htdocs/_smc
$ smc update htdocs
-- 0 files.  0.003 sec.  0.000 sec/file.
$ touch htdocs/index.html.smc
$ smc update htdocs
A /index.html
-- 1 files.  0.005 sec.  0.005 sec/file.

Since there are no template files here in this sample, an empty index.html will be created.

smc files

The basic behavior of SmallCage is, converting a file named (filename).smc into (filename). For example, index.html.smc will be converted into index.html. smc files are plain text formatted in YAML.

Sample smc file:

--- |
<h2>How to use SmallCage</h2>
<p>You can create websites with SmallCage.</p>

Also, smc file can be finely structured like:

 template: gallery
 image: photo1.jpg
 date: 2010-12-31
 title: my picture
 --- |
 <p>These are photographs I took.</p>

You can set any keys as you like to the Mapping (image, date, title, site). In templates, you can refer to the values in the Mapping by its keys.

Sample template file:

<h1><%= title %></h1>
<p><%= date %></p>
<%- site.each do |s| -%><li><%= s %></li><%- end -%>
<%= body %>

Note that some keys have special meaning to SmallCage, or automatically set by SmallCage.

  • template – name of the template currently applying.
  • dirs – information on directory structure.
  • uri / uri.smc – URI of output file / smc file.
  • file / file.smc – path of output file / smc file.
  • strings – array of strings held in smc file.
  • arrays – array of arrays held in smc file.
  • body – alias for strings[0]

SmallCage sets additional keys when ‘URI template’ is used. Discussion on URI template appears later in this manual.

  • uris – result of processing a URI template (as array).
  • cursor – current position on uris array.

Now we will show how the special keys above are handled by SmallCage.


Giving template on Mapping section of smc file, you can choose a template file to be applied to. The template file is assumed to be placed under /_smc/templates/. For example:

template: free
-> /_smc/templates/free.rhtml will be used.

If no template is set in smc file, /_smc/templates/default.rhtml will be used.


An array of information on directories can be referred to as dirs in templates. Each element of the array contains information on ancestor directories of output file. dirs[0] is for document root, dirs[1] for first descendant of document root, dirs[-1] for directory that contains the output file.

When processing /abc/def/index.html.smc:

dirs[0]: information on '/'
dirs[1]: information on '/abc'
dirs[2]: information on '/def'
dirs[-1]: information on '/def'

You can add information to an element of dirs array by putting key-value pairs in _dir.smc file.


URI for the output file is set to uri. URI for smc file can be referred to as uri.smc. For example:

smcfile: /abc/def/index.html.smc
-> uri: /abc/def/index.html
-> uri.smc: /abc/def/index.html.smc


Pathname object representing the path of output file is set to file. As uri, file.smc will return Pathname object for the smc file. For example:

Document root: /home/smc/project 
smc file: /abc/def/index.html.smc
-> file: /home/smc/project/abc/def/index.html (Pathname)
-> file.smc: /home/smc/project/abc/def/index.html.smc (Pathname)


An array of strings. String elements in YAML document are added to this array.


An array of arrays. Array elements in YAML document are added to this array.


Alias for strings[0]. The first string element found in YAML document can be referred to as body.

smc object

SmallCage loads smc file and build smc object from it. smc object is an instance of Hash (Ruby).

All the elements of Mapping type in YAML document are added to this hash. If values with the same key added, the first one will be overwritten by the later.

Elements of Scalar type in YAML document can be referred to by the key strings of smc object. An array of strings will be returned.

Elements of Sequence type in YAML document can be referred to by the key arrays of smc object. An Array of arrays will be returned.

Example – a smc files like:

 template: default
 title: This is the page!
 --- |
 - a
 - b
 - c
 --- |
 <p>something difference</p>
 - x
 - y
 - z

will be built into an object like:

 @obj = {
  "template" => "default",
  "title" => "This is the page!",
  "site" => "",
  "strings" => [
    "<p>something difference</p>"
  "arrays" => [
    ["a", "b", "c"],
    ["x", "y", "z"]
  "body" => "<p>abc</p>" # body is an alias for strings[0]

This is for making it easy to refer to by simple name in templates.

_dir.smc file

You can set some parameters for current directory in _dir.smc. File dir won’t be generated from _dir.smc file.

Most popular use of _dir.smc is to show topic path on multiple pages. _dir.smc at document root can also be used as config file to hold site-wide parameters.

In templates, information on directories are referred to by object name ‘dirs’. dirs[0] contains information on document root.

_local.smc file

_local.smc acts totally same as _dir.smc file. It overwrites the values declared in _dir.smc file. Use _local.smc file to set environment-dependent parameters.

For example, set parameters for live environment in _dir.smc. At sandbox, make _local.smc file to overwrite the parameters. In this case, never put the _local.smc file into version control system. It should not be commonly used across sandboxes.

_smc directory

The direcotry where _smc dir lives will be considered as document root. When smc update invoked, SmallCage goes up the directory until _smc directory is found. With no _smc dir found, SmallCage pukes and stops.

Template files

Template files are written in ERB, placed under /_smc/templates. Suffix should be .rhtml. In smc file, property named template will define what the template file should be used to render it.

template: sample

When this sample is rendered, /_smc/templates/sample.rhtml is used. Without template property, then default.rhtml is used.

In templates, smc object can be referred to by the name ‘@obj’.

<%= @obj["image"] %>

@obj can be ommitted. This means same as above:

<%= image %>

To print the URI of output,

<%= uri %>

will show what’s expected (‘uri’ is a special variable set by SmallCage).

To print the URI of directory that contains smc file currently processing, the template code will be:

<%= dirs.last["uri"] %>

You can include other templates by giving their name.

<%= header %>
<%= body %>
<%= footer %>

header.rhtml will be inserted before body, footer.rhtml after body.

URI template

To output multiple files from a single smc file, or dynamically change file name of the output, use URI template.

URI template is a file like /_smc/templates/(templatename).uri.rhtml

See Publish Multi Files for detailed discussion on URI template.

Helper methods

Methods declared in /_smc/helpers/*_helper.rb can be called in templates, by the name of the methods.

Example helper (/smc/helpers/sitehelper.rb):

module SmallCage
  module SiteHelper
  	def current_date"%Y-%m-%d")

In template:

<%= current_date %>

When rendered, this shows current date time in format like “2010-12-31”.

To make yours own, create a module under ‘SmallCage’ module, name it camel-cased file name (ex: site_helper.rb → SiteHelper), and add methods to it.


If there are multiple objects/methods/templates with a same name, which will be returned by that name is determined by some priority.

1. Local variables and methods declared in templates.

If an object/mehod is declared inside templates, these will be treated with first priority.

2. Helper methods

If there is nothing with that name inside templates, SmallCage searches helper methods.

3. smc object

If no helper method found by the name, SmallCage searches keys in smc object.

4. Template name

No keys found in smc object, then SmallCage searches for a template with that name.

Depending on this priority, you can make some trick on what will be actually returned by same name.

<%= copyright %>

For example, this template code usually includes copyright.rhtml (template) into that point. Occasionally you can set variable named ‘copyright’ in smc file like this.

copyright: (c) 2001-2020 Special Page Inc.

Then <%= copyright %> will print ‘… Special Page Inc.’ instead of what is defined in copyright.rhtml. Also, since helper methods are prior to smc object, it overwrites key in smc objects. If there is a method which named copyright, then a template named ‘copyright.rhtml’ and an object named ‘copyright’ will be ignored even if they exist.

Tips: if you want smc object to be prior to helper methods, call helper method in another template and include it.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.