Configuration

Alloy reads its configuration from alloy.config.yaml (also .yml, .toml, or .json) in the project root. The first match wins.

# alloy.config.yaml title: "My Site" baseURL: "https://example.com" language: "en"

Both title and baseURL are required. Other fields default to sensible values when omitted.

Top-level fields

Field	Type	Default	Description
`title`	string	— (required)	Site title. Available in templates as `site.title`.
`baseURL`	string	— (required)	Full URL including protocol. Used by `absolute_url` filter and sitemap generation.
`language`	string	`"en"`	Default site language code. Available as `site.language`.
`updateCheck`	boolean	`false`	Check for newer Alloy versions when `alloy dev` or `alloy serve` starts. See below.

`updateCheck`

When true, Alloy checks GitHub Releases for a newer version each time alloy dev or alloy serve starts. The check runs in the background without blocking server startup. alloy build never checks.

Alloy caches the result at ~/.config/alloy/update-check.json (respects XDG_CONFIG_HOME) for 24 hours. Within that window, Alloy reads the cache instead of making a network request. Running alloy version --check queries GitHub immediately and overwrites the cache, resetting the 24-hour TTL.

updateCheck: true

`build`

Controls output directory and cleanup behavior.

build: output: "_site" clean: true

Field	Type	Default	Description
`build.output`	string	`"_site"`	Output directory for the built site.
`build.clean`	boolean	`true`	Delete the output directory before each build. Set `false` to preserve files from previous builds.

`content`

Controls which files are treated as content and how Markdown is rendered.

content: formats: ["md", "html"] markdown: toc: true goldmark: unsafe: true typographer: false templateTags: true autoHeadingID: true customElements: true

Field	Type	Default	Description
`content.formats`	string[]	`["md", "html"]`	File extensions treated as content pages. Other files in `content/` are copied as passthrough.
`content.markdown.toc`	boolean	`true`	Generate `page.toc` heading structure for Markdown pages. Set `false` to disable.
`content.markdown.goldmark.unsafe`	boolean	`true`	Allow raw HTML in Markdown. Set `false` to escape all HTML tags.
`content.markdown.goldmark.typographer`	boolean	`false`	Convert straight quotes to smart quotes, `--` to en-dash, `---` to em-dash.
`content.markdown.goldmark.templateTags`	boolean	`true`	Treat `{{ }}` and `{% %}` in Markdown prose as template syntax. Set `false` to render them as literal text.
`content.markdown.goldmark.autoHeadingID`	boolean	`true`	Add `id` attributes to headings. Also activates `{.class #id key=value}` block-level attribute syntax.
`content.markdown.goldmark.customElements`	boolean	`true`	Treat multi-line custom elements (tags with hyphens) as block-level HTML. Preserves content inside verbatim.

`templates`

templates: engine: "liquid"

Field	Type	Default	Description
`templates.engine`	string	`"liquid"`	Template engine. `"liquid"` or `"gotemplate"` (alias `"go"`). One engine per project.

`structure`

Override default directory names. All paths are relative to the project root.

structure: content: "content" layouts: "layouts" assets: "assets" static: "static" data: "data" plugins: "plugins"

Field	Type	Default	Description
`structure.content`	string	`"content"`	Content files directory.
`structure.layouts`	string	`"layouts"`	Template layouts directory.
`structure.assets`	string	`"assets"`	Processed assets directory.
`structure.static`	string	`"static"`	Static files directory (copied verbatim to output root).
`structure.data`	string	`"data"`	Global data files directory.
`structure.plugins`	string	`"plugins"`	Plugin files directory.

`plugins`

plugins: timeout: 5000 workers: "auto"

Field	Type	Default	Description
`plugins.timeout`	integer	`5000`	Hook timeout in milliseconds. Alloy discards a timed-out hook’s mutations.
`plugins.workers`	integer or `"auto"`	`"auto"`	Node subprocess worker count for per-page hooks. `"auto"` uses `min(CPU_count / 2, 8)` with a floor of 2.

`taxonomies`

Declare which front matter keys create taxonomy collections. Each key can be a bare declaration or an object with options.

taxonomies: tags: categories: permalink: "/sections/:slug/" layout: "term" render: false

Field	Type	Default	Description
`taxonomies.<name>.permalink`	string	`"/<name>/:slug/"`	URL pattern for term pages.
`taxonomies.<name>.layout`	string	taxonomy name	Layout template for index and term pages.
`taxonomies.<name>.render`	boolean	`true`	Generate output pages. Set `false` for data-only taxonomies.

See Taxonomies for usage.

`collections`

Declare sections as collections without date-based permalink patterns.

collections: releases: sortBy: "date" order: "desc"

Field	Type	Default	Description
`collections.<name>.sortBy`	string	`"date"`	Front matter field to sort by.
`collections.<name>.order`	string	`"desc"`	Sort direction. `"asc"` or `"desc"`.

See Collections for usage.

`pagination`

pagination: path: "page"

