Thoughts • AI and engineering • • 6 min read

I Built a Live Map of My Own Blog

I write constantly about giving complex things a map and a vocabulary. My own blog did not have one. So I directed an agent to read the site as a graph, and the first thing the map did was catch me. A build log, a deliverable, and what I hope to learn as I improve it.

A glowing constellation of connected nodes and threads rising above a dark cartographer's map

I tell people, constantly, that the way to take hold of a complex thing is to give it a map and a vocabulary. I just published a field guide making exactly that argument about sound, that you cannot fix what you cannot name. I believe it enough to have built a career on it.

Then I looked at my own blog and realized it had no map at all. If you had asked me which pages were the important ones, or which pointed at which, I would have had to guess. The holes I could not have named at all. The cobbler's children have no shoes. So I sat down with an agent and built the map, and the building of it is as much the point as the map itself.

How this actually got made

Most of the code here was written by an agent I was directing. That is how nearly all of my work happens now. Saying "I used AI" describes none of it, so here is the method.

I started from what I wanted to see. This site as a graph, every page a node, every internal link an edge, colored by the role each page plays. Then I handed the building to an agent and stayed in the two seats only I can sit in, deciding what it should be and verifying what came back. Most of the typing for the generator, the drift report, the interactive view and the page you are reading was the machine's. The decisions were mine, and so was every bug I had to catch, and there were several, because this is real work and real work bites you. I wrote the longer version of this working method in the AI-assisted engineering HOWTO, and how I check what the agent hands back in my code-review workflow. This article is one of those loops, run in public.

What the map is made of

A blog is already a graph. Every page is a node and every internal link is an edge, you just never see it from above.

So the map is built from precisely that, at build time, out of the site's own content.

  • Nodes are the published pages, each tagged with the one role it plays. A pillar is a cornerstone idea promoted to its own clean URL, a cornerstone is a post that anchors a cluster, a hub is a curated landing page that points outward, and the rest are category indexes and ordinary posts colored by kind.
  • Edges are the internal links between them, read straight out of the writing.
  • The whole thing is written to a single file the atlas reads, with no database and no service behind it. The site already contains the graph, and a build step just makes it look at itself every time the site is rebuilt.

That last part is the one I care about. A hand-drawn map of a living thing goes stale the day you draw it, and a generated one cannot, because it is the data.

What it told me on the first run

The map caught me. I mark important posts two different ways in the plumbing of this site, and the map found that the two ways share not a single entry. One system thinks a dozen posts are cornerstones and the other thinks six completely different ones are. I had been running two definitions of the same word that never once agreed, and I never noticed, because nothing had ever shown me both at once.

Then it found the orphans, starting with my single best-performing essay in search, the one I keep telling myself needs more support around it. It has zero links pointing to it from the body of any other post. I had written the supporting essays. I had simply never linked them home. On the map it sits as a bright dot with no threads attached, which is exactly what the traffic had been trying to tell me for a month.

I knew the goal and believed I was meeting it. I was not, and nothing short of the view from above would have shown me.

What I hope to learn as I improve it

This is a first pass and I am shipping it as one on purpose, because what I want is to see what the map teaches me as it gets better. A few things I am watching for.

  • It only reads the links inside post bodies right now, not the ones baked into landing pages by hand. So "zero inbound" currently means "zero from prose," which is a useful but partial truth. Closing that gap will change the picture, and I want to see by how much.
  • I want one source of truth for what a cornerstone is. The map made the drift visible, and the fix is to make the definition live in one place and have everything else, including the map, read from it.
  • Does patching the orphans move anything? Internal linking is supposed to be the lever, and now that I can see the holes I can fill them deliberately and watch the search numbers over the next few months instead of guessing.
  • I want the shape to carry more meaning. Clusters should show me which parts of the work are densely connected and which are islands, so the map becomes a planning tool that says where to write next, what to wire together and what to retire.

The map is not finished. It is an instrument, and an instrument earns its keep by telling me things I did not already know.

The point under the point

The blog is just the nearest example. It is the same move I make on every system I touch. A thing I cannot see is a thing I cannot reason about, and a thing I cannot reason about will drift on me in the dark. More discipline has never fixed that for me. What fixes it is making the system show itself, continuously, whether I remember to look or not.

I spent years on the wrong side of a wall with sound, and the wall turned out to be made of missing words. My own site had a quieter version of the same wall. I could feel that the structure was off and could not see where. Now I can see it, and that is most of the repair. You can explore the map here, the same one I use to catch my own drift.

Related reading: How to Map a Domain: The Six Layers, the frameworks, each a map of one domain, and Topics First, where the one source of truth for a cornerstone became a file and the whole site reads it.