Documentation
DOCUMENTATION
The Foundation documentation is not a brochure with a manual attached. It is the operating knowledge for the software, published in the same repository as the code it describes — so it cannot drift away from what it explains, and it stays available to you whatever happens next.
Everything published here is public
You can read all of it before deciding whether Foundation is right for your project, and you can follow it yourself, at your own pace, without an account or a conversation. Nothing is gated, and there is no version of it reserved for customers.
That is a deliberate part of how the project is built. A platform is only genuinely reusable if the knowledge needed to adopt it, configure it, deploy it and keep it current travels with the software rather than staying with whoever wrote it.
The operating manuals
Eight manuals, each authoritative for its own subject. They are written for someone who has never seen Foundation before.
- Adoption — creating a new Foundation project
How a new project is established from an immutable Foundation release, so it starts with the platform and the operating knowledge together.
- Deployment — taking a validated site live
The workflow and the critical checks before a site goes live, including the domain and DNS work that only the owner of an account can do.
- Foundation Upgrade — absorbing a newer release
How a newer Foundation release is adopted, and how the classification of platform-owned and adopter-owned files protects your configuration, content, assets and branding.
- Site customization
The downstream user guide: what to edit, how to add a language, and where a site's identity actually lives.
- Branding and assets
The asset roles a site replaces with its own artwork, and how each one is swapped.
- Content management
How pages and their files are authored, in both the Markdown and the declarative JSON form.
- Validation
The gate a change has to pass, and what each check in it actually proves.
- Troubleshooting
What to do when something looks wrong, beginning with the checks that resolve most problems.
At the top of the repository
Five documents that describe the product itself rather than a procedure.
Following them needs no account and no permission
The manuals assume you are working in your own copy of the repository, with your own deployment and your own domain. There is nothing to register for and nobody to ask. Where a step needs something you do not have — access to a domain's DNS settings, for instance — the manual says so plainly, because that is where the work stops without it.
Where to go next
Where to begin
The order that wastes least time. Each step names the document that covers it.
Read what Foundation is
The repository README: what the platform provides, what it deliberately leaves out, and what a site built on it looks like.
Look at it running before reading more
Start it locally and click through the base site. An hour spent using it answers more questions than a day spent reading specifications.
Decide how you will hold it
One site or several, your own accounts or a managed arrangement. This decides more of the rest than any technical choice does.
Establish your own project
The Adoption manual: creating a project from a Foundation release, so you start with the platform and the operating knowledge together.
Make it yours
Site customization and branding and assets: identity, content, languages, artwork — in configuration and files, not by editing the platform.
Deploy it on your own domain
The Deployment manual and the launch runbook, including the DNS work that only the owner of the domain can do.
Keep it current
The Foundation Upgrade manual when a newer release is worth adopting, and the Validation manual for what the gate proves.
What the manuals assume — and what they do not
The manuals are written for a competent developer who has never seen Foundation. They assume you can use a terminal, run a package manager, edit files and deploy a web application to a provider of some kind. They do not assume you have written a framework, and they do not assume you will read the whole architecture before doing anything.
They also assume the work is yours to do. Every procedure is written for somebody working in their own copy of the repository, with their own hosting account and their own domain. Where a step cannot be completed without something only an account owner can supply — access to a domain registrar's DNS settings, for instance — the manual says so at that point rather than leaving it to be discovered later.
What they do not do is make decisions for you. They describe the platform's supported options and the consequences of each; they do not tell you which hosting provider to use, how many languages to publish, or whether to operate the site yourself. Those are decisions about your business, and the documentation's job is to make them informed decisions rather than accidental ones.
One further limitation is worth stating plainly, because it is easy to assume otherwise. The manuals describe the platform's own behaviour and the adopter's responsibilities. They cannot describe the internal workings of any third-party service a site connects to, and they do not claim to: where a seam points at somebody else's product, the documentation of that product is authoritative.