Template Files

Guide to writing template files

Nift retro neon rainbow vaporwave artwork

For each file tracked by Nift there is a specified template path. When building an output file, Nift will start parsing the template file the same as it will parse any other file, using Nift's template language n++ while producing the output. The files specific to building individual pages are referred to as content files, it does not matter whether you consider other files injected in to a template file as content or template files, it is up to you which file extension you use for them.

Basically all of the functions documented here are available when writing template and content files. However, unlike content files, template files (or one of their dependencies) need to use the page content file as a page dependency.

[contents]

Contents

Specifying where to input/inject content

Nift treats any instance of @content as being equivalent to @input($[contentpath]), where $[contentpath] is the content path for the tracked page.

Note: if @content is in any dependency of the content file (content file inclusive), then an input loop is formed when attempting to build the page so Nift throws an error. You may however put @content in any other dependencies of the template file. For example were your template to include a file template/body.content or template/body.template, it is fine for @content to reside in body.content/body.template and not the main template file.

Alternatively to @content you can:

  • use @content{raw} which will input the content file without parsing it with Nift's template language
  • use @system{content}(sys-call) which is equivalent to @system(sys-call $[contentpath]), where $[contentpath] injects the content path, except Nift also recognises that the content file has been inject. For example if your content files are markdown and you use @system{content}("pandoc") then the content files will be injected after being converted to html using pandoc
  • use @script($[contentpath]) (if the content file is a script/program)
  • use @script{content}(script-path, params) which is equivalent to @script(script-path, $[contentpath], params), where $[contentpath] injects the content path as parameter 1, except Nift also recognises that the content file has been injected
  • use @dep($[contentpath])

Optionally injecting head content

To inject a custom head file for each name using a given template you can use for example:

@input($[contentdir]/$[name].head)
which will input content/name.head.

If you would like to inject a custom head file for only some names using a given template you can use for example:

@input{if-exists}($[contentdir]/$[name].head)
So if you want to optionally add code for a page at that point add a file name.head in the same directory as the content file.

Inputting/injecting titles

When building a page, Nift will replace any instance of $[title] with the title Nift has tracked for the file. Unlike @content, $[title] may be placed inside content files (template files inclusive).

Example template files

A very simple html template file, that specifies both where content and the title are to be inputted, would be:

<!DOCTYPE html>
<html>
	<head>
		<title>site title - $[title]</title>
	</head>

	<body>
		@content
	</body>
</html>

It can be convenient to break what would typically be found inside the template file up into various content files (or you can think of them as also being template files, which extension you use is up to you). For example you may have template/head.content, template/menu.content and template/footer.content. A suitable html template file, say the default template/page.template would then be:

<!DOCTYPE html>
<html>
	<head>
		@input(template/head.content)
	</head>

	<body>
		@input(template/menu.content)

		@content

		@input(template/footer.content)
	</body>
</html>

Note: the head tags may be put inside either template/page.template or template/head.content. However if the head tags are left inside template/page.template then, rather than specifically having to alter template/head.content, the head may be altered from both template/page.template and template/head.content.

Sponsors