Labelled demo site — not a live bakery. Get started

Example / demo website. Fictional business. Not a real company, review, or service listing.

Enquire

Build a website from this boilerplate

This page is the in-browser copy of docs/getting-started.md: run the demo, start a new client site in its own Git repo, and share mockups and design spec.

What you are looking at

This is a static HTML foundation for SEO client websites. Content is JSON. Markup is HTML templates. One Python command writes a complete site into dist/.

  • No npm, framework, database, or CMS in v1.
  • JavaScript is optional. Pages must work with it blocked.
  • A live client site is never a branch of this boilerplate. Copy the source into a new independent Git repository. There is no automated sync of later boilerplate changes into client repos.

What you need

Python 3, Git, a text editor, and permission to create a Bitbucket (or other) repository for the client. For a real job you also need the design file (usually Figma). On Windows, use py -3 if python is not on your PATH. You do not need Node.js.

1. Build and preview this demo

From the boilerplate repository root:

py -3 scripts/build.py
py -3 -m http.server --directory dist

Open the homepage via http://127.0.0.1:8000/ — not as a file:// URL. Every successful build deletes and recreates dist/. Do not edit those files by hand.

2. How a page is made

  1. Shared facts go in src/data/site.json.
  2. Each page is a JSON file in src/data/pages/.
  3. scripts/build.py fills the page template and partials, then writes dist/.../index.html.
  4. Canonical URLs, sitemap, robots.txt, and JSON-LD are generated at the same time.

Change copy in JSON and rebuild. You should not need to edit the build script for a normal brochure site.

3. Configure the business

Do this in the client repository after you copy (section 8), not as a long-lived fork of the boilerplate. Edit src/data/site.json: name, production domain only (no https, no staging host), language, real telephone, email, and address, HTTPS social URLs, optional icons, og.image (a 1200×630 JPEG or PNG on live sites), forms.adapter (not none once demo is off), structured hours objects or omit the key, leave Trustindex off unless reviewed, footer.legal_page_ids for privacy / cookies / terms, navigation entries that match page id values, and remove "demo": true. Rebuild, then check the header, footer, and sitemap.xml.

4. Replace the example pages

Edit the JSON under src/data/pages/. Required fields include id, type (home, content, or error), slug (empty string for the homepage), title, seo_title, h1, and content. Public URLs always use a trailing slash, for example About, Areas, Services, Knowledge Hub, Privacy policy, Cookies, and Terms of use. The homepage, About, services, areas, Knowledge Hub, contact, and legal pages are lists of modules in JSON, not unique template files. Legal templates are not a compliance guarantee.

Indexable pages need unique titles and unique H1s. Duplicate slugs fail the build. Missing meta descriptions warn; they do not fail the build. Indexable pages also need Open Graph title, description, image, and url. Never invent reviews, ratings, awards, or addresses.

5. Add a new page

  1. Copy src/data/pages/about.json to a new file.
  2. Give it a new id, slug, titles, H1, and copy.
  3. Add that id to navigation in site.json.
  4. Rebuild. Visit the new trailing-slash URL.

Ordinary pages use the standard content layout. Home, About, /services/, /areas/, and contact opt into modules. This guide uses settings.body_partial to load getting-started.html instead. You only need that for a custom main body. The host must map unknown URLs to HTTP 404 and dist/404.html; the HTML cannot fake that status.

6. Rebrand

Map the agreed design (section 9) onto CSS tokens. Change colours and type in the :root block of src/css/base.css. Replace the header/footer file in src/assets/branding/ and site.logo. Replace other images in src/assets/images/. Fonts go in src/assets/fonts/ (no Google Fonts by default). Do not add a CSS framework. Do not put primary content in src/js/main.js.

7. When the build fails

The command prints error: and a file or field name, then exits non-zero. Typical causes are missing required fields, an invalid slug, duplicate URLs, a missing title or H1, a broken internal link, a staging hostname in production SEO output, two area pages sharing the same body / leftover [town] placeholders, or unresolved privacy tokens such as company-name placeholders when demo is off. Fix the source and rebuild.

8. Start a new site from scratch (new Git repository)

A new website is a copy, then it lives on its own. Do not keep shipping the client from this boilerplate remote.

  1. Create an empty Git repository for the client (Bitbucket or wherever the team hosts client sites). Suggested folder: client-name-website. Do not add this boilerplate as a submodule, subtree, or package.
  2. Copy source, not generated output: src/, scripts/, docs/, README.md, CHANGELOG.md, BOILERPLATE_VERSION, .gitignore. Do not copy dist/ as source.
  3. Initialise new history in that folder (the first commit starts the client repo):
cd client-name-website
git init
git add .
git commit -m "Initial site from boilerplate."
git remote add origin <new-client-repo-url>
git push -u origin HEAD
  1. Leave BOILERPLATE_VERSION as the version this site started from. It is a human record, not a live link back to the boilerplate.
  2. In that repository, do sections 3–6 (real site.json, pages, tokens, assets), then:
py -3 scripts/build.py
py -3 -m http.server --directory dist
  1. Before production, work through docs/pre-launch-checklist.md.
  2. Deploy the client repository (or its generated dist/) on HTTPS with the production hostname. Do not deploy client sites from this boilerplate repository. More copy/deploy rules: docs/new-client.md.

9. Share mockup and design spec

This boilerplate does not store Figma files and is not a design CMS. Split design intent from HTML preview.

Design spec

  • Keep a Figma file per client (or a clearly named page in a shared file).
  • Share the Figma link with comment access for designers, account, and client sign-off.
  • Put that URL in the client README and/or the Jira ticket.
  • When you implement, map Figma tokens to :root in src/css/base.css.
  • Do not commit huge PNG dumps of every artboard unless someone needs an offline PDF.

HTML mockup

The shareable site is generated dist/, not src/.

  • You, locally: py -3 -m http.server --directory dist after a successful build.
  • Team / client review: host dist/ on a password-protected or otherwise gated preview. Do not put that hostname in site.json domain, canonicals, sitemap, robots, or JSON-LD.
  • Pictures only: Figma, or a short PDF export from Figma.

Bitbucket is for code (pull requests). Point the PR at the Figma file and, if you have one, the gated preview URL.

Practical order: agree Figma → create the client Git repo (section 8) → tokens + JSON + assets in that repo → rebuild dist/ → share Figma for spec and gated HTML for “this is the site.” After launch, the live domain is the public site; Figma remains the design record.

Contact page is demo content only — replace it in the client repo before go-live.

What not to do

  • Do not treat dist/ as source.
  • Do not add npm, React, a CMS, or a database for a standard v1 site.
  • Do not invent reviews, ratings, or addresses.
  • Do not put staging hosts in canonicals, sitemap, robots, or JSON-LD.
  • Do not wire live clients back to this repository as a submodule or package.
  • Do not automatically push boilerplate upgrades into live client repos.
CallEnquire