Templates

A template is a file in templates/ that pages are built in: HTML, with places for each page’s values.

Write a template

In templates/page.html:

<!doctype html>
<html lang="{{ page.language }}" dir="{{ page.direction }}">
<title>{{ headline(page) }} - {{ site.title }}</title>
{% if page.title %}<h1>{{ page.title }}</h1>{% endif %}
{{ page.content }}
</html>

{{ ... }} shows a value. {% if ... %} shows a part only where something is so, and {% for ... %} shows it once for each item. The language is Jinja, as MiniJinja reads it.

A value is written with <, > and & made safe. page.content is HTML already and goes in as it is, as does a value passed through safe.

Two things on a built page are Statac’s own until a file of yours takes their place:

Which template builds a page?

A page is built with the first of these:

1. the template its own layout: names, as layout: post;
2. the template its type: names, where templates/ has one;
3. a layout: handed down from its folder or statac.yaml, as pages.layout: post, unless the page speaks for a list;
4. home for the home page, folder for any other page that speaks for a list, and page for the rest.

The pages that speak for a list are a folder’s index.md, a tag’s or a series’ page, a page with posts: or each:, and the later pages of each: see the page at a list’s address.

On a page with each:, layout: names the template of the pages it makes, not its own: see make a page for each item.

A template is named by its file’s name without .html: post is templates/post.html. One for another kind of file keeps its ending, as layout: sitemap.xml, and what it shows is made safe for that kind: as markup in HTML and XML, as JSON values in .json, and not at all in .txt.

Statac also looks for two templates by name:

Share a frame with extends

In templates/post.html:

{% extends "base" %}
{% block main %}
<article>
{{ page.content }}
</article>
{% endblock %}

templates/base.html holds the whole page, with {% block main %}{% endblock %} where each page’s own part goes. Each block takes the place of the block of the same name there.

Statac has no include, import or from. For a piece used in many templates, such as a post in a list, write a snippet and call it: {{ card(post) }}.

What a template is handed

Every page a template meets has the names page has, so post.url works as page.url does. In a snippet too, page is the page being built, not the post a call hands it.

Serve’s panel shows every name a template can write on a page, with its value there.

The site’s words

{% set words = site.data.words[page.language] %}
<a href="#content">{{ words.skip }}</a>

Statac hands a template nothing called words. A new site keeps the words its pages show in data/words.yaml, under each language’s code, and each template that shows one reads them with the set line above. The line in base.html doesn’t reach a template that extends it. See the words your pages show.

When a page has no such value

{% if page.summary %}
<p>{{ page.summary }}</p>
{% endif %}

Where a template shows a value a page doesn’t have, Statac stops rather than publish an empty space. Say what a page without it shows, as above, or show nothing with {{ page.summary | default("") }}. Defaults chain: {{ page.description | default(page.summary) | default("") }}.

A test such as {% if page.subtitle is defined %} never stops: it may ask about a field no page has yet.

How the built page’s source is laid out

<main>
    {{ page.content }}
</main>

builds as

<main>
    <p>The first paragraph.</p>
    <ul>
      <li>One</li>
      <li>Two</li>
    </ul>
</main>

Statac adds no indentation and no blank line of its own, and takes none of yours away.

• A line holding only a template tag, such as {% if %} or {% for %}, leaves nothing behind.
• A value on a line of its own, such as {{ page.content }} or a snippet call, has each of its lines indented as that line is. Where it comes to nothing, the line isn’t written.
• Lines inside <pre>, <textarea> and an attribute’s value are left exactly as they are.

What a template sees on page

Pictures and files beside the page

A file gives url, the address to link to. A picture, a video and a recording give src, for the element that shows them. A name is found as the writing finds it, and any page can be asked, as post.photo(post.cover). Pictures in templates and files and videos in a template say what each field holds.

What a mention gives

Each is plain text, never HTML, and each but kind and url may be missing, so ask first. Show words as they are: markdown or safe would put another site’s HTML into your page. See webmentions.

What a template sees on site

On a site in several languages, site.posts, site.folders, site.tags, site.series and site.feed are those of the page’s language, and site.pages is every language’s: see each language in templates.

Filters

Jinja’s usual filters are there, such as default, upper, lower, join, replace, length and safe. Statac adds these:

What markdown builds

Functions

Each snippet in snippets/ is called the same way, by its file’s name: {{ card(post) }} places snippets/card.html. See snippets.

What headline calls a page

headline(page) gives the first there is of:

1. its title:, as written;
2. for the home page, the site’s title;
3. the # heading its writing opens with, as a reader reads it, its punctuation set and its Markdown gone: # Using `grep` gives Using grep;
4. for a page that speaks for a list, such as a folder’s or a tag’s, the list’s name, a tag as it is shown;
5. its summary, or else the words of its opening paragraph, cut at a word to 70 characters with … after;
6. its date, written as the site writes dates;
7. its address.

A list’s later pages are called what its first page is. A page marked untitled is called by its date before its summary: see pages without titles.

A template that calls such a page something else asks whether it has a title: {% if page.title is defined %}.

Where next?

• Snippets: pieces of HTML a template or the writing calls by name
• Lists, tags and series: what every list gives a template, and a list’s pages
• Front matter: the fields Statac reads, and fields of your own
• The starter: the templates a new site has