Templates are written in Tilt. Tilt is, itself, written in Lua and the templating language and leans heavily on Lua and Lua syntax. Within reason, if you can do it in Lua, you can do it in Tilt. This makes the templates incredibly powerful and helps avoid the bloat that comes from trying to do more programmatic things with templating languages like Jinja, while also keeping things pretty simple and readable.

Inheritance

Tilt doesn’t explicitly support inheritance, but it’s possible to achieve something very similar using partial code blocks.

  1. The parent template calls a function–content in the example below–to render customizable elements:

    <!DOCTYPE html>
<html lang="en-US">
 {% include "head.html"  %}
 <body>
   {% include "navigation.html" %}
   <div class="content">
       {% content() %}
   </div>
   {% include "footer.html" %}
 </body>
</html>

  2. The inheriting template provides an implementation of the content functions using partial code blocks and, finally, includes the the parent template:

    {% function content() %}
   <div class="post">
       {% include "post_header.html" %}
       <article class="post-content">
           {{ incontext.renderDocumentHTML(document) }}
       </article>
   </div>
{% end %}
{% include "default.html" %}

Global Variables

{% if document.title then %} <h1>{{ document.title }}</h1> {% end %}

Utilities

RFC 4122 version 4 UUID string.

{% if document.subtitle then %} <h2>{{ titlecase(document.subtitle) }}</h2> {% end %}

Details

Convenience function that fetches a document’s HTML content (document.html()) and evaluates any inline Tilt templates (render()).

Examples

Render the contents of a document:

<html>
  <head>
    <title>{{ document.title or "Untitled" }}</title>
  </head>
  <body>
    <h1>{{ document.title }}</h1>
    {{ incontext.renderDocumentHTML(document) }}
  </body>
</html>

Site

site.url”>site.url

String containing the site URL, as defined in ‘site.yaml’.

site.documents()”>site.documents()

Returns all the documents in the site.

Document

Details

Returns the first document found by walking up the document path; nil if no ancestor can be found.

Examples

Link to Parent

Generate a convenience link for returning to a document’s parent:

{% local ancestor = document.closestAncestor() %}
{% if ancestor then %}
  <a href="{{ ancestor.url }}">Return to {{ ancestor.title }}</a>
{% end %}

Renders:

Return to Documentation

Breadcrumbs

Generate full breadcrumbs for the current document by adding pure-Lua convenience functions:

function reversedipairsiter(t, i)
  i = i - 1
  if i ~= 0 then
      return i, t[i]
  end
end

function reversedipairs(t)
  return reversedipairsiter, t, #t + 1
end

function ancestors(document)
  local ancestor = document
  local ancestors = {}
  while true do
    ancestor = ancestor.closestAncestor()
    if ancestor then
      table.insert(ancestors, ancestor)
    else
      return ancestors
    end
  end
end

Calling it as follows:

{% for _, ancestor in reversedipairs(ancestors(document)) do %}
  &gt; <a href="{{ ancestor.url }}">{{ ancestor.title }}</a>
{% end %}

Renders:

> Home > Documentation

Options

sort “ascending” or “descending” Document sort order. Defaults to “ascending”.

Details

Returns all children, sorted by date, “ascending” or “descending”.

Examples

List a documents immediate children:

<ul>
  {% for _, child in ipairs(document.children({ sort = "descending" })) do %}
    <li>{{ child.title }}</li>
  {% end %}
</ul>

Options

maximumDepth Integer Maximum depth of children to return, relative to the parent.
sort "ascending” or “descending” Document sort order. Defaults to “ascending”.

Details

Returns all descendants of a document, with a primary sort on the date property, and secondary sort the title property of the returned documents.

Specifying a maximum depth of 1 will return the document’s immediate children. Omitting the maximum depth will return all descendants.

Examples

Table of Contents

Generate a table of contents including all the document’s descendants:

<ul>
  {% for _, descendant in ipairs(document.descendants()) do %}
    <li><a href="{{ descendant.url }}">{{ descendant.title }}</a></li>
  {% end %}
</ul>

Children

Generate a list of the document’s immediate children:

<ul>
  {% for _, descendant in ipairs(document.descendants({ maximumDepth = 1 })) do %}
    <li>{{ descendant.title }}</li>
  {% end %}
</ul>

Details

Returns the original path of the document in the site source tree relative to the ‘content’ directory.