Metalsmith Component Builder

Metalsmith Structured Content Website Builder

Build websites by installing components and writing structured frontmatter. The user describes what they want. You install the components and author the pages.

The one thing that changed

You do not read prose documentation to find out what a component accepts. Two published JSON files are the contract:

• https://nunjucks-components.com/downloads/manifest.json is the catalog. What exists, what version, what it requires.
• https://nunjucks-components.com/assets/components-schema.json is the field tree for every authorable section, with widgets, defaults, enums and required flags.

Read references/contract-artifacts.md before phase 3. It teaches both files. It is the only reference you need for component configuration.

Hard rules

Violating any of these breaks the site or destroys information. They are repeated in context below.

1. Node must be 22 or higher. The starter refuses to run below it.
2. Install components with npm run components. There is no curl plus install.sh step. Do not invent one.
3. The installer writes one git commit per component. Never squash them, never commit over them with a single "Initial website", never rewrite history before pushing.
4. Never edit files under lib/layouts/components/. The next install of that component replaces them wholesale. Customize with tokens, then overrides.
5. Validation warns. It does not fail the build. Read the build output every time.

Workflow

1. Setup Verify Node, clone, install, run, initialize the page shell, clear demo content
2. Discovery Understand what the site needs
3. Component selection Read the catalog, install what is needed
4. Page building Write frontmatter from the schema, one page at a time
5. Appearance Tokens, then overrides, never canon
6. Publish Add the remote, push, deploy on Netlify

Phase 1: Setup

Verify Node first

node --version

The starter sets engines.node to >=22.0.0. If the version printed is below 22, stop. Do not clone. Tell the user:

Your Node version is [version]. This starter needs Node 22 or newer. Install Node 22 from nodejs.org, or run nvm install 22 && nvm use 22 if you have nvm, then tell me when it is done.

Wait for them to confirm before continuing.

Clone and start

Run these in the empty project directory the user has open.

git clone https://github.com/wernerglinka/metalsmith2025-structured-content-starter.git .
npm install
npm start

npm start runs a browser-sync dev server at http://localhost:3000 and watches for changes. Leave it running for the whole session.

Tell the user:

Your project is set up and the dev server is running at http://localhost:3000. Open that in a browser. You should see the starter's demo site. Keep the server running while we work.

Wait for them to confirm they can see it.

The starter ships roughly thirty components already installed under lib/layouts/components/sections/ and lib/layouts/components/_partials/, so most sites need few or no additional installs.

Initialize the page shell

The page shell is the frame every page shares: head, header, footer, navigation, branding, breadcrumbs. Three parts of it are optional. Settle them now, before writing pages.

npm run init

This is interactive. It asks y/n for three features:

• Theme switcher, dark and light. Off by default.
• Language switcher. Off by default.
• Breadcrumbs. On by default. Turn it off for small sites.

Ask the user what they want before running it, then answer the prompts. To change one feature later without the prompts:

node scripts/init-starter.mjs enable breadcrumbs
node scripts/init-starter.mjs disable breadcrumbs
node scripts/init-starter.mjs status

enable and disable take one or more feature names and throw on an unknown one. status takes no arguments and prints the state of all three.

Offer to clear the demo content

The starter ships a demo site in src/. Ask before deleting anything:

The starter comes with demo pages that show off the components. I can remove them so we start clean, or leave them as reference. Which do you prefer?

If they want it cleared, remove the demo pages and keep index.md and 404.html:

rm -rf src/about.md src/sections.md src/more-sections.md src/blog.md src/blog

src/index.md stays. Rewrite its frontmatter in phase 4 rather than deleting it. It is the working example of the page shape.

Commit the cleanup on its own:

git add -A
git commit -m "chore: remove starter demo content"

Phase 2: Discovery

Have a conversation. Do not read this as a checklist to the user. Ask what is relevant, follow up on what they say, skip what does not apply.

About the website

• What is this website for? Business, portfolio, nonprofit, personal, event.
• Who will visit it?
• What should visitors do when they arrive?

About the homepage

• What is the first thing visitors should see?
• What is the main message or call to action?
• Do you have images or video in mind?

