Build your first Foundry site

This guide uses the maintained starter template (likestyle-foundry-starter) so new sites are runnable immediately with Foundry core + theme.

The starter is a reference implementation pinned to a known compatible bundle. Treat it as the baseline for new sites and for evaluating future upgrades.

Prerequisites

Install these first:

• Hugo Extended >= 0.155
• Go >= 1.19
• Node.js >= 20
• pnpm >= 9

1) Choose a Stable Bundle

Before creating or upgrading a site, choose a stable bundle from likestyle-foundry-distribution.

That bundle tells you:

• which module tags belong together
• which starter version matches them
• which verification commands must pass

2) Clone Starter and Run Locally

git clone https://github.com/jerrybroughton/likestyle-foundry-starter.git my-site
cd my-site
pnpm install
pnpm dev

Open http://localhost:1313.

3) Understand Starter Structure

Key files:

• go.mod: Pins module versions (core + theme).
• config/_default/module.yaml: Hugo module imports/mounts.
• config/_default/hugo.yaml: Base URL, title, cascade (type: foundry, layout: landing).
• config/_default/params.yaml: Feature flags + header/footer params.
• config/_default/menus.yaml: Main navigation.
• content/_index.md: Homepage block composition.
• content/about.md, content/contact.md: Example inner pages.

When you create a site from starter, keep those versions pinned until you are ready to adopt a newer Foundry bundle.

4) Customize Brand

Fast customizations in params.yaml

Update:

• site title in config/_default/hugo.yaml
• logo in config/_default/params.yaml
• header.cta
• footer.tagline

Theme color/font variables

Theme tokens live in CSS custom properties (--foundry-*).

Recommended approach:

1. Add a small site stylesheet (for example assets/css/site.css) with token overrides.
2. Load it via a local layouts/partials/css.html partial.

Optional pattern for keeping brand values in params.yaml:

foundry:
  theme:
    brand_primary: "#1f3b82"
    brand_primary_strong: "#162a5d"
    brand_accent: "#c7352f"

Then output these as CSS variables in a local layouts/partials/head-start.html override.

5) Add/Arrange Content Blocks

Pages are composed with sections in front matter.

---
title: "Your Page"
type: foundry
layout: landing
sections:
  - block: hero
    content:
      title: "Your headline"
      text: "Your supporting copy"
      primary_action:
        text: "Get Started"
        url: "/contact/"
  - block: features
    content:
      title: "Core capabilities"
      items:
        - name: "Capability 1"
          description: "What it does"
---

The order in sections is the render order.

6) Available Blocks

Foundry ships 40+ blocks (hero, features, steps, pricing, tabs, gallery, accordion, page-list, and more).

• Full contracts + examples: docs/BLOCKS.md
• Canonical block implementation template: layouts/partials/blocks/_template.html (in core)
• Block design options registry: data/foundry/block-options.yaml (in core)

7) Deploy

GitHub Pages

• Build command: pnpm build
• Publish directory: public/
• Add CI that installs Hugo Extended + Go + Node, then runs pnpm install && pnpm build.

Netlify

• Build command: pnpm build
• Publish directory: public
• Ensure Hugo Extended is selected in environment.

Manual rsync / SSH

pnpm build
rsync -avz --delete public/ user@server:/var/www/your-site/

8) Upgrade Safely

When you want newer framework features:

1. pick a newer distribution bundle
2. update your pinned module versions
3. run the bundle verification steps
4. review visual changes on key pages
5. deploy only after the upgrade passes

9) Next Docs

• Architecture: docs/ARCHITECTURE.md
• Theming and token overrides: docs/THEMING.md
• Migration from older Foundry setups: docs/MIGRATION.md
• Compatibility and upgrade policy: docs/COMPATIBILITY.md