Render HTML from Jade, Handlebars, Swig and most other kinds of templates on the command line. Uses the consolidate.js template engine consolidation library for all heavy lifting.
This is a fork of render-cli to allow using newer or specific versions of rendering engines. For example, the original can't render pug templates because it declares locked dependencies on "consolidate" and all supported rendering engines.
Render is an advanced command-line interface that renders text or HTML from Jade templates, Handlebars templates, Swig templates and pretty much any other kind of templates you can think of.
Use it to generate your static site, to fill out code skeletons, to populate config files – anything you can think of.
dynamic output by passing JSON or YAML data (a.k.a. context variables) to your template
one to many means you can iterate over context data and render the same template once for each set of data
a generic interface so you don't have to learn a different command-line utility for every templating language you'd like to give a try
flexible naming with output paths that can vary based on the data, using path placeholders
Context variables
Pass context variables to your templates with --context <file>... for dynamic rendering. Context can be YAML or JSON.
# no contextrender page.jade# context from a single filerender page.jade \ --input page.json# context from multiple files which will be # merged (if objects) or appended (if arrays)render page.jade \ --context globals.json,page.json# specify globals separately (for clarity)render page.jade \ --context page.json \ --globals globals.json
One-to-one and one-to-many
Render a single page:
# output to `stdout`render page.jade# or redirect to wherever you likerender page.jade > hello-world.html
Render a single page with context:
# one template, one rendered html filerender page.jade \ --context page.json
Pick your own output filename, optionally using information from the context:
Useful if you don't have control over the input JSON and the array or object to iterate over is not at the root. Note that you can traverse multiple levels using dot notation, e.g. results.data.pages.
Namespacing context data
You can pass more than one file to render. Objects will be merged, arrays will be appended to.
When merging different inputs would result in name clashes, you have the option of namespacing
the data from each input file.
Namespaces come in three flavors:
Type
Description
Flag
explicit
you pick the namespace
--input (namespace):(filename)
automatic
the basename of the file
--namespaced
automatic
the full path to the file
--fully-namespaced
Explicit namespaces
Explicit namespaces: put globals.json in a globals key rather than at the root of the context object.
Output paths can contain placeholders that will be interpolated to determine the final path to which to write the HTML for each rendered set of context. Think of your output path as a little template of its own.
If you're a web developer, this is similar to the kind of URL routing you see in web frameworks.
In a path like build/{date}/{permalink}, the date and permalink keys in your data determine where the final HTML ends up. This is especially useful when you ask render to iterate over your context data with --many, which will render and save each set of data separately.
Paths are interpolated using the exact same context data that was used to render your template.
Not just the output path, even the path to your template can be dynamic and based on the data. For example, templates/{layout}.swig will figure out which layout to use by looking for a layout key in your context variables. This means a single render command isn't limited to rendering just a single template.
Output paths that end in a slash will get /index.html tacked on the end.
Pattern
Context
Output
posts/{permalink}.html
permalink: hello-world
posts/hello-world.html
posts/{permalink}/
permalink: hello-world
posts/hello-world/index.html
posts/{permalink}/index.html
permalink: hello-world
posts/hello-world/index.html
Supported template languages
By default, Render uses the templating language matching your extension (.swig for Swig, .jade for Jade). You can explicitly specify which renderer to use with the --engine option.
Render uses the consolidate.js template engine consolidation library for all rendering. For more information on how to contribute a new template engine wrapper, please take a look at their documentation.
Conditional rendering
If your context data includes a date in ISO format, you're in luck. Using the --newer-than <key> flag, you can tell render to only re-render if the context data is newer than the HTML that's already there.
The key flag indicates where in your data render can find the modified date.
This is particularly useful when iterating over multiple context sets: two or three sets of data might have changed but nothing else, and you shouldn't have to rerender all of it.
Speed
The speed of render will depend on the complexity of your templates, the template engine and the speed of your CPU and hard drive. You can reasonably expect to be able to render about 10 to 20 pages per second.
IO is usually the bottleneck, even on machines with solid state drives, so render processes content serially to avoid filesystem contention.