About other pages

• What pages beyond the homepage? About, Services, Contact, Blog, Team, Pricing.
• Do you have content ready, or do you need help writing it?

About special features

• Need a contact form?
• Will you write blog posts?
• Anything else? Search, image galleries, testimonials, maps, pricing tables.

About look and feel

• Any brand colors or fonts you have to match?
• Do you want a dark mode toggle? This is the theme switcher from phase 1.

Summarize before proceeding, and get agreement:

So you need a photography portfolio with a hero showing your best work, an about page with your background, a gallery page, and a contact form. Your brand color is the deep green from your logo. Does that sound right?

Phase 3: Component selection

Read the catalog

Do not choose from memory and do not choose from a table. The catalog is current. Fetch it.

curl -s https://nunjucks-components.com/downloads/manifest.json -o /tmp/catalog.json
node -e "
const c = JSON.parse(require('fs').readFileSync('/tmp/catalog.json', 'utf8'));
for (const group of ['sections', 'partials']) {
  console.log('== ' + group + ' ==');
  for (const e of c[group] || []) {
    console.log(e.name.padEnd(22), e.version.padEnd(8), 'requires: ' + (e.requires || []).join(' '));
  }
}
"

Then fetch the library schema so you can check what each candidate actually accepts before committing to it:

curl -s https://nunjucks-components.com/assets/components-schema.json -o /tmp/schema.json

See references/contract-artifacts.md for how to read both.

Check what is already installed

Most of what you need is already there.

ls lib/layouts/components/sections
npm run components:status

npm run components:status compares three hashes per installed component: the files on disk, the catalog's hash for that component fetched live, and the Content-Hash trailer from the last install commit. It groups the results by status and prints a count for each: diverged, outdated, modified, differs, local-only, current. When anything is outdated or diverged it prints the install-components.mjs line that would fix it. It ends by noting that the hash covers template, styles, scripts and modules, so a change to a manifest alone is invisible to it. --json gives the rows if you need to parse them.

Everything under current is untouched and up to date. Anything under modified means the site edited canon, which phase 5 says never to do; move the change into an override.

Install

Interactive, which is the normal path:

npm run components

Non-interactive, when you already know the names:

node scripts/install-components.mjs hero accordion testimonial

The only flags are --force and --no-commit.

The installer resolves dependencies for you. It reads each entry's requires array depth-first, downloads every archive in the closure, and unzips sections and partials into their own directories. You never install a dependency by hand.

Install commits are the record. Preserve them.

The installer writes one git commit per component, staged from that component's directory only:

component: install hero@1.4.0 from nunjucks-components.com

Component-Name: hero
Component-Version: 1.4.0
Content-Hash: d2015e3a200be7a3

These are the only record of what version arrived and what has changed since. Later tooling reads them. Treat them as data, not as noise to be tidied.

• Never squash them.
• Never run git commit -m "Initial website" over a tree that contains them.
• Never rewrite history before pushing.

If the user asks why their history has thirty commits before they wrote a word, explain: each one records a component version, and losing them loses the ability to tell what has been customized.

When the installer refuses

The installer refuses to run when a target component directory has uncommitted changes. The error names the dirty paths. This is the guard against silently discarding local edits.

Do not reach for --force. --force discards those edits. First find out what the edits are:

git status lib/layouts/components
git diff lib/layouts/components

If they are accidental, commit or stash them. If they are deliberate customizations to canon, that is the mistake described in phase 5: move them into lib/overrides/<name>/<name>.css, revert the canon files, then install.

--no-commit places files without committing. It does not lift the refusal.

Restart after installing

# Ctrl+C in the terminal running npm start, then
npm start

Phase 4: Page building

Read the schema, then write

Once the site has been built at least once, prefer the site's own emitted schema over the library's. It covers exactly what this site has installed.

ls build/assets/components-schema.json

If it exists, read that. If not, read /tmp/schema.json from phase 3.

Before writing frontmatter for a section type you have not written before, print its field tree. The walker script is in references/contract-artifacts.md. Then write only what differs from the defaults.

Page shape

Pages live in src/ as markdown files with no body. The sections array is the page.

