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

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

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:

<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

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.

Source: Zas at d89a28125f63. AGPL-3.0-or-later license. Documentation index · Full documentation.