Template engine

As the Wikipedia says, a template engine is software designed to combine one or more templates with a data model to produce one or more result documents. jqt fully satisfies this definition.

Implementation

jqt orchestrates several shell utilities to transform MarkDown text and YAML or JSON data into a final HTML page. The transformation is driven by a template, where HTML is mixed with jq snippets to implement the transformation logic. This diagram shows how document, template and data inputs (on the left) are combined by jqt to produce the final HTML output:

           jqt        +------+   +-------+  jq script
Template +----------->|expand|-->|convert|-------------------------------+
                      +------+   +-------+                               |
                                             HTML and CSS                | 
                                             fragments                   v
           MarkDown   +------+   +------+   /-------->+-----+  JSON   +------+ HTML
Document +----------->|expand|-->|markup|--+          |merge|-------->|render|------> Page
                      +------+   +------+   \-------->+-----+         +------+
                                             YAML      ^   ^
                                             metadata  |   |
           JSON       +------+                         |   |
         +----------->|expand|-------------------------+   |
    Data   YAML       +------+                             |     CSS  +------+ 
         +-------------------------------------------------+    +---->|expand|------> Style
           YAML snippets         +------+                  |          +------+
         +---------------------->|markup|------------------+
                                 +------+

The command jqt is a shell script executed by bash. The external shell commands called by jqt are cat, gpp, jq, mkdir, mkfifo, pandoc, python, rm, sed, sleep and tee.

jqt has been tested with Bash 4.3, GNU sed 4.2, GPP 2.24, jq 1.5 and Pandoc 1.13. A small Python snippet is used which depends on the modules json (introduced with Python 2.6) and yaml (PyYAML implementation). The project uses GNU Make on several development activities, but make is not necessary to run jqt.

Invoking jqt

Synopsis

jqt accepts several options and can be called with zero, one or two filename arguments. The usage possibilities are:

jqt [options] infile result

Options

Preprocessor options

-D NAME=STRING

Defines the user macro NAME as equal to STRING.

-I DIRECTORY

Appends DIRECTORY to the end of the preprocessor list of directories to be searched for include files.

-P LANGUAGE

Expands input file with the macro-processor (LANGUAGE can be jqt, md, json, css or css-min).

Template options

-L DIRECTORY

Appends DIRECTORY to the end of the jq list of directories to be searched for included and imported modules.

-i MODULE

Includes the jq MODULE in the render stage.

-j NAME:MODULE

Imports the jq MODULE in the render stage and define helper function named NAME if MODULE is a data module and has the suffix .json.

Document options

-4, -5

Sets the output HTML version (HTML4 / HTML5).

-d FILE

Reads the content document from FILE.

-w

Build the data model without input document, only from JSON and YAML input files.

Data options

-M NAME:FILE

Adds a FILE in YAML or JSON format to the input data at the top level (NAME is ignored but must be present and unique).

-m NAME:FILE

Adds a FILE in YAML or JSON format to the input data as the value of object NAME.

-T [NAME:FILE]

Transforms front matter YAML top level MarkDown scalar values to HTML. If NAME:FILE is provided add the transformed data to the input data as a value of object NAME. Otherwise, outputs a new YAML document.

Debugging options

-C

Stops processing before the render stage and outputs the full JSON data model.

-H

Stops MarkDown processing after generating HTML (outputs several HTML fragments).

-S

Stops template processing before the render stage (outputs the jq script).

Information options

-h

Displays this message.

-p

Prints information about Pandoc options.

-V

Displays version information.

Preprocessing

One distinctive feature of jqt is the text expansion, using GPP, applied to almost all kinds of input files. Also, jqt can be used as a standalone preprocessor thanks to the -P option.

jqt uses two different syntaxes for macros, one for jqt templates and MarkDown documents and another for JSON and CSS files. The following table summarizes the syntax of macro calls:

The following table summarizes the syntax of text skips: