A Macro Output Key Kit, acronymed as Mokk, is a collection of files. These files contain human-readable data in the form of key-value pairs, which allows the creation of mass output from the values referenced by the keys in a kit, or collection of keys.
A Mokk file (which will be referred to as a File for the remainer of this document)
utilizes text templating to access data in an object-oriented manner. Often,
.mokkf files will contain ‘mustache-like’ tags:
{{ page.year }}
The first component is a ‘context’, which contains variables. These variables have names (keys)
and their data (values). In this case, the templating tag will output the value of the year
variable for the page context.
There are three primary contexts which comprise the Mokk standard:
{{ global }}{{ page }}{{ collections }}Additionally exist the {{ layout }} and {{ include }} contexts, but these are not accessible
in most situations.
{{ global }}This context is accessible across all Files in a Mokk, and is, as a result, called ‘the global context’.
It is defined within the _global.yml file at the root of every Mokk, written in human-readable YAML 1.2.
The only required variable within the global context is the locale variable, which defines how date & time
information is rendered. The locales are derived from the
GNU C Library’s list of locales.
locale: "fr_FR"would define Metropolitan French as the Mokk’s locale
{{ page }}Mokk files have a context of their own. Each File can be thought of as a Page comprised of a Document and metadata.
Following along with this abstraction, a Document can best be defined as whatever which has been written—the unrendered contents
of a File. In addition to metadata, such as a Page’s location or date-time information, a Document defines a Page.
The most important component of a Document is its ‘frontmatter’, data which provides information pertaining to the File.
Frontmatter is preceded and followed by three en dashes, each given a new line, at the top of the File, the contents being
accessible from the {{ page.document }} variable.
One can consider a simple Page as follows:
--- title: "Hello, world!" --- {{ page.data.title }}
Such a Page would be rendered as:
“Hello, world!”
{{ collections }}Collections are for the categorization of Files, allowing the incorporation of several Files into one. The ‘collections’ context contains collections by name, which can be indexed:
{{ collections["posts"] }}
A File can be assigned to a collection by specifying a collection key in its frontmatter:
--- collection: posts ---
The collection object is an iterable list, containing ‘raw’, or layout-less rendered copies of each File within the collection the object represents. One notable use case would be for a blog, where posts can be assigned collections and then presented on an index page which iterates through the collection.
--- title: Homepage for Blog permalink: index.html --- {% for post in collections["posts"] %} # {{ post.data.title }} by {{ post.data.author }} \ {{ post.content }} ## END OF ARTICLE \ {% endfor %}
Layouts allow a Page to be embedded within a template. Layouts reside in the layouts folder within
a Mokk, and are defined in a page’s frontmatter. A layout’s data is contained within the {{ layout }}
context. Layouts may be within other layouts.
layouts/example_layout.mokkf:
--- title: Example Layout --- # {{ page.data.title }} {{ page.content }}
example_of_page_with_layout.mokkf:
--- title: Example Page --- Layout title: {{ layout.data.title }}
Result:
<h1>Example Page</h1> Layout title: Example Layout
Snippets allow a file’s contents to be embedded within a File. Snippets reside in the snippet folder within
a Mokk, and are called as a Liquid tag.
{% include SnippetFileToEmbed.filetype %}
Optionally, arguments may be passed to a snippet, accessible within the snippet’s source as the {{ include }}
context.
snippets/example_snippet.html:
<p>{{ include.myargument }}</p>
example_of_page_with_snippet.mokkf:
… {% include example_snippet.html myargument="Bonjour, le monde!" %} …
Result:
… <p>Bonjour, le monde!</p> …
Human readable data in Mokk Files is written in the YAML 1.2 data serialization language
Document annotation in Mokk Files is written in the Markdown markup language
Tags, filters, and data placeholders in Mokk Files are written in the Liquid templating language