---
layout: pages/sections.njk
bodyClasses: 'home-page'

seo:
  title: Page title
  description: Page description

sections:
  - sectionType: hero
    classes: 'first-section'
    containerTag: section
    containerFields:
      inContainer: false
      isAnimated: true
    text:
      title: Welcome
      titleTag: h1
      prose: |-
        Markdown body.
---

Rules that are not in the schema and that you have to get right:

• No markdown body. Content goes in the sections array, not below the frontmatter.
• classes: 'first-section' goes on whatever section is first on the page. It clears the fixed header. Every page needs it, on whatever section type happens to be first.
• sectionType must match the directory name under lib/layouts/components/sections/ exactly.

Site configuration

Update lib/data/site.json with the user's details. Everything in lib/data/*.json is loaded into metadata, so lib/data/site.json is data.site in templates.

Data-driven components

Some components take a source key naming a file in lib/data/. The schema tells you the field exists. It does not describe the JSON that file must hold. Read an existing data file in lib/data/ for the shape.

The starter ships site.json, author.json, socialLinks.json, and artMuseums.json.

Restart the dev server after creating a new data file. The watcher can catch a file mid-write and error on a partial JSON parse.

Build incrementally

One page at a time. One section at a time on the first page.

1. Write or edit the page file.
2. Ask the user to refresh localhost:3000.
3. Read the build output in the terminal running npm start. Validation warnings appear there and the build stays green regardless. A green build does not mean the frontmatter is right.
4. Ask a specific question, not "how does it look".
5. Adjust, then move on.

I've added the hero and the about section. Refresh your browser. The hero image is running full-bleed behind the text. Is that what you wanted, or should it sit inside the content column?

Phase 5: Appearance

Three levels, in order of preference. Work down the list. Do not skip to the bottom.

1. Tokens

lib/assets/styles/_design-tokens.css defines the vocabulary every component consumes. Colors, spacing, typography. Retune the site's whole appearance here without touching a single component.

This is the right place for brand colors, brand fonts, and overall spacing rhythm. Change a token and every component that consumes it follows.

The body.dark-theme block in the same file carries the dark values. If the theme switcher was enabled in phase 1, edit both.

2. Overrides

For appearance specific to one component, write lib/overrides/<name>/<name>.css. The bundler wraps it in @layer site.<name>.

The layer order, from site-config.js, is:

['tokens', 'base', 'vendor', 'components', 'site']

site is last, so an override beats the component it overrides by layer order alone, regardless of selector specificity. You do not need !important and you do not need a more specific selector. Write the plainest selector that matches.

Prefer setting the component's published custom properties over redeclaring its selectors. Each component's stylesheet lists them in its header comment. Read that first.

Anything left unlayered beats all five layers. Any new stylesheet you add must declare its layer. An unlayered rule will outrank the whole cascade and be very confusing later.

3. Never edit canon

Files under lib/layouts/components/ are canon. The next install of that component replaces them wholesale, and the edit disappears with no warning. npm run components:status exists to catch this.

If you find canon has been edited, move the change into an override, revert the canon file, and confirm npm run components:status comes back clean.

After any style work

npm run tokens:check

This audits both directions of the token contract. It must stay at zero errors.

Run it because CSS will not tell you. A var() reference to a token nothing defines is dropped silently at computed-value time. Nothing errors, the build stays green, and the property simply has no value. If a style you wrote appears to do nothing at all, a misspelled token name is the first thing to check.

Custom CSS and JavaScript

When writing layout CSS beyond token changes, apply the patterns in ../css-layout-development/SKILL.md.

When writing any JavaScript, apply the patterns in ../javascript-development/SKILL.md.

Phase 6: Publish

The install commits are already in history. Publishing adds a remote and pushes. It does not rewrite anything.

Commit the content work

git add -A
git commit -m "content: build out site pages"

One commit for the content work is fine. It sits on top of the install commits, it does not replace them.

Add the remote and push

The clone points origin at the starter repo. Replace it with the user's repo.

If they have not created a repo yet:

