Foundry Overview

Core ideas

Content lives in Markdown files with frontmatter.
Routes are assigned from structured content and language-aware conventions.
Themes own presentation through layouts and partials.
Plugins extend behavior through explicit hook interfaces.
A dependency graph supports incremental rebuilds for both documents and taxonomy archive outputs.

Key directories

/content      pages, posts, images, assets, uploads, config
/data         structured data files exposed to rendering
/themes       active theme layouts and assets
/plugins      installed plugins
/public       generated output
/docs         GitHub Pages content and generated coverage output

Common commands

foundry
foundry version
foundry build
foundry build --preview
foundry build --env preview --target production
foundry serve
foundry serve --debug
foundry serve-preview
foundry plugin list --enabled
foundry theme list
foundry routes check
foundry admin hash-password your-password

If you want additional logging, run foundry serve --debug to log request timing, slow-render warnings, memory snapshots, goroutine counts, active request counts, connections, and process CPU time deltas. If admin.debug.pprof is enabled, the admin Debug page also surfaces runtime, content, storage, integrity, activity, and persisted build-report snapshots alongside authenticated pprof links.

Live reload supports two transport modes: stream uses Server-Sent-Events (sse) and is the default. poll checks a lightweight endpoint every 1.5 seconds and is the safer choice if your browser hits local connection limits while reloading.

Media files now live under dedicated collection roots such as content/images, content/videos, content/audio, and content/documents. Reference them from Markdown with the media: scheme, for example ![Hero](media:images/hero.jpg), ![Demo](media:videos/demo.mp4), ![Theme](media:audio/theme.mp3), or [Spec PDF](media:documents/spec.pdf). Static builds also write a frontend search index to public/search.json, and preview builds write public/preview-links.json.

Important config groups

Admin: admin.path controls the mount point for the themeable admin shell and defaults to /__admin; username/password login is backed by content/config/admin-users.yaml, browser sessions expire after 30 minutes of inactivity by default, and the default admin theme includes structured frontmatter editing, restore-preview workflows, media replacement, audit log browsing, user-security flows, a command palette, and keyboard shortcuts.
Security: security.allow_unsafe_html controls whether raw HTML is preserved in Markdown output.
Server: preview/admin serving uses read, write, and idle timeouts by default, and live reload can run in stream or poll mode.
Deploy: deploy.targets can override base URL, public dir, theme, preview mode, and related output settings; foundry build --env <name> also layers site.<name>.yaml over the base config when present, and deploy.default_target is applied automatically when no explicit --target is passed.
Taxonomies: default and custom taxonomies participate in rendering and incremental rebuild planning.
Plugins: enabled plugins are validated and synced into generated registration code.
Themes: themes must satisfy the minimum slot contract validated by foundry theme validate.

For the full key-by-key config reference, including all defaults and the exact meaning of each entry, see the Configuration guide.

Operations commands

foundry doctor reports timing breakdowns for plugin config, graph load, route assignment, route hooks, asset sync, renderer, and feed generation.
foundry validate checks broken links, broken media: references, missing templates, orphaned media, duplicate routes/slugs, and taxonomy inconsistencies.
foundry content export, foundry content import, and foundry content migrate cover basic portability and schema/layout migration workflows, including --dry-run support for layout and field-rename migrations.

Admin shortcuts

Cmd/Ctrl+S saves the current form.
Cmd/Ctrl+Enter previews the current document.
Cmd/Ctrl+K opens the command palette.
Shift+/ toggles shortcut help.
g d, g m, g u, and g a jump to Documents, Media, Users, and Audit.