Foundry Configuration Reference

What this file does

content/config/site.yaml is the main runtime config for a Foundry site. It controls site identity, serving, admin behavior, build output, content layout, taxonomies, fields, plugin activation, deploy targets, feeds, and theme-facing values.

Foundry also supports environment overlays such as content/config/site.preview.yaml. Those files are layered on top of the base config when you run commands like foundry build --env preview.

If you want a full explicit config with every current default written out, start from content/config/example.site.yaml.

Minimal example

name: "foundry"
title: "Foundry CMS"
base_url: "http://localhost:8080"
theme: "default"

server:
  addr: ":8080"
  live_reload: true

admin:
  enabled: true
  path: "/__admin"
  theme: "default"

content:
  pages_dir: "pages"
  posts_dir: "posts"

Top-level keys

These keys define the overall site identity and root directory layout.

name: machine-oriented site identifier used in status output and metadata. Default: foundry.
title: human-facing site title. Default: Foundry CMS.
base_url: canonical site base URL used for absolute links, feeds, preview manifests, and deploy output. Default: empty.
theme: active frontend theme name under themes/. Default: default.
environment: environment label such as default, preview, or production. Default: default.
default_lang: default language code for content routing. Default: en.
content_dir: root content directory. Default: content.
public_dir: build output directory. Default: public.
themes_dir: theme root directory. Default: themes.
data_dir: runtime data directory used for state files and structured data. Default: data.
plugins_dir: plugin installation directory. Default: plugins.

`server`

This group controls the preview server and live reload behavior.

addr: bind address for the preview server. Default: :8080.
live_reload: enables or disables live reload. Default: false.
live_reload_mode: reload transport. Use stream for Server-Sent Events or poll when browser connection limits make SSE unreliable. Default: stream.
auto_open_browser: automatically opens the preview URL after startup. Default: false.
debug_routes: enables extra debug-only route output where supported. Default: false.

server:
  addr: ":8080"
  live_reload: true
  live_reload_mode: "poll"
  auto_open_browser: false
  debug_routes: false

`admin`

This group controls the admin shell, admin auth, persistent session state, and admin-only debug features.

enabled: enables or disables the admin surface. Default: false.
addr: reserved for a separate admin bind address. The current server mounts admin under the main HTTP server. Default: empty.
path: admin mount path. Default: /__admin.
local_only: rejects forwarded or non-local admin access when true. Default: true.
access_token: optional API token for automation or non-browser admin access. Default: empty.
theme: active admin theme under themes/admin-themes/. Default: default.
users_file: filesystem-backed user database file. Default: content/config/admin-users.yaml.
session_store_file: persistent session store file. Default: data/admin/sessions.yaml.
lock_file: persistent document lock file used by editor locking. Default: data/admin/locks.yaml.
session_ttl_minutes: idle browser session timeout. Default: 30.
password_min_length: minimum password length for save and reset flows. Default: 12.
password_reset_ttl_minutes: password reset token lifetime. Default: 30.
totp_issuer: issuer string embedded in TOTP setup URIs. Default: Foundry.

`admin.debug`

pprof: enables authenticated net/http/pprof access and the admin Debug page runtime summary. Default: false.

admin:
  enabled: true
  addr: ""
  path: "/__admin"
  local_only: true
  access_token: ""
  theme: "default"
  users_file: "content/config/admin-users.yaml"
  session_store_file: "data/admin/sessions.yaml"
  lock_file: "data/admin/locks.yaml"
  session_ttl_minutes: 30
  password_min_length: 12
  password_reset_ttl_minutes: 30
  totp_issuer: "Foundry"
  debug:
    pprof: true

`build`

This group controls the shape of static build output.

clean_public_dir: removes public/ before a build. Default: false.
include_drafts: includes draft content in build output. Default: false.
minify_html: minifies rendered HTML. Default: false.
copy_assets: copies content-owned static assets into output. Default: false.
copy_images: copies image media into output. Default: false.
copy_uploads: copies legacy uploads plus the current non-image media collections where applicable. Default: false.

`content`

This group defines directory names under content/ and a few core content defaults.

pages_dir: page document directory. Default: pages.
posts_dir: post document directory. Default: posts.
images_dir: image media directory. Default: images.
videos_dir: video media directory. Default: videos.
audio_dir: audio media directory. Default: audio.
documents_dir: document-like media directory. Default: documents.
assets_dir: content-owned static asset directory. Default: assets.
uploads_dir: legacy upload directory retained for compatibility. Default: uploads.
max_versions_per_file: maximum retained filesystem versions per file before pruning. Default: 10.
default_layout_page: default layout for pages. Default: page.
default_layout_post: default layout for posts. Default: post.
default_page_slug_index: slug used for section-index pages. Default: index.

content:
  pages_dir: "pages"
  posts_dir: "posts"
  images_dir: "images"
  videos_dir: "videos"
  audio_dir: "audio"
  documents_dir: "documents"
  assets_dir: "assets"
  uploads_dir: "uploads"
  max_versions_per_file: 10
  default_layout_page: "page"
  default_layout_post: "post"
  default_page_slug_index: "index"

`permalinks`

This group defines the route templates used when Foundry assigns URLs to pages and posts.

page_default: default-language page route pattern.
page_i18n: non-default-language page route pattern.
post_default: default-language post route pattern.
post_i18n: non-default-language post route pattern.

