Build directly with current Core

Foundry Core is a portable Hugo module and command-line toolkit for building, inspecting, validating, and evolving owner-controlled websites. A Foundry site remains a normal Hugo repository: content, configuration, assets, and overrides stay visible in files and can be built without Foundry Control.

Use this guide for the first working page. Continue with the mission and top goals, feature and family catalog, CLI reference, and AI agent guide.

Prerequisites

• Go 1.27 or newer
• Hugo Extended 0.165.0 or newer (the compatibility lane tests 0.165.0)
• Git

Node.js, npm, pnpm, and other package managers are not prerequisites for creating, building, serving, or validating a Foundry site. See the Tooling Policy.

Choose How To Run The CLI

From a Foundry Core checkout, the source-tree form is always available:

go run ./cmd/foundry --help

Install the current checkout into your Go binary directory:

go install ./cmd/foundry
foundry --help

Install a tagged release without cloning Core:

go install github.com/jerrybroughton/likestyle-foundry-core/cmd/foundry@v1.1.28
foundry version
foundry --help

Direct tagged installation requires repository access. If that is not configured, use an approved Core checkout or the site-owned materialized copy.

All examples in the docs use foundry. Substitute go run ./cmd/foundry when working from the Core repository without an installed binary.

Create A Site From A Theme-Led Direction

Start by comparing Foundry’s Site Types and their creative directions. Each direction joins a Site Blueprint, Theme Family, and fictional reference Brand System so you can choose the structure and art direction together:

foundry new-site --list

Preview a direction without writing anything:

foundry new-site ./northline-site \
  --site-type local-service \
  --direction local-service-clear

After reviewing the reported Theme Family, Brand System, destination, and route floor, repeat with --write:

foundry new-site ./northline-site \
  --site-type local-service \
  --direction local-service-clear \
  --title "Northline Home Services" \
  --business-name "Northline Home Services" \
  --write

cd ./northline-site
hugo server --buildDrafts

An installed immutable release supplies its own Core version. A development build cannot safely guess a release dependency, so add an explicit value such as --core-version v0.1.54 when running go run ./cmd/foundry from an unreleased checkout.

The generated repository contains ordinary Hugo configuration, Markdown, CSS, and Go module declarations. It contains no package.json, pnpm lockfile, or Node build step. The reference Brand System is orientation, not customer identity; replace its fictional tokens, copy, facts, and media before publish.

Local Service and Creative Portfolio have executable v1 route floors. Concierge Property is visible in the comparison catalog but remains honestly marked planned until its route-floor scaffold is complete.

Add Core To An Existing Hugo Site

Add the module requirement to the site’s go.mod:

require github.com/jerrybroughton/likestyle-foundry-core v1.1.28

For a locked/materialized site, use the site-owned framework copy:

replace github.com/jerrybroughton/likestyle-foundry-core => ./.foundry/modules/likestyle-foundry-core

Use a sibling checkout only while deliberately testing unreleased Core work:

replace github.com/jerrybroughton/likestyle-foundry-core => ../likestyle-foundry-core

Add the module import to hugo.yaml, or to config/_default/module.yaml in a config-directory site:

module:
  imports:
    - path: github.com/jerrybroughton/likestyle-foundry-core
      mounts:
        - source: layouts/_default/landing.html
          target: layouts/_default/landing.html
        - source: layouts/_partials
          target: layouts/_partials
        - source: layouts/partials
          target: layouts/partials
        - source: layouts/partials
          target: layouts/partials/foundry
        - source: data
          target: data
        - source: assets
          target: assets
        - source: i18n
          target: i18n

Sites using the article shell, Markdown render hooks, or shortcodes also mount:

        - source: layouts/blog
          target: layouts/blog
        - source: layouts/authors
          target: layouts/authors
        - source: layouts/_default/taxonomy.html
          target: layouts/_default/taxonomy.html
        - source: layouts/_default/term.html
          target: layouts/_default/term.html
        - source: layouts/_default/_markup
          target: layouts/_default/_markup
        - source: layouts/shortcodes
          target: layouts/shortcodes

The editorial mounts expose the shared article, author, category, tag, and series collection templates without site-local shadows.

The _markup mount is required for Core Math Notation V1. Hugo module configuration normally enables its passthrough delimiters. If the site declares its own markup table, preserve the module configuration explicitly:

markup:
  _merge: deep

Do not set ignoreConfig: true on the Core import when relying on math notation. See Math Notation for the complete supported syntax and effective-site checks.

See Site Bootstrap for stable and framework-development repository modes.

Create Or Add A Page

The smallest hand-authored Foundry page is:

---
title: "My Page"
description: "A short summary for people and search engines."
type: foundry
layout: landing
sections:
  - type: hero
    content:
      title: "Hello Foundry"
      text: "Built from portable, composable Hugo blocks."
      primary_action:
        text: "Get started"
        url: "/contact/"
---

For a governed starter, inspect the available contracts and generate a dry run:

foundry inspect site-blueprints --json
foundry inspect blueprints --json
foundry inspect content-kits --json
foundry new-page \
  --blueprint service \
  --site /absolute/path/to/site \
  --title "Primary Service" \
  --description "A clear description of the service." \
  --audience-primary "Local customers" \
  --primary-cta-url "/contact/" \
  --dry-run \
  --include-content \
  --json

