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.

Foundry can be used on its own.

LikeStyle Control is optional. LikeStyle hosting is optional.

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.

At this point you have a normal Foundry site. You do not need LikeStyle Control or LikeStyle hosting to build, run, or deploy it.

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.

If you later choose to connect the site to LikeStyle Control or other tooling, that should be an additive decision on top of this baseline, not a prerequisite for using Foundry.

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

Foundry output is standard static site output. Deploy anywhere compatible with a static Hugo build.

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/

Other deployment targets are equally valid as long as they can serve the built site correctly.

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

• Charter and product stance: docs/CHARTER.md
• Owner visibility and inventory: docs/OWNER-INVENTORY.md
• Shared framework acceptance rules: docs/ACCEPTANCE-RULES.md
• 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