Consistency Is Infrastructure

The Metalsmith Redux series kept circling one claim: structure you can read is structure a machine can read too. This is the chapter where that claim stops being a nice property and becomes infrastructure.

In one coordinated pass I brought seventeen of my Metalsmith plugins to a single modern standard. On its own that is housekeeping, and not worth a post. What makes it worth writing down is what the housekeeping produced. Once every plugin agrees on how a component describes itself, the description becomes data, and data accepts more than one kind of author.

The Sweep

Seventeen plugins, republished together, all moved onto the same footing: ESM, Node 22, the native test runner, the same project layout and documentation shape. Six of them crossed a major version because the changes were breaking: metalsmith-prism reached 6.0, metalsmith-markdown-partials and metalsmith-safe-links and metalsmith-blog-lists each reached 3.0, metalsmith-mdn and metalsmith-sectioned-blog-pagination reached 2.0. If you are pinned to an old version, the release notes on each repository are the record to read before you upgrade. This post is the story around them, not the migration guide.

I did not do this by hand, plugin by plugin, from memory. I used metalsmith-plugin-mcp-server, a tool that scaffolds and validates Metalsmith plugins against the ecosystem's conventions. The MCP server is how the standard stays a standard. It is easier to make seventeen plugins consistent when a machine checks each one against the same rules than when a person tries to remember them.

Sections Became Data

The structured-content approach these plugins support has always treated a page as a list of sections in frontmatter, each section a small bag of data that a component renders. What changed in this pass is that the components now describe their own authoring surface. Each component's manifest can carry a fields block: a declaration of what a section accepts, field by field. A field names a widget (text, markdown, select, checkbox, image) with a label, a default, and constraints. Groups nest; arrays repeat. Two directives, $use and $extends, let a section pull in a partial's fields the same way its template already pulls in the partial, so the shared parts, a container wrapper or a call-to-action array, are defined once and reused.

The point is not the format. The point is that a section is now data with a published shape. A human reading the frontmatter and a program reading the manifest see the same thing.

What the Schema Unlocks

Once the shape is declared, something has to collect it. metalsmith-bundled-components already walks every component, follows each one's dependency graph, and bundles the CSS and JavaScript a page actually uses. With one option, schema: { enabled: true }, it does the same walk for the field declarations and emits a single JSON artifact describing every section's fully composed fields. An editor consuming that file never has to re-implement how components compose, because the bundler has already done it.

Alongside it, metalsmith-site-data emits two more read-only artifacts, one describing the site's pages and one describing its data. Between the schema and these, an external tool has everything it needs to know what a site is made of and how to author it.

That tool is the in-situ editor. This is the first time I am writing about it, though the honest disclosure is that it is already on npm for anyone who goes looking. Run npx @wernerglinka/in-situ-editor inside a starter-derived site and it vendors an admin into the site itself, files you own and commit. Open /admin/?admin=true and you edit sections through forms generated from that schema, with Chrome's built-in AI on hand. Publishing goes through Netlify Identity and a serverless function that holds a GitHub token, so the credential that writes to your repository lives on the server and never reaches the browser. The editor deserves its own chapter. Here it is the proof that a declared schema is worth something.

Many Authors, One Contract

A form is one author. It is not the only one. Because a section is data, metalsmith-section-pages can build an entire site from a JSON object: hand it the sections and it generates the pages. And because the schema states exactly what shape that JSON must take, the object does not have to be written by a person at all. A conversation can produce it.

I have already shown that path: a SKILL that lets Claude interview someone about the site they want and assemble it from the component library. What I did not say at the time, because the pieces were not yet in place, is that it is the same contract underneath. The form, the build script, and the conversation are three front-ends onto one declared shape. Uniform data accepts many authors.

The Missing Hop

There is one hop left, and it is worth naming rather than papering over. The conversation can produce the sections. section-pages can turn them into a site. What still wants a human is the last step: committing the result and letting it deploy. Claude can already operate the developer half of GitHub. In the session where I wrote this, it branched and committed on my say-so. The gap is the unattended version, where the conversation itself, not a person at a terminal, owns and drives the repository.

And the gap is not really capability. It is doing it inside a credential model I would trust. The in-situ editor already draws the line in the right place: the token that can write to your repository lives in a serverless function and never reaches the browser. The interesting question is not whether an AI can push to a repository, which it plainly can, but whether it can do so under that same discipline, a scoped and auditable credential it acts through without ever holding. Closing the loop means letting the conversation stand where the human stands today, inside those same constraints.

That is the next chapter. For now the foundation is set: seventeen plugins on one standard, every section a declared shape, and three different authors already writing to it.