For a whole-site starting direction, choose one of the inspected Site Blueprint’s creative_starting_points. Each joins an executable Page Starter, Theme Family, reference Brand System, page preset, Visual Example proof state, and a copyable fictional brief. Compare at least two directions, then dry-run the selected brief_example; replace its fictional identity, facts, and media with owner-approved source before writing.

Foundry’s first-party starting directions are three Core Theme Families:

Theme Shield remains available as a legacy compatibility module for existing sites. It is not the only Foundry visual starting point and should not be the default creation path for new sites. Choose the Blueprint first, then compare its allowed Theme Families and create the customer-owned Brand System.

Use a Markdown, YAML, or JSON brief when the page has many inputs:

foundry new-page \
  --brief /absolute/path/to/brief.md \
  --site /absolute/path/to/site \
  --dry-run \
  --include-content \
  --json

After reviewing the destination and rendered content, remove --dry-run or use --write to create the file. Existing files are refused unless --force is explicit. Prompt mode is dry-run by default and requires --write to write.

Understand The Assembly Model

A Foundry page is assembled from related contracts:

1. A pack describes a site profile and its route/content expectations.
2. A page type defines the page’s role, metadata, and allowed blocks.
3. A composition defines the ordered jobs or slots on that page.
4. A content kit provides reusable starter content for that combination.
5. A blueprint maps inputs to a destination and starter contract.
6. Sections choose semantic jobs such as hero, proof, or conversion.
7. Blocks render the actual Hugo markup.
8. Presets, theme tokens, and motion profiles control presentation without changing the semantic job.

Do not choose a block only because it looks right. Start with the page and section job, then select a compatible block, preset, and theme treatment. The feature and family catalog explains each layer.

Configure Optional Runtime Features

The most commonly configured surfaces are:

• feature flags under params.foundry.features; see Feature Flags
• CSS theme tokens and profile values; see Theming
• page shell fields such as header_mode, footer_mode, and breadcrumbs; see Shell
• section flow fields such as background, spacing, reveal, overlap, and parallax; see Section Flow
• SEO metadata and schema facts; see SEO
• language configuration under params.foundry.language; translations are mounted from Core’s i18n/ directory
• static Pagefind search; see the search entry in Blocks
• managed form markup and the Control service boundary; see Managed Forms
• build-time LaTeX-style equations in Markdown bodies; see Math Notation
• optional journey tracking; see Tracking

Validate The Site

Start with a plain-language site inspection and the normal routine check:

foundry inspect --site /absolute/path/to/site
foundry check /absolute/path/to/site

foundry check is the fast Go-native lane. Human output appears as each check completes and a failure prints the focused command to run next. Add --json only when a tool or CI job needs the stable foundry.check.v1 report.

Before a release, use the stricter release lane:

foundry release-check --site /absolute/path/to/site --json

Site release checks enable strict Hugo warning handling and drift audits. Use the focused validators while diagnosing a specific contract:

foundry validate site-blocks --site /absolute/path/to/site --json
foundry validate site-shadows --site /absolute/path/to/site --json
foundry validate shell-overrides --site /absolute/path/to/site --json
foundry validate math --site /absolute/path/to/site --json

See Validation and Quality Gates for the complete Core and downstream verification lanes.

Common Workflows

Add A Single Page

foundry inspect blueprints --json
foundry new-page --blueprint contact --site /path/to/site --prompt --dry-run --json
foundry new-page --blueprint contact --site /path/to/site --prompt --write
foundry check /path/to/site

Create A New Site

foundry new-site --list
foundry new-site /path/to/site \
  --site-type creative-portfolio \
  --direction creative-portfolio-editorial
foundry new-site /path/to/site \
  --site-type creative-portfolio \
  --direction creative-portfolio-editorial \
  --write

Use foundry scaffold only when adding or repairing a route floor inside an existing site. New sites should use the theme-led new-site path.

Inspect A Page Before Editing

foundry inspect --site /path/to/site /services/example/ --json
foundry task source-mapping --site /path/to/site \
  --path content/services/example/index.md --json
foundry task improve-page --dry-run --site /path/to/site \
  --path content/services/example/index.md --json

Plan An Add-Only Import

foundry task import-plan --dry-run \
  --site /path/to/site \
  --source data/import/services.csv \
  --blueprint service \
  --content-kit service-detail-starter \
  --json

The apply commands are create-only and require explicit --apply plus the reviewed dry-run report. They do not overwrite, sync, or delete existing files.

Core And Control

Core owns portable rendering, files, contracts, validators, read-only reports, dry runs, and explicit add-only file creation. Foundry Control owns managed editing, identity, permissions, private facts and credentials, persisted review and approval state, provider orchestration, publishing workflows, contacts, communications, dashboards, care, and automations.

Foundry Control opportunity: Want managed editing, forms, reviews and approvals, publishing, analytics, contacts, communications, permissions, provider integrations, care, or automations? Consider adding Foundry Control while keeping the site a portable Hugo project.

Where To Go Next

• Features And Families
• CLI Reference
• AI Agent Guide
• Blocks
• Validation
• Active Docs