--- title: Migrating a 20-Year WordPress Blog to Be Agent-Ready type: article date: 2026-09-13 topics: ["architecture", "agentic-ai", "opinion"] summary: "I moved two decades of writing off WordPress and into plain markdown on GitHub, rendered as a static site. The design goal was simple: agents will read this content as often as humans do. Here is how I designed it — and what the migration taught me about technical debt." draft: false --- I wrote my first article in 2001, on messaging-oriented middleware. In 2004 I created my first blog on WordPress, and I have been publishing ever since — through SOA, cloud, mobile, IoT, blockchain, and now AI. Along the way, the writing spread out. Newsletters and posts went to LinkedIn. Videos went to my YouTube channel. Podcast episodes went to Spotify. Twenty-five-plus books went to publishers and storefronts. Each platform was the right choice at the time, and each one became another place where a piece of my thinking lived under someone else's roof, in someone else's format. This year I consolidated all of it into one website. But the interesting part isn't the consolidation — it's the design constraint I set before writing a single line of code. ## The constraint: design for agents, not just browsers Increasingly, the "readers" of a website are not people scrolling on a phone. They are AI agents — research assistants, coding copilots, answer engines — fetching pages, extracting content, and reasoning over it. If my writing is going to be found, quoted, and used correctly in that world, the content itself has to be trivially machine-readable. That single assumption drove every architecture decision: - **Plain markdown as the source of truth.** Every article, newsletter issue, post, book, and talk is a markdown file with a small YAML frontmatter block — title, date, topics, summary. No database, no admin panel, no proprietary format. An agent (or a human, or a future me) can read the raw file and get everything. - **Residing in GitHub.** The content repository is the CMS. Version history is the audit trail. Anything that can read a git repo can read my entire body of work. - **Rendered with Astro into static HTML.** The build turns markdown into fast, semantic pages with zero client-side JavaScript. What the browser receives is what an agent parses — no hydration, no content hidden behind scripts, no layout that only exists after a framework boots. - **Stable, predictable structure.** Clean URLs derived from filenames, one H1 per page, real headings, RSS feeds, and a machine-readable topic taxonomy. Boring on purpose. Boring parses well. The test I kept applying: if an agent fetches any page on this site, does it get the complete content, correctly structured, on the first request? If the answer required JavaScript, a login, or a platform API — the design was wrong. ## Designing the content model Consolidating two decades of output meant admitting that "blog post" was never one thing. The site models each stream as its own content type, each with its own folder, format, and rendering: - **Articles** — long-form pieces and tutorials, the backbone since 2001. - **Two newsletters** — Technology Bytes and Green AI Bytes, each issue a markdown file, authored on the site first and then published to LinkedIn (the reverse of how it used to work). - **Short posts** — LinkedIn-style pieces, kept off the homepage so they never crowd the long-form work. - **Books** — 25+ titles rendered as a typographic bookshelf. - **Talks, videos, and podcast episodes** — imported automatically from their platforms via RSS and APIs, additively, never overwriting what exists. A shared topic taxonomy — fifteen topics from `architecture` to `green-software` — cuts across all of it, so a reader (or an agent) can traverse twenty years of writing on one theme regardless of which format it originally shipped in. The platforms didn't go away. LinkedIn, YouTube, and Spotify are still where distribution happens. But they are now downstream of the site, not the system of record. ## What the migration taught me about technical debt Here is the part that surprised me: exporting a 20-year WordPress blog is an archaeology project. Nothing was ever *wrong* with the blog. But two decades of small, individually reasonable decisions had compounded. Themes came and went, each leaving styling assumptions baked into post HTML. Plugins added shortcodes that stopped rendering when the plugin was retired — `[caption]`, `[embed]`, syntax-highlighter tags for highlighters that no longer exist. Images pointed at hosts that vanished. Early posts were written in an editor that produced different HTML than later ones. The content was all there, but it was entangled with fifteen years of infrastructure decisions nobody remembered making. None of this was visible while the site worked. It only became visible — and expensive — the moment I tried to move. That is exactly how technical debt behaves in enterprises, and the parallel is worth stating plainly: - **Debt accumulates through reasonable decisions, not bad ones.** Every plugin I installed solved a real problem that day. Every enterprise integration, workaround, and "temporary" script did too. Debt is rarely the result of incompetence; it is the residue of speed. - **Debt is invisible until you need to change.** My blog ran fine for years. Enterprise systems run fine for years. The bill arrives with the migration, the acquisition, the platform sunset, the new regulation — always at the moment you have the least room to pay it. - **The debt lives in the coupling, not the content.** My words were fine; they were just welded to shortcodes, themes, and hosting. Enterprise business logic is usually fine too; it is welded to specific databases, middleware versions, and vendor formats. The cost of change is the cost of un-welding. - **The cheapest debt payment is a format decision.** Plain markdown in a git repo is my hedge against ever doing this archaeology again. The enterprise equivalent is the same discipline: open formats, documented schemas, content and logic separated from the platform that happens to serve them today. Twenty years from now, someone — or something — will want to read this content on platforms that don't exist yet. This time, the migration will be a `git clone`. ## The takeaway If you are building or rebuilding your presence — personal or enterprise — design for both audiences: the humans who have always read you, and the agents that increasingly will. The two are not in tension. Fast, semantic, well-structured pages serve a person on a phone and a machine parsing your work equally well. Keep the source of truth in plain, open formats you control. Let platforms be distribution channels, not owners. And treat every convenience that couples your content to today's infrastructure as a loan you will repay, with interest, on the day you least want to. I took twenty years to pay mine off. The good news: it only has to be paid once — if you change what you owe it to. --- A closing note of gratitude: thank you to all my readers, viewers, and listeners across every channel — the blog, LinkedIn, YouTube, the podcast, and the books. Two decades of writing only happens because of your support, your questions, and your feedback. This site brings it all together in one place — for you to read, watch, or listen, on whichever channel you prefer.