Layouts
Layouts turn discovered content into HTML using the Trellis template engine.
Layout resolution
For a single or list page, Trellis selects the first matching layout:
- Front-matter
layoutsuch aslayout: custom→custom.html. - Type-specific layout →
{type}/{single|list}.html. - Section-specific layout →
{section}/{single|list}.html. - Default layout →
_default/{single|list}.html.
Home pages resolve home.html, then index.html, then
_default/list.html. A site-owned layout wins over a theme layout at the same
path.
Template context and data cascade
Values enter the template context from lowest to highest priority:
- Site configuration and
${site.params.*}. - Global files under
data/, exposed as${data.filename.*}. - The current section's
_index.mdfront matter. - The current page's front matter.
Layouts also receive:
${page.*}– URL, rendered content, summary, TOC, section,sectionPath, ancestors, kind, and previous/next neighbors.${pages}– the ordered child pages of a home, section, or taxonomy list.${site.menu}– the generated navigation tree available on every page.${pagination.*}– page number, totals, links, and the current slice.${taxonomy.*}and${feeds.*}– taxonomy or feed data when configured.
Navigation menu
${site.menu} mirrors the content hierarchy. Each node contains title,
url, and children. It follows the same weight-aware ordering as section
pages, omits drafts and menu_exclude: true pages, and uses menu_title before
the page title or a humanized slug.
<nav>
<ul>
<li tl:each="item : ${site.menu}">
<a tl:href="${item.url}" tl:text="${item.title}">Page</a>
</li>
</ul>
</nav>
Previous and next
Single pages receive ${page.prev} and ${page.next} for their immediate
neighbors at the same sectionPath. Each value has url and title. The first
and last page omit the missing neighbor; home, section, and taxonomy list pages
do not receive these links.
Taxonomies
Declare collections such as tags and categories:
taxonomies: [tags, categories]
Matching front matter generates a taxonomy listing at /{taxonomy}/ and a page
per term at /{taxonomy}/{slug}/. Layouts read the generated terms and matching
pages through ${taxonomy.*}.
Pagination
Set a page size in trellis_site.yaml:
paginate: 10
Home, section, and taxonomy-term lists are split into pages. The first keeps
its base URL and later pages use /page/{n}/. Read
${pagination.page}, ${pagination.totalPages}, ${pagination.hasNext},
${pagination.prevUrl}, ${pagination.nextUrl}, and ${pagination.pages} in
the layout.