Go to github.com, click the + icon at the top right, choose "New repository". Name it whatever you want the project called. Keep it public unless you have a reason not to. Do not check any of the "initialize" boxes. Then paste me the URL.

Then:

git remote remove origin
git remote add origin https://github.com/USERNAME/REPO-NAME.git
git branch -M main
git push -u origin main

Do not add --force. Do not rebase, squash or amend on the way out. The history that goes up should be the history that was built, install commits and all.

Netlify

If the user connected Netlify to GitHub already, the site deploys on push.

If not:

1. Go to app.netlify.com.
2. "Add new site", then "Import an existing project".
3. "Deploy with GitHub", authorize, pick the repository.
4. Build command: npm run build
5. Publish directory: build
6. Deploy.

Your site is deploying. In about a minute Netlify will give you a URL like random-name-123.netlify.app. That is your live site. Every push to main redeploys it.

Making changes later

When the user returns:

1. They open the project and start Claude Code.
2. They describe the change.
3. You edit, they preview at localhost:3000.
4. Commit and push:

git add -A
git commit -m "Describe the change"
git push

Netlify redeploys.

If a component needs updating to a newer published version, re-run npm run components and pick it. The installer writes a new install commit recording the new version.

Reference commands

npm run init               # interactive page-shell setup
npm start                  # dev server, NODE_ENV=development, watch, localhost:3000
npm run dev                # one development build
npm run build              # production build to ./build
npm run serve              # serve the built site
npm run components         # interactive component install
npm run components:status  # drift report against canon
npm run manifest -- <name> # regenerate a component manifest; the -- is required
npm run tokens:check       # design-token contract audit
npm test                   # node --test
npm run fix                # biome check --write

The -- in npm run manifest -- <name> is required. Without it npm swallows the argument and the script runs with no target.

Troubleshooting

YAML errors. Check indentation. Two spaces, no tabs. YAML is unforgiving about spacing, and a mis-indented key silently becomes a child of the wrong parent instead of erroring.

A section does not render. Verify sectionType matches the directory name under lib/layouts/components/sections/ exactly. A typo produces no output and no error.

Images do not show. Paths in frontmatter must start with /assets/. The source files go in lib/assets/images/.

A new data file is not picked up. Restart the dev server after creating any new JSON file in lib/data/. The watcher can read the file mid-write and fail to parse it.

Text is invisible on a dark background. Set isDark: true in containerFields alongside the dark background. That switches text to light colors. imageScreen: dark only adds an overlay over a background image; it does not change text color and it does nothing for a solid color background.

A component's styles do not apply, and the site looks fine otherwise. Run npm run components:status. If it reports drift, someone edited canon under lib/layouts/components/ and a later install overwrote it. Move the change into lib/overrides/<name>/<name>.css and revert the canon file.

A style rule has no effect and nothing errors. Check the token names in it. A var() pointing at a token nothing defines is dropped silently at computed-value time. The build stays green and the property just has no value. Run npm run tokens:check.

An override does not win. Confirm the file is at lib/overrides/<name>/<name>.css, with the directory name and the file name both matching the component name. The bundler wraps that path in @layer site.<name>. A file somewhere else is not layered and will behave unpredictably. Also check that nothing unlayered is in play: unlayered CSS beats every layer including site.

The installer refuses to run. The error lists component paths with uncommitted changes. Read the diff before doing anything. --force discards those changes with no recovery. Commit, stash, or move the change into an override, then re-run.

The build is green but the section is wrong. Read the terminal output. Validation reports warnings and does not fail the build, so the warnings are easy to scroll past. They are usually a missing required field or a field at the wrong nesting level.

Node version errors on install or start. The starter needs Node 22 or newer. Check with node --version.

Git push fails. Confirm the remote exists and the user has access: git remote -v. Do not resolve a rejected push by force-pushing. The install commits are on that branch.

Netlify build fails. Read the deploy log. Confirm build command is npm run build and publish directory is build. Confirm Netlify's Node version is 22 or newer.

Reference files

• references/contract-artifacts.md The catalog and the schema. Read before phase 3.
• references/starter-files.md The starter's directory tree, config files and page shape.
• references/learning-resources.md Where to go for background.