Grender
Grender is a static site generator. It combines source files with metadata to
produce a website.
Installation
If you have a working Go installation, you
can easily get an up-to-date grender binary.
go get github.com/peterbourgon/grender
Background
Grender is designed to power a large class of simple websites, including but
not limited to blogs. It was created as a response to the perceived complexity
of Jekyll, both in terms of configuration and implementation.
Usage
Single file
Grender renders source files from the source directory (specified by the
commandline flag -source, default src) into the target directory
(-target, default tgt). Grender can render a single source file using
metadata provided in the file itself. Metadata is always valid JSON, and can be
put at the top of certain source files if it's separated by a line containing
only ---.
See the example.
Separate JSON
Metadata doesn't need to be in the source file directly. A valid .json file
provides metadata to every source file in the same directory. In case of
collision, grender prefers "closer" metadata; a file's specific metadata always
overrides a directory's metadata, for example. .json files are read in
lexigraphical order, before any source files are read.
See the example. Note that the .json file isn't copied to the target dir.
Layering metadata
.json files provide metadata not only to every source file in the same
directory, but to all files in all subdirectories, too. In this way you can
"layer" metadata. The source file always receives a single, well-composed
metadata object for rendering.
See the example. The concept and application of composable metadata is
grender's Secret Sauce™.
Imports
You can refer to the same content from multiple source files by using imports.
Save the shared content in a file; use the .source extension so grender knows
not to copy it to the target directory. Then use one of the import directives
to import it:
{{ importhtml "../relative/path.html.source" }}for HTML snippets{{ importcss "../relative/path.css.source" }}for CSS snippets{{ importjs "../relative/path.js.source" }}for JS snippets
See the example.
Markdown and templates
Sometimes it's nice to specify a page merely as its content, and leave it to
the rendering engine to put that into a nice template. .md (Markdown) files
have this behavior by default. Grender expects to find a "template" key in
their metadata, and uses that filename as the template into which the rendered
Markdown is placed. Rendered content is available under the "content" key.
Template files should have the extension .template, so that grender knows not
to copy them to the target directory.
See the example.
Bonus: if a Markdown filename matches the format YYYY-MM-DD-some-text.md,
grender will treat that file as a "blog entry", and perform special behavior.
Given 2013-03-04-foo-bar-baz.md:
- default metadata key title, value "Foo bar baz"
- default metadata key date, value "2013 03 04"
- default target file is 2013/03/04/foo-bar-baz.html (relative to source)
- http-equiv refresh redirects to the target URL are written for all of the
following relative URLs: 2013/03/04/index.html, 2013/03/4/index.html,
2013/3/04/index.html, 2013/3/4/index.html
Discovering other files and metadata
So far we have enough tools to build a basic website. But we don't have any way
of linking to pages we don't explicitly know about. Grender solves this using
something called the Global Key (specified by the commandline flag
-global.key, default files). Any template may refer to any other file,
including all of its contextual metadata, via this key.
Say you want to build a list of every file available in the "blog" directory.
In your template, you can do:
<ul>
{{ range .files.blog }}
<li> <a href="{{ .url }}">{{ .title }}</a> </li>
{{ end }}
</ul>
(url is a special key that grender autopopulates in the Global Key space for
every rendered file.) And what if you only want to list most of the files in
the "blog" directory? You can create blog/default.json:
{ "list": true }
And for the pages you don't want to include:
{ "list": false }
---
Content here
Then, in your template:
{{ range .files.blog }}
{{ if .list }}
<a href="{{ .url }}">{{ .title }}</a>
{{ end }}
{{ end }}
See the complete example.