Field	Type	Default	Description
`pagination.path`	string	`"page"`	URL segment for paginated pages (e.g., `/articles/page/2/`).

See Pagination for usage.

`data`

Map external files into the site.data.* namespace.

data: files: tokens: "node_modules/@rhds/tokens/json/rhds.tokens.json" cem: "../custom-elements.json"

Field	Type	Default	Description
`data.files.<key>`	string	—	Path to an external data file (YAML, JSON, or TOML). Relative to project root. Available as `site.data.<key>`.

See Data Files for formats and external sources.

`sources`

Fetch data from REST APIs, GraphQL endpoints, or plugin handlers at build time.

sources: posts: type: "rest" url: "https://api.example.com/posts.json" cache: 3600 as: "posts" products: type: "graphql" endpoint: "https://api.example.com/graphql" query: | { products { id, name, price } } cache: 1800 as: "products" blog: type: "plugin" plugin: "cms-posts" cache: 3600 as: "blog"

Field	Type	Default	Description
`sources.<name>.type`	string	—	`"rest"`, `"graphql"`, or `"plugin"`.
`sources.<name>.url`	string	—	Endpoint URL (rest).
`sources.<name>.endpoint`	string	—	GraphQL endpoint URL.
`sources.<name>.query`	string	—	GraphQL query string.
`sources.<name>.plugin`	string	—	Plugin source handler name (for `type: "plugin"`).
`sources.<name>.cache`	integer	—	Cache TTL in seconds. Cached to `.alloy/fetch-cache/`.
`sources.<name>.as`	string	source key	`site.data.*` key for the fetched data. Defaults to the source map key.

See Data Files — External data sources for usage.

`passthrough`

Copy external directories or glob patterns into the output.

passthrough: - from: "../design-system/dist/elements" to: "elements" - from: "fonts/**/*.woff2" to: "assets/fonts" exclude: - "*.map"

Field	Type	Default	Description
`passthrough[].from`	string	—	Source path or glob pattern. Relative to project root.
`passthrough[].to`	string	—	Destination path in the output directory. `"."` targets the output root.
`passthrough[].exclude`	string[]	—	Glob patterns to skip.

`watch`

Register external directories for file watching during alloy dev and alloy serve. Changes trigger the appropriate pipeline stage.

watch: - from: "../design-system/elements" type: "content" - from: "../shared-layouts" type: "layout"

Field	Type	Default	Description
`watch[].from`	string	—	Directory to watch. Cannot overlap `structure.*` directories.
`watch[].type`	string	—	Pipeline stage to trigger: `"content"`, `"layout"`, or `"data"`.

`sitemap`

Alloy generates sitemap.xml by default. Disable it or set global defaults.

sitemap: changefreq: "weekly" priority: 0.5

Disable sitemap generation entirely:

sitemap: false

Field	Type	Default	Description
`sitemap`	boolean or object	`true`	Set `false` to disable sitemap generation.
`sitemap.changefreq`	string	—	Default `<changefreq>` for all pages.
`sitemap.priority`	float	—	Default `<priority>` for all pages (0.0–1.0).

Per-page overrides in front matter: sitemap: { priority: 1.0 } or sitemap: false to exclude a page.

`languages`

Opt-in multilingual support. Each key is a language code with its own content tree under content/<code>/.

languages: en: title: "My Site" weight: 1 root: true strings: read_more: "Read more" fr: title: "Mon Site" weight: 2 strings: read_more: "Lire la suite"

Field	Type	Default	Description
`languages.<code>.title`	string	—	Language-specific site title. Overrides top-level `title`.
`languages.<code>.weight`	integer	—	Sort order. Lowest weight is the default language.
`languages.<code>.root`	boolean	`false`	Output at site root (`_site/`) instead of `_site/<code>/`.
`languages.<code>.strings`	map	—	Translation strings for shared layouts. Access via `site.language.strings.<key>`.

See Internationalization for content structure and template usage.

`ssr`

Experimental server-side rendering. See SSR for details.

ssr: command: "node ssr-worker.js" mode: "full" timeout: "10s"

Field	Type	Default	Description
`ssr.command`	string	—	SSR worker command.
`ssr.mode`	string	—	Rendering mode.
`ssr.timeout`	string	—	Per-page timeout (Go duration string, e.g., `"10s"`).

Full example

title: "My Site" baseURL: "https://example.com" language: "en" updateCheck: true build: output: "_site" clean: true content: formats: ["md", "html"] markdown: toc: true goldmark: unsafe: true typographer: true templateTags: true autoHeadingID: true customElements: true templates: engine: "liquid" structure: content: "content" layouts: "layouts" plugins: timeout: 5000 workers: "auto" taxonomies: tags: categories: pagination: path: "page" sitemap: changefreq: "weekly" priority: 0.5 passthrough: - from: "node_modules/@rhds/elements/elements" to: "assets/elements" exclude: ["*.map", "demo/"] sources: team: type: "rest" url: "https://api.example.com/team.json" cache: 3600 as: "team"