hymark
Render markup using templates and YAML front-mattered content.
Installation
The hymark command line utility can be installed globally with npm (which you'll get by installing Node).
npm install hymark --global
Alternatively, you can install hymark locally as a development dependency of a Node-based project.
npm install hymark --save-dev
Usage
hymark <input> <output> [options]
Hymark takes source files from an <input> directory and transforms them into HTML files in an <output> directory. The <input> directory must be a path to an existing directory. The <output> directory will be created if it does not exist.
Options
match
The match option is a list of patterns that determines which of the files in the input directory should be processed. By default, all Markdown and HTML files are processed, and files in directories starting with _ are ignored.
hymark src dist --match='**/*.md' --match='**/*.html' --match='!**/_*/*'
As shown above, the CLI accepts multiple match options to form a list. If you need something different than the default behavior (processing Markdown and HTML and ignoring _ directories), you can supply your own patterns. Below is a brief overview of the pattern syntax:
*matches any number of characters, but not/?matches a single character, but not/**matches any number of characters, including/, as long as it's the only thing in a path part{}allows for a comma-separated list of "or" expressions!at the beginning of a pattern will negate the match
See globby and minimatch for more detail on the pattern syntax.
engine
Including an engine option triggers template rendering.
hymark src dist --engine=handlebars --templates=src/_templates
The supported engines are atpl, dust, eco, ect, ejs, haml, haml, handlebars, hogan, jade, jazz, jqtpl, JUST, liquor, lodash, mustache, QEJS, ractive, swig, templayed, toffee, underscore, walrus, and whiskers. To use a template engine, it must be installed with npm first.
templates
The templates option is the path to a directory containing templates. By default, the current directory will be searched for templates. Typically you'll want to provide an alternate path. Note that if you keep templates in the same directory as your source Markdown or HTML files, you'll want hymark to ignore your template directory when processing input files. The default behavior is to ignore directories starting with _ when processing input files. So it works well if you keep templates alongside your source files in a directory named _templates.
For example, given the following files:
src/
hello.md
world.md
_templates/
page.html
Running hymark src dist --engine=handlebars --templates=src/_templates will produce the following output files:
dist/
hello.html
world.html
YAML Front Matter
When templates are rendered, the content from an input source file is made available as the content variable. To make additional data available for template rendering, input source files can include YAML front matter.
For example, consider the following hello.txt input file:
---
title: Hello
template: page.html
---
body content here
In parsing this input file, the data below would be made available to the template:
Note that depending on the template engine that you choose, you'll want to make sure that the content is rendered directly, without additional HTML escaping. An example Handlebars template might look like this:
{{ title }} {{{ content }}}