trellis_site
trellis_site turns Markdown content and Trellis HTML layouts into a complete
static site. This page is the package reference. For the guided workflow, start
with Sites Getting Started.
Installation
dependencies:
trellis_site: ^0.13.0
Quick start
Create trellis_site.yaml:
title: My Site
baseUrl: https://example.com
taxonomies: [tags]
paginate: 10
Build programmatically:
import 'package:trellis_site/trellis_site.dart';
final config = SiteConfig.load('trellis_site.yaml');
final site = TrellisSite(config);
final result = await site.build();
print('Built ${result.pageCount} pages in ${result.elapsed.inMilliseconds}ms');
Or use trellis_cli:
trellis build
trellis serve
Configuration keys
trellis_site.yaml accepts:
title,baseUrl, anddescriptionfor site identity;pathPrefixfor a site served below the domain root;contentDir,layoutsDir,staticDir,dataDir, andoutputDirfor filesystem locations;themeandtheme_paramsfor an installed theme;taxonomiesandpaginatefor generated collections;paramsfor arbitrary values exposed as${site.params.*};feeds,search, andhighlightfor generated discovery artifacts and build-time code highlighting.
Paths can be relative to the site root or absolute.
title: My Site
baseUrl: https://example.com
pathPrefix: /my-site/
description: Notes about Dart and server-rendered HTML
contentDir: content
layoutsDir: layouts
staticDir: static
dataDir: data
outputDir: output
taxonomies: [tags, categories]
paginate: 10
params:
author: Site Author
feeds:
atom: true
rss: true
sections: [posts]
limit: 20
search:
enabled: true
output: search-index.json
fields: [title, summary, content, tags]
highlight:
enabled: true
Content organization, ordering, bundles, drafts, dates, and shortcodes are covered in Sites: Content.
Taxonomies, pagination, menus, and previous/next navigation are covered in Sites: Layouts.
Sitemaps, Atom/RSS feeds, section feeds, and search indexes are covered in Sites: Search and feeds.
Theme installation and customization are covered in Sites: Themes.
Path prefix
pathPrefix mounts the generated site below the domain root, such as GitHub
Project Pages at https://user.github.io/my-site/. Values like my-site,
/my-site, and /my-site/ normalize to /my-site/; '' and / mean the
domain root.
The prefix changes emitted URLs, not disk paths. A page at
output/posts/intro/index.html can therefore render a URL such as
/my-site/posts/intro/. baseUrl remains the absolute origin and composes with
the prefix in the sitemap and feeds.
Root-absolute internal href and src values in rendered HTML are rewritten
with the prefix. Relative links, anchors, external URLs, and already-prefixed
engine URLs are unchanged. ${site.pathPrefix} exposes the normalized prefix
to layouts for references that need an explicit join:
<link rel="stylesheet" tl:href="${site.pathPrefix} + 'css/main.css'">
For host configuration and link-integrity checks, see Sites: Deploy.
Front matter fields
YAML front matter begins at the first line of a Markdown file:
---
title: Hello World
date: 2026-03-15T09:30:00Z
draft: false
summary: A custom listing summary.
layout: custom
type: article
weight: 10
tags: [dart, web]
menu_title: Hello
menu_exclude: false
sitemap:
exclude: false
feed: true
search: true
---
Recognized fields include title, date, draft, summary, layout,
type, weight, sitemap, feed, search, menu_title, and
menu_exclude. Taxonomy fields come from the configured taxonomy names. Other
fields remain available as ${page.fieldName}.
Template context
Layouts receive a cascade in this order, with later sources taking precedence:
- Site configuration and
${site.params.*}. - Global
data/*.yamlvalues under${data.*}. - Section front matter.
- Page front matter.
Additional values include:
${page.*}– metadata includingurl,content,summary,toc,section,sectionPath,ancestors,kind,prev, andnext;${pages}– ordered children for list pages;${site.menu}– the generated hierarchical navigation tree;${pagination.*}– pagination state and the current page slice;${taxonomy.*}– taxonomy data for generated collection pages; and${feeds.*}– generated site-wide feed URLs.
See Sites: Layouts for worked navigation, taxonomy, and pagination examples.
Layout resolution
Single and list pages resolve the first available layout in this order:
- Front-matter
layout, such aslayout: custom→custom.html. - Type-specific
{type}/{single|list}.html. - Section-specific
{section}/{single|list}.html. _default/{single|list}.html.
Home pages resolve home.html, then index.html, then
_default/list.html. Site-owned layouts take precedence over theme layouts at
the same path.
For the full authoring workflow, return to the Sites guide.