Authoring content

Authors must be freed from any concern regarding the presentation of his writings, and his dedication to its structure must be the essential minimum: MarkDown promises and delivers exactly this.

General operation

jqt transforms MarkDown documents to HTML using Pandoc, but before that GPP is used to preprocess them. Pandoc’s output is packaged as JSON data and then merged with the YAML front matter metadata and other input data before be sended to the render stage. This is described on the middle of this diagram:

           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|------------------+
                                 +------+

File structure

Document files contain MarkDown text preceded by an optional YAML front matter.

Front matter

jqt extracts the YAML front matter, located at the very beginning of the file, and injects it into the render stage under a global JSON object named ._front_matter.

Body

Pandoc translates the document body to HTML, and jqt injects it into the render stage under the global JSON scalar ._content. If the document contains fenced code blocks specifying the language of the code block, the related highlight CSS code will be in the scalar ._highlight. Also, the HTML table of contents is available in the scalar ._toc, and the path to the document file in the scalar ._source.

MarkDown snippets

This feature can be used to collect multiple text snippets in only one file (YAML file or MarkDown file with only front-matter). The MarkDown can be transformed to HTML and put in a new YAML or JSON file with a command like this:

jqt -T -- text.yaml | yaml2json > snippets.json

Then this converted file can be loaded by jqt in succesive calls:

jqt -j snippets:snippets.json ...

Template files (only!) can expand the snippets without never containing raw content:

<h1>{{snippets.title}}</h1>

This allows the absolute separation of structure and content, as it should be.

Document syntax

Document’s conversion has two stages. In the first the text is preprocessed, and the second does the proper conversion to HTML.

Preprocessing

The MarkDown input content is preprocessed using GPP. All the expected options in a preprocessor are available, like defining new macros, include other files, etc. For example, a macro call like <%version> will expand to the jqt version (0.5.1) as you can see in this paragraph.

Macro calls

All the power of GPP is available to help you when transcluding the input MarkDown document. The macro syntax used by jqt in templates and input documents precedes macro names with the characters <% and finishes the macro calls with the character >. Here are some of the predefined macros:

<%defeval x y>
<%define x y>
<%elif expr>
<%else>
<%endif>
<%eval expr>
<%if expr>
<%ifdef x>
<%ifeq x y>
<%ifndef x>
<%ifneq x y>
<%include file>
<%undef x>

Inside macro definitions parameters are prefixed by a dollar ($1, $2, etc.), but named parameters are also possible:

<%define sc
    <span style="font-variant:small-caps;">$1</span>
>

Predefined macros and user define macros have the same call sequence:

<%include content/LINKS.txt>
<%sc 'A title in small caps'>

Warning: you must see the GPP manual if you want to know all the gory details.

Skips

Some fragments of text are skipped during macro expansion, like comments, continuation lines and arbitrary but delimited strings of characters:

<# Block comments, removed #>
Continuation lines using an ampersand &
just before the newline character

Strings are copied to the output, but evaluation of macros inside strings can be enabled or disabled depending on the type of string. Also, string delimiters can be copied, or not, to the output:

<!-- XML comments -->
<%sc 'Single quoted strings, only available in user defined macro calls'>
<%sc "Double quoted strings, only available in user defined macro calls">
Inline code `inside backticks`
```
Fenced code blocks with tildes (~~~) or backticks (```)
```

This table summarizes all the available skips:

Pandoc’s Markdown

jqt accepts as input format for documents the Pandoc’s MarkDown variant, with the title block extension disabled, and produces by default transitional HTML. When running jqt all long options specified in the command line will be forwarded untouched to pandoc (as for example with --help), but some are reserved or have no meaning.

Pandoc options used internally by jqt (do not play with them):

    --from=FORMAT
    --to=FORMAT
    --template=FILE
    --table-of-contents
    --output=FILE