How It Works
Your inputs go in, a deployed website comes out — and everything operational stays beside it.
Foundation is easiest to understand as one direction of flow with one clear boundary: what you own goes in, and what you get out is a static site you host yourself, connected to the systems that run your business.
- Site-owned inputs, Foundation machinery, your deployed site
- External systems sit beside Foundation, never inside it
- Everything below is verifiable in the repository
What you own goes in
Everything on the left of the flow is yours and stays yours. None of it is platform code.
Configuration
Identity, languages, navigation, feature switches and UI choices — validated settings rather than scattered constants.
Content
Your pages and collections as files in your repository, each with its own title and body.
Translations
One interface dictionary per language, plus the content directory for that language.
Branding and assets
Your logos, favicon, social preview and any optional artwork, each in a named role.
You can change any of these without touching the foundation's architecture.
What Foundation does with them
Foundation reads your inputs and produces the site. This is the part you did not have to build, and it runs when you build and deploy — not while a visitor waits.
1
Validation
Configuration and dictionaries are checked against their schemas, so a mistyped setting fails the build instead of reaching a visitor.
2
Content and routing
Pages are loaded through a content interface, given stable addresses, and fall back per page when a translation is missing.
3
Presentation
Your content and identity are composed through the shared design-token system, in light or dark, at every viewport.
4
Discovery and metadata
Titles, canonical addresses, language annotations, structured data, sitemap and robots output are generated from what you configured.
5
Integration seams
Where you enabled a capability, Foundation renders the connection and hands visitor intent to your provider.
6
Output
A static website, built and deployed to your own account and domain.
Nothing here is a service you rent: the same repository can be built anywhere you can run it.
What runs beside Foundation, not inside it
Foundation expresses intent — "book an appointment", "get directions", "send a message" — and the destination behind that intent is yours to change. It does not become these systems.
- Booking and scheduling
- Enquiry and message receivers
- Maps and directions
- Analytics
- CRM and customer records
- Payments and accounting
- Customer accounts and sign-in
- Any other system your business already runs
An external service is connected through a seam; the service keeps its data, its rules and its own account.
From obtaining Foundation to a site you maintain
Ten practical steps. The repository's own manuals carry the detail — this page shows the shape of the work.
1
Obtain it
Clone or fork the public repository into your own account.
2
Run it
Install and start it, to see a working site before you change anything.
3
Configure it
Set your identity, languages, navigation and feature switches in configuration.
4
Add your identity
Replace the named artwork roles with your own logos, favicon and previews.
5
Author your content
Write your pages and collections as files in the repository.
6
Choose your capabilities
Turn on only what you need; an unused capability adds no routes and no placeholders.
7
Connect your providers
Point each enabled seam at the provider you already use.
8
Validate it
Run the gate and the browser verification, so problems appear before your visitors do.
9
Deploy it
Build and deploy to your own account and domain.
10
Maintain it
Keep your content and configuration yours, and absorb future improvements when you choose to.
The website never becomes a second copy of the GitHub manuals.
Who owns what
Foundation is infrastructure you hold rather than a service you rent. The split is deliberately plain.
You own
- Configuration, identity and navigation
- Content and collections
- Locale dictionaries and translations
- Branding and all artwork
- Provider choices and their accounts
- Your hosting account, domain and deployment
- Everything you or your supplier add afterwards
Foundation owns
- The reusable architecture and its enforced boundaries
- Presentation machinery and design tokens
- Routing and the content pipeline
- Configuration validation
- The integration seams
- The verification infrastructure
You can leave, and everything you own leaves with you — the repository is your source.
What happens when you change something
Two deliberate rules keep this predictable: content decides existence, configuration decides presentation — and neither can silently invent the other.
Site name, tagline or description
Header, footer, page titles, social metadata and structured data.
A page's own file
That page's content, and the generated sitemap.
A dictionary file
The interface strings for that language.
The accent colour token
Every branded and emphasis element across the site.
A logo, favicon or preview asset
The corresponding visual role only.
Navigation configuration
Menu order and labels — never whether a page itself exists.
A feature switch
Whether that capability's routes and surface exist at all.
An operational location
That location's own opening status, address, directions and structured data.
An absent optional thing renders nothing: no placeholder page, no borrowed artwork, no empty shell.
Why a bad change fails early
Your configuration is checked when the site is built rather than when a visitor arrives, so mistakes surface immediately.
- An unknown or misspelled setting is rejected, not ignored
- A structurally invalid value fails the build, naming the setting
- A capability that is configured but incomplete fails rather than silently rendering nothing
- A declared language with no dictionary fails instead of quietly showing another language
That is why the loop is: change a file, build, and see the truth — rather than discovering it in production.
Adopting improvements without losing your work
Your configuration, content, dictionaries and assets sit in their own areas, which is what makes a later improvement possible to take without rewriting your site.
- Your site's own areas are yours to keep as you upgrade
- You decide when to adopt an improvement, rather than being pushed into it
- The repository records what changed and why, so the decision is informed
This is the documented model. It is not an automatic update service, and the project does not claim one.
Start from a working base
Read the capabilities, look at two businesses already running on it, then start from something that already works.