← Back to thinking
Thinking

How this site is built

The site itself is a small case study in context design: plain files, no database, and nothing shown to you that isn't the real thing underneath.

0 database tables, admin logins, or hidden layers between what you read and what's on disk

Why bother explaining this

Most "how this site was built" posts are written for other developers. This one isn't. It's here because the same argument this site makes about AI and business context turns out to be just as true about the site itself: the interesting part was never the tool, it was what the tool was given to work with.

So this is a short, plain explanation of what's actually happening when a page loads, for anyone curious rather than technical. Nothing on it is generated on the fly for a visitor, and nothing is hidden behind a login. It happens in four small, ordinary steps.

How a page gets built

  1. 1 You open a page A case study, an article, a demo. Nothing more than a normal web address.
  2. 2 The site finds the matching file Every case study, article and demo on this site is a plain text file sitting in a folder, not a row hidden inside a database.
  3. 3 The file becomes a page A small program reads that file and lays it out in the site's design, the same way a printer lays text onto a page template.
  4. 4 You see the result What arrives in your browser is only ever that file, formatted. Nothing is added, summarised or invented along the way.

The file behind this exact page

The "Human / Machine" toggle at the top of this article isn't a mock-up of what the raw file might look like, it switches to the actual file. This is it:

Every case study and demo on the site works the same way. There's nothing to unlock or dig for; the toggle is just a shortcut to what was already there.

content/thinking/how-this-site-is-built.md

  • title: How this site is built
  • slug: how-this-site-is-built
  • summary: the one-line description you read at the top of the page
  • everything below the frontmatter: this article, word for word, in plain text

What's actually worth noticing

None of this is complicated engineering. That's rather the point. Every choice above is small and legible on its own; the only skill involved is deciding, deliberately, what a visitor and a machine each need to be given to understand this correctly. Which is the same job described everywhere else on this site, just applied to the site rather than to a client's problem.

Plain files instead of a database anyone can read the source, not just a developer with admin access
The Human / Machine toggle what you're shown is the real file, not a simulation of one
Structured data on every page the site is written to be understood correctly by AI systems too, not just people reading it
The sitemap and llms.txt rebuild themselves add a file and it appears everywhere automatically, nothing kept in sync by hand
The interactive demos on the Work page the argument about context isn't just stated here, it's something you can try

Frontmatter: content/thinking/how-this-site-is-built.md

title: How this site is built
slug: how-this-site-is-built
summary: 'The site itself is a small case study in context design: plain files, no
  database, and nothing shown to you that isn''t the real thing underneath.'
stat: '0'
stat_label: database tables, admin logins, or hidden layers between what you read
  and what's on disk

If this way of thinking is relevant to a problem you're facing, I'd be glad to talk it through.

Start a conversation