permalinks:
  page_Default: "/:slug/"
  page_i18n: "/:lang/:slug/"
  post_Default: "/posts/:slug/"
  post_i18n: "/:lang/posts/:slug/"

`taxonomies`

This group enables taxonomy rendering and defines which taxonomies exist.

enabled: enables taxonomy support. Default: false.
default_set: taxonomy names enabled by default for content. Default: [tags, categories].
definitions: per-taxonomy definitions keyed by taxonomy name. Default: {}.

Each taxonomy definition supports:

title: human title for the taxonomy.
labels: per-language label map.
archive_layout: optional archive layout override.
term_layout: layout used for individual term pages.
order: ordering hint such as alpha.

taxonomies:
  enabled: true
  default_set:
    - tags
    - categories
  definitions:
    tags:
      title: "Tags"
      labels:
        en: "Tags"
        es: "Etiquetas"
      archive_layout: "list"
      term_layout: "list"
      order: "alpha"
    categories:
      title: "Categories"
      labels:
        en: "Categories"
      archive_layout: "list"
      term_layout: "list"

`plugins`

This group controls which installed plugins are enabled for the site.

enabled: list of plugin names to enable. Default: empty list.

plugins:
  enabled:
    - toc
    - relatedposts
    - readingtime

`fields`

This group enables schema-driven fields and validation for content types.

enabled: enables schema-backed field support. Default: false.
allow_anything: accepts undeclared field data even when schemas exist. Default: false.
schemas: map of schema definitions keyed by schema name or document kind. Default: {}.

Each schema contains a fields list. Each field supports keys such as name, label, type, required, default, enum, fields, item, help, and placeholder.

fields:
  enabled: true
  allow_anything: false
  schemas:
    post:
      fields:
        - name: hero_style
          label: "Hero Style"
          type: "select"
          enum:
            - "standard"
            - "feature"
          help: "Choose the post hero treatment."
        - name: hero
          label: "Hero"
          type: "object"
          fields:
            - name: image
              type: "text"
              placeholder: "media:images/hero.jpg"
            - name: eyebrow
              type: "text"
        - name: authors
          label: "Authors"
          type: "list"
          item:
            name: "author"
            type: "object"
            fields:
              - name: name
                type: "text"
                required: true
              - name: role
                type: "text"

`seo`

This group controls SEO-oriented output defaults.

enabled: enables SEO-related handling where supported. Default: false.
default_title_sep: default title separator when combining page and site titles. Default: empty.

`cache`

This group controls cache-related behavior where supported by the current runtime.

enabled: enables cache-related behavior. Default: false.

`security`

This group controls security-sensitive rendering behavior.

allow_unsafe_html: preserves raw HTML from Markdown when true. Leave this false unless you intentionally trust raw HTML in content. Default: false.

`feed`

This group controls RSS and sitemap output.

rss_path: RSS route path. Default: /rss.xml.
sitemap_path: sitemap route path. Default: /sitemap.xml.
rss_limit: maximum number of items in the RSS feed. Default: 50.
rss_title: feed title. Default: the site title.
rss_description: feed description. Default: the site title.

feed:
  rss_path: "/rss.xml"
  sitemap_path: "/sitemap.xml"
  rss_limit: 50
  rss_title: "Foundry CMS"
  rss_description: "Foundry CMS"

`deploy`

This group defines named deploy targets that can override selected config values during builds.

default_target: target name to use by default. Default: empty.
targets: map of named deploy targets. Default: {}.

Each deploy target supports:

base_url: override canonical base URL.
public_dir: override output directory.
theme: override frontend theme.
include_drafts: override build draft inclusion.
environment: override environment label.
preview: when true, forces preview-style draft inclusion.
live_reload_mode: override live reload transport for the target.

deploy:
  default_target: "production"
  targets:
    production:
      base_url: "https://example.com"
      public_dir: "public-prod"
      theme: "default"
      include_drafts: false
      environment: "production"
      preview: false
      live_reload_mode: "stream"
    preview:
      base_url: "https://preview.example.com"
      public_dir: "public-preview"
      include_drafts: true
      environment: "preview"
      preview: true
      live_reload_mode: "poll"

`params`

This is a free-form map of site-level values exposed to themes, templates, and plugins.

params: arbitrary key-value data. Default: {}.

params:
  company_name: "Sphire"
  support_email: "support@example.com"
  home_eyebrow: "Launch Week"

`menus`

This group defines named menus. Each menu contains items with name and url.

menus: menu map keyed by menu name. Default: {}.
name: item label shown in the UI.
url: destination URL.

menus:
  main:
    - name: "Home"
      url: "/"
    - name: "Docs"
      url: "/docs/"
  footer:
    - name: "RSS"
      url: "/rss.xml"
    - name: "GitHub"
      url: "https://github.com/sphireinc/foundry"

Defaults and examples

Use content/config/example.site.yaml when you want every current default spelled out explicitly.
Keep content/config/site.yaml focused on the values you are actually overriding.
Use overlays like content/config/site.preview.yaml or named deploy targets when a setting should only change for preview or production builds.
When a group contains nested structures like taxonomies.definitions, fields.schemas, or deploy.targets, prefer full YAML snippets over terse one-line docs so the expected shape stays obvious.