Template Files

Guide to writing template files

Nift badger mascot

Remember that 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 while producing the output. Consequently everything that applied to writing content files also applies to writing template files. However, unlike content files, template files (or one of their dependencies) need to use the page content file as a page dependency.

Specifying where to input/inject/insert 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 would be formed when attempting to build the page so Nift will throw 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{inject, content}(sys-call) which is equivalent to @system{inject}(sys-call @[contentpath]), where @[contentpath] injects the content path, except that Nift recognises that the content file has been included. For example if your content files are markdown and you use @system{inject, content}("pandoc") then the content files will be injected after being converted to html using pandoc
  • use @script{inject}(@[contentpath]) (if the content file is a script/program)
  • use @script{inject, content}(script-path, param 2, ..., param n) which is equivalent to @script{inject}(script-path, @[contentpath], param 2, ..., param 2), where @[contentpath] injects the content path as parameter 1, except that Nift recognises that the content file has been included
  • 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/inserting 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.