ZeroSite
Source

Build your first site

This tutorial creates a small Markdown site, checks its links and routes, and previews the generated files. ZeroSite reads the repository without changing its Markdown sources.

Create a site repository

ZeroSite requires Go 1.27.1 or later. Create a separate directory for the content you want to publish:

mkdir -p /tmp/first-site/docs /tmp/first-site/site
cd /tmp/first-site

Create README.md:

# Field Notes

Short guides for the team.

[Start with the first guide](docs/first-guide.md)

Create docs/first-guide.md:

---
title: First guide
description: A short example page.
---

# First guide

This page is written in Markdown and will become a static HTML page.

Create site/config.json:

{
  "title": "Field Notes",
  "description": "Short guides for the team.",
  "lang": "en",
  "include": ["README.md", "docs/**/*.md"],
  "exclude": ["**/TEMPLATE.md"],
  "sections": [
    { "title": "Overview", "match": ["README.md"] },
    { "title": "Guides", "match": ["docs/**"] }
  ]
}

Unknown configuration keys fail the build, so misspelled options are caught early. See the configuration guide for publication rules and the configuration reference for all fields.

Pin and run ZeroSite

Choose a full ZeroSite commit SHA and use that same revision for every command. For a published build, replace FULL_COMMIT_SHA below with the revision you intend to pin. The command fetches that exact Go module version:

go run github.com/ornew/zerosite@FULL_COMMIT_SHA -repo . -config site/config.json -out site/dist -check
go run github.com/ornew/zerosite@FULL_COMMIT_SHA -repo . -config site/config.json -out site/dist
go run github.com/ornew/zerosite@FULL_COMMIT_SHA -repo . -config site/config.json -out site/dist -serve localhost:8080

The first command validates the inputs without writing output. The second creates site/dist/; the third rebuilds and serves it at http://localhost:8080. Preview builds once, so restart it after editing source files. Generated output must be new, empty, or marked as output owned by ZeroSite.

To run from a ZeroSite source checkout, use the checkout path instead of a published module version:

go -C /path/to/zerosite run . -repo /tmp/first-site -config /tmp/first-site/site/config.json -out /tmp/first-site/site/dist -check
go -C /path/to/zerosite run . -repo /tmp/first-site -config /tmp/first-site/site/config.json -out /tmp/first-site/site/dist
go -C /path/to/zerosite run . -repo /tmp/first-site -config /tmp/first-site/site/config.json -out /tmp/first-site/site/dist -serve localhost:8080

What to explore next