Troubleshooting

Most problems come down to a file path, a JSON typo or browser caching. Find your symptom below.

The page has no styling (plain text, blue links)#

The page can't find assets/. Pages inside a demo folder load ../assets/…, so the assets folder must sit next to the demo folder, not inside it. Upload both.
With npm run site, upload the contents of site/, so index.html and assets/ are directly in your web folder.

My changes don't show up#

Refresh without the cache: Ctrl + Shift + R (Windows) or Cmd + Shift + R (Mac).
Using the source files? Make sure npm run dev is running, or run npm run build / npm run site again, and check the terminal for errors.
Edited a file in dist/ or site/? Those are regenerated on every build; edit src/ instead.
Edited an HTML file but the change is on another page? The header and footer are repeated on every page; see Changes on every page.

The build says “Unexpected token” or “Demo skipped”#

A JSON file has a typo. The message names the file and position, e.g. src/demos/cafe/pages/about.json: Unexpected token } in JSON at position 812. Usual causes:

A missing comma between two items, or a comma after the last item in a list: ["a", "b",] is not allowed.
Curly quotes “ ” instead of straight quotes ", often from pasting text from a word processor.
A double quote inside text. Write it as \", or use typographic quotes “like this”, which are fine inside text.

Visual Studio Code underlines JSON mistakes in red as you type. The other demos keep building while one has an error.

The build says “unknown type”#

A section's "type" is misspelt. Compare it with the names in the section reference.

npm or node “is not recognized” / “command not found”#

Node.js isn't installed, or the terminal was open before you installed it. Install it from nodejs.org, then close and reopen the terminal.

“Cannot find module” when building#

Run npm install in the source folder first. Make sure your terminal is in source (the folder containing package.json).

Port 3000 is already in use#

Another program (or a second npm run dev) is using it. Close it, or start on another port: PORT=4000 npm run dev (macOS/Linux) or $env:PORT=4000; npm run dev (PowerShell).

My images don't appear#

Source files: the file must be in src/img/ and the path must start with assets/img/ (not src/, not ../).
HTML files: pages in a demo folder need ../assets/img/….
File names are case-sensitive on most web servers: Photo.JPG is not photo.jpg. Use lowercase names without spaces.

A font doesn't load#

Check the spelling matches Google Fonts exactly (including capitals and spaces). If the font has only one weight, set headingFontSpec/bodyFontSpec; see Fonts.

The form says thanks but I get no email#

The form is still in demo mode: set formAction (and newsletterAction) in site.json, or change action="#" in the HTML. If you use send.php, check your hosting supports PHP mail and look in your spam folder. See Forms.

The map is blank#

Maps need an internet connection and don't load in some browser privacy modes. Check the address in map/query is one Google Maps can find.

The colour looks different from what I set#

A visitor's colour-switcher choice is remembered in their browser, and that includes yours. Click the palette button and choose the first (default) scheme, or remove the switcher for your live site.

Grids have a gap or a lonely card#

Use item counts that fill the rows: 3 or 6 in three columns, 4 or 8 in four, 2 or 4 in two. Bento grids need tile sizes that add up; see Bento.

Opening index.html from my computer shows a blank map or no fonts#

That's expected when offline: maps and Google Fonts load from the internet. Everything else works from the files.

Still stuck?#

See Support. Tell us the demo and page, what you changed, and any error text from the terminal or the browser console (press F12 → Console).