Guide

Configuration reference

SSG can be configured with command-line flags or a YAML, TOML or JSON file. This guide explains the configuration model and advanced features. The exhaustive, copyable YAML template is .ssg.yaml.example.

Loading configuration

Select a file explicitly:

1ssg --config path/to/site.yaml

Without --config, SSG checks the current directory in this order:

1.ssg.yaml  .ssg.yml  .ssg.toml  .ssg.json
2ssg.yaml   ssg.yml   ssg.toml   ssg.json

Command-line flags are parsed after the file and override matching file values. The positional values source, template and domain are read from the file when all three are present. Otherwise, provide all three positionally — source itself is optional once content_sources is configured.

Two diagnostics make a misconfigured file obvious instead of silent:

  • Unknown keys warn. A YAML key this binary does not know is reported by name and ignored. A config written for a newer ssg therefore still builds, and the version mismatch is visible rather than looking like a missing value.
  • Missing required settings are named. Instead of printing usage alone, ssg reports which of source/template/domain is missing, which config file it read and what that file provided.

Splitting the config across files (include:)

A .ssg.yaml can pull in other YAML files — from a local path or a URL — so a large config splits into focused pieces (each worker its own file, shared defaults in a base):

1include:
2  - shared/base.yaml                      # local, relative to this file
3  - workers/comments/config.yaml
4  - url: https://example.com/team.yaml    # remote
5    auth:                                 # private source (optional)
6      type: bearer                        # bearer | basic | header
7      token: $TEAM_CONFIG_TOKEN           # secrets are env refs, never literals

Merge rules (YAML configs only):

  • Base-first. Includes are merged in listed order, then the including file is overlaid on top, so the main file always wins.
  • Maps merge recursively.
  • Lists of named maps merge by name — so each worker's own file can add one entry to workers: (or content_sources:) without clobbering the others. Any other list is replaced wholesale.
  • Includes may nest; a cycle is an error, and a diamond (two files pulling the same base) is fine.

Remote includes reuse the auth model below: type is bearer, basic (username + password) or header (header name + value), and every secret field must reference an environment variable.

A remote include can also tune its own fetch. All four are optional and fall back to the defaults shown:

1include:
2  - url: https://config.example.com/base.yaml
3    auth: { type: bearer, token: $CONFIG_TOKEN }
4    timeout: 30s        # per-attempt timeout (default 30s)
5    retries: 3          # extra attempts on a transient failure (default 3; 0 disables)
6    retry_delay: 5s     # wait between attempts (default 5s)
7    on_error: fail      # fail the build (default) or warn and continue without it
  • A transient failure — a network/transport error or an HTTP 429/5xx — is retried up to retries times, retry_delay apart. A 4xx (missing, forbidden) is not retried, since it will not recover.
  • on_error: warn prints a warning and continues the build without that include, so an optional or occasionally-unreachable remote config doesn't block a publish. on_error: fail (the default) stops the build.
  • timeout/retry_delay accept a Go duration (30s, 1m) or a plain number of seconds. Remote worker source: archives use the same defaults.
1source: my-blog
2template: simple
3domain: example.com
1ssg my-blog simple example.com

Most features are disabled by default. Defaults listed below are the effective ones: config.DefaultConfig plus the values the build applies when a key is unset; omitted strings and booleans otherwise use Go's empty value.

Editing the config from the command line

ssg config view                                   # the whole file, as written
ssg config view highlight_style                   # one value
ssg config view taxonomies.audience               # one section
ssg config view --effective toc_depth             # after defaults and normalisation
ssg config set highlight_style github-dark
ssg config set outputs [html,markdown,json]       # a list
ssg config set taxonomies.audience.multiple true  # a nested path
ssg config set headers."/css/*".Cache-Control "public, max-age=86400"
ssg config set robots_rules[1].allow /docs/       # a list position
ssg config set --json marketing '{"og_site_name":"Example"}'
ssg config unset mermaid_background

The file keeps its shape. Setting one value changes one line: comments, blank lines, key order and the column trailing comments are aligned in all survive, because the edit is spliced into the text rather than produced by re-serialising the parsed config. That is not a nicety here — the configs in this project carry their reasoning in comments, and an editor that dropped them would make ssg config set a thing nobody could safely run twice.

Paths. Dots descend into mappings. A key that contains dots or slashes is quoted (headers."/css/*"). A list position is [n], and it must already exist: inventing list entries is guesswork. A path whose parent mappings do not exist yet is written whole.

Values are typed the way they read: true is a bool, 8080 an int, [a,b,c] a list, everything else a string. --string forces text (for a version label that looks like a number), and --json takes any structure.

An edit that would break the config is refused. The result is validated in a scratch file before the real one is touched, so a rejected edit leaves the config byte-for-byte as it was.

Version one edits YAML. A TOML or JSON config is refused with a message rather than rewritten without its comments.

--effective masks credentials. The effective view has $NAME references already resolved, so every key the schema classes secret (below) reads «redacted — read it from the file or the environment» wherever it sits — jwt_secret, tts.api_key, workers[].auth.token, external_sources.sources.*.auth.token, ai.models.*.key and the rest — together with tls_key and the sections ai, worker, deploy, notify and external_sources.sources, which are masked whole. ssg config view without --effective prints the file as written.

The MCP designer tools (ssg mcp) write through the same engine, so an assistant and a person editing the same file get the same result — with the difference that MCP still restricts itself to an allow-list of presentation keys, while the CLI is the project owner's own tool and edits anything. That allow-list is the set of schema keys marked mcpWritable (below).

The configuration schema (ssg config schema)

ssg config schema > config-schema.json

prints every key ssg reads as JSON, built from ssg's own configuration types, so it cannot fall behind the code: a field without an entry fails ssg's tests. It needs no project. designer-ui builds its options tab from a generated copy, workers/designer-ui/src/config-schema.json (UPDATE_CONFIG_SCHEMA=1 go test ./internal/config -run TestSchemaTwinUpToDate regenerates it).

 1{
 2  "schemaVersion": 1,
 3  "overlayFile": ".ssg.designer.json",
 4  "groups": [{ "id": "site", "title": "Site", "description": "…" }],
 5  "keys": [
 6    { "path": "port", "key": "port", "type": "int", "default": 8888,
 7      "description": "port the server listens on", "group": "server",
 8      "class": "executes" }
 9  ]
10}

Each key has path, key, type (bool, int, number, string, enum, list, map, object or any), enum values, a default when the loader starts from one, description, group and class. A list has items, a map has values, an object has fields; open: true on an object means it also takes keys it does not name (story:). alternate is a second accepted form — story: true, prefix: /blog/, languages as full entries. In a path, [] is any list element and * any map key: external_sources.sources.*.auth.token. Elements (items, values, alternate) take their description and class from the key that owns them.

Classes. Every key has exactly one, and there is no default:

Class Meaning
plain an ordinary setting
executes runs a command, deploys, changes what a server does, names a program, file or directory the build reads (or writes outside the output), loads a third-party script on every page, can send visitors to another place, or weakens a security guard — hooks, workers, deploy, sass_binary, static_dir, variables, sanitize_html, shortcodes[].template, render_hooks, outputs_custom[].template, analytics_ids, redirects, link_rewrites, domain, modules[].url…
secret carries a credential; only an environment reference may be written. secretFormat says which: whole ($NAME or ${NAME}), login (login:$NAME, server_users) or inline (text holding a reference, Bearer $TOKEN)

The settings overlay (.ssg.designer.json)

A JSON file beside the config file, nested like the configuration, that ssg lays over .ssg.yaml when it loads it. designer-ui writes its settings there, so .ssg.yaml — hand-written, with its comments — is never rewritten by a program.

1{
2  "title": "Example",
3  "marketing": { "theme_color": "#1a73e8" },
4  "image_formats": ["avif", "webp"],
5  "mermaid_theme": null
6}
  • Merge. Mappings merge key by key; any other value replaces the file's — a list replaces the whole list; null removes the key, so its default applies. A value means exactly what it would written in .ssg.yaml.
  • Validation. The overlay is checked against the schema before the build reads it. An unknown key (include: among them — an overlay cannot pull in more config), a value of the wrong type, an enum value not in the list, or invalid JSON stops the build with the key's path, e.g. .ssg.designer.json: feeds[0].format: "rss2" is not one of …. Nothing is dropped silently. template written in the overlay is one folder name inside templates_dir, never a path (no /, \, . or ..).
  • Secrets. A secret key with a literal value is an error; a $NAME reference passes. The overlay lives in the repository, and a secret in a repository is a leak, not a setting.
  • YAML configs only. An overlay beside a .ssg.toml or .ssg.json is an error rather than being ignored.
  • No overlay file, no change: the config is read byte for byte as before.
  • ssg config view --effective notes on stderr which keys came from the overlay.
  • --watch (and ssg mcp --watch) rebuild when the overlay changes, as for the config file.

Order of sources, lowest first: built-in defaults → include: files → the config file → .ssg.designer.json → command-line flags. $NAME references are resolved from the environment where each key is used, after all of these.

Core and paths

Key Default CLI Purpose
source required positional Local content collection
template required positional Theme name
domain required positional Canonical host, without a scheme — example.com, not https://example.com. A scheme or trailing slash is stripped and reported, since it would otherwise reach every absolute URL the site publishes
title empty config only Site name → .Site.Title (a migration fills it in)
description empty config only Site tagline → .Site.Description
colors empty config only Palette by role → .Site.Colors.<role> and --ssg-color-<role>
posts_page empty config only Where the post listing goes, e.g. blog → /blog/
paginate 0 --paginate Posts per page of the post listing and archives, continued at /page/2/; 0 puts them all on one page. Other generators call this posts_per_page
content_dir content --content-dir Parent of local sources
content_sources empty --content-source (repeatable) Extra Markdown roots merged into the site; see CONTENT
auto_excerpt false --auto-excerpt Derive a missing excerpt from the opening paragraph
flat_posts false — Load Markdown sitting directly in posts/ as posts, not only from folders under it
templates_dir templates --templates-dir Parent of themes
output_dir output --output-dir Generated site destination
static_dir static --static-dir Verbatim passthrough files. A declared directory that does not exist is skipped, not an error
static_sources empty config only Extra verbatim passthrough roots, each keeping its own name
data_dir data --data-dir YAML/JSON data for .Data
pages_path pages config only Pages directory inside a source
posts_path posts config only Posts directory inside a source
quiet false --quiet, -q Suppress normal output

Site identity and palette (title, description, colors)

1title: "Magna Valor"
2description: "Supply Chain Global Advisory"
3colors:
4  primary: "#7b2ff7"
5  secondary: "#54595f"
6  accent: "#61ce70"
7  text: "#222733"
8  background: "#f6f6f6"
9  link: "#a4836d"

Templates read these as .Site.Title, .Site.Description and .Site.Colors.primary. The palette is also emitted on :root as --ssg-color-primary, --ssg-color-secondary, … so a theme can style against the site's own colours without the values being copied into its stylesheet, and the primary colour stands in for <meta name="theme-color"> when nothing else declares one. Roles beyond the six above are allowed and follow them alphabetically; a theme that already declares --ssg-color-* itself wins.

ssg migrate fills all three in from the source site (see MIGRATE) — but only where the config has nothing, so an edit here is never overwritten.

The front page (posts_page)

By default / is the generated post listing. A content page takes it instead as soon as one resolves there — link: "/" in front matter, which is what a WordPress static front page exports as:

1posts_page: blog     # the listing moves to /blog/ and /blog/page/2/
1🏠 Front page: home.md — replaces the theme's home page
2   Post listing: /blog/

A front page that says robots: noindex stops the build (#394). It is nearly always a migration leftover, and it would make the site's home page noindex. Remove its link: to keep the theme's home page, or remove the noindex. A redirect at / and sitemap: "no" are allowed.

Without posts_page the listing has nowhere to go, so it is not generated — reported, not silent:

1🏠 Front page: home.md — replaces the theme's home page
2   8 post(s) are not listed anywhere — set posts_page: "blog" to publish the listing

posts_page works on its own too: a site with no front-page document can still move its listing off the root. In multilingual builds the language prefix comes first (/pl/blog/), and each language has its own front page.

A front page per language

Each language names its own root in link:. The default language's root is /, unless prefix_default_language is on. Every other language's root is its prefix. link: is never prefixed for you, so write it in full:

1# home.hi.md (default language)   # home.en.md                  # home.pl.md
2link: "/"                         link: "/en/"                  link: "/pl/"
3translation_key: home             translation_key: home         translation_key: home

Each of these pages is its language's front page. Each language's post listing moves to its own posts_page (/en/blog/), or is not generated when posts_page is unset. The build names every language's front page:

1🏠 Front page: home.hi.md — replaces the theme's home page
2   Post listing: /blog/
3🏠 Front page: home.en.md — replaces the theme's home page
4   Post listing: /en/blog/

Giving two languages link: "/" is a collision at the site root. The error says how to fix it.

The two are usually set together with paginate, which decides how many posts each page of the listing holds:

1posts_page: blog
2paginate: 9          # /blog/, /blog/page/2/, … — 0 (the default) is one page

Extra feeds (feeds)

feed: true publishes one Atom feed of every post at /feed.xml, plus one per language and one per taxonomy term. That is all-or-nothing: a site with several content roots cannot offer "just the blog", and "the three tags that mean release" would need three subscriptions.

A term's feed is written beside its archive — /category/news/feed.xml for an ordinary category, /projects-archive/feed.xml for one served away from /category/ by its own link:, /category/rooms/kitchens/feed.xml for a nested one — and a term whose archive was not rendered gets no feed. Before 1.8.56 the category feeds were addressed by slug alone, which put them next to no archive in the last two cases.

feeds: declares any number of extra feeds, each choosing what goes in, where it is written and in what format. feed: true keeps doing exactly what it does today, so adding this changes nothing that already works.

 1feeds:
 2  - path: /blog/feed.xml       # a whole content root
 3    title: "Blog"
 4    source: blog               # a content folder, MDDB section or external source
 5
 6  - path: /blog/rss.xml        # the same posts, a second format
 7    title: "Blog"
 8    source: blog
 9    format: rss
10
11  - path: /docs/feed.json
12    title: "Documentation updates"
13    source: docs
14    format: json
15
16  - path: /releases.xml        # several terms in one feed
17    title: "Release notes"
18    format: rss
19    categories: [release, changelog]
20    items: 10

Two things worth knowing even if you only ever want Atom:

  • feed: true names the feed after the site's title, and after the bare hostname only when there is none; under i18n each language's feed adds the language name, Magna Valor (Polski). A declared feed takes a title of its own, so it can be called what it actually is.
  • SSG injects the autodiscovery <link> tags itself, for every feed, into every page — so a theme should not hand-write them or the page ships duplicates. Turn injection off with feed_autodiscovery: false if the theme wants to own them.
Key Meaning
path Output path — also the URL. Required
title Feed title; defaults to the site domain
format atom (default), rss (2.0), json (JSON Feed 1.1), google-merchant or acp (product feeds, see below)
ucp on a google-merchant feed: add Google's Universal Commerce Protocol attributes (see below)
source A content root: matches that folder and everything beneath it; also an MDDB section or an external_sources entry by name (1.9.0)
prefix URL path prefix, or a list of them, as in sitemaps: (1.9.0)
categories Category names or slugs — any of
tags Tags — any of
type post (default) or page
items Item cap for this feed; defaults to feed_items
full_content Full body vs summary; defaults to feed_full_content. A full body's relative URLs are made absolute against the post's address

Selection criteria are optional and combine with AND — source: blog plus tags: [release] means release posts from the blog folder. A feed with no criteria covers every post, at a path you choose.

Product feed for Google Merchant Center

format: google-merchant writes the site's products as a Merchant Center feed (RSS 2.0 in the g: namespace). Google fetches the file on a schedule you set in Merchant Center, so nothing has to run or hold credentials (since 1.8.84, #196).

1feeds:
2  - path: /merchant.xml
3    format: google-merchant
4    title: "Example Shop"
5    source: shop               # the usual selection; without type: both posts and pages
6    merchant:                  # for what a product page does not say
7      availability: in_stock
8      brand: Example
9      condition: new

The rows come from the JSON-LD the page already gets (.Schema: site, section and page schema: merged), so a page that ships valid Product + Offer data needs no extra authoring. Every product is listed — feed_items does not cap a catalogue; items: does when set.

Google attribute From
id sku, then merchant.id in front matter, then the page's URL
title, description name, description; else the page's title and description
link url of the product or offer; else the page's canonical URL
image_link image (a URL, a list or an ImageObject), made absolute
price offers.price + offers.priceCurrency → 12.50 PLN
availability offers.availability (InStock → in_stock, OutOfStock/SoldOut/Discontinued → out_of_stock, PreOrder → preorder, BackOrder → backorder); else the feed's merchant.availability; else in_stock with a warning
condition itemCondition (UsedCondition → used, RefurbishedCondition → refurbished); new is left out, as Google asks
brand brand (text or a Brand); else the feed's merchant.brand
gtin, mpn gtin/gtin13/gtin12/gtin14/gtin8, mpn
item_group_id a ProductGroup's productGroupID (or sku): each of its hasVariant products is a row of its own and inherits what it leaves out

A page's merchant: front matter (id, availability, condition, brand, gtin, mpn) wins over the JSON-LD. merchant.id applies only to a page with one product; variants need their own sku.

Keep the id stable. To Google a changed id is a new product, and the old one's history is gone. An id taken from the URL changes when the slug does, so the build says how many products use one — give them a sku or merchant.id.

Stock is what it was at build time. Rebuild when it changes, or let Google update price and availability from the structured data on the product pages (Merchant Center's automatic item updates). The build warns about products that state no availability at all.

A product Google would reject — no title, description, link, image or price — is left out with a warning naming the page. The feed is not offered to readers in the pages' autodiscovery links.

Product feed for the Agentic Commerce Protocol (ACP)

format: acp writes the same products as google-merchant as an Agentic Commerce Protocol product feed — the file OpenAI reads to show a shop's products in ChatGPT (1.9.10, GO-161, #197). The rows come from the same place: the page's merged Product + Offer JSON-LD and its merchant: front matter, read by the same code, so a page already in the Merchant feed needs nothing new. ACP adds a seller block, which the feed repeats on every row, and a few optional per-product fields.

 1feeds:
 2  - path: /acp.jsonl
 3    format: acp
 4    source: shop
 5    merchant:                    # the same defaults as google-merchant
 6      brand: Example
 7    acp:
 8      seller_name: Example Shop  # required
 9      target_countries: [US]     # required, ISO 3166-1 alpha-2
10      store_country: US          # required
11      seller_url: /
12      seller_privacy_policy: /privacy/   # needed for checkout
13      seller_tos: /terms/                # needed for checkout
14      return_policy: /returns/
15      accepts_returns: true
16      return_deadline_in_days: 30        # written only with accepts_returns: true
17      shipping_price: "4.90 USD"         # when an offer states no shippingRate
18      is_digital: false
19      is_eligible_search: true           # the feed's default when unset
20      is_eligible_checkout: false        # unset = false
21check_acp: warn

Specification. Written against the OpenAI Product feed schema, developers.openai.com/commerce/specs/feed, and Submit product feeds, as read on 2026-11-14. Neither page carries a version or a date; the agentic-commerce-protocol.com copy linked from #197 did not resolve that day. If the schema moves, this section and the code move with it.

Format: JSON Lines (.jsonl, UTF-8), one product object per line. The schema also describes CSV and TSV, but its own example is JSON Lines, and in JSON the lists (target_countries, additional_image_urls) and the variant map stay JSON instead of a comma-joined cell and a JSON string inside a cell. No compression — the schema does not mention it.

The required seller fields — seller_name, target_countries, store_country — are configuration: without them the build fails, naming them. URLs in the block may be site paths; they are made absolute. target_countries and store_country are upper-cased. The schema says standard uploads use US today and other markets need OpenAI's confirmation.

ACP field From
item_id as Merchant's id: sku, then merchant.id, then the page's URL
title, description, url, brand, gtin, mpn, condition as the Merchant feed
image_url, additional_image_urls the first image, then the rest
price offers.price + offers.priceCurrency → 14.00 EUR
availability as Merchant, in ACP's spelling: in_stock, out_of_stock, pre_order, backorder; unknown when the page or the feed's merchant.availability says unknown (since 1.9.11; OpenAI's product feed accepts it, Google's does not, so the Merchant row of the same product says in_stock, counted in the "state no availability" warning)
group_id, listing_has_variations, variant_dict a ProductGroup: each hasVariant is a row; variant_dict holds the properties named in variesBy (else color and size) with the variant's values
offer_id acp.offer_id, else offers.sku
product_category, material, color, size category, material, color, size of the Product
review_count, star_rating aggregateRating (reviewCount or ratingCount; ratingValue rescaled to 0–5 from bestRating, two decimals); no count, no rating
shipping_price offers.shippingDetails.shippingRate (value + currency), else the feed's acp.shipping_price
seller, returns, countries, is_digital, is_eligible_* the feed's acp: block

A page's acp: front matter adds or overrides, for every product on the page: product_category, material, gender (male, female, unisex), age_group (newborn, infant, toddler, kids, adult), size_system (US, UK, EU…), shipping_price, is_digital, is_eligible_search, is_eligible_checkout; and on a page with one product (variants need their own JSON-LD, as with merchant.id): offer_id, color, size, sale_price ("35.00 EUR"). merchant: front matter (id, availability, condition, brand, gtin, mpn) works as in the Merchant feed and accepts pre_order too.

 1---
 2title: Enamel mug
 3schema:
 4  "@type": Product
 5  sku: MUG-350
 6  image: /images/mug.jpg
 7  offers: { price: "14.00", priceCurrency: EUR, availability: https://schema.org/InStock }
 8acp:
 9  product_category: Home & Garden > Kitchen & Dining > Drinkware
10  is_eligible_checkout: true
11---

The schema names fields this feed does not write: is_ads_eligible and ads_metadata (Ads), marketplace_seller, store_review_count, store_star_rating, accepts_exchanges, the shipping tuple, and separate length/width/height/weight. Several need setup with OpenAI first. The delivery_estimate, inventory_quantity and custom_variant1_* fields named in #197 are not in the current schema (the custom_variant pairs are legacy, replaced by variant_dict), so they are not written either.

A row missing a per-product required field (title, description, url, brand, image_url, price) is left out of the file, since OpenAI rejects it. With check_acp off, the build prints one line counting those rows and the ones whose availability no page states.

check_acp (GO-162) names each problem by source file and field. The feed decides what an agent shows and the checkout decides what it charges. When they disagree the product is dropped without a warning, so the build is the only place that reports it:

⚠️  ACP feed in content/shop/pages/mug.md → acp.jsonl item MUG-1: price — 12 has no currency; set offers.priceCurrency — the row is left out
⚠️  ACP feed in feeds: /acp.jsonl → acp.seller_tos — required when a row has is_eligible_checkout: true
  • a row missing a required field (and so left out);
  • a price with no currency, or any amount (price, sale_price, shipping_price) not written amount CURRENCY, or not in the price's currency; a sale_price not above zero and below the price;
  • an availability no page states, which comes from the feed's merchant.availability or is assumed in_stock;
  • a duplicate item_id or offer_id;
  • a product url on this site that does not resolve in the output;
  • seller_privacy_policy or seller_tos missing while a row asks for checkout, and any seller URL on this site (seller_url, the policies, return_policy) that does not resolve;
  • is_eligible_checkout: true on a row whose is_eligible_search is false;
  • a feed with no rows at all, with the likely cause: no selected page has a schema: Product (sku: and price: as plain front matter give no row), or every product lacks a required field. With the check off the build prints one line for it.

strict (or strict: true) fails the build on any of them. URLs on other sites are not fetched.

What this does not do. ssg writes the file and stops there. Sending it to OpenAI (an upload, a hosted URL or SFTP, set up in the merchant portal) and the checkout (the REST endpoints, the payment through Stripe's Shared Payment Token, the order webhooks) are not part of the build. In 1.9.10 they come from the shop worker (workers/ecommerce) and a Cloudflare Cron Trigger beside it that pushes the feed. Stock in the file is what it was at build time, and live inventory stays with the shop. OpenAI's commerce pages, read 2026-11-15, describe no certification; its feed schema says checkout "requires a separately enabled integration" without saying how it is enabled, and the protocol's site (agenticcommerce.dev, same date) says each AI platform manages its own process. Neither the feed nor the shop worker has been tested by any platform: treat both as a starting point written against the published schema. Steps and current facts: ACP.

Universal Commerce Protocol (UCP) on the Merchant feed

The Universal Commerce Protocol (ucp.dev) is the open protocol Google uses to let shoppers buy in its AI surfaces — AI Mode in Google Search and the Gemini app — with Google Pay, without leaving for the shop's site. Google reads which products can be bought that way from Merchant Center, so on the build side UCP is a few extra attributes on the google-merchant feed above, switched on with a ucp: key (1.9.10, GO-166). The checkout itself — the UCP REST endpoints, the Google Pay payment handler, order updates — is not part of the build; in 1.9.10 it is the shop worker's job (workers/ecommerce, GO-167).

 1feeds:
 2  - path: /merchant.xml
 3    format: google-merchant
 4    source: shop
 5    merchant:
 6      brand: Example
 7    ucp:                          # the opt-in; without it the feed is unchanged
 8      checkout_eligibility: true  # the default once ucp: is present
 9      cart_eligibility: true      # optional; left out = eligible (opt-out)
10check_ucp: warn

Why not a format: ucp. The UCP specification has no product file: its catalog is a live API (dev.ucp.shopping.catalog.search / .lookup) the shop serves, next to checkout and cart. What Google asks for in a feed are Merchant Center attributes on the products it already has, and its guide gives them in the Merchant feed's own XML. So they go into that file, one feed for both uses.

Sources (read 2026-11-14; the pages carry no version or date of their own):

  • Google, UCP — Prepare your Merchant Center account, developers.google.com/merchant/ucp/guides/overview/merchant-center — the attributes, product restrictions and account settings below;
  • Google, UCP implementation overview, developers.google.com/merchant/ucp/guides/overview, and About UCP integration in Merchant Center, developers.google.com/merchant/ucp/guides/tools/merchant-center/overview;
  • Merchant Center Help: Native commerce (answer/17251586), Variant option (answer/17085214), Item group title (answer/17085146), Returns (answer/17081382);
  • ucp.dev specification index, release 2026-08-25 (catalog capability);
  • Microsoft Advertising, Make your store UCP ready, learn.microsoft.com/en-us/advertising/msa-help/hlp_ba_conc_bmc_ucp (updated 2026-06-26).

What a row gets with ucp::

Merchant attribute From
native_commerce → checkout_eligibility the feed's ucp.checkout_eligibility (default TRUE), else the page's merchant.checkout_eligibility; FALSE for a product Google lists as ineligible (below)
native_commerce → cart_eligibility the feed's ucp.cart_eligibility, else the page's merchant.cart_eligibility; written only when one of them is set
item_group_title a ProductGroup's name, on each of its variants
variant_option (name, value) the variant's values of the properties its group lists in variesBy (else color and size), in that order — the same data as ACP's variant_dict
consumer_notice (notice_type, notice_message) the page's merchant.consumer_notice: one {notice_type, notice_message} or a list; the message keeps its <b>, <br>, <i>, <a href>
merchant_item_id the page's merchant.merchant_item_id, on a page with one product, when it differs from id — for a checkout that knows the product by another id

Every row of a ucp: feed carries the whole native_commerce group: Google overwrites the group on each upload and blanks a flag that is missing. Without ucp: none of these elements is written and the feed is byte for byte what it was before 1.9.10 (held by a golden test).

 1---
 2title: Steel kettle
 3schema:
 4  "@type": Product
 5  sku: KETTLE-1
 6  image: /images/kettle.jpg
 7  offers: { price: "49.00", priceCurrency: USD, availability: https://schema.org/InStock }
 8merchant:
 9  merchant_item_id: kettle-checkout-1     # only if the checkout uses another id
10  checkout_eligibility: true              # per product, over the feed's value
11  consumer_notice:
12    - notice_type: prop_65                # legal_disclaimer, safety_warning or prop_65
13      notice_message: 'This product can expose you to <b>lead</b>.'
14---

Products Google does not take into checkout. Its guide lists subscriptions, instalments, personalised goods, used, refurbished and final-sale items, pre-orders, bundled services, special shipping, gifting, in-store activation, age-restricted and prohibited products, services, rentals, virtual items and goods that need software installed first. ssg can see three of them in the page's data and writes checkout_eligibility FALSE for them whatever the feed or page asks: availability preorder, a condition of used or refurbished, and a return policy of no returns (hasMerchantReturnPolicy with returnPolicyCategory MerchantReturnNotPermitted on the offer or product). For every other category, set merchant.checkout_eligibility: false on the page yourself.

check_ucp ("", warn, strict, like check_acp) names each problem by source file and field. With it off, the build prints one line counting them.

⚠️  UCP feed in content/shop/pages/radio.md → merchant.xml item RADIO-1: native_commerce — written FALSE: Google lists refurbished items as ineligible for checkout
  • a row missing a required Merchant attribute (and so left out), or a price with no currency;
  • a product asked into checkout that Google lists as ineligible (above);
  • a checkout-eligible row whose availability no page states;
  • a consumer_notice whose notice_type is not legal_disclaimer, safety_warning or prop_65, whose notice_message is empty, longer than 1000 characters, or uses a tag other than <b>, <br>, <i>, <a>;
  • a variant without variant_option or item_group_title (Google "strongly recommends" both), an item_group_title over 150 characters, more than 30 options, an option name or value over 250 characters, variants of one group with different option names or the same combination of values;
  • a ucp: feed in which no row is eligible for checkout;
  • a ucp: feed with no rows at all, with the likely cause: no selected page has a schema: Product, or every product lacks a required attribute. With the check off the build prints one line for it.

What the merchant does in Merchant Center (Google's guide, as read on 2026-11-14):

  1. Have a Merchant Center account in good standing with products approved for free listings, and the feed above added as a data source. Google recommends a supplemental data source for the UCP attributes and allows the primary feed, warning that a formatting error there affects normal product ingestion. ssg writes them into the feed it generates, so they arrive with the products.
  2. Set a return policy in Merchant Center (return cost, return window and a link to the full policy; on an advanced account, per sub-account). It is shown on the checkout screen. The product-level returns attribute exists too; ssg does not write it.
  3. Set customer support information — at least one of a website URL, an email address or a phone number — used for the "Contact merchant" link.
  4. Configure shipping.
  5. Join the UCP waitlist (support.google.com/merchants/contact/ucp_integration_interest): Google approves each integration before it goes live. Merchant Center's UCP integration hub is rolling out in the United States and applies to products sold there; Google names Australia and Canada next.
  6. Publish the shop's UCP profile and implement checkout (or cart transfer) — the shop worker's part.

Google also recommends keeping price and stock fresh through the Merchant API rather than a scheduled feed alone, so the price in checkout matches the listing. A static feed is what it was at build time.

Microsoft Merchant Center also asks for a "UCP-ready" feed for Copilot checkout. Its page (above) asks for a return policy and a customer service URL in Store settings → UCP settings, and for product warnings in fields it names consumer_message_type and consumer_message_content — not Google's consumer_notice. It does not name the feed attributes for checkout eligibility or the merchant item id. ssg writes Google's attribute names only; whether Microsoft's feed import reads them is not confirmed.

Open questions (not implemented until an official source settles them): Microsoft's exact attribute names and nesting for checkout eligibility, merchant item id and product warnings; whether e-books and other downloads fall under Google's "virtual items" restriction (its examples are in-game goods); the returns attribute generated from Schema.org MerchantReturnPolicy.

Aggregating feeds (a "planet")

A feed can merge several inputs — other sites' feeds and your own posts — into one published feed. Read the sources with format: feed, then list them:

 1external_sources:
 2  sources:
 3    ssg:  { type: http, url: https://blog.example.com/feed.xml,  format: feed }
 4    mddb: { type: http, url: https://docs.example.com/feed.xml, format: feed }
 5
 6feeds:
 7  - path: /planet.xml
 8    title: "Planet Example"
 9    format: rss
10    aggregate:
11      - source: ssg
12        label: "SSG"
13      - source: mddb
14        label: "MDDB"
15        exclude:
16          tags: [events]        # narrow this source only
17      - site: blog              # your own content — "*" for every post
18        label: "Example"
19    exclude:
20      words: [sponsored]        # applies to the whole feed
21    items: 200                  # how many entries the feed carries at all
22    paginate: 20                # how many per page

Your own blog is an input like any other. A planet without you is not your planet — an aggregate that only republishes other people reads as a link dump.

Key Meaning
aggregate[].source An external_sources name declared with format: feed
aggregate[].site Your own content: a folder name, or * for every post
aggregate[].label Provenance — attached to each item and emitted as a category
aggregate[].include / .exclude Filters for that source only
include / exclude Filters for the merged feed
paginate Items per page; 0 (default) writes one file

Filtering happens twice on purpose: per source first, then feed-wide. What counts as noise depends on the feed it came from, and that context is gone once everything is merged — one rule for the whole aggregate either lets noise through or drops wanted items from the quieter sources. words match the title and summary case-insensitively; tags match an item's categories. Exclusion beats inclusion: a feed republishing other people's writing has to be able to say "not this" with certainty.

Items are sorted newest first and deduplicated by URL — the same post reached through two feeds is one item, and publishing it twice is the most visible way an aggregate looks broken. A source that is unreachable or not declared with format: feed warns and is skipped, rather than failing the build over one site being down.

Paginated feeds are linked with RFC 5005 rel="next"/"prev"/"first"/"last", so a reader can walk the whole archive. Page one keeps the declared path — /planet.xml, never /planet-1.xml — so the URL people already subscribed to does not move as the archive grows.

Every published feed gets its own <link rel="alternate"> with the correct MIME type and title, injected into every page including the homepage — a reader offering a choice reads exactly those links, so one Atom link would hide the rest. A theme that advertises its own feed is left alone.

On a multilingual site the feed: true link follows the page's language: a page under /pl/ offers /pl/feed.xml, the feed of the posts it is written in, rather than the default language's /feed.xml. A page in a language the site does not declare keeps the root feed.

Set feed_autodiscovery: false to keep the feeds but stop the injection into your HTML — for a theme that wants control over the links' order, their titles, or which feeds are advertised at all:

1feed: true
2feeds:
3  - path: /rss.xml
4    format: rss
5feed_autodiscovery: false     # the feeds are still written; the <link> tags are yours

The links then have to come from the theme. A theme that already emits its own feed link suppresses injection anyway — this is the explicit form of that, so the behaviour does not depend on SSG noticing what the theme happened to render.

Publishing files that live elsewhere (static_sources)

static_dir is a single root. When the files a site publishes verbatim already live somewhere else in the repository — a specification the validator, the tests and CI all read at the repo root — copying them into static/ means maintaining two copies that will drift, and staging them with a script means every contributor has to know to run it.

1static_sources:
2  - path: schema.json      # a file, served at /schema.json
3  - path: xml              # a directory, served at /xml/... — the name is kept
4  - path: editor
5    dest: app              # placed at /app/ instead
6  - path: build/assets
7    dest: "."              # contents spread at the output root, like static_dir

Each entry keeps its own name by default, which is the point: URLs that already exist keep resolving. Sources are copied after static_dir, so a later entry wins a collision, and a missing path is a warning rather than a failed build.

A verbatim HTML document can join sitemap.xml. A copied file never becomes a page, so no part of the sitemap could reach it — a hand-authored SPA linked from every page in the nav was absent from the file the site uses to state its own structure. The generator cannot tell a document from an asset by looking, so say which one is:

1static_sources:
2  - path: editor/index.html
3    dest: editor/index.html
4    sitemap: true            # listed at /editor/
5    priority: 0.8            # optional; 0.8 is what an ordinary page gets

Opt-in, because most of what a site copies verbatim is an asset. A directory entry resolves to the index.html at its root; anything that is not an HTML document is a warning rather than a sitemap line, and a document whose own HTML says noindex keeps itself out like every other entry. The <lastmod> comes from the source file's last commit under lastmod_from_git; without it a copied document has no <lastmod>, since it has no frontmatter date and a file's modification time is no reliable one (1.8.74).

output_dir is generated state. clean: true deletes its old contents before building. See CONTENT for the source directory contract.

Template selection

Key Default CLI Purpose
engine Go behaviour --engine go, pongo2, mustache or handlebars
online_theme empty --online-theme GitHub, GitLab or direct ZIP theme URL; repo@ref pins a tag, branch or commit
online_theme_sha256 empty --online-theme-sha256 Expected SHA-256 of the theme archive; a mismatch stops the build before extraction

The template core value names the destination/local theme directory. Engine aliases accepted by the CLI include jinja2/django for Pongo2 and hbs for Handlebars. Non-Go themes must ship their own templates in the chosen syntax. See TEMPLATES.

A downloaded theme is code: its templates run during the build. Pin it to a tag or commit (https://github.com/user/theme@v1.2.0) and set online_theme_sha256 to the archive's sum. Without a sum the build warns and prints the sum it saw, ready to copy into the config.

Development server

Key Default CLI Purpose
http false --http Start the built-in server after building
host 127.0.0.1 --host Bind address
port 8888 --port TCP port. Taken if free; otherwise the server walks forward (8889, 8890, …, up to 64 ports) and announces where it landed. 0 = any free port
watch false --watch Rebuild after local file changes (content, templates, data and the config file)
auto_reload on with --http --watch --auto-reload, --no-auto-reload Inject a live-reload client into served HTML so the browser refreshes after each successful rebuild; false opts out
watch_runner "" --watch-runner Spawns a background watch runner process; none turns off the one a configured worker would start
watch_runner_config "" --watch-runner-config Config file the runner should use
watch_runner_dir "" --watch-runner-dir Directory the runner starts in
clean false --clean Remove previous output before builds
incremental false --incremental Rebuild only the pages a change can reach. Always on under --watch
markdown_cache false --markdown-cache Keep converted Markdown between builds. Off for a reason — see below

watch_runner: none (or off) keeps a configured worker for builds and deploys but starts no runner in --watch, so the preview serves only the static site. If the runner's command is not installed, the preview still starts and ssg says so once. This is the usual case in the Docker image, which has no Node:

1ℹ️  Watch runner "npx wrangler pages dev ." not started: npx is not installed here, so /api/* Functions are not served (the static preview works).
2   The ssg Docker image has no Node: run `npx wrangler pages dev output` on the host beside it, or use an image with Node.

watch_runner coordinates background execution of development emulators (like wrangler or workerd). When configured, ssg automatically monitors files for rebuilds and spawns the runner in parallel, piping its output and terminating it on exit. Spelled --wrangler (for npx wrangler dev) or --workerd (for workerd serve) as CLI convenience flags.

What the watcher observes

--watch names its inputs at startup, e.g. 👀 Watching for changes in content, templates, data, config (.ssg.yaml)...

The config file is a watched input of its own: editing it reloads the configuration and rebuilds with the new settings — no restart needed to change a theme, a permalink scheme or any other option. Command-line flags still win over the file, exactly as at startup. If an edit leaves the file unparseable, the error is reported and the watcher keeps the last good configuration running rather than exiting, so a half-saved file never kills a dev session.

A change is detected by content, not mtime: touching a file without changing its bytes does not trigger a rebuild.

Rebuilding only what changed

--watch builds incrementally: after the hash check says something did change, only the pages that change can reach are rendered. A one-shot build is full unless --incremental asks otherwise, because a build nobody is waiting on should be the simple one.

An uncertain dependency means a full build, always. A changed template or partial, a changed configuration file, a file the last build never saw, --clean, or content coming from MDDB, external sources or a CMS import each rebuild everything — the graph does not model which pages those reach, and a stale page with a green build is a worse failure than a slow one.

1ssg graph                                # what the last build recorded, or why it cannot be narrowed
2ssg graph content/site/posts/hello.md    # what changing that file rebuilds
3ssg graph --dot | dot -Tsvg > graph.svg

The graph is recorded by every build, incremental or not, in .ssg-cache/graph/graph.json. Delete it and the next build is full. An incremental build produces the same output tree as a full one, byte for byte; a property test asserts exactly that over random sequences of edits.

What it narrows is the render phase, which on a 5 000-post corpus is about a fifth of a warm build — see INCREMENTAL for the measurements and for why the wall clock moves less than the page count does.

Keeping conversions between builds

markdown_cache: true stores each converted document under .ssg-cache/markdown/ and reads it back next time. It is off by default, and the measurements are the reason.

Converting Markdown is a pure function of its input, so it looked like the obvious thing to cache. In wall-clock terms it is not: conversion runs across every core, and reading a cache back does not. On a 5 000-post corpus:

Machine Without the cache With it
32 cores 1.44 s 1.39 s
4 cores 1.45 s 1.41 s
2 cores 1.74 s 1.58 s

It costs disk equal to the size of your content — 79 MB for that corpus — to buy 3% on a workstation and 9% on a small runner. Turn it on for the case it was built for: continuous integration with two cores and a cache carried between runs. Leave it off on your own machine.

A build with render hooks never uses it, whatever the setting says. A hook is a template and a template can call the build's helpers, so its output can depend on the whole site rather than on the document being converted, and a key over the document would be a lie. ssg cache stats lists the namespace; deleting it costs one build.

watch_runner_config points the runner at a config file kept anywhere on disk, so a wrangler.toml does not have to sit in the project root next to .ssg. The path is passed as --config <path> to wrangler and to custom runners, and as the positional config argument to workerd serve. A missing file is reported as a warning; the runner is still started so its own error message is visible.

watch_runner_dir starts the runner in another directory — the monorepo case, where the Worker lives in booking/apps/api/ while content and templates stay at the repo root. Without it npx wrangler dev runs where ssg was invoked and fails with "Missing entry-point to Worker script or to assets directory". A relative watch_runner_config is resolved against ssg's working directory before the runner is started, so both options can be combined safely. A directory that does not exist aborts the runner (the build itself continues).

--wrangler-config=FILE, --wrangler-dir=DIR, --workerd-config=FILE and --workerd-dir=DIR are convenience spellings: each sets its value and selects that runner (so --wrangler is implied), in any flag order. Use --watch-runner-config=FILE / --watch-runner-dir=DIR with a custom --watch-runner.

1# Worker in a subdirectory of the same repo (issue #35)
2ssg --watch --wrangler-dir=booking/apps/api my-site simple example.com
3
4# wrangler config kept in deploy/, not in the project root
5ssg --wrangler-config=deploy/wrangler.toml my-site simple example.com
6
7# equivalent, spelled out
8ssg --watch-runner=wrangler --watch-runner-config=deploy/wrangler.toml \
9    my-site simple example.com
1watch_runner: wrangler
2watch_runner_dir: booking/apps/api
3watch_runner_config: booking/apps/api/wrangler.jsonc

Pair it with environment variables in external_sources to point the same config at the local Worker during development and at the production API in CI.

watch monitors content, templates and data. Touch-only changes whose bytes are unchanged do not trigger a rebuild; actual changes still cause a full build.

Use host: 0.0.0.0 only when the preview must be reachable from other machines.

Public TLS and hardening

1http: true
2port: 443
3tls_cert: cert.pem
4tls_key: key.pem
5http3: true
6gzip: true
7max_conns: 1024
8resources:
9  memory: 512MiB
Key Default CLI Purpose
tls_cert empty --tls-cert Manual PEM certificate
tls_key empty --tls-key Manual PEM private key
tls_auto false --tls-auto Obtain certificates with Let's Encrypt
tls_domain empty --tls-domain Autocert host names, comma-separated
http3 false --http3 Add HTTP/3/QUIC alongside HTTPS
gzip false --gzip Compress accepted responses
max_conns 0 --max-conns Connection limit; 0 is unlimited
mem_limit empty --mem-limit Alias of resources.memory, which wins when both are set. Since 1.9.0 it applies to every command, not only the server — see Running on a small machine

TLS enables HTTP/2 automatically through ALPN. HTTP/3 requires TLS and uses the same UDP port. Manual certificate/key configuration takes priority over automatic certificates. Autocert requires a public domain and access to ports 80/443.

The server automatically applies X-Content-Type-Options, X-Frame-Options, Referrer-Policy, HSTS under TLS, and cache-control suitable for HTML and fingerprinted assets.

Output and URLs

Key Default CLI Purpose
minify_html_keep_comments empty config only Comment openings minify_html must not delete, beyond the host directives kept by default. Name the directive (email_off) or the whole opening (<!--email_off)
sitemap_off false --sitemap-off Disable sitemap.xml
sitemaps empty config only Declared sub-sitemaps, each with its own path and selection; sitemap.xml becomes their index. See Splitting the sitemap
sitemap_max_urls 50000 config only Per-file URL ceiling; a larger set is split and indexed
robots_off false --robots-off Disable robots.txt
not_found_off false --not-found-off Disable the generated 404.html. Without a 404 page, static hosts fall back to index.html for unmatched paths and answer 200, so every dead URL reads to a crawler as a live copy of the home page. A page slugged 404 takes precedence, and is never listed in sitemap.xml
pretty_html false --pretty-html Remove blank lines from HTML
relative_links false --relative-links Convert absolute site links to relative links
base_path path of domain config only Path the site is served under (/<repo> for a GitHub project page); prefixes every root-relative URL, and check_links and ssg --http follow it. / forces the root. See DEPLOYMENT
host_files true config only Write _headers and _redirects. false for hosts other than Cloudflare Pages and Netlify, which serve them as public files
autolink_list_items true config only Link a list item whose whole text is a page title to that page. Code blocks are never touched; false turns it off
post_url_format date behaviour --post-url-format date or slug
page_format directory behaviour --page-format directory, flat or both
permalinks.post empty --permalink-post Tokenised post URL pattern
permalinks.page empty --permalink-page Tokenised page URL pattern
rewrite_md_links true config only Rewrite source .md links to final URLs (anchors/queries carried over); false opts out
strip_md_link_text false config only Drop .md from link text that is a bare filename ([CONFIGURATION.md]… → "CONFIGURATION")
link_rewrites empty config only Map an href prefix to a replacement, for links to repository files the site never publishes
preserve_slug_case false config only Do not lowercase slugs
slug_transliterate false config only Fold Latin diacritics in the slugs ssg makes from labels (Straße → strasse, not stra-e); old URLs get a 301. See Transliterated slugs
outputs HTML only --outputs=html,json Which representations each page publishes — a flat list, or a map per content type. See Outputs
outputs_custom empty config only Formats this site defines with a template of its own
markdown_publish false config only Publish a Markdown copy of every page (index.md + page.md), a text/markdown <head> alternate, and a root llms.txt — for language models and agents
site_graph false config only Publish site-graph.json: every page, section, taxonomy, link and redirect, stamped with the build — one model for agents and tools, also queryable over MCP as site_*. See AI-AGENTS
clean_special_chars false config only Normalise AI "smart" punctuation (curly quotes, en/em dashes, ellipsis, NBSP, zero-width) to ASCII across all content; CJK and other scripts untouched
output_encoding utf-8 config only Text-output encoding: utf-8, utf-16le or utf-16be (BOM added, <meta charset> kept in step)
output_encoding_sections empty config only Per-section output_encoding overrides, keyed by content directory (longest prefix wins; home = root)
home_pages_limit / home_posts_limit 6 config only Cap home-page guide/post cards before a "see all" link (0 = default 6, negative = no limit)
robots_rules empty config only Explicit per-crawler robots.txt directives (welcome/deny GPTBot, OAI-SearchBot, Googlebot…); empty = allow-all default

The Markdown-for-agents set (markdown_publish, clean_special_chars, output_encoding) serves crawlers that consume Markdown — including ChatGPT Search and other LLMs. The published copy is the authored Markdown source, not an HTML round-trip. Note that Google Search ignores llms.txt and Markdown alternates (it reads the standard HTML), so these help third-party agents, not Google ranking; ssg's standard SEO surface (seo, schema, canonical, sitemap, check_meta/check_images, hreflang) covers Google's AI-optimization guidance. robots_rules lets you state crawler policy explicitly for both.

Pages the site keeps out of search get no Markdown copy and no llms.txt line (1.9.0, #393). That means robots: noindex, sitemap: no, redirects and the 404 page, the same rule the sitemap applies. A page that lists markdown in its own outputs: still gets the file, but llms.txt leaves it out while it says noindex.

The permalinks map contains the optional post and page patterns. Permalink tokens are :year, :month, :day, :slug and :category.

rewrite_md_links turns in-repository links (CONFIGURATION.md, ./guide.md#section) into the built page URLs, carrying any #anchor or ?query across. Only in-repository links: an href with a scheme or a // prefix is left alone, so a link to a file's history on a code host stays where it points even though it ends in .md. The emitted URL follows pretty_urls, so the rewriter and check_redirects agree about the same link. strip_md_link_text complements it at publish time: when a link's visible text is exactly a filename ending in .md, the .md is dropped ([CONFIGURATION.md](CONFIGURATION.md) renders as "CONFIGURATION"). Only bare filename link text is touched — prose, inline code (`CONFIGURATION.md`) and code blocks are left alone, and the source .md files are never modified. link_rewrites covers the other half of a documentation site: links to repository files that the site never publishes. It maps an href prefix to its replacement, longest match first, so one rule can cover a folder and another override a single file:

List items that name a page become links. A list item whose entire text is the title of a page — - Documentation on a site with a page titled "Documentation" — is written as a link to that page. Lines inside fenced and indented code blocks are never touched (before 1.8.64 they were, so a YAML example containing - Documentation rendered a Markdown link inside the code). autolink_list_items: false turns it off.

1link_rewrites:
2  "../examples/": "https://code.example.com/ssg/tree/main/examples/"
3  "../.ssg.yaml.example": "https://code.example.com/ssg/blob/main/.ssg.yaml.example"

With both set, check_links on a documentation site can reach zero warnings. Frontmatter link always has higher priority. Detailed URL rules are in CONTENT.

Transliterated slugs

ssg makes some slugs from a label rather than a file name: tag, series and custom taxonomy terms, authors, the categories an extra content source names, pages built from external-source records, and story pages. That rule keeps only a–z and 0–9, so every other letter becomes a hyphen:

Label Slug (default) slug_transliterate: true
Zażółć gęślą jaźń za-g-l-ja zazolc-gesla-jazn
Crème brûlée cr-me-br-l-e creme-brulee
Straße stra-e strasse
Þórður Guðmundsson r-ur-gu-mundsson thordur-gudmundsson
Привет, नमस्ते, 日本語 empty empty
1slug_transliterate: true

With the switch on, a label is lowercased and split into base letters and combining marks (Unicode NFD); the marks are dropped. The Latin letters NFD leaves whole are folded by this table:

Letter ASCII Letter ASCII
ß (ẞ) ss ı (dotless i) i
æ ae ħ h
œ oe ŀ l
ø o ij ij
ł l ŧ t
đ, ð d þ th

The table does not guess a language: German ä, ö, ü become a, o, u, as NFD gives them, not ae, oe, ue.

Other scripts are not romanised. Cyrillic, Greek, Devanagari, CJK and the rest each have several transliteration standards that disagree with each other (Russian г is g, Ukrainian г is h), so their letters are dropped as before. A label with no Latin letter still has no slug, and each place that needs one keeps its fallback: a term or series without a slug gets no archive, and a record page without one is reported.

Old URLs. Off is the default, and an existing site builds byte for byte as it did. Turning it on moves the URL of every archive and record page whose label had such letters, so ssg writes the way back itself: a 301 in _redirects from each moved archive root (/tag/za-g-l-ja/ → /tag/zazolc-gesla-jazn/), and an alias on each moved record page (a 301 and, unless alias_stubs: false, a meta-refresh stub). A rule is not written when the old slug is still the slug of another archive under the same path, or when two labels shared it. Paginated pages (/page/2/) and per-term feeds of a moved archive are not redirected; add a redirects: splat if you need them. A redirects: entry for the same path wins over the generated one.

Slugs from file names and from slug: front matter never used this rule and are not affected: a file named zażółć.md keeps its letters in its URL with the switch on or off. An export's canonical tag slug and a slug: in term metadata win over the derived one, also unchanged.

The editor-ui worker reads the key from the site configuration and proposes new file names with the same rule; the table it is tested against is internal/models/testdata/slug-translit.json, the one ssg's own test reads.

Minification and assets

Key Default CLI Purpose
minify_all false --minify-all Enable HTML, CSS and JS minification
minify_html false --minify-html Minify HTML only
minify_css false --minify-css Minify CSS only
minify_js false --minify-js Minify JavaScript only. Comments are removed by a scanner that understands strings, template literals and regex literals, so comment characters inside them are kept
sourcemap false --sourcemap Emit v3 maps for minified CSS/JS
fingerprint false --fingerprint Hash CSS/JS names and rewrite references
scss false --scss Compile SCSS with Dart Sass
sass_binary sass on PATH --sass-binary Explicit Dart Sass executable
bundles empty config only Concatenate named CSS/JS groups

Bundle names and sources are paths relative to the output root, not to the theme. A theme whose assets land in output/css/ must say so, otherwise every source is reported missing and the bundle is written empty — which looks like a broken theme rather than a config mistake:

1bundles:
2  css/app.css:
3    - css/reset.css
4    - css/layout.css
5    - css/theme.css
6  js/app.js:
7    - js/vendor.js
8    - js/main.js

Bundling runs after assets are copied, so the paths to use are the ones you see in output/ after a build.

Bundles are created before minification and fingerprinting. Fingerprinting renames CSS/JS to name.<hash8>.ext, emits assets-manifest.json, and rewrites HTML/CSS references in dependency order. In HTML only references are rewritten: URL attributes (src, href, srcset, poster, data-*, style), <style> and <script> blocks. Page text, <pre>/<code> samples and comments keep the original name. Anywhere, an absolute URL on another host keeps its name too, so a CDN snippet such as https://cdn.example.org/pkg/app.js stays copyable (1.8.68+). Source maps require corresponding CSS or JavaScript minification. SCSS is removed from final output after compilation; if Dart Sass is missing, the step is skipped with a warning.

HTML regions can opt out of minification:

1<!-- htmlmin:ignore -->
2<pre>Whitespace is preserved here.</pre>
3<!-- /htmlmin:ignore -->

Outputs

One page, several representations. outputs: says which.

1outputs:
2  page: [html, json, txt]
3  post: [html, markdown]

html is always written. The others land beside it — index.json, index.md, index.txt — and are announced in the page's <head> with a rel="alternate" link, so a reader or an agent can find them.

The flat form still means what it always did. outputs: [html, json] applies to every content type, which is what every existing config says. The mapping form is the new one; a type the map does not name publishes HTML only.

A page can override both from its own frontmatter (see Content dimensions):

1---
2title: API reference
3outputs: [html, json]
4---

Precedence is narrowest first: the page, then its content type, then the site.

Built-in formats

Format File MIME What it is
html index.html — Always written
json index.json application/json The page record — title, dates, taxonomies, body
markdown index.md text/markdown The Markdown copy, plus the flat /section.md sibling and llms.txt
txt index.txt text/plain The title, then the body with the markup taken out

markdown_publish: true is the older way to ask for the Markdown output and keeps working exactly as it did — it adds markdown to whatever the lists say.

Formats you define

1outputs:
2  page: [html, onix]
3outputs_custom:
4  - name: onix
5    suffix: index.xml
6    mime: application/xml
7    template: formats/onix.xml
{{/* formats/onix.xml */}}
<?xml version="1.0" encoding="UTF-8"?>
<record>
  <title>{{ xmlEscape .Page.Title }}</title>
  <url>https://{{ .Domain }}{{ .Page.GetURL }}</url>
</record>

The template receives .Page, .Site, .Domain and .Content (the rendered body), plus your theme's helpers and xmlEscape.

A custom taxonomy can publish these formats beside its index and term pages too, with outputs: on the taxonomy; the template then gets the taxonomy view's data instead of .Page. See TAXONOMIES.

Custom formats render through text/template, not html/template, and that difference is deliberate: a custom format is by definition not HTML, and contextual HTML escaping is wrong everywhere else — it turns an XML declaration into &lt;?xml. The template owns its own escaping, which is what xmlEscape is for.

This is also why there is no built-in XML output. A generic one would have to invent a schema, and a schema nobody agreed on is noise; a site that wants XML knows which XML it wants.

Why feeds are not outputs

RSS and Atom are representations of a collection, not of a page. A per-page "RSS output" would be a one-item feed nobody can subscribe to usefully. Feeds stay where they are — feed: and feeds: — and are documented under Blog, feeds and search.

Running on a small machine (resources)

A build uses the whole machine by default: one worker per CPU and as much memory as the site needs. Next to other services on a small VPS, on a shared CI runner or in a container with a memory limit, one block sets a ceiling for every command: a build, --watch, --http, ssg mcp, ssg daemon and ssg migrate (1.9.0).

1resources:
2  cpu: 2            # use at most 2 CPUs; also caps build_workers
3  memory: 512MiB    # soft memory limit for the whole process; "none" = no limit
4  gc_percent: 50    # optional; lower = smaller heap, more GC work
Key Default CLI Purpose
resources.cpu no cap --cpu-limit=N Caps GOMAXPROCS and every worker pool (pages, images, WebP/AVIF, TTS). An explicit build_workers above it is lowered to it, and the external encoders, started one per worker, stay inside it too
resources.memory 90% of a cgroup limit --mem-limit=SIZE Soft limit for the process: 512MiB, 2GiB, 500MB, a byte count, or none
resources.gc_percent Go's 100 --gc-percent=N Heap growth allowed between collections; -1 turns the collector off

The older keys still work: mem_limit is resources.memory when the block leaves it unset, and build_workers still sets the worker count. A command-line flag overrides the file.

These are ceilings, not guarantees. Go's memory limit is soft: the collector works harder as the heap nears it, and a single allocation larger than the limit still succeeds. A limit keeps a build polite on a shared machine; it does not make a site that needs 2 GiB fit in 512 MiB, it makes it slower until it does not fit at all.

In a container, when no memory is configured, ssg reads the cgroup v2 memory.max of its own cgroup and sets the limit to 90% of the tightest one, so the collector tries harder before the kernel's OOM killer acts. memory: none turns that off. Go already fits GOMAXPROCS to a cgroup CPU limit by itself. The effective values are printed once at startup:

1   🧠 memory limit 512 MiB · ⚙️ 2 CPU(s)

ssg mcp prints the line on stderr, since its stdout is the protocol. ssg daemon and ssg migrate have no site config of their own and take the flags only. Each project the daemon runs is an ordinary ssg --watch process, so it applies its own resources: block; the daemon's flags limit the supervisor.

To tune the numbers, build with --profile: the report shows the peak resident memory and the number of GC cycles (memory.peak_rss_bytes and memory.gc_cycles in build-profile.json; Windows reports no RSS).

Images

Key Default CLI Purpose
webp false --webp Convert copied JPG/PNG images to WebP
webp_quality 60 --webp-quality Quality from 1 to 100
webp_keep_original false --webp-keep-original Keep originals next to the .webp files
reconvert_images false --reconvert-images Ignore existing conversion result
image_sizes empty --image-sizes Responsive widths; no upscaling
image_sizes_attr 100vw --image-sizes-attr Generated HTML sizes value
build_workers one per CPU --workers=N Parallel build workers; 0 = off (sequential); capped at resources.cpu
images_gc false --images-gc After the build, prune image-cache entries the build no longer references
images_gc_dry false --images-gc-dry Only report what images_gc would remove

build_workers (--workers=N) sets how many pages/posts render and images convert to WebP in parallel. Leave it unset to use the whole machine (one worker per CPU), set an explicit N (e.g. --workers=2) to cap it on a shared box, or --workers=0 to turn parallelism off and build sequentially. The render is grouped by language, so multilingual output stays correct; each item writes its own file, so the output is byte-identical whatever the worker count — only the wall-clock changes (verified with the race detector and the golden snapshot harness).

WebP encoding requires the optional cwebp executable. Build-time resize, crop, filter and source-set helpers are covered by IMAGES.

Scope. WebP conversion runs over the entire output tree — content media, copied static/ files and theme assets alike, every .jpg/.jpeg/.png — not just images under your content. There is no per-directory exclude list; webp_keep_original (below) is the escape hatch when something must keep its original extension.

Platform icons are the exception (1.9.0, #392). They are never converted and their links are never rewritten. iOS takes only a PNG touch icon, and a manifest is JSON that the rewrite does not read. An icon is anything a page links with rel icon, shortcut icon, apple-touch-icon(-precomposed) or mask-icon, plus the icons of a web app manifest. The manifest can be linked with rel="manifest" or sit at the root as manifest.webmanifest, site.webmanifest or manifest.json.

By default WebP conversion replaces each original in the output (the historical behaviour): logo.png becomes logo.webp and references are rewritten to match. Rewriting covers <img src>/srcset, the lazy-load data-src/data-srcset/data-bg attributes (since 1.9.3), href, CSS url(...), the og:image/twitter:image social-preview metas and the JSON-LD image value — so share previews follow the conversion instead of pointing at a removed .jpg. Only references SSG cannot resolve to a local file stay on the original extension: absolute URLs to your own images (https://…/logo.png, left untouched on purpose) and — the common footgun — paths built in JavaScript at runtime. SSG only rewrites HTML/CSS, so a script that fetches marker-icon.png (e.g. a map library's default marker) keeps requesting the .png that replace mode just deleted → a silent 404. When an asset is referenced from JS, set webp_keep_original: true to emit the .webp next to the original — rewritten HTML/CSS references serve WebP, the runtime .png still resolves (v1.8.5) — or reference it from HTML/CSS instead so the rewrite can reach it.

With webp_keep_original: true the og:image and twitter:image metas keep pointing at the original (since 1.9.0). The original is still published, and some link-preview consumers — LinkedIn's among them — do not render a WebP share card. Page images and the JSON-LD image still move to WebP.

Authoring

Key Default CLI Purpose
sanitize_html false (true for an MDDB build without mddb.trusted) --sanitize-html Apply bluemonday's UGC policy to rendered content
highlight false --highlight Highlight fenced code with Chroma
highlight_style github --highlight-style Chroma style name
highlight_line_numbers false — Prefix highlighted blocks with line numbers (needs highlight)
toc false --toc Expose .TOC; `

also expands | |toc_depth|3|--toc-depth| Maximum TOC heading level | |heading_anchors|false| — | Append a#link to its own id on each heading, so a reader can copy the section's address | |attribution|true| — | Keep the generator meta tag and the "Built with ssg" notice in every page.falseis allowed on non-commercial sites; a commercial site needs a commercial license — [LICENSING.md](LICENSING.md) | |math|false|--math| Inject KaTeX on pages containing math | |mermaid|false| — | Render ```` ```mermaid ```` fences as diagrams | |mermaid_theme| — | — | Mermaid built-in theme:default, neutral, dark, forest, base| |mermaid_background` | — | — | Solid CSS colour boxed behind each diagram |

heading_anchors: true gives every h1–h3 that has an id a link to itself, written at build time, so it works without JavaScript and every theme gets it:

1<h2 id="overview">Overview <a class="heading-anchor" href="#overview" aria-label="Link to the section Overview">#</a></h2>

The mapping form changes what is written. A mapping turns the links on unless it says enabled: false:

1heading_anchors:
2  levels: [2, 3]                   # default [1, 2, 3]
3  symbol: "¶"                      # default "#"
4  class: heading-anchor            # default
5  label: "Link to the section {text}"   # aria-label; {text} is the heading

The links are added to the page body only. The table of contents, the search index, feeds, summaries and the read-aloud audio read the Markdown, so the symbol never appears in them. A heading that already links to its own id, for example from a heading render hook, is left as it is. Style the link in the theme; a common choice is to show it only on hover:

1.heading-anchor { opacity: 0; text-decoration: none; margin-left: .25em; }
2h1:hover .heading-anchor, h2:hover .heading-anchor, h3:hover .heading-anchor,
3.heading-anchor:focus { opacity: 1; }

mermaid: true rewrites a ```mermaid fence into a <pre class="mermaid"> block before rendering (so the diagram source is passed through verbatim, not HTML-escaped) and injects the mermaid.js runtime only on pages that contain a diagram — the same page-scoped approach as KaTeX. A mermaid fence stays a plain code block when the option is off.

Diagrams are transparent by default, so on dark site chrome they can be hard to read. mermaid_background (any CSS colour — #ffffff, white, hsl(0 0% 100%)) paints a solid panel behind each diagram with padding and rounded corners, and mermaid_theme picks a matching palette (neutral or the light default read best on a dark page). Both apply only to pages that contain a diagram. Example:

1mermaid: true
2mermaid_theme: neutral
3mermaid_background: "#ffffff"

Math detection recognises display $$...$$ and fenced ```math blocks (fences are rewritten to display math before rendering, GO-055). Inline \(...\) is not supported — CommonMark backslash-escaping would consume the delimiters. Sanitisation is recommended for untrusted remote content; it is off for trusted local authoring to avoid changing intentional HTML.

Shortcodes

Shortcodes are configured reusable snippets whose template file is required:

 1shortcodes:
 2  - name: promo
 3    template: shortcodes/promo.html
 4    type: banner
 5    title: Summer offer
 6    text: Read the terms before continuing.
 7    url: https://example.com/offer
 8    logo: /images/offer.png
 9    legal: Terms apply.
10    ranking: 4.5
11    tags: [public, featured]
12    data:
13      colour: green

Use `` in Markdown. The template receives .Name, .Type, .Title, .Text, .Url, .Logo, .Legal, .Ranking, .Tags and .Data.

Enable WordPress-style syntax with:

1shortcode_brackets: true

It supports attributes and paired content:

1[link url="https://example.com" label="Read more"]
2[box type="warning"]Inner Markdown content[/box]

Templates read inline values from .Attrs and paired text from .InnerContent. Unknown bracket tags remain unchanged.

Site-wide variables: are reachable as .Vars.key / $.Vars.key, the same spelling page templates use. Page context (.Page, .Site, .Posts, …) is not in scope — one shortcode instance may render on many pages. The full scope table is in TEMPLATES.

Key Default CLI Purpose
shortcode_errors drop --shortcode-errors What a shortcode that fails to render — or a component call made wrongly — leaves in the page
components_dir components --components-dir=DIR Where typed content components live. See COMPONENTS
versions empty config only noindex_old: true marks superseded versions noindex. See CONTENT
render_hooks empty config only A template per Markdown node kind — image, link, heading, code, table, blockquote. See RENDER_HOOKS
  • drop — a warning, and the shortcode is removed from the page (historical behaviour, so existing sites build byte-identically).
  • keep — a warning, and the shortcode's raw source (``, [promo a="b"]) stays in the page, so the failure is visible rather than shipping as a silently missing block.
  • strict — as keep, and the build fails once rendering finishes, listing every shortcode that failed. Recommended in CI.
1variables:
2  stripe_public_key: "pk_test_123"
3
4shortcode_errors: strict
Key Default CLI Purpose
paginate 0 --paginate Posts per index page; 0 disables
date_archives false — Publish /YYYY/, /YYYY/MM/ (and /YYYY/MM/DD/ for dated permalinks) listings of your posts. Rendered by category.html with Kind: "date" and a label like "May 2014". Opt-in: WordPress has these URLs and links to them from every byline, a hand-authored site usually does not — ssg migrate turns it on. Real content that already owns such a path keeps it.
type_archives empty — Which content types get a listing at /<type>/ — the archive the source CMS renders and links to from its own menu, which is not a document and so is in no export. Keyed by type slug: realizacje: true builds it, reviews: false refuses it even when the export says the source had one. Rendered by category.html with Kind: "type". See Custom post type archives
sanitize_output on — Remove invisible characters from generated HTML — zero-width spaces, bidi overrides, tag characters. warn reports without changing, off does neither. Never touches <pre>/<code>. See Invisible characters
image_metadata strip — Remove EXIF/IPTC/XMP from published images. keep publishes it
image_formats [webp] --image-formats=avif,webp Formats to publish images in, in preference order — [avif, webp] offers AVIF first. See Image formats
avif_quality 45 --avif-quality avifenc -q for the AVIF pass
feed false --feed Root and category/tag Atom feeds at /feed.xml
feeds empty config only Extra feeds — each with its own selection, path, title and format (atom, rss, json, google-merchant, acp)
feed_autodiscovery true config only Inject <link rel="alternate"> for every feed into every page
feed_items 20 --feed-items Maximum feed items
feed_full_content false config only Full rendered body instead of summary; its relative src, href, srcset and url() become absolute against the post's address, since a feed reader has no page to resolve them against (#347)
search_index false --search-index Emit search-index.json
api_docs empty config only Document JavaScript/TypeScript packages as pages of the site, with api.json. See docs/API_DOCS
api_docs[].language detected config only javascript, typescript, go, php or python; detected from package.json, go.mod, composer.json, pyproject.toml when empty. See docs/API_LANGUAGES
api_docs[].playground "" config only The package as an ES module URL: JavaScript @example blocks become runnable in the browser
api_docs[].openapi "" config only An OpenAPI 3.0/3.1 file (YAML or JSON) to document as a REST API instead of code. See docs/REST_API_DOCS
api_docs[].try_it true config only The "Try it" console on every operation of an openapi entry
listen off config only "Listen" button that reads the article with the visitor's browser voice (Web Speech API). See docs/AUDIO
tts off config only An MP3 of each article made at build time by a TTS API (generic, OpenAI, ElevenLabs, Google), cached, with a jingle, a fallback when the API is down, and a podcast feed. See docs/AUDIO
webmcp false --webmcp Declare the site's tools to a browser agent via navigator.modelContext (WebMCP). Turns search_index on, which its tools read

Pagination writes page 1 at the site root and pages 2 onward under /page/N/. Themes receive .Pager.

search-index.json is a JSON array of document objects, one per published page and post, for a client-side search widget. Each object:

Field Type Notes
title string Page title
url string Final page URL
lang string Language code (empty on single-language sites)
locale string BCP-47 locale (empty if unset)
translation_key string Groups a page's translations (empty if unset)
tags string[] Tag names
excerpt string Summary text
text string Full body as plain text (HTML stripped)
taxonomies object Present only when the page has custom taxonomies: { name: [terms…] }

On a multilingual build the array is still flat; filter by lang client-side.

Taxonomies

category, tag and series are built in. The config-only taxonomies: map declares additional dynamic taxonomies with per-term archives, metadata files, optional per-term feeds and template helpers — the full reference (keys, frontmatter priority, normalization rules, template fallback chains) lives in TAXONOMIES.

External sources

The config-only external_sources: block feeds templates from local files (YAML/JSON/TOML/CSV/XML), remote HTTP APIs (hardened client + shared disk cache), read-only SQL queries (MySQL/MariaDB/PostgreSQL/SQLite) and CMS imports (WordPress, Drupal, Movable Type — merged into the site or exposed as data). Everything lands under .ExternalData; .Data is unchanged. Secrets come exclusively from environment variables. CLI: --offline, --refresh-external-sources, --clear-external-cache, --external-source=NAME. Full reference: EXTERNAL_SOURCES.

A source can also become pages rather than data: mode: content with a content_map naming which record field is the title and which is the body turns one record into one page, with its own URL, taxonomy archives and sitemap entry. See Records as pages.

Analytics

Two sources, two consent rules.

1analytics_ids:
2  gtm: GTM-XXXXXXX
3  ga4: G-XXXXXXX

Ids you declare here render on their own. Writing one down is the decision analytics: true exists to ask for, so it does not also need that flag. Ids a migration's crawl recorded in metadata.json still do, because nobody chose those — they are whatever the old site happened to be running.

Google Tag Manager gets both of its halves. The vendor's install is a script in <head> and an iframe immediately after <body>; only the first used to be emitted, so a visitor with JavaScript off, or a consent-mode setup that defers the script, was counted by neither.

Tracking reaches every page, including the home page and the archives, and does not depend on seo:. Those were always separate decisions; before 1.8.60 the code had them tangled, so a site with seo: false got no tracking at all despite having asked for it, and a site with both on still had an untracked front page.

Nothing is emitted while a value is empty, and a theme that already wires the same id keeps its own snippet rather than getting a second one. Wiring means the id inside a <script> element, in its src or its body; a page that only mentions the id — a cookie notice listing the _ga_<id> cookie — still gets the tag.

A placeholder is not an id. A value with four X in a row — the vendors' own GTM-XXXXXXX and G-XXXXXXXXXX — is held back from every page, so a config can commit the key with a stand-in for someone to fill in later without injecting a container that does not exist. The build says which ids it is doing what with:

1   🎯 Site metadata: gtm (rendered), ga4 (placeholder id, replace it to render)

An id a migration recorded and nobody declared reads set `analytics: true` to render. Every bundled theme carries a comment in its head pointing here, so there is no theme edit to make.

The ids stay readable at .Site.Analytics either way, for a theme that wants to place a vendor this generator does not know how to embed.

Server access control

Key Default CLI Purpose
server_auth empty config only basic or jwt (HS256); empty = open
server_users empty config only Basic-auth users as login:$PASS_ENV
jwt_secret empty config only HS256 shared secret, env reference
ip_allowlist empty config only Only these IPs/CIDRs may connect
ip_blocklist empty config only These IPs/CIDRs are refused first
rate_limit 0 config only Requests/second per client IP
rate_burst 0 config only Token-bucket size (default 2×rate)

The chain runs blocklist → allowlist → rate limiter → auth, before the file server. Passwords and the JWT secret must reference environment variables; X-Forwarded-For is not trusted. SSO and LDAP are deliberately not implemented.

SEO and validation

Key Default CLI Purpose
seo false --seo Inject missing Open Graph, Twitter and JSON-LD metadata
analytics false — Render the tracking snippets a migration recorded in metadata.json
analytics_ids empty — Tracking ids this site declares, by vendor: gtm: GTM-XXXXXXX, ga4: G-XXXXXXX. Declaring one is its own consent. See Analytics
schema empty — Site-wide JSON-LD defaults merged into every page (e.g. a publisher)
schema_defaults empty — JSON-LD defaults per content section, so a section can carry an @type without every file repeating it
check_links empty --check-links[=warn|strict] Validate internal links: href/src in HTML, and url()/@import in stylesheets, reported with the stylesheet and line
check_links_ignore [] config only Site paths the link check skips: an exact path (/core/nav.js) or a prefix ending in / (/core/). For references that are optional by design, such as a worker panel that loads the core worker's files when it is deployed
check_images empty --check-images[=warn|strict|strict-decorative] Report images with no alt attribute
check_meta empty --check-meta[=warn|strict] Validate <title> and meta description on indexable pages
check_orphans empty --check-orphans[=warn|strict] Report indexable pages nothing links to
check_markup warn --check-markup[=warn|strict|off], --no-check-markup Report source markup indented into a code block (ssg repair --fix)
check_schema "" --check-schema[=MODE] Validate emitted JSON-LD against the properties search engines require: "" (off), warn, strict
check_acp "" --check-acp[=MODE] Validate the rows of every format: acp feed: "" (off), warn, strict. See the ACP product feed
check_ucp "" --check-ucp[=MODE] Validate the UCP attributes of every google-merchant feed with ucp:: "" (off), warn, strict. See UCP on the Merchant feed
recipe_headings built-in names config only More section headings a Recipe's ingredients and method are read from: {ingredients: [...], instructions: [...]}
check_schema_recommended false config only With check_schema, also list the recommended properties a rich result shows (a Recipe's recipeYield, totalTime or cookTime, nutrition…). Advice only: never fails a strict build
check_redirects empty --check-redirects[=warn|strict] Report links the host would redirect (needs pretty_urls)
check_admin_theme warn config only Report problems with admin_theme: a logo or font file not in the build output, a tokens: override that breaks a contrast or distinctness pair, admin_theme without a core worker. off, warn or strict. Invalid values are configuration errors regardless — see the admin panels' look
check_modules warn config only Report problems with module manifests and modules: entries: an invalid or newer-contract module.json, duplicate ids, two modules on one panel path or nested base paths, an id that disagrees with its manifest, modules: without a core worker. off, warn or strict. Silent on a site with neither a core worker nor modules: — see the module registry
check_api "" config only Report documentation problems in api_docs entries: undocumented exports, dead {@link}s, unreadable code, broken OpenAPI $refs and operations. warn or strict
pretty_urls false config only The host strips .html and appends trailing slashes
meta_limits see below — Advisory title/description length ranges for check_meta
sitemap_prune_canonical false — Also drop non-self-canonical pages from sitemap.xml
content_exclude empty — Globs for Markdown under content_dir that is not a page
content_schemas empty — Per-type frontmatter contracts, validated at build
strict false --strict Escalate schema violations, link checks and unparseable frontmatter to build failures
route_manifest false --route-manifest Write routes.json — every route and its metadata
build_report `` --build-report[=FILE] Write a JSON report of the build into the output directory: version, duration, pages and files written, content by type. A bare flag writes build.json; so does build_report: true (false writes none)
profile `` --profile[=json] Report where the build's time went, with peak RSS and GC cycles; json also writes build-profile.json
profile_pprof `` --profile-pprof=DIR Also write cpu.prof and heap.prof for go tool pprof
lastmod_from_git false --lastmod-from-git Use Git commit dates in sitemap. Needs git on PATH; the snap cannot see it (see CONTENT)

SEO injection is non-destructive, and it is not all-or-nothing. It looks at what the page already rendered and fills only the gaps:

The theme emitted SSG injects
neither Open Graph, Twitter and JSON-LD
og:title, no application/ld+json JSON-LD only
application/ld+json, no og:title Open Graph and Twitter only (1.8.77, #349)
both nothing but the breadcrumb and FAQ (below)

The two are decided apart. Until 1.8.77 a theme with its own JSON-LD but no og:title got ssg's JSON-LD beside its own, so a page could describe itself twice, as two different types.

A theme's own JSON-LD replaces ssg's description of what the page is. The BreadcrumbList (where the page sits) and the FAQPage from faq: do not compete with that, so they are still added beside the theme's block unless it already has one of that type (1.8.78, #351). A theme that writes the trail itself has it as data: {{ toJSON .BreadcrumbSchema }}.

Every image URL ssg writes into og:image, twitter:image and the JSON-LD image is absolute against domain, as Open Graph requires: a featured_image: /media/hero.jpg or og_image: /card.png becomes https://example.com/… (1.8.77, #350). Social networks fetch the image without resolving it against the page.

The middle row is the useful one: a theme can own its Open Graph tags — to control og:image, say — and still get structured data generated from frontmatter, with no need to hand-write JSON-LD. It also fills in a missing meta description from the frontmatter description:.

seo_off: true and --seo-off are deprecated: SEO is off unless you turn it on, so their only effect is to force it off over seo: true. Plain --check-links selects warning mode; strict mode fails the build.

Invisible characters

Content arrives from a CMS export, a word processor, a chat window or a clipboard, and it carries characters that render as nothing and break things:

Character What it does to a published page
Zero-width space, joiner, word joiner Splits a word for Ctrl+F, for the site's own search index and for a screen reader. A visitor searching for a word plainly on the page finds nothing
Bidi overrides and isolates Text renders in a different order than it is stored — a link's visible text can disagree with where it goes
Unicode tag characters Invisible everywhere, and a way to carry text only a machine reads
Soft hyphen mid-word Breaks copy-paste and search for a hyphen nothing asked for
Exotic-width spaces Break line wrapping and make copied text fail to match its source

None of it is authored on purpose; all of it survives a migration. sanitize_output removes it and reports what it took:

   🧹 Removed 412 invisible character(s) in 37 page(s)
      zero-width space 380 · bidi override 24 · tag characters 8

On by default, because the failure is invisible in every sense: nothing renders, nothing warns, and the symptom — a search box that cannot find its own words — is never traced back to the cause. warn reports without changing anything; off does neither.

What it never touches, because a page documenting these characters is exactly the one a careless pass would ruin:

  • anything inside <pre>, <code>, <script>, <style> or <textarea>;
  • a leading byte order mark, which is a BOM rather than residue;
  • a single non-breaking space — that is typography between a number and its unit. Only a run of them is a word processor holding a line together.

One thing it cannot do, stated rather than implied: an author who writes &#8203; cannot be told apart from residue, because the Markdown renderer decodes the entity into the raw character long before this runs. A code span is how to publish one on purpose.

Image formats

webp: true publishes WebP. image_formats says which formats a site wants and in what order:

1webp: true
2image_formats: [avif, webp]
3avif_quality: 45
4image_sizes: [480, 960, 1600]

Each image gets a derivative per format at every configured width, and the <img> the WebP pass produced is wrapped so the browser picks the first format it understands:

1<picture>
2  <source type="image/avif" srcset="/img/hero-480.avif 480w, /img/hero-960.avif 960w" sizes="100vw" src="/img/hero.avif">
3  <img src="/img/hero.webp" srcset="/img/hero-480.webp 480w, ..." alt="Hero">
4</picture>

The <img> is never modified — it stays exactly as it was, so a browser that understands neither source still gets the image it always got.

Why it is worth the extra pass. AVIF is roughly half of WebP on photographs. One migrated hero image, same picture, same visual result:

bytes vs JPEG
JPEG, as it came from the camera 570,935 —
WebP 278,516 -51%
AVIF 95,619 -83%

Old WordPress sites gain most, because their media is JPEG straight from a phone. Across a shop with a thousand product photographs it is the difference between a site somebody browses and one they leave.

The encoders are optional. AVIF needs avifenc:

1apt install libavif-bin      # Debian/Ubuntu
2apk add libavif-apps         # Alpine
3brew install libavif         # macOS

A format whose encoder is not installed is skipped with a warning and the build carries on — the site still publishes its WebP and its originals:

warning: image_formats lists avif but avifenc is not installed - skipping it.

That rule matters more than it looks: a build that failed here would make the format unusable on exactly the machines least likely to have the tool.

avif_quality is lower than webp_quality by default because AVIF holds detail at settings where WebP starts to soften; 45 is a good starting point for photographs, and raising it toward 60 is the first thing to try if a particular image looks flat.

Image metadata

A photo straight from a camera or a phone carries GPS coordinates, the camera's serial number and often the owner's name. A migration copies a whole media library across, so a site can publish an author's home address without anyone choosing to.

Generated derivatives never carried it — the encoders write only pixels — but originals are published byte for byte. image_metadata: strip (the default) removes EXIF, IPTC, XMP and editor comments from published JPEGs:

   🧼 Removed EXIF/IPTC metadata from 84 published image(s)

The colour profile and the JFIF density are kept: dropping the first shifts every colour on the page, and orientation is normalised into the pixels before the tag goes, so photos do not rotate. A file that cannot be parsed is published exactly as it arrived — a corrupted image is worse than one carrying a location.

image_metadata: keep for a photography portfolio that shows camera settings on purpose.

Custom post type archives

A migration brings a WordPress custom post type across as a folder of documents, each at the address the source served. What it cannot bring across is the type's archive: /realizacje/ is not a document anywhere — it is a listing WordPress renders from has_archive. So the entries build, the site's own menu links to the section, and the section is a 404.

type_archives says which types deserve one:

1type_archives:
2  realizacje: true
3  reviews: false

It cannot be inferred from the content, and that is not caution — a site can register one type whose section exists and another whose section 404s on the source as well. Building an index for every folder would publish pages the original never had.

An export that records has_archive answers for itself — wpexporter 1.8.15+ writes both fields, so a migrated project needs no configuration at all. When content/<source>/metadata.json carries

1{"custom_types": [
2  {"slug": "realizacje", "name": "Realizacje", "has_archive": true},
3  {"slug": "reviews",    "name": "Reviews",    "has_archive": false}
4]}

the archive is built with no configuration at all, and a type marked "has_archive": false is skipped. A false in type_archives overrules the export — the operator has looked at the source and the export has not.

archive_link moves the listing when the source did not serve it at the type's own slug. WordPress lets has_archive be a slug, so a type called realizacje can publish its archive at /nasze-prace/:

1{"slug": "realizacje", "has_archive": true, "archive_link": "/nasze-prace/"}

.ContentType stays the type either way, so a theme styles the section by what it is rather than by where it lives.

The listing is rendered by category.html, with the same context every other archive gets plus two fields of its own:

Field Value
.Kind "type"
.ContentType the type slug, so a theme can style one section differently from another
.Name the type's name from the export, or its slug made readable
.Posts, .Pager as on a category archive — paginate applies, giving /realizacje/page/2/

Real content wins: a hand-written page that already owns /realizacje/ keeps it and the build says so. Nothing is built for a declared type with no entries.

Validating structured data

check_schema reads the JSON-LD each page actually emits and reports required properties that are missing:

⚠️  structured data in recipes/pierogi.html → Recipe is missing image, recipeIngredient
⚠️  structured data in shop/laptop.html → Offer is missing priceCurrency

Search engines reject incomplete structured data and say nothing the author can see: the build succeeds, the page ships, the rich result never appears, and the feedback arrives weeks later in Search Console. Nested objects are checked too — an Offer missing priceCurrency invalidates the Product containing it.

Types checked: Recipe, Product, Offer, Event, JobPosting, LocalBusiness, HowTo, VideoObject, Article, BlogPosting, NewsArticle, FAQPage. An unrecognised @type passes silently — that is deliberate: schema.org has hundreds of types, and warning about the ones SSG does not know would take away the generality schema: exists for. A block that is not valid JSON is always reported, since a crawler cannot read it either and nothing in the rendered page shows it.

Only the required properties are checked, not the recommended ones. Warning about every optional field would train people to ignore the warning.

A type a section promised but never emitted

Missing entirely is a louder failure than present-but-incomplete, and it used to be the one nothing reported. When schema_defaults declares an @type for a section, every page in that section must carry it — and if none of the page's JSON-LD does, the build says so:

⚠️  structured data in recipes/soup/index.html → schema_defaults promises @type "Recipe"
    and no JSON-LD on the page carries it — the theme emits 1 block(s) of its own, which
    turns auto-injection off for this page (emit the derived data yourself with
    {{ toJSON .Schema }}, or move the hand-written block into an @graph)

The usual cause is the SEO injection rule above: a theme that emits any application/ld+json block of its own opts the whole page out of auto-injection. So a theme with a hand-written FAQPage partial silently takes the section's Recipe down with it — the page ships with complete FAQPage markup, the check reports every required property present, and the Recipe rich result never appears.

Two ways to have both, and the check accepts either:

1<!-- 1. emit the derived data beside your own block -->
2<script type="application/ld+json">{{ toJSON .Schema }}</script>
3<script type="application/ld+json">{"@context":"https://schema.org","@type":"FAQPage", …}</script>
1<!-- 2. or put both in one @graph -->
2<script type="application/ld+json">
3{"@context":"https://schema.org","@graph":[{{ toJSON .Schema }}, {"@type":"FAQPage", …}]}
4</script>

.Schema is the structured data SSG would have injected, already merged in precedence order — see Template helpers. Sibling blocks are what Google's own guidance asks for when a Recipe and an FAQPage describe the same page, so the first form is usually the right one.

A section whose @type is a list (["Recipe", "Product"]) promises nothing specific and is not checked: which of them a given page must carry is the author's business, and guessing would produce a warning nobody could act on.

Structured data per section

schema: in frontmatter is arbitrary JSON-LD, so any schema.org type works without SSG knowing it — Recipe, Product, Event, Car, nested objects and all:

1schema:
2  "@type": Recipe
3  cookTime: PT20M
4  recipeIngredient: ["500 g flour", "400 g potatoes"]
5  nutrition: { "@type": NutritionInformation, calories: "320 kcal" }

What site-wide schema: cannot carry is @type: it applies to every page, so setting SoftwareApplication for the home page would stop each post being a BlogPosting. schema_defaults fills that gap — defaults keyed by section:

 1schema:
 2  publisher: { "@type": Organization, name: Food }
 3
 4schema_defaults:
 5  home:
 6    "@type": WebSite
 7    name: "Food — recipes and notes"
 8  pages/recipes:
 9    "@type": Recipe
10    recipeCuisine: Polish

Keys match the page's directory relative to the source folder, by prefix, longest match first — the same rule link_rewrites uses. home is reserved for the site root, the only page that can hold a site-level type without claiming it for everything else.

Precedence, lowest to highest:

schema:  <  derived (BlogPosting/WebPage/WebSite)  <  schema_defaults  <  page frontmatter

Section defaults sit above the derived data deliberately — overriding the derived @type is what they exist for — while a page's own schema: still wins over its section.

Recipes

A page whose structured data is a Recipe gets recipeCategory from its own categories: one category as a string, several as a list. It is filled only when nothing above set one, so a section default (recipeCategory: Desserts) or the page's own schema: still wins. Together with what every post already gets (name, image, author, the dates, and keywords from tags), a recipe post needs only its ingredients, method, times and yield in schema::

1schema:
2  recipeYield: "16 servings"
3  cookTime: PT1H
4  recipeIngredient: ["5 large eggs", "200 g sugar"]
5  recipeInstructions: ["Set the oven to 160°C.", "Whisk the eggs with the sugar."]

When a Recipe's schema: has no recipeIngredient or recipeInstructions, ssg reads them from the post itself: the list under a heading named "Ingredients" (or "Składniki", "Zutaten", "Ingrédients", "Ingredientes", "Ingredienti") and the steps under "Method" (or "Instructions", "Directions", "Preparation", "Steps", "Przygotowanie", "Sposób przygotowania", "Zubereitung"…). A heading may also be a paragraph in bold (<strong>Ingredients</strong>), and may go on ("Ingredients for 16 servings"). Steps are the list items. Without a list, each paragraph is a step, and bold sub-headings such as <strong>Step 2</strong> separate them. The page's own field wins over the one read from its body, field by field. Add a site's own heading names with:

1recipe_headings:
2  ingredients: ["What you need"]
3  instructions: ["How to make it"]

check_schema reports a Recipe without image, recipeIngredient or recipeInstructions. With check_schema_recommended: true it also lists, as advice, the properties a recipe card shows when they are there: description, nutrition, recipeCategory, recipeCuisine, recipeYield, and totalTime or cookTime.

Key Type Default Description
print.enabled bool false Print / PDF button plus print stylesheet
print.label string "Print / PDF" Button text
print.sections list [posts] posts, pages, or both
print.auto bool true Place after the first </h1> when the theme has no data-ssg-print-slot
print.labels map — recipe, ingredients, steps, yield, prep, cook, total, printed
cook_mode bool or map false true is shorthand for {enabled: true}
cook_mode.enabled bool false Cook Mode on Recipe pages with ingredients and instructions
cook_mode.label string "Cook mode" Button text
cook_mode.auto bool true Place after the first </h1> when the theme has no data-ssg-cook-slot
cook_mode.labels map — title, ingredients, step ("Step {n} of {total}"), next, back, close, restart, done, finished

See PRINT_AND_COOK_MODE.

Web Stories

Google Web Stories (AMP) made from posts. See WEB_STORIES.

Key Default Description
web_stories.enabled false Make a story from each selected post with a featured image. web_stories: true is shorthand.
web_stories.publisher_logo — Square image, at least 96×96, found like imageResize sources: inside assets/, the static dir, the content source or the theme, or from the project root (assets/logo.png). Required: without it no story is made (the warning lists where it looked).
web_stories.sections [posts] posts, pages, or a content directory (posts/recipes).
web_stories.url /web-stories/ The hub; stories live at <url><slug>/.
web_stories.pages 4 Most photo pages between the cover and the last page.
web_stories.min_images 2 Distinct images (featured included) a post needs.
web_stories.cta Read the full article Last page's link text (overrides the i18n catalog).
web_stories.background_audio — The stories' soundtrack, a site path or URL. A post's story_audio: overrides it (false: silent) (1.9.5).
web_stories.narration false Record each page's text through tts:; pages advance with it (1.9.4).

Images are WebP when webp: true or image_formats includes webp, JPEG otherwise.

Story mode

A reading companion and fullscreen presentation on articles, with narrator, music, share and deep links, feeding the same slides to the Web Story (1.9.4). See STORY.

Key Default Description
story.enabled false story: true turns it on; a mapping turns it on unless it says enabled: false.
story.sections [posts] posts, pages, or a content directory (posts/recipes).
story.rules — {when: {category, tags, section, contains}, set: {…}}: settings for the pages a rule matches.
story.* — Every other key goes to the page script: progress, stage, slides, widgets, audio, narrator, slideshow, share, analytics, labels, theme… snake_case or camelCase.

A post adds its own settings in story: front matter or in <name>.story.yaml beside its source; story: false keeps it out.

A résumé

resume: publishes a CV from a Schema Resume JSON document as a page, with ProfilePage structured data and the document at <url>resume.json. See RESUME.

Key Default Description
resume.file — Path to the Schema Resume JSON document; empty turns the feature off
resume.url /cv/ URL of the page (always a directory)
resume.title basics.name Page title
resume.contact false Publish e-mail, phone and street address in the page, JSON-LD and resume.json
1resume:
2  file: cv.json
3  url: /cv/
4  contact: false

Questions and answers

A page that lists questions in front matter gets an FAQPage block beside its main structured data:

1faq:
2  - question: Can I freeze the cheesecake?
3    answer: Yes, wrapped, for up to a month. Thaw it in the fridge.

Answers are Markdown, published as plain text. A theme renders the list itself from .faq.

Listings, authors and the site

With seo: true, the pages ssg generates carry structured data too:

Page Blocks
The post listing and every archive (category, tag, date, custom taxonomy) ItemList of the posts on that page, in order
An author archive ProfilePage with the author as Person, plus the ItemList
The site's front listing also an Organization: marketing.og_site_name (else the title), marketing.logo, and marketing.social_profiles as sameAs

The blocks are injected only where the theme wrote no JSON-LD of its own, as for every page. A theme that writes its own gets them as .StructuredData and can add them: {{ range .StructuredData }}<script type="application/ld+json">{{ toJSON . }}</script>{{ end }}.

Content contracts (schemas, strict mode, route manifest)

content_schemas declares what a page of each type must look like, so a missing author or a malformed date fails at build time — with a precise message (file, field, reason) — instead of silently shipping a broken page. Each schema lists required fields and per-field type/format/enum rules:

1content_schemas:
2  post:
3    required: [title, date, author]
4    fields:
5      title:  { type: string }
6      date:   { type: date }
7      status: { type: enum, values: [publish, draft] }
8      featured_image: { type: url }
9      weight: { type: int }

Field types are string, int, bool, date, url, list and enum (with values). Well-known frontmatter fields (title, date, author, tags, …) resolve automatically; any other name is read from the page's custom frontmatter.

Violations warn by default so a site can adopt schemas incrementally. Turn on strict (or --strict) to make them — and internal link checking — hard build failures: a renamed slug that orphans a link, a post missing a required field, or a Markdown file whose frontmatter is not valid YAML then fails the build instead of shipping. strict enables link checking even when check_links is unset.

Validating the built output

Three checks run over the generated HTML, in the same shape as check_links: empty (off), warn, or strict (a finding fails the build). strict: true escalates any enabled check. A fourth, check_markup, reads the source instead — see below.

check_images reports images with no alt attribute at all. It never generates alt text — an invented description reads as authoritative while being wrong, which is worse for a screen-reader user than silence. alt="" is the correct treatment for a decorative image (a logo next to the site name that would otherwise be announced twice) and stays silent; strict-decorative opts into reviewing those too.

state verdict
no alt attribute reported — the author has to decide
alt="" valid (decorative), silent unless strict-decorative
alt="…" valid

check_meta requires a non-empty <title> and meta description on every indexable page. noindex pages are skipped: a 404 page legitimately has neither. This catches a failure that is otherwise invisible — a theme interpolating a field that happens to always be empty emits a blank tag on every page, forever, and the generator has no reason to complain because it did exactly what the template asked.

Lengths are reported as advisory notes, never as build failures, and the ranges are yours to set. A headline that reads well at 62 characters beats one mangled to fit, and a check that blocked the build on it would simply get switched off.

1check_meta: warn
2meta_limits:
3  title_min: 30          # unset ⇒ default; explicit 0 disables the bound
4  title_max: 60
5  description_min: 70
6  description_max: 160

check_orphans reports indexable pages that nothing links to. Only <a href> counts: every page links to itself through <link rel="canonical">, so counting all references would make nothing an orphan and the check would pass on a site full of them. Self-links, noindex pages and the site root are ignored.

check_markup reports source Markdown whose markup is indented four columns or more, which CommonMark renders as a literal code block. It is the one check that is on by default (warn), because it does not weigh a judgement call the way the others do: the page provably does not render as written, and the build otherwise says nothing. It is silent when there is nothing to report.

This is what a page-builder export leaves behind — Elementor indents its nested <div>s with tabs, the exporter turns </p> into a blank line, the blank line ends the HTML block, and every following line is four columns deep. The visitor reads </div> in monospace down the middle of the page.

1check_markup: warn      # default; "strict" fails the build, "" or "off" disables

Fix the content in place with ssg repair --fix (dry run without --fix, which exits 1 on findings so CI can gate on it). Front matter, fenced code blocks and list continuations are never touched. Re-exporting with wpexporter 1.8.2+ produces clean sources in the first place.

seo: true also fills in a missing meta description from the front-matter description:. Nothing is invented — the author already wrote it, it just never reached the output. An existing but empty tag is rewritten in place rather than joined by a second one.

check_links resolves a URL against the output directory. That is not how a host answers it, so a link can pass and still cost every visitor a redirect. Most static hosts serve pretty URLs: they strip a .html extension and append a trailing slash, answering the un-normalised form with a 308.

1pretty_urls: true       # describe how the host serves URLs
2check_redirects: warn   # "" | warn | strict

pretty_urls makes link checking agree with the host in both directions:

  • check_links stops reporting /docs/swagger as broken when the output holds docs/swagger.html and the host serves it — without this the checker pushes you to restructure a page into a directory to satisfy the tool rather than the site.
  • check_redirects reports the reverse: links that resolve only through a redirect, naming the destination so the fix is obvious.
⚠️  redirected link in index.html → /docs/swagger.html  →  /docs/swagger/
⚠️  redirected link in index.html → /docs/intro  →  /docs/intro/

Nothing here is broken, which is why check_links passes it — but each one is a round trip per visitor and a hop of crawl budget per crawler, and it multiplies: a single .html link in a shared footer puts every page on the site through a redirect. It is invisible locally, because local resolution is not what the host does.

Leave pretty_urls off for a plain object store, which rewrites nothing. There /docs/swagger is a genuine 404 rather than a redirect, and check_redirects skips with a message rather than reporting shapes the host never rewrites.

Keeping the sitemap honest

sitemap.xml never lists a page whose rendered HTML says noindex: asking a crawler to index a URL the page itself declines is reported as an error by search consoles. This needs no configuration — the sitemap is written after rendering, so the answer is already on disk, wherever the noindex came from.

Pages whose canonical points at a different URL are a separate case, and are kept by default. A canonical that disagrees with the permalink is far more often a theme bug than a deliberate exclusion, and quietly removing real pages from the sitemap over one would be worse than the contradiction it fixes. Opt in with sitemap_prune_canonical: true.

The site's social card (marketing)

og:image decides whether a link to the site posts as a card with a picture or as a bare line of text. A theme that asks for twitter:card: summary_large_image and names no image gets the bare line — the format is defined by having a picture.

The generator has always had a site-wide fallback for pages with no featured_image, but it was reachable only through the metadata.json an ssg migrate crawl writes, so a site built from scratch could not declare one. It is configuration now:

1marketing:
2  og_image: "/img/card.png"      # 1200×630; a site-relative path is written absolute
3  og_site_name: "SSG"
4  twitter_site: "@example"
5  theme_color: "#0f172a"
6  favicon: "/favicon.ico"

Values here win field by field over anything a migration recorded, the same precedence title and description follow — and maps (verification, social_profiles, colors) merge per key, so adding one token does not drop the three an export found.

The bundled ssgtheme uses the page's own featured_image when it has one and this default otherwise, and drops twitter:card to summary when there is no image at all, so the tag describes what is actually there.

A card for every page (og_cards)

One site-wide picture makes every shared link look the same. og_cards draws a card for each page that has no featured_image of its own. It is off unless the site asks for it, and the site has to say how its cards look: there are no default colours, because a card is the site's own look. Each card shows the page's title, its category above it and the site's name below, 1200×630, drawn at build time. It is done in Go, so there is no browser, no external tool and no service to run. Shared links show the card on Facebook, LinkedIn, X, Slack, Discord, Telegram, WhatsApp and iMessage.

 1og_cards:
 2  text_color: "#FFFFFF"   # required
 3  background: "#202124"   # required, unless background_image is set
 4  accent_color: "#8AB4F8" # the bar on the left and the category line; default text_color
 5  dir: og                 # output directory → /og/<page>-<key>.png
 6  sections: [posts, pages]
 7  width: 1200
 8  height: 630
 9  background_image: assets/card-bg.jpg   # may replace `background`; cropped to fill
10  overlay: 0.6            # 0..1: how strongly `background` covers the image
11  logo: static/logo.png   # optional; bottom-right, up to 72 px tall
12  font: assets/Inter-Bold.ttf            # optional TTF/OTF; default Go Bold
13  format: png             # or jpeg
14  quality: 85             # jpeg only
Key Default Notes
dir og Under the output directory
sections posts, pages Which pages get a card
width, height 1200, 630 The text scales with the height
text_color required #rgb or #rrggbb
background required without background_image #rgb or #rrggbb; with an image, the colour of the overlay (black if not set)
accent_color text_color Bar on the left and the category line
background_image none PNG or JPEG, path from the project root
overlay 0.6 0 shows the image untouched
logo none PNG or JPEG
font Go Bold Covers Latin (with Polish, Czech, …), Greek and Cyrillic. For CJK, Arabic or Hebrew, name a font that has the glyphs
format png jpeg is smaller when background_image is a photo
quality 85 JPEG quality

What a card shows. The title is set as large as the space allows, from 76 px down to 40 px, and wrapped at spaces. A title still too long at 40 px ends in an ellipsis. The line above the title is the page's category, or the name of its first category. The footer is the site's title, else marketing.og_site_name, else the domain.

Precedence. A page's featured_image always wins. The card comes next, and marketing.og_image is the fallback for pages without either (a section left out of sections, listings). With SEO injection on (seo: true), the generator writes og:image, twitter:image, og:image:width/height and the JSON-LD image. A theme that writes its own tags reads the card's URL as .Page.OGCard / .Post.OGCard (see TEMPLATES). The bundled ssgtheme already does.

Required values. og_cards: true on its own, or a mapping without text_color, or without both background and background_image, stops the build with a message naming the key to add. Nothing is drawn with colours the site did not choose.

Colours and contrast. If the colours fall under 4.5:1 (WCAG 2.2 AA), the build says so. The check is skipped over a background_image, where the photo decides. It does not stop the build. For example, Google Grey 900 #202124 with white text (16:1) and a Blue 200 #8AB4F8 accent (7.6:1) passes.

Format. The platforms do not render SVG previews, and LinkedIn and WhatsApp are unreliable with WebP. So the cards are PNG or JPEG, and the webp/avif passes leave the card directory alone.

Rebuilds. The file name carries a key built from the layout (colours, the bytes of the font, logo and background) and the page's words. The platforms cache og:image by URL for weeks, so a changed title gets a new URL and is fetched again. An unchanged card already in the output is not touched. A clean output copies cards from .ssg-cache/ogcards/ instead of drawing them again.

An empty canonical is always reported

Separate from the sitemap, and needing no configuration: every build says so when a page ships <link rel="canonical" href=""/>, or an empty og:url or twitter:url.

1   ⚠️  10 page(s) name their own URL with an empty value
2      category/air-conditioning/index.html → <link rel="canonical">, og:url

The cause is always a template naming a value its context does not carry: Go templates resolve a missing key to nothing and render empty rather than failing, so one typo in one theme file ships an empty canonical on every page it renders, with a green build and a clean check_links. There is no site for which the empty value is correct, which is why this needs no mode — unlike a canonical that merely disagrees with the permalink, which needs judgement and stays behind sitemap_prune_canonical.

It is a warning, never a failure: the site is publishable, and a build that refused to finish over a theme bug would be worked around rather than fixed.

Splitting the sitemap (sitemaps, sitemap_max_urls)

One sitemap.xml holding everything is right for almost every site, and stays the default: nothing below changes a build that does not ask for it.

Two things eventually ask. sitemaps.org caps one file at 50,000 URLs (and 50 MB uncompressed), above which a <sitemapindex> is required — and Search Console reports indexing coverage per submitted sitemap, so "how much of the blog is indexed" is a question only a separate file can answer.

Size is handled without configuration. A set over either ceiling — 50,000 URLs or 50 MB (52,428,800 bytes) rendered — is split into sitemap-1.xml, sitemap-2.xml… and sitemap.xml becomes the index naming them. More files than one index may name (50,000) fails the build. sitemap_max_urls lowers the ceiling (never raises it — a larger file is invalid whatever the config says), which is useful for testing the shape on a small site.

Structure is declared, in the shape feeds: already uses:

1sitemaps:
2  - path: /sitemap-blog.xml
3    source: blog                        # a content folder, MDDB section or external source
4
5  - path: /sitemap-archives.xml
6    include: [categories, tags, authors]

Three narrowings, all optional:

Key Selects
source Documents from a content folder (that folder and everything beneath it), an MDDB section, or an external_sources entry by name (1.9.0)
include Kinds of URL: home, listing, pages, posts, static, categories, tags, series, authors, taxonomies
prefix URL path prefix, or a list of them (1.9.0). Compared after base_path and after any language prefix, whole segments only: /net/ does not claim /netbsd/x/. Works for every kind

An unknown include: kind, and a source: that is neither a content folder nor an external_sources entry, fail the build rather than writing an empty file. Narrowings combine with AND, and a spec with none of them claims everything still unclaimed — which is how a catch-all is written.

A generated site, split per section. Pages built from external_sources in mode: content used to be one block of pages, so a site made almost entirely of them had nothing to split on. Each such page now carries its source's name, and prefix: splits within a source:

 1sitemaps:
 2  - path: /sitemap-compare.xml
 3    source: compare              # an external_sources entry
 4  - path: /sitemap-openbsd.xml
 5    prefix: /openbsd/
 6  - path: /sitemap-netbsd.xml
 7    prefix: [/netbsd/, /pkgsrc/]
 8  - path: /sitemap-people.xml
 9    include: [taxonomies]
10  - path: /sitemap-freebsd.xml
11    source: ports                # what is left of ports after the prefixes above
12  # everything else -> sitemap-main.xml

A declared file over 50,000 URLs or 50 MB is still split (sitemap-freebsd-1.xml, …) and indexed.

Selection is a partition, not a set of views: a URL lands in the first spec that matches it, so order matters like a routing table, and no URL is listed twice. Whatever matches nothing goes to sitemap-main.xml, which is always written and always in the index — nothing is silently dropped by a sitemaps: block that does not cover the whole site. A spec that selects nothing is reported and its file is skipped, since an index entry pointing at an empty urlset is a fetch that teaches a crawler nothing.

What the sitemap promises

What Google's Build and submit a sitemap asks, and what a build checks in its tests:

  • UTF-8 XML, every <loc> an absolute URL, entity-escaped (& → &amp;), anything outside ASCII percent-encoded (/usługi/ → /us%C5%82ugi/).
  • Canonical URLs only: a page that says noindex, a redirect, sitemap: no and the error page stay out; sitemap_prune_canonical also drops pages whose canonical points elsewhere.
  • <lastmod> only where it is known. A document's is its modified (falling back to date), or its last commit under lastmod_from_git. A page that lists others — the front page, a post listing, category, tag, series and author archives, taxonomy indexes and terms — takes the newest lastmod of what it lists (#339); one listing nothing dated has none. An index entry carries the newest date of its file, never the build time.
  • <changefreq> and <priority> are written for other crawlers; Google ignores them.

A document with neither date nor modified in its frontmatter has no <lastmod> (1.8.74), as in Hugo and jekyll-sitemap. It still sorts and shows by its file's modification time, but that time is accurate only on the machine that wrote the file — a fresh clone dates every file to the clone — and Google trusts a sitemap's dates only while they are consistently accurate. Give such documents a date, or turn on lastmod_from_git with enough history to date each file. Feeds keep the fallback, because Atom requires <updated>.

robots.txt is unchanged either way: it points at /sitemap.xml, which is now the index. That is exactly what the protocol expects, so a site already submitted to Search Console needs no resubmission.

What the sitemap lists

Everything the build rendered and nothing it did not: the front page, pages, posts, the post listing (/blog/ under posts_page — the hub every post links back to, and the site root otherwise, where the front-page entry already names it), and the category, tag, author and custom-taxonomy archives that were actually written.

Only the first page of a listing or archive is named; a paginated tail is left out on purpose. Category archives are read from what the build wrote, so a term with no posts is not advertised and a term served away from /category/ by its own link: is named where it really lives. The exporter's catch-all term — Uncategorized, Bez kategorii and their translations — is left out, recognised by its slug or name; before 1.8.56 that rule was "category id 1", which silently dropped a real archive on every export numbering its categories from 1.

Excluding Markdown that is not a page

content_dir is scanned recursively and every .md becomes a page. A file that is data — a sample documenting another tool's front-matter format, say — may be perfectly valid for its own purpose and unparseable as a page, and status: draft cannot help because the failure happens while unmarshalling, before any status field is read.

1content_exclude:
2  - "docs/examples/<strong>"    # </strong> crosses directory separators
3  - "sample-*.md"         # bare filenames work too

Patterns are matched before parsing, against the full path, the content-relative path and the filename, so each form behaves the way it reads. Excluded files are also left out of the "Markdown file(s) in the source tree were not read" warning, since leaving them out was the point.

build_report: build.json (or --build-report) writes, once the last page is out and before the post_build hooks, a small report a site can publish (#338):

 1{
 2  "generator": "ssg",
 3  "version": "1.8.74",
 4  "buildTime": "2026-10-21T17:41:56Z",
 5  "started": "2026-10-21T17:41:56Z",
 6  "finished": "2026-10-21T17:42:32Z",
 7  "durationSeconds": 36.2,
 8  "pages": 38037,
 9  "files": 38211,
10  "content": {"page": 4, "port": 35270, "post": 0}
11}

pages counts the .html files in the output, files every file but the report; content counts the loaded documents by type. buildTime is .BuildTime (so SOURCE_DATE_EPOCH pins it), started and finished are the clock. The report is published with the site, which is the point: a footer script can show "38,037 pages in 36.2 s" without shell around the build. For why a build is slow, use --profile=json, which writes the time of every phase and page to build-profile.json beside the project, not into the site.

route_manifest (or --route-manifest) writes routes.json to the output root: a sorted, deduplicated list of every generated route — posts, pages, and category / tag / series / author / custom-taxonomy archives — each with its type, title, source file and language. It is a machine-readable contract external tooling (or generated typed clients) can diff to catch a route that moved.

A page's featured_image becomes the og:image, twitter:image (a summary_large_image card) and the JSON-LD image, so one frontmatter field drives every social preview. With webp on, all three follow the conversion to .webp exactly like in-content images — no separate social-image setting to keep in sync.

AI-first JSON-LD structured data

With seo on, every page also gets <script type="application/ld+json"> Linked Data in its <head>, derived from existing frontmatter with zero extra configuration — so AI agents and answer engines read structured, machine- readable data without executing JavaScript. Content types map to Schema.org:

Page @type Derived from
Blog post BlogPosting title, description, date/modified, author, tags → keywords, featured_image
Home page WebSite title, description
Any other page WebPage title, description

Every non-home page additionally gets a BreadcrumbList built from its URL path, placing it in the site hierarchy. A step names a document the build writes — a page, a post listing, a taxonomy, type or date archive — with that document's title; a URL segment with nothing behind it is left out and the positions are numbered after the gap (#335). Under i18n the trail starts at the language's own home. The error page (slug 404) has none.

breadcrumbs: names the steps, or turns them off for a theme that writes its own:

1breadcrumbs:
2  home: "Strona główna"            # the first step; default "Home"
3  sections:                        # a URL segment → its step
4    posts:  {name: "Baza wiedzy", url: /baza-wiedzy/}   # always shown, pointing at url
5    uslugi: {name: "Usługi"}       # renames the step; shown only if /uslugi/ exists
6# breadcrumbs: false               # emit no BreadcrumbList
Key Type Default Meaning
breadcrumbs bool or map on false emits no BreadcrumbList
breadcrumbs.home string "Home" First step's label
breadcrumbs.sections.<segment>.name string the page's title Label of that segment's step
breadcrumbs.sections.<segment>.url string the segment's path Where the step points; with a URL the step is always shown

Overrides. Two knobs extend or replace the generated data, deep-merged in order (most specific wins): site-wide schema: in the config, then per-page schema: in frontmatter. Use the site-wide default for a publisher/Organization that belongs on every page, and the per-page one to correct a @type or add fields a single page needs:

1# .ssg.yaml — appears on every page
2schema:
3  publisher:
4    "@type": Organization
5    name: Acme Inc.
6    logo: https://example.com/logo.png
1# frontmatter — this page only
2schema:
3  "@type": TechArticle
4  proficiencyLevel: Expert

The generated JSON-LD is valid Schema.org and passes Google's Rich Results Test. </script> in any field is escaped, so untrusted titles cannot break out of the block.

Data and variables

Files below data_dir with .yaml, .yml or .json extensions are loaded by path into .Data:

1data/authors/ada.yaml → .Data.authors.ada

Custom variables are exposed as .Vars and exported to hooks as SSG_*:

1variables:
2  analytics_id: $ANALYTICS_ID
3  api:
4    endpoint: https://api.example.com

Values beginning with $ resolve from the current process environment. Nested keys are flattened for environment names, for example SSG_API_ENDPOINT. Do not commit secrets to configuration files.

Variables the bundled theme reads

ssgtheme is generic: each block below renders only when its variable is set, so nothing here is required. They are the supported integration points, and are listed because they were previously discoverable only by reading the theme.

Variable Renders
gtag Google Analytics 4 (gtag.js) with Consent Mode v2 defaulting every storage type to denied
gtm_id Google Tag Manager. When cookie_consent is also set the loader ships as type="text/plain" data-consent-category="analytics", so the consent worker starts it only after the visitor accepts — the container request is itself a third-party call, so a site running a banner should not make it first
cookie_consent The cookie banner. The value is serialised to the worker's client config; see the worker's README for the keys
marquee A horizontal "works with" strip: {title, items: [{name, url, icon}]}, where icon is SVG path data on a 24×24 viewBox
repository_url The "source" link in the hero
1variables:
2  gtag: G-XXXXXXXXXX
3  gtm_id: GTM-XXXXXXX
4  cookie_consent:
5    policyUrl: /cookie-policy/
6    categories:
7      - { id: necessary, required: true }
8      - { id: analytics }

Internationalisation and timezones

1languages: [pl, en]
2default_language: pl
3timezone: Europe/Warsaw
4language_timezones:
5  en: America/New_York
6  pl: Europe/Warsaw
Key Default CLI Purpose
languages empty --languages=pl,en Enable multilingual output
default_language empty --default-language Language kept at the root
language_sections empty config only Assign a language to a whole content section, keyed by content directory (longest prefix wins; home = root)
timezone empty --timezone IANA zone for content dates
language_timezones empty config only Per-language zone override

Non-default languages are written below /<lang>/. Templates receive .Lang, .Languages, .DefaultLanguage, .Translations and .Hreflang. Timezones affect permalink calendar tokens and template dates; feeds and sitemap remain UTC.

For the opt-in expanded multilingual system (the i18n: block), translation dictionaries and prefix/fallback policies, see I18N.

A language for a whole section (language_sections)

1languages: [en, de, fr]
2default_language: en
3language_sections:
4  de: de
5  fr/blog: fr
6  home: en

A page can declare its own lang:, and languages:/default_language: say what the site has. language_sections says "everything under this directory is German" in one place.

That is the shape a migrated site arrives in, and it is the case this exists for. A bilingual WordPress site keeps its languages in /de/ and /fr/ and says so nowhere a page carries — the language was a plugin's property of the section, not a field on the post. An export therefore produces a few hundred documents with no lang at all, and the alternatives were to write it into every file, which the next export overwrites, or to hand-edit after every build. A migration is not a one-off: it is run again whenever the source changes, so the assignment has to live where re-running it does not touch.

Keys are read exactly as output_encoding_sections and schema_defaults read theirs — the page's directory relative to the source, longest prefix wins, home for the site root — so there is one prefix convention in the project rather than three. Content loaded through content_sources resolves against the content root instead, so a section under an extra source can be keyed too.

Precedence, most specific first:

  1. the page's own lang: in frontmatter;
  2. the longest language_sections prefix that contains it;
  3. default_language.

A section naming a language languages: does not declare is reported once for the section, not once per file beneath it:

   ⚠️  language_sections "es" uses unconfigured language "es"

The assignment happens before translation grouping, LangPrefix and hreflang, so a section-assigned language reaches all of them. A page that already carries an explicit link: keeps it whole — link: is the highest-precedence URL source — so an export that already wrote link: /de/impressum/ does not become /de/de/impressum/ once the section assigns German.

Build profiling

A build that has grown slow has to say where its time goes, and until now the only number ssg reported about its own work was a count of markdown conversions:

1profile: text     # or: ssg --profile
⏱️  Build profile (2026-09-10 12:55:50)
   Total                                  1.55 s
   Loading content                          9 ms     1%
   Generating site                        407 ms    26%
   Search index                           655 ms    42%
   Assets and checks                      449 ms    29%
   Counters: pages rendered 96 · markdown conversions 81 · markdown cache hits 45
   Slowest pages (10 of 96):
     /configuration/                         25 ms

Phases appear in the order they ran and sum to the total, including the steps that happen after generation: images, archives, deployment. The counters are the tallies the build already kept — markdown conversions and cache hits, external sources served from cache, AI queries, images converted.

profile: json (or --profile=json) additionally writes build-profile.json beside the project, not into the output: a build's timings are the project's business, not part of the site, and nobody asked to publish them. CI can archive that file and diff two commits. Then:

$ ssg profile page /configuration/
/configuration/
   render              25.4 ms
   share                1.6% of a 1.56 s build
   build           2026-09-10 12:55:42 · ssg 1.8.60
   built from      content/site/pages/configuration.md
                   data/nav.yaml

built from reads the dependency graph the last build recorded, so it names real inputs rather than a guessed tree. On a site whose builds cannot be narrowed it says so instead, and ssg graph gives the reason.

--profile-pprof=DIR writes cpu.prof and heap.prof for go tool pprof. That is a maintainer's instrument — --profile answers where the time goes, pprof answers why.

Profiling does not change a single byte of output, and measuring costs about 120 nanoseconds per page against a page that takes milliseconds to render.

Build hooks

Hooks execute trusted local commands without a shell:

1hooks:
2  pre_build: [./scripts/prepare.sh]
3  post_build: [./scripts/report.sh]
4  post_page: []
Phase Timing Failure behaviour
pre_build Before generation Fails the build
post_page After each page Logged and non-fatal
post_build After generation Fails the build

Commands are argv-split, time-limited to 60 seconds, and never loaded from content. Hooks receive SSG_OUTPUT_DIR, SSG_PHASE, and for page hooks SSG_PAGE_PATH, plus exported custom variables.

Before rendering, ssg looks up the program of every pre_build and post_build hook and stops at once if one is missing (since 1.9.2), rather than after every page has rendered. The snap cannot run programs installed on the host, so a hook that calls node, python or similar needs another install method — see INSTALL.

MDDB content

MDDB replaces local Markdown with remote documents:

 1template: simple
 2domain: example.com
 3
 4mddb:
 5  enabled: true
 6  url: http://localhost:11023
 7  protocol: http
 8  collection: blog
 9  lang: en_US
10  api_key: ""                    # optional; prefer --mddb-key from a secret env value
11  timeout: 30
12  batch_size: 1000
13  watch: true
14  watch_interval: 30
Nested key Default CLI
mddb.enabled false enabled by --mddb-url
mddb.url empty --mddb-url
mddb.protocol HTTP behaviour --mddb-protocol=http|grpc
mddb.collection empty --mddb-collection
mddb.lang empty --mddb-lang
mddb.api_key empty --mddb-key
mddb.allow_http false —
mddb.trusted false --mddb-trusted
mddb.timeout 30 --mddb-timeout
mddb.batch_size 1000 --mddb-batch-size
mddb.watch false --mddb-watch
mddb.watch_interval 30 --mddb-watch-interval
mddb.sources empty — (config only; replaces collection when set)

Several collections, filtered on the server

mddb.sources reads more than one collection in a build, each with its own filter, content type and section:

 1mddb:
 2  enabled: true
 3  url: http://mddb:11023
 4  sources:
 5    - collection: articles
 6      filter: { visibility: [public] }
 7      type: post
 8      section: articles
 9    - collection: events
10      type: post
11      section: events
12    - collection: kb
13      type: page
Source key Meaning
collection The collection to read. Required
filter Metadata the documents must have: each key lists the values it accepts. Sent to MDDB as filterMeta
type page or post files every document as that. Empty uses each document's own type meta, which is how collection always worked
section The content section the documents belong to. schema_defaults, language_sections, output_encoding_sections, Web Stories sections and a declared feed's or paginated page's source: match it the way they match a directory

MDDB applies the filter, so a document it leaves out is never downloaded. It does not reach the build directory, the search index or llms.txt. Filtering in templates instead would put private documents in all three. Leave type out when you want a filter on type itself. A source that sets type reads every document in the collection that matches the filter. With sources set, collection and --mddb-collection are ignored. Categories, media and users still come from the categories, media and users collections. Watch mode rebuilds when any of the listed collections changes.

mddb.allow_http permits the API key over plaintext http:// to a host that is not loopback. It is off by default and should stay off for anything routable — but a container network that never leaves the host is the same trust boundary as loopback, spelled with a service name, and http://mddb:11023 had no way to say so. The key itself travels in X-API-Key; a value shaped like a JWT is sent as Authorization: Bearer instead.

HTTP commonly uses http://localhost:11023; gRPC commonly uses localhost:11024. MDDB watch polls the collection checksum and rebuilds when it changes. Values beginning with $ are resolved only inside variables, not in arbitrary configuration fields. In CI, pass an MDDB secret at runtime, for example --mddb-key="$MDDB_API_KEY".

Content from MDDB is sanitized by default (since 1.9.0). Markdown renders raw HTML, so a compromised or shared MDDB server could otherwise plant a <script> in every generated page. An MDDB build therefore applies sanitize_html on its own. When the server holds only your own authors' content and pages need raw HTML that the UGC policy strips (inline <script>, <iframe> outside the protected shortcodes, style attributes), set mddb.trusted: true or pass --mddb-trusted. sanitize_html: true still forces the sanitizer, trusted or not.

Structured frontmatter through MDDB's flat meta

MDDB stores metadata as a flat key → list of strings map, by design. A field that is not flat — a faq: list of {question, answer} objects, a schema: object — therefore has exactly one way through: the producer JSON-encodes it into a single meta string, and ssg decodes it back when the document becomes a page. Round-tripping is lossless and the theme ranges over the value as it would with local frontmatter.

1{ "faq": "[{\"question\":\"How long?\",\"answer\":\"20 minutes\"}]" }

What does not work is stringifying the value. A loader that formats a Go map stores map[answer:20 minutes question:How long?], which cannot be recovered by anyone. The build names the document and the field rather than letting the theme fail on it:

1⚠️  document "chicken-soup": meta field faq looks like a stringified Go value
2    (map[answer:20 minutes question:How long?]) — mddb stores meta as flat
3    strings, so structured fields must be JSON-encoded by the producer

A value that is neither JSON nor a printed Go map reaches the template exactly as it always has.

Archives and deployment

Key Default CLI
zip false --zip
targz false --targz
tarxz false --tarxz
deploy empty --deploy
deploy_project empty --deploy-project
deploy_branch provider default --deploy-branch
deploy_target provider-specific --deploy-target

Deployment credentials always come from environment variables. Provider details and GitHub Action inputs are in DEPLOYMENT.

Redirects and headers (Cloudflare Pages / Netlify)

Key Default Notes
redirects empty list of {from, to, status, force} rules
alias_stubs true also write meta-refresh stub pages for aliases: (false = 301 only; per-page frontmatter alias_stubs overrides)
headers empty map of path pattern → {header: value} overrides, merged into a built-in block header by header; "" removes a header (DEPLOYMENT)
headers_defaults_off false drop the built-in security/cache blocks

redirects: generates a real _redirects file: exact paths, /old/* splats (:splat in the destination) and statuses 301/302/303/307/308/410.

⚠️ 410 is a Netlify extension. Cloudflare Pages honours 301, 302, 303, 307 and 308 only, and drops anything else without a word — so the path keeps answering 200 while the rule reads as handled. Building with deploy: cloudflare warns about this; serve a gone page from a Pages Function if you need one. Frontmatter aliases: are added as 301s and exact chains are flattened to a single hop. By default each alias also gets a meta-refresh stub copy (a fallback for hosts without server redirects); set alias_stubs: false — site-wide or per page in frontmatter — to emit the 301 only, with no duplicate 200-serving copy. headers: overrides or extends the generated _headers per pattern. Full reference and the ssg import redirects importer: DEPLOYMENT.

1redirects:
2  - from: /old-pricing
3    to: /pricing        # status defaults to 301
4  - from: /blog/*
5    to: /articles/:splat
6    status: 301
7headers:
8  /api/*:
9    Access-Control-Allow-Origin: "*"

AI content (build-time [ai …] shortcode)

Two layers configure build-time AI, then you ask questions from inside content with the [ai …] shortcode:

  • A model is an endpoint — where to reach the provider (url, key, provider model id) and the base generation params. It is the connection.
  • An agent is a role built on a model — it runs on a model and layers a persona plus user-defined rules (constraints it must follow) and skills (jobs it applies) on top. It is the behaviour.

A shortcode invokes an agent (agent="…", preferred) or a bare model (model="…"). The answer is fetched once, at build time, and content-addressed cached so a rebuild is deterministic and only re-queries when the question or the effective request (model, prompt, rules, skills, params) changes. Keys reference environment variables, never literals; the request/response shape is OpenAI-compatible chat completions.

Key Notes
ai.models.<name>.url Chat-completions endpoint
ai.models.<name>.key Bearer token — use $ENV_VAR
ai.models.<name>.model Provider model id
ai.models.<name>.system Optional base system prompt
ai.models.<name>.max_tokens / temperature Optional generation controls
ai.agents.<name>.model Model this agent runs on (empty ⇒ default/sole model)
ai.agents.<name>.system Persona, layered on the model's system prompt
ai.agents.<name>.rules Constraints the agent must follow (folded into the prompt)
ai.agents.<name>.skills Capabilities the agent applies (folded into the prompt)
ai.agents.<name>.max_tokens / temperature Override the model when non-zero
ai.default_agent Agent used when a shortcode names neither
ai.default_model Model used when a shortcode names neither and no default agent
ai.cache_dir Content-addressed answer cache (default .ssg-cache/ai; the pre-1.8.27 .ai-cache is still read and migrated by copy)
ai.timeout Default per-query timeout (e.g. 30s)
 1ai:
 2  default_agent: writer
 3  cache_dir: .ssg-cache/ai    # commit it for reproducible, key-free CI builds
 4  models:                     # endpoints — the connection
 5    fast:
 6      url: https://ai.example.com/v1/chat/completions
 7      key: $OPENAI_KEY
 8      model: gpt-4o-mini
 9      system: "Answer in one short paragraph."   # house style, inherited by agents
10  agents:                     # roles — built on a model
11    writer:
12      model: fast             # runs on the "fast" model
13      system: "You are the site's copy editor."
14      rules:                       # constraints the agent must follow
15        - "Answer in the page's language."
16        - "Never invent facts or links."
17      skills:                      # jobs the agent is set up for
18        - "Summarise long text into one sentence."
19        - "Write concise meta descriptions."

The effective system prompt for an agent is its model's system, then the agent's system, then its rules, then its skills — all composed and folded into the cache key, so editing any of them re-queries. Define an agent once and every [ai agent="writer" …] inherits its role; a bare [ai model="fast" …] uses only the model's own settings.

In content:

1[ai agent="writer" question="Summarise the 1.8 release line in one sentence."
2   ifs="lang == en AND status == publish" timeout="20s" fallback="_summary unavailable_"]
  • Precedence when resolving a shortcode: an explicit agent, then an explicit model, then ai.default_agent, then ai.default_model, then a sole agent, then a sole model.
  • ifs is an optional guard evaluated against the page's fields (lang, status, type, category, series, slug, title, tags, any custom frontmatter, and site variables). It supports AND/OR and the operators ==, !=, contains, >, <, >=, <=. When it is false — or the query fails, or nothing answers — the fallback text is used.
  • Because answers are cached by the effective request, committing cache_dir lets CI rebuild the exact same content with no API key and no network.

Notifications (announce new posts)

Send each newly published — or changed — post to webhook destinations you define: point them at a platform API, an automation service (Zapier / Make / n8n / IFTTT) or your own endpoint, and they receive the post as JSON. A committed state file dedupes, so a post is announced once, again only when its content changes. It never fires unless you pass --notify, so local dev builds stay quiet.

Key Notes
notifications[].url Destination the post JSON is POSTed to
notifications[].name Label used in build logs
notifications[].method HTTP method (default POST)
notifications[].headers Extra headers (auth) — use $ENV_VAR for secrets
notifications[].allow_private Permit a private/loopback destination
notify_state Dedup state file (default .ssg-notifications.json)
notify / --notify Actually send this build (off by default)
1notify_state: .ssg-notifications.json   # commit it — CI needs the sent-history
2notifications:
3  - name: zapier
4    url: https://hooks.example.com/catch/…   # fans out to X / LinkedIn / …
5    headers: { X-Token: $ZAP_TOKEN }
1ssg --config .ssg.yaml --notify --deploy cloudflare   # announce on publish

The payload is {slug, title, url, excerpt, date, tags}. The dedup key is a hash of the post's title, body and date, so an edit re-announces it and an untouched post is skipped. A destination that fails is retried on the next --notify run. The transport refuses private/loopback ranges at dial time unless allow_private is set, so a webhook URL can't be turned into an SSRF pivot.

Development MCP server (ssg mcp)

Full reference — roles, every tool with its CAN/CANNOT contract, and the git write-back flow — is in MCP. This section covers the configuration block.

ssg mcp runs a Model Context Protocol server over stdio so an AI assistant can work on the site during development in two clearly-scoped roles:

  • Designer (designer_*) — changes how the site looks: lists, reads and writes templates, partials, CSS and theme assets. It cannot touch content, delete files, or write outside the template/static directories. It also owns the presentation settings in the config file — see below.
  • Content manager (content_*) — changes what the site says: lists, reads, creates, updates and deletes Markdown (frontmatter + body). It cannot touch templates or write non-Markdown files.

Every tool description tells the model exactly what it can and cannot do, an always-present help tool restates the whole contract, and the same guidance is handed to the client at connect time. By default every successful change triggers a rebuild — a template or content error comes straight back to the model as the tool result, so it fixes its own mistakes before moving on.

1ssg mcp                    # both roles, rebuild after every change
2ssg mcp --role=designer    # designer only
3ssg mcp --role=content     # content manager only
4ssg mcp --no-watch         # edit only, no rebuilds

Register it in an MCP-capable assistant as a stdio server:

1{ "command": "ssg", "args": ["mcp", "--config", ".ssg.yaml"] }

Designer-owned configuration keys

Presentation does not live in templates alone — the theme, the syntax-highlight style, whether diagrams render. So the designer gets designer_config_read and designer_config_set over a narrow allow-list of presentation settings:

Kind Keys
Site title, description
Theme and rendering template, mermaid, mermaid_theme, mermaid_background, highlight, highlight_style, highlight_line_numbers, math, toc, toc_depth, paginate
Text clean_special_chars, autolink_list_items, strip_md_link_text
Output minify_html, minify_css, minify_js, minify_all, pretty_html, sourcemap, fingerprint
Images webp, webp_quality, image_formats, image_sizes_attr
Switches (1.9.6) story, listen, print, cook_mode, heading_anchors, og_cards, breadcrumbs
For agents (1.9.6) markdown_publish, site_graph, webmcp, search_index, outputs
Share identity (1.9.6) marketing.og_site_name, marketing.og_image, marketing.twitter_site, marketing.theme_color, marketing.logo, marketing.favicon, marketing.apple_touch_icon

A switch takes true or false and writes <key>.enabled, so the feature's other settings (a story's slideshow, the Listen button's voice) stay as you wrote them. A switch you wrote as heading_anchors: true stays a scalar. designer_config_read shows a switch by its enabled alone. Lists (image_formats, outputs) are given comma-separated, "webp,avif". A list never replaces a mapping: outputs: written per content type is refused, and you edit it in the file.

Every other key is refused by construction — secrets (API keys, tokens, jwt_secret, auth, marketing.verification), deployment, server, endpoints, hooks, sass_binary (an executable path) and all content/URL structure. designer_config_read shows only the writable keys, so the rest of the file is never even surfaced to the model.

Three properties make this safe to hand over:

  • Comments and key order survive. The file is edited as a YAML document, not re-serialised, so your annotated config stays annotated.
  • Invalid changes roll back. After each write the config is re-loaded; if it no longer loads, the previous file is restored and the model is told why.
  • Changes apply immediately. Since the watcher treats the config as a watched input, a designer_config_set in watch mode reloads and rebuilds at once.

The tools appear only when a config file is in play; without one, there is nothing to edit and they are not exposed.

Git write-back (optional)

With a git account and token configured, the assistant additionally gets a safe write-back flow: git_new_branch → edit → git_commit → human reviews → git_open_pr. Edits never land on the base branch, commits stage only the content/template directories, and the pull request is opened only after the person explicitly approves. The token must reference an environment variable, never a literal.

Key Notes
mcp.git.account Git account/owner the PR is attributed to
mcp.git.token API token for opening PRs — use $ENV_VAR (e.g. $GITHUB_TOKEN)
mcp.git.repo owner/name; empty = derived from the remote URL
mcp.git.remote Remote to push to (default origin)
mcp.git.default_branch PR base branch (default main)
mcp.git.branch_prefix Working-branch prefix (default mcp/)
1mcp:
2  git:
3    account: spagu
4    token: $GITHUB_TOKEN        # never a literal
5    default_branch: main
6    branch_prefix: mcp/

Without mcp.git.token, the git_* tools are simply not exposed — the assistant edits files in place and version control stays fully manual.

mcp.search — an MDDB-backed find (optional)

designer_find / content_find scan the project directories, which needs nothing installed and answers most queries — identifiers, colours, class names. What a scan cannot do is answer a question phrased as a sentence. Point it at an MDDB collection and it can:

Key Notes
mcp.search.mddb_url MDDB base URL; empty ⇒ local scan only
mcp.search.mddb_collection Collection holding the theme; empty ⇒ local scan only
mcp.search.mddb_api_key Optional API key — use $ENV_VAR, never a literal
mcp.search.mddb_lang Language used to tokenise the query, e.g. en
mcp.search.mddb_fuzzy Typo tolerance: 0 off, 1 or 2 edit distance
mcp.search.mddb_validate Check each document before storing it (ssg mddb push-theme, MDDB 2.12.0+). Default on; warnings never fail a push
mcp.oauth.issuer OAuth 2.1 authorization server whose access tokens the HTTP endpoint accepts; tokens' iss must equal it. See MCP_TRANSPORTS
mcp.oauth.resource This endpoint's public URI (https://mcp.example.com/mcp); tokens' aud must name it
mcp.oauth.scopes Scopes a token must carry, also advertised in the metadata
mcp.oauth.jwks_url The issuer's key set; discovered from its metadata when empty
mcp.media_allow_private Permit media_upload to fetch a URL resolving to a loopback or private address. Off by default: an unguarded fetch on someone else's instruction is server-side request forgery
mcp.search.mddb_allow_http Permit the API key over plaintext http:// to a non-loopback host — a private container network. Off by default
1mcp:
2  search:
3    mddb_url: http://localhost:11023
4    mddb_collection: theme
5    mddb_api_key: $MDDB_TOKEN
6    mddb_lang: en

Fill the collection with ssg mddb push-theme. The index is consulted first and is never required: on an error or an empty answer the local scan still runs, so a search backend that is down cannot take the ability to edit the site down with it. See MCP.

Server endpoints (portable, no vendor lock-in)

endpoints: declares small server-side pieces — a redirect that depends on the request, a proxy that keeps an upstream key on the server, a form delivered to a webhook, a Basic-auth section — once, for the built-in --http server or compiled for Cloudflare, Netlify or Vercel with endpoints_platform. The keys and their security rules are in SERVER-ENDPOINTS.

Cloudflare Worker / Pages Functions

Workers — comments, a newsletter, a shop, accounts, the admin home, editing in the browser — are documented apart from the core build, starting with WORKERS, the list of every template. Their keys in this file are worker: and workers:, modules: and check_modules, and web_push: (WORKERS-CONFIGURATION), and admin_theme: with check_admin_theme (ADMIN-THEME). Their secrets never go here (WORKERS-SECRETS).

Complete example

 1source: my-blog
 2template: simple
 3domain: example.com
 4
 5content_dir: content
 6templates_dir: templates
 7output_dir: output
 8static_dir: static
 9data_dir: data
10
11clean: true
12minify_all: true
13fingerprint: true
14feed: true
15search_index: true
16seo: true
17check_links: strict
18
19webp: true
20webp_quality: 80
21image_sizes: [480, 960, 1600]
22
23paginate: 10
24outputs: [html]

Before relying on a key in automation, compare it with .ssg.yaml.example and ssg --help from the installed version.