Getting Started
This guide takes a new static site from an empty directory to deployment.
1. Create a site
Install the CLI, then scaffold its static blog starter:
dart pub global activate trellis_cli
trellis create my_site --template blog
cd my_site
dart pub get
The generated project is ready to build:
my_site/
|-- trellis_site.yaml
|-- content/
| |-- _index.md
| |-- about.md
| `-- posts/
| |-- _index.md
| |-- welcome.md
| `-- getting-started.md
|-- layouts/
| |-- base.html
| |-- home.html
| |-- _default/
| | |-- list.html
| | `-- single.html
| `-- posts/single.html
`-- static/styles.css
2. Add a Markdown page
Create content/uses.md:
---
title: What this site covers
summary: A short guide to this site.
---
# What this site covers
Write the page in Markdown. Trellis turns it into `/uses/index.html`.
See Content for front matter, ordering, bundles, and shortcodes.
3. Build
trellis build
The build writes the complete static site to output/. Re-run the command
after changing content, layouts, configuration, or assets.
4. Preview
trellis serve
Open http://localhost:8080. The preview server resolves clean URLs such as
/uses/ to their generated index.html files.
5. Deploy to GitHub Pages
For a project site served at https://user.github.io/my-site/, set the origin
and sub-path in trellis_site.yaml:
baseUrl: https://user.github.io
pathPrefix: /my-site/
Build again and publish the contents of output/ as the Pages artifact. The
prefix is written into URLs while files keep their normal on-disk paths. Run a
link check before publishing so a valid-looking but root-relative URL cannot
become a production 404.
The deployment guide includes a complete GitHub Actions workflow, the root-served variant, and both link-check commands.