Skip to content

Content

Trellis discovers Markdown under content/ and derives pages from its directory structure.

Content conventions

File URL Kind section sectionPath
content/_index.md / home `` ``
content/about.md /about/ single `` ``
content/posts/_index.md /posts/ section posts posts
content/posts/hello.md /posts/hello/ single posts posts
content/docs/guides/_index.md /docs/guides/ section docs docs/guides

An _index.md file defines the home page or a section listing. Other Markdown files become single pages. A nested section lists pages at its own level rather than flattening sibling sections into one list.

Front matter

Start a file with YAML between --- delimiters:

---
title: Hello World
date: 2026-03-15T09:30:00Z
tags: [dart, web]
draft: false
layout: custom
summary: A custom summary for listings.
weight: 20
---

# Hello World

Content here.

Standard fields include title, date, draft, summary, layout, type, weight, sitemap, feed, search, menu_title, and menu_exclude. Custom fields are available to layouts as ${page.fieldName}.

menu_title changes a page's label in the generated menu without changing its page title. menu_exclude: true removes it from the menu.

Dates and time zones

A date without a zone is interpreted as UTC calendar fields, so feeds and the sitemap stay identical across build machines. Add Z or a numeric offset when the timestamp represents a specific instant:

date: 2026-03-15
date: 2026-03-15T09:30:00Z
date: 2026-03-15T09:30:00+02:00

Page ordering

Within a section, pages with an integer weight come first in ascending order. Equal-weight and unweighted pages fall back to date descending, then URL ascending. The same order drives section listings, pagination, menus, and previous/next links. A malformed weight produces a warning and is treated as unweighted.

Page bundles

A directory containing index.md is a page bundle:

content/posts/my-trip/
|-- index.md
`-- photo.jpg

The page renders at /posts/my-trip/; co-located assets are copied beside the generated page. Use bundles when content and its images belong together.

Drafts

Pages with draft: true are excluded from normal builds. Include them in a local preview when needed:

trellis build --drafts

Shortcodes

Reusable content snippets live under layouts/shortcodes/. The pre-Markdown form can emit Markdown before parsing:

{{% callout kind="note" %}}

The post-Markdown form transforms rendered HTML:

<!-- tl:figure src="diagram.svg" alt="Build flow" -->

Shortcode arguments are exposed to the matching Trellis fragment template. Keep document structure in Markdown and use shortcodes for repeated, parameterized content.