HTML Templater documentation

Contents

  1. HTML Templater CLI
  2. Manifest file
  3. Element file

HTML Templater CLI

The HTML Templater CLI tool is a very simple command-line application that facilitates static site generation. It's available for most platforms and can easily be integrated into existing toolchains, or function as the sole driver for any static website, such as this very website.

Usage

HtmlTemplater <path-to-manifest>

Alternatively the -v or --version argument can be provided instead, causing the program to output its version and exit cleanly.

Manifest file

This file contains configuration for running HTML Templater. A path to this file must be supplied as an argument when running the HTML Templater CLI. The manifest file's parent folder will be considered the root for all relative paths for the duration of the run, which includes the pages and elements folders.

{
  "elements": [
    "string"
  ],
  "outputPath": "string",
  "assets": {
    "input": "string",
    "output": "string",
    "include": [
      "string"
	],
	exclude": [
	  "string"
	]
}
elements string[]

This array enumerates all custom elements for the given site. For each entry there should be a file in the elements folder with the same name and the htmt extension. For more information on element files, see the section on Elements

outputPath string

Path to the output root folder, where all generated files will be placed. Can be absolute or relative to the location of the manifest file.

assets Object

Defines how assets are handled by HTML Templater.

assets.input string

Path to the assets input folder. When specified with a non-whitespace string, all files and (sub)folders in this folder will be copied to the assets output folder. If not specified, assets will be copied from the pages folder and subfolders therein.

assets.output string

Path to the assets output folder where all assets will be copied to. If not specified, or left empty, assets will be copied to the root of the site's output path.

assets.include string[]

List of strings against which assets are matched for inclusion. Can be partial paths and supports the use of wildcards to indicate whether a path should begin with a string begin* or ends with a string *end.

When no path separators are used in a filter, all paths where only the filename matches are considered included. When not specified, or left empty, will include all files that do not have a htmt extension.

assets.exclude string[]

List of strings against which assets are matched for exclusion. Filter matching works the same way as include filters. Takes precedence over include filters, meaning that any included files will be removed if they also match an exclude filter.

Element file

Each element defined in the manifest file must have a corresponding element htmt file. This file contains all markup to be inserted wherever an element is used inside a page.

Reserved placeholders

These placeholders perform specific functions within an element definition, and can therefore not be used as attribute placeholders.

Note on stability: This list may expand to include additional placeholders, so be sure to revisit this section when upgrading your version of HTMLTemplater prior to the first stable 1.0 release. After the 1.0, any changes to reserved placeholders will be considered a breaking change and will only be introduced in major version updates.

InnerHtml

The {{ InnerHtml }} placeholder will be replaced with the inner HTML inside the element tags on the page.

Example 
<html>
  <body>
    {{ InnerHtml }}
  </body>
</html>elements/page.htmt
<page>
  <h1>Hello World</h1>
</page>pages/index.htmt
<html>
  <body>
    <h1>Hello World</h1>
  </body>
</html>output/index.html

Attribute placeholders

Attributes on the element tags can be used to insert text values anywhere in the element definition, using a placeholder whose name matches the attribute.

Example 
<html>
  <head>
    <title>{{ Title }}</title>
  </head>
</html>elements/page.htmt
<page title="Hello World"></page>pages/index.htmt
<html>
  <head>
    <title>Hello World</title>
  </head>
</html>output/index.html