# Zas — full documentation

Source: https://github.com/darccio/zas/tree/3868cbc501fbce52f4cc51183bef0c39f37e17e3/docs

License: AGPL-3.0-or-later (https://dario.cat/zas/LICENSE.txt). Each section identifies its Markdown URL for resolving relative links.

---

Source: https://dario.cat/zas/index.md

# Zas

Zas is a static site generator written in Go. It walks a site's files, renders Markdown and HTML through a shared layout, and copies ordinary assets into the deploy directory. The source directory structure becomes the site's URL structure.

## Install and start

The current source requires Go 1.26 or newer.

```sh
go install github.com/darccio/zas/cmd/zas@latest
mkdir my-site
cd my-site
zas init
```

Write `index.md`, edit `.zas/layout.html`, and build:

```sh
zas -full
```

The generated site is in `.zas/deploy` by default. Upload that directory to your static host.

`zas init` preserves an existing configuration and layout. `zas init -force` replaces both with scaffolded defaults.

These guides describe the current source. For reproducible builds, install a selected release tag or commit instead of `@latest`, and choose a revision containing the features you use.

## Guides

- [Configuration](configuration.md): site settings, page overrides and languages.
- [Templates and plugins](templates.md): layouts, metadata, embeds and the trust model.
- [Publishing](publishing.md): sitemaps, RSS, Markdown twins and deployment.

## Project links

- [Source repository](https://github.com/darccio/zas)
- [API reference](https://pkg.go.dev/github.com/darccio/zas)
- [Releases](https://github.com/darccio/zas/releases)
- [Report a bug](https://github.com/darccio/zas/issues)
- [Sponsor maintenance](https://github.com/sponsors/darccio)

Zas retains its module path `github.com/darccio/zas`. Hosting these guides on dario.cat does not change how Go users install or import it.

## License

Zas and these docs are distributed under the [GNU Affero General Public License, version 3](LICENSE.txt), or any later version.

---

Source: https://dario.cat/zas/configuration.md

# Configuration

Zas reads `.zas/config.yml`. You can keep the defaults and add only the settings your site needs.

```yaml
zas:
  layout: .zas/layout.html
  deploy: .zas/deploy
  allowed_dotdirs: [".well-known"]
site:
  baseurl: https://example.com
  language: en
  image: https://example.com/static/avatar.webp
  sitemap: true
  publish_markdown: true
```

## Site settings

| Setting | Default | Purpose |
| --- | --- | --- |
| `zas.layout` | `.zas/layout.html` | Shared HTML layout. |
| `zas.deploy` | `.zas/deploy` | Generated output directory. |
| `zas.allowed_dotdirs` | Empty | Specific top-level dot-directories to publish. |
| `site.baseurl` | `http://example.com` | Absolute site URL used by URL helpers, sitemaps and feeds. |
| `site.language` | `en` | Default page language. |
| `site.image` | Unset | Site image available through `.Site.Image`. |
| `site.sitemap` | `false` | Generate a sitemap and its robots directive. |
| `site.publish_markdown` | `false` | Publish rendered Markdown twins. |
| `site.feed` | `false` | Generate RSS feeds. |

Use a real HTTP(S) `baseurl` when generating a sitemap or feed. See [Publishing](publishing.md) for feed options and output behavior.

Dot-files and dot-directories are skipped by default. `allowed_dotdirs` accepts exact top-level names, such as `.well-known`; it does not allow nested dot-directories or patterns. `.git` and `.zas` remain excluded.

## Page metadata

Put YAML in the leading HTML comment of a Markdown or HTML page:

```markdown
<!--
title: My article
language: en
date: 2026-10-11T10:00:00+02:00
summary: A short plain-text description.
tags: [go, writing]
-->
# My article
```

For resolved settings such as `language`, page metadata takes precedence over the nearest directory `.zas.yml`, which takes precedence over site settings. Page metadata remains available through `.Page`.

| Page setting | Effect |
| --- | --- |
| `title` | Override the first H1 as the page title. |
| `language` | Override the resolved language. |
| `date` | Explicit RFC3339 publication timestamp with a timezone. |
| `updated` | Explicit RFC3339 update timestamp with a timezone. |
| `summary` | Plain-text summary string. |
| `tags` | List of strings. |
| `publish: false` | Exclude a standalone page, while retaining it as embed content. |
| `template: false` | Skip the page's own Go template execution. |
| `draft: true` | Exclude the page from feeds and Markdown twins; existing HTML generation remains enabled. |
| `publish_markdown: false` | Opt this page out of Markdown twins. |
| `feed: false` | Opt this page out of feeds. |
| `article: false` | Classify a utility page as outside the article feed selection. |

`template: false` still allows parsing and embed processing. Use `-no-plugins` to prevent content-triggered external programs; see the [trust model](templates.md).

## Languages

Set the site default in `site.language`. For a language subtree, add a `.zas.yml` such as:

```yaml
language: es
```

Place it in `es/`, alongside `es/index.md` and other Spanish pages. Pages can also override their language individually.

Translations live in `.zas/i18n.yml`:

```yaml
Hello:
  en: Hello
  es: Hola
  ca: Hola
```

Use `{{.E "Hello"}}` in a page or layout. Missing translations produce `**Hello**`. Language directories with matching relative page paths are paired automatically for sitemap `hreflang`; a page-only language override does not create that pairing.

---

Source: https://dario.cat/zas/templates.md

# Templates and plugins

Zas uses Go templates in page content and in the shared `.zas/layout.html`, with different escaping behavior.

## Layout

A minimal layout can use:

```html
<!doctype html>
<html lang="{{.Language}}">
<head>
  <meta charset="utf-8">
  <title>{{.Title}}</title>
  <link rel="canonical" href="{{.Canonical}}">
  {{with .Summary}}<meta name="description" content="{{.}}">{{end}}
</head>
<body>
  <main>{{.Body}}</main>
</body>
</html>
```

The layout runs through Go's `html/template`, which escapes values according to their HTML context. `.Body` contains the already-rendered page body.

## Metadata helpers

| Helper | Value |
| --- | --- |
| `.Title` | Explicit page `title`, otherwise the first H1. |
| `.Language` | Resolved page language. |
| `.Canonical` | Absolute page URL with a final `/index.html` replaced by `/`. |
| `.URL` | Absolute generated path; retains `/index.html` when that is the filename. |
| `.Date` | Explicit RFC3339 `date`, or zero time. |
| `.Updated` | Explicit `updated`, otherwise the tracked source's latest git commit date, or zero time. |
| `.Summary` | Explicit `summary`, or an empty string. |
| `.Tags` | Explicit string-list `tags`, in their original order. |
| `.Page` | Page YAML map. |
| `.Directory` | Directory configuration map. |
| `.Resolve "language"` | Page, directory, then site setting. |
| `.Extra "/site/baseurl"` | Direct string lookup in the site configuration. |

A standalone `article.md` has canonical `/article.html`; the helper only normalizes index pages. To format a publication date, first check that it is present:

```html
{{if not .Date.IsZero}}<time datetime="{{.Date.Format "2006-01-02T15:04:05Z07:00"}}">{{.Date.Format "2006-01-02"}}</time>{{end}}
```

Invalid explicit metadata stops template execution when its helper is used. Publication dates are never inferred from git, file timestamps or build time. A full-history checkout gives `.Updated` accurate git history.

Inside a page's own content, `.Page`, `.Title` and `.FirstTitle` use a best-effort preview. The layout sees the final values after page rendering. `.Body` is empty inside the page's own template.

## Page listings

Set `site.page_listings: true` to expose `.Pages "posts"` in page, Markdown
and layout templates. The option defaults to false; disabled sites do no
listing scan, and a `.Pages` call explains how to enable it.

For a page archive, use explicit HTML escaping because page content runs
through `text/template`:

```html
<!-- title: Posts -->
<h1>Posts</h1>
<ul>
{{range .Pages "posts"}}
  <li><a href="{{html .URL}}">{{html .Title}}</a>{{with .Summary}}<p>{{html .}}</p>{{end}}</li>
{{end}}
</ul>
```

In the layout, use `.URL`, `.Title` and `.Summary` directly: `html/template`
auto-escapes their plain strings. `.Pages(section)` returns independent
`[]PageSummary` slices and an error. Summaries contain:

| Field | Value |
| --- | --- |
| `Title` | Literal page `title`, otherwise static first H1 text. |
| `URL` | Escaped root-relative canonical path, including any baseurl hosting subpath, for local preview navigation. |
| `Canonical` | The existing canonical helper's path with `site.baseurl`, or root-relative if unset. |
| `Date` | Explicit RFC3339 publication date as `time.Time`, otherwise zero time. |
| `Language` | Page, nearest directory configuration, then site language. |
| `Summary` | Literal page `summary`, otherwise empty. |

`posts` recursively includes the directory's pages and nested article
indexes, omitting only `posts/index.md` or `posts/index.html`. It does not
match `posts-old`. Empty and `.` sections select the root; missing sections
return empty lists. Paths must be relative directory paths; trailing `/`
is allowed. Traversal, absolute paths, backslashes, queries, fragments and
encoded path syntax are invalid and reported when `.Pages` is called.
As with other template failures, a full build may already have cleared
deploy; use a staging directory to preserve published output on failure.
Known dates sort newest first, then by URL; undated pages sort last by URL.
Dates never come from file timestamps, git or build time.

Listings use a complete static-source snapshot collected before rendering,
without executing templates, embeds or plugins. They skip the layout,
deploy output, symlinks, hidden sources (following the normal dot-directory
allowlist), `publish: false` and `draft: true`. Drafts keep their existing
standalone HTML behavior. Listing metadata must be valid literal values in
the leading YAML comment; template actions there are rejected unless
`template: false`. Template-generated H1 text yields an empty title; provide
a literal `title` to name it. A leading action that could generate the
configuration comment is rejected: put a literal comment or heading first.
Missing static titles are allowed. Invalid static metadata fails before
full-build cleanup; generated publication flags that disagree with the
snapshot fail the build when rendering reveals them. Enabled runs render
every HTML/Markdown source so all archives reflect additions, removals,
renames and metadata edits; newly unpublished
HTML is removed during incremental builds. This trades incremental render
speed for consistent lists.

## JSON in layouts

`dict`, `list` and `json` are layout-only helpers. Build objects rather than passing a pre-encoded JSON string:

```html
{{$person := dict "@type" "Person" "name" "Dario Castañé" "url" .Site.BaseURL}}
<script type="application/ld+json">{{json (dict "@context" "https://schema.org" "@graph" (list $person))}}</script>
```

`json` serializes the value with `encoding/json` and retains its HTML-sensitive character escaping. Serialization errors fail the build. It adds no schema automatically.

## Embeds

Built-in handlers support Markdown, HTML and plain text:

```html
<embed src="navigation.md" type="text/markdown" />
```

Page-body embeds resolve relative to the containing page. Layout embeds resolve relative to the site root. Built-in nested embeds remain inside the site root and have a depth limit.

Mark an embedded-only navigation file `publish: false` to prevent it also becoming a standalone page. With Markdown twins enabled, Markdown embeds must occupy a standalone line; combinations with reference definitions or footnotes are rejected to avoid changing reference scopes.

## Plugin and template trust model

Page content runs through Go's `text/template` with no automatic escaping. This includes template actions inside code fences. To display literal actions, put `template: false` in the page's leading configuration comment. The layout still runs normally.

External subcommands named `zs<name>` and MIME handlers named `mzs<name>` are programs found on `PATH`. Content can trigger MIME handlers through embeds, or `zs` programs through `<script type="application/zas+name">` tags. Zas does not sandbox or verify these binaries.

Build content you do not fully control with:

```sh
zas -full -no-plugins
```

`-no-plugins` rejects content-triggered external MIME and script plugins rather than executing them. Built-in embeds still run, and the flag does not restrict a plugin explicitly invoked as `zas <name>` on the command line.

`template: false` alone does not disable embeds or plugins, and `-no-plugins` alone does not disable Go template execution. For untrusted documentation, render or sanitize it separately, avoid executing its template actions, and keep `-no-plugins` enabled in the assembly build.

Use layout `noescape` or `.H` only for HTML you trust. `.E` is escaped in the layout but not in a page's own template; `.H` marks translations as trusted HTML in the layout.

---

Source: https://dario.cat/zas/publishing.md

# Publishing

Build all files with `zas -full`, then upload `.zas/deploy` to a static host. Choose `-no-plugins` when content is not fully controlled by the site author.

Without `-full`, Zas updates changed inputs incrementally. Layout, configuration, translation files, directory configuration and resolvable built-in embed dependencies can also trigger rendering. Use a full build after changing a dynamic embed source or a plugin's additional inputs.

## Sitemap

```yaml
site:
  baseurl: https://example.com
  sitemap: true
```

Zas writes a sitemap containing generated pages and updates the deploy copy of `robots.txt` with its `Sitemap:` directive. Large sites are split into numbered sitemaps and an index automatically.

Sitemap modification dates use source git history, falling back to file modification time when needed. Unlike sitemap dates, publication metadata never falls back to file modification time. In GitHub Actions, use `fetch-depth: 0` for accurate history.

Matching relative paths under language directories receive reciprocal sitemap `hreflang` links. Pages without a translated sibling remain valid.

## RSS 2.0

```yaml
site:
  baseurl: https://example.com
  language: en
  feed: true
  feed_title: My writing
  feed_description: Articles about Go and static sites.
  feed_sections: [posts]
  feed_limit: 50
  feed_per_language: true
  feed_strict: true
```

The root feed is `/feed.xml`. With `feed_per_language`, non-default languages that have articles also get `/<language>/feed.xml`. Each feed is sorted newest first and capped independently by `feed_limit`.

Feeds are disabled by default. When enabled, `feed_title` falls back to `site.title` and must be non-empty. `feed_description` falls back to `site.description`, then the title. The default limit is 50, and strict validation is enabled by default.

Every selected article needs an explicit RFC3339 `date` with a timezone. A configured `feed_sections` includes descendant pages but treats the section-root index as an archive. A nested `posts/article/index.md` remains an article. Without sections, dated pages or pages marked `article: true` are selected, apart from the unclassified root homepage.

`publish: false`, `draft: true` and `feed: false` exclude pages before metadata validation. `article: false` excludes utility pages. Non-strict mode warns and skips invalid selected items; it does not invent their dates.

RSS items contain the full pre-layout HTML body, a plain-text summary, stable canonical permalink GUIDs, RFC1123Z publication dates and tags. Relative content links are made absolute. The channel has a self link and a build date derived from item updates, so rebuilding unchanged content does not insert a new build timestamp.

Add feed discovery to your own layout:

```html
<link rel="alternate" type="application/rss+xml" title="My writing" href="https://example.com/feed.xml">
```

Configure your host to serve feeds as `application/rss+xml; charset=utf-8`. Zas writes files; it does not configure HTTP response headers.

## Rendered Markdown twins

```yaml
site:
  publish_markdown: true
```

`section/index.md` produces both `section/index.html` and `section/index.md` in deploy. `contact.md` produces `contact.html` and `contact.md`. HTML source pages do not receive automatic Markdown conversions.

The twin contains the post-template Markdown body, with leading configuration comments removed and without the shared HTML layout. Template values are expanded once before Markdown parsing. This is an opt-in change in rendering order from the legacy path; template values containing Markdown participate in Markdown rendering.

`publish: false`, `draft: true` and page-level `publish_markdown: false` suppress twins. With `template: false`, literal template actions are intentionally preserved in both formats. Unsupported external content plugins fail with opt-out guidance before execution; the ordinary HTML layout pass can still contain permitted plugins.

Zas records paths and hashes in the private `.zas/markdown-outputs.json` ownership manifest. Incremental builds clean previous owned twins when sources disappear or are opted out, while preserving manually changed or unowned files. Disabling the site option cleans previous owned twins after a successful build. Full builds retain their normal deploy-directory replacement behavior after preflight checks.

Choose the conventional deploy directory or a new, empty destination. Output collisions and unsafe source/deploy overlap fail preflight rather than overwriting unrelated source files.

Zas does not add discovery links or HTTP content negotiation. Add links and a host adapter separately when those are useful to your site.

## Reproducible deployment

Pin the Zas version and external documentation revisions. Keep credentials in your CI or host secret store. Build in a temporary assembly directory, verify the output, and promote the completed deploy directory only after validation.

This repository's docs workflow requests a pinned update in `darccio/darccio`; it does not publish a site directly. The site update is reviewed as a pull request, and Cloudflare Pages deploys it after merge.