docs/guide/04-templates.org

A block of content that is not really layout — an invitation to reply, a licence line, a donation ask — is better as its own file than as a line inside base.html:

{% extends "base.html" %}
{% block content %}
{{ body | safe }}
{% include "reply.html" %}
{% endblock %}

Emptying reply.html removes it everywhere; editing it re-renders exactly the pages that include it, because the render key follows includes. And because the page chooses its layout, an individual page opts in with #+TEMPLATE: post.html or out with #+TEMPLATE: base.html, without a rule deciding for a whole directory.

The rendered page HTML. Always use {{ body | safe }} — it is already HTML, and escaping it would print tags at the reader.

Empty on generated pages, which build their content from pages or groups instead.

page.keywords is the escape hatch: #+CUSTOM_THING: x is {{ page.keywords.custom_thing }}, so your own metadata works without orgo knowing it exists.

site.title, site.base_url, site.description, site.language — straight from [site] in the config.

A list of {title, url}, with URLs relative to the current page.

The ../ prefix back to the site root from this page: empty at the top level, ../ one level down. Prefix it to any site-root-relative path so the same template works at any depth:

<link rel="stylesheet" href="{{ root }}style.css">
<a href="{{ root }}{{ post.url }}">{{ post.title }}</a>

URL of the generated syntax.css, relative to this page. Link it or code blocks are unstyled.

URL of theme.css, relative to this page — the built-in theme named by site.theme. Empty when there is none, which is the default, so guard it and link it before stylesheet or the theme's code colours would override the highlighter's:

{% if theme %}<link rel="stylesheet" href="{{ theme }}">{% endif %}
{% if stylesheet %}<link rel="stylesheet" href="{{ stylesheet }}">{% endif %}

A layout that ignores it is a layout with its own CSS, which is the point at which you have outgrown the setting.

Present on generated pages; see Collections. pages is also available on every page when [templates] expose_page_list = true.

The page's headings as a tree — a table of contents is one, and rebuilding a tree from a flat list of levels inside a template is what Jinja is worst at.

Each entry has title, anchor, level, number and children:

{% macro toc_list(entries) %}
<ul>{% for e in entries %}
  <li><a href="#{{ e.anchor }}">{{ e.number }} {{ e.title }}</a>
  {%- if e.children %}{{ toc_list(e.children) }}{% endif %}</li>
{% endfor %}</ul>
{% endmacro %}

{% if page.toc | length > 1 %}{{ toc_list(page.toc) }}{% endif %}

number is the section number — 1., 3.1. — always computed and printed only if you ask for it. Print it when [html] section_numbers is on, or the contents will number what the headings do not.

Anchors come from the same function that emits heading id attributes, so a TOC link cannot drift from the heading it points at. The tree is empty when the page has no headings, when [html] toc = false, or when the document says #+OPTIONS: toc:nil.

<link>{{ post.url | absolute }}</link>

Apply it to the site-root-relative values — page.url, pages[].url, group.url — and not to nav[].url, paginator.*_url, stylesheet or root, which are relative to the page carrying them and already correct there.

An already-absolute URL passes through, so a template can apply it uniformly to internal paths and external links. With no base_url it is an error naming the setting, rather than a relative URL that would make a feed invalid.

minijinja ships no truncate, and an excerpt is usually a whole paragraph — so without one a listing's only options are the full paragraph or nothing.