tmpl

tmpl is a small command-line utility to execute Go templates (defined in text/template and html/template) on files.

Features

By default, tmpl processes configuration from a file named tmpl.config.json in the working directory. You can override this file path with the -f flag.

Here's a sample configuration file:

[
	{
		"in": "index.tmpl",
		"out": "out/index.html",
		"format": "html", // Can be "html", "json", or "".
		"options": {
			// Whether or not to minify the output (default: false; has no effect
			// when the format is "")
			"minify": true,

			// Environment variables to pass in for use in the template. You can
			// also set environment variables normally; variables set in the config
			// file take precedence.
			"env": {
				"FOO": "BAR"
			}
		}
	}
]

Functions

In addition to the built-in functions provided by the text/template package, these functions are available in every template:

• add
• asset
• autoreload
• env
• file
• formatTime
• getJSON
• inline
• jsonify
• markdown
• now
• parseTime
• ref
• safeCSS
• safeHTML
• safeHTMLAttr
• safeJS
• seq
• sub
• svg
• timeIn

add

add returns the sum of the two arguments.

{{ add 2 2 }}

returns

4

asset

asset returns the path provided. In the future, asset may gain the ability to clean or validate the path.

{{ asset "/css/style.css" }}

returns

/css/style.css

autoreload

autoreload returns an HTML snippet that you can embed in your templates to automatically reload the page when a change is detected.

{{ autoreload }}

returns

<script>...</script>

env

env returns the environment variable defined at the provided key. Variables set in tmpl.config.json take precedence.

{{ env "NODE_ENV" }}

returns

production

file

file loads the file at the path provided and returns its contents. It does not create a ref; updating this file's contents won't trigger an update in watch mode.

{{ file "some-letter.txt" }}

returns

...data...

formatTime

formatTime formats the provided time with the provided format. You can either specify both arguments at once or pipe a time.Time into this function to format it.

{{ now | formatTime "Jan 2, 2006 3:04 PM" }}
{{ formatTime now "Jan 2, 2006 3:04 PM" }}

returns

Nov 28, 2021 10:09 AM
Nov 28, 2021 10:09 AM

getJSON

getJSON loads the file at the provided path and unmarshals it into a map[string]interface{}. It does not create a ref; updating this file's contents won't trigger an update in watch mode.

{{ getJSON "REVISION.json" }}

returns

map[string]interface{}{
    ...
}

inline

inline loads the file at the path provided and returns its contents. It creates a ref so that updates to the file trigger an update in watch mode.

{{ file "some-letter.txt" }}

returns

...data...

jsonify

jsonify marshals the provided input as a JSON string.

{{ now | jsonify }}

returns

"2021-11-28T10:09:00Z"

markdown

markdown reads the file at the provided path, parses its contents as Markdown and returns the HTML. It creates a ref so that updates to the file trigger an update in watch mode.

{{ markdown "path-to-markdown.md" }}

returns

<h1>...</h1>

<p>...</p>

now

now returns the time of the template's execution in the local timezone.

{{ now | jsonify }}

returns

"2021-11-28T10:09:00Z"

parseTime

parseTime returns a time.Time from the provided string in RFC3339 format.

{{ parseTime "2021-11-28T10:09:00Z" }}

returns

a time.Time

ref

ref creates a ref to the provided path so that an automatic update is triggered when the file at that path is changed. ref produces no output.

{{ ref "public/style.css" }}

returns

safeCSS

safeHTML

safeHTMLAttr

safeJS

The safe* functions mark their inputs as "safe" so they're not further escaped. See the documentation for CSS, HTML, HTMLAttr, and JS in html/template.

seq

seq returns a slice of n elements. Useful for range.

{{ seq 5 }}
{{ range seq 3 }}
Hello!
{{ end }}

returns

[0, 1, 2, 3, 4]
Hello!
Hello!
Hello!

sub

sub returns the difference between the two arguments.

{{ sub 3 2 }}

returns

1

svg

svg reads the file at the provided path and returns its contents. It creates a ref so that updates to the file trigger an update in watch mode.

{{ svg "path-to-svg.svg" }}

returns

<svg>...</svg>

timeIn

timeIn returns the provided time in the provided timezone.

{{ now | timeIn "America/Los_Angeles" | jsonify }}

returns

"2021-11-28T02:09:00-0800"

---

Watch mode

Watch mode (-w) watches all of the templates in your config for changes and rebuilds them when they're changed. Additionally, any files referenced in your templates via ref or similar template functions will trigger a rebuild of the template.

Server mode

Server mode (-s) is the same as watch mode except it also spins up a webserver that will serve the base directory.

Additionally, this webserver has an endpoint (/__tmpl) which will resolve when a change is made. You can use the autoreload function in your template to automatically reload the page when this endpoint resolves.

Subcommand

You can pass in a subcommand to be run by providing the -- flag and then your command. You might want to use this if you need to run a second development process, like webpack, alongside your templates.

Here's an example:

$ tmpl -w -- webpack -w --mode=development

License

MIT