Migrating from WordPress to MDX 🔗 **Source:** [Migrating from WordPress to MDX](https://nickdiego.com/migrating-from-wordpress-to-mdx) > [!note]+ Document Notes > tags: [wordpress, mdx, ai-workflows] > author: Nick Diego > source: nickdiego.com > reference: [https://nickdiego.com/migrating-from-wordpress-to-mdx] > date created: 2026-01-30 14:30 > > # 🏷️ Title: Migrating from WordPress to MDX > <!-- deep-read:sections start --> ## 🧭 Table of Contents - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📚 References](#-references) - [🗣️ Paraphrase](#️-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-assessment) - [✅ Logical Validity](#-logical-validity) - [🛡️ DARVO Analysis](#-darvo-analysis) - [🎯 Conclusion](#-conclusion) ### 🔗 References - Include links cited in or relevant to the article. ## 📝 Summary - What happened: Nick migrated his personal site from WordPress (database + block editor) to a flat-file Next.js + MDX stack wired tightly to Claude Code skills. - Why it matters: Plain-text content and colocated assets give AI tools full project context, enabling automated authoring, refactoring, and maintenance. - Key stakeholders: WordPress/JS developers, technical bloggers, teams exploring AI-assisted workflows, DevRel and docs owners. - Risks and tradeoffs: Loss of CMS niceties (comments, search, editorial flows), more engineering ownership, experimental skills ecosystem. - Bottom line: For a personal, developer-oriented blog, MDX + Git + AI agents can be faster, cheaper, and more malleable than WordPress. ## 📖 Main Content - Core arguments: - WordPress’s abstractions (database, media library, block editor, plugins) obscure content structure from AI tools, which makes it hard for agents to read, refactor, or extend the site using real context. - Moving to MDX files in a simple folder structure (with images colocated per post) plus a small Next.js/Tailwind/Shiki codebase lets AI “see” everything: content, layout, components, and patterns. - A CLAUDE.md file and docs folder describe conventions and components, giving agents a “map” of the system. - Reusable “skills” (slash commands) automate repetitive work: scaffolding new posts, drafting commits, and running expert reviews (e.g., design guidelines, React best practices). - The result is a small (~5,200 LOC) open-source site that’s easy to iterate on via prompts, not dashboards. - Definitions/context: - MDX: Markdown extended with JSX components inside content. - Flat-file / file-based CMS: content lives as text files in the repo rather than a database. - Agentic workflows: AI tools acting as semi-autonomous helpers that can read code/content, make changes, and iterate with you. - Uncertainties or limitations: - Author notes gaps (no comments, basic search, manual PR-based publishing) and acknowledges this setup wouldn’t fit all production editorial teams. - Skills ecosystem is early; reliability and coverage will evolve. - WordPress AI work is ongoing; these constraints may change over time. ### 🗒️ Notes - The post opens with Nick using `/new-post` in Claude Code to generate an MDX file with frontmatter in ~15 seconds, illustrating the AI-first workflow. - Lee Robinson’s “The cost of abstractions with AI is very high” inspires the move away from a headless CMS-style architecture toward MDX. - WordPress is framed as still “the right choice for an enormous number of projects,” but its abstraction layers interfere with AI tools’ ability to read and act on the site. - In WordPress, content and media are split (database vs `wp-content/uploads`), themes and plugins add layers, and the block editor adds additional structure; this is great for visual editing but opaque to AI. - On the new stack: - Next.js 16 for the app. - MDX for posts. - Tailwind for styling. - Shiki for syntax-highlighted code blocks. - Content structure: - Posts live under `src/blog/YYYY/slug.mdx`. - Posts with images use a folder: `post-with-images/index.mdx` plus colocated image files. - No media library or attachment IDs; images are just files next to content. - Author can embed components like `<Image>`, `<Video>`, `<GHRepoCard>` directly into MDX. - Light/dark mode and code highlighting are handled globally; posts don’t need per-post configuration. - Everything is in Git, deployed via Vercel; AI tools thus get “direct access to the full context of the site,” including components and styles. - Example AI task: add copy buttons and expandable sections to long code blocks, then batch-apply the pattern across posts in about ten minutes. - A root `CLAUDE.md` file plus a `docs/` folder (components, content authoring, design patterns, getting started, styling) guide AI agents about how the system works. - Skills: - `new-post` asks questions, then scaffolds correct file structure and frontmatter, optionally on a separate branch. - `commit` groups changes and writes commit messages, with flags like `all` and `push`. - Community skills such as `web-design-guidelines` and `vercel-react-best-practices` help enforce UI and performance standards. - Skills.sh is mentioned as a directory for exploring and sharing skills. - Acknowledged gaps: - No comments; search is just browser find. - Publishing is tied to merging PRs to `main`. - Some parts may be overengineered; others too simple. - Alternative tools: - Astro is cited as an excellent static-site tool that solves many similar problems “out of the box.” - Migration timeline: - Core migration over a weekend, followed by about a week of sporadic design and feature tweaks. - Result: - A fast, cheap, easy-to-iterate site aligned with the author’s thinking and working style. - Entire site is open source; readers are invited to browse, fork ideas, and share similar experiments. ## 📚 References - Nick Diego – “Migrating from WordPress to MDX” (primary article): https://nickdiego.com/migrating-from-wordpress-to-mdx - Lee Robinson – “The cost of abstractions with AI is very high” (inspiration for MDX move): https://leerob.io - Skills.sh – Community skills directory for Claude Code: https://skills.sh - Next.js 16 – Framework used for the new site: https://nextjs.org - MDX – Content format: https://mdxjs.com - WordPress – Original platform: https://wordpress.org ## 🗣️ Paraphrase - Paragraph A paraphrase: Nick rebuilt his personal blog from WordPress to a Next.js + MDX site so AI agents can work directly with his content, design, and code, making tasks like creating new posts and refactoring patterns as simple as issuing skills-based prompts. - Paragraph B paraphrase: He accepts losing classic CMS conveniences (comments, search, visual editing) because the flat-file, Git-based setup leads to a smaller, more transparent system that’s easy to iterate on and showcases what AI-assisted development can look like in practice. ## 📰 Newsletter AI is reshaping how we think about “CMS.” In this piece, long-time WordPress contributor Nick Diego walks through migrating his personal site from WordPress to a lean Next.js + MDX stack designed for Claude Code. By storing posts as flat files, colocating images, and documenting conventions in `CLAUDE.md`, he turns his repo into an AI-friendly playground. For WordPress folks, this is a fascinating contrast to database-centric editorial flows. You’ll see how skills like `/new-post` and `/commit` scaffold content and commits, and how community skills can review your UI against design and performance best practices. If you’re exploring hybrid setups, pair this read with resources on WordPress headless patterns, Astro, and file-based content workflows to decide which tradeoffs best fit your team. ## ✅ Action Items #### DevRel - Highlight this site as a case study in AI-assisted content workflows for dev blogs (talks, demos, blog posts). - Build a workshop comparing WordPress vs MDX for docs/blogs, focusing on AI tooling integration. - Create example repos and quickstarts showing CLAUDE.md + skills patterns for common stacks. - Run a small “AI skills clinic” with office hours to help developers design maintainable skills. - Capture feedback on developer friction in both WordPress and MDX setups for DX roadmap inputs. #### OSPO - Draft guidance on when file-based content plus AI tooling is appropriate for internal docs vs when a CMS is required. - Review licensing of community skills and templates (Skills.sh) before promoting them internally. - Integrate AI-assisted code/content review into secure contribution workflows, with clear policies and audit trails. - Track repos adopting AI skills and ensure they are included in SBOM and inventory practices. - Coordinate with legal and security to document expectations around AI-modified content and code. #### Community - Host conversations between WordPress, Next.js, and Astro communities about AI-friendly content architectures. - Offer maintainer clinics on documenting projects for AI agents (CLAUDE.md, docs folders). - Promote contributor-friendly issues to extend skills (e.g., better commit messages, content linting). - Encourage sponsors to support open-source examples of AI-first sites and workflows. - Run cross-project tabletop exercises on AI-assisted incident response and refactors. #### WordPress - Core: Evaluate where AI visibility into content and structure is blocked by current abstractions; explore APIs or file-based mirrors. - Core Performance: Benchmark WordPress vs static MDX setups for blogs; document realistic tradeoffs. - Core AI: Prototype features that expose richer, AI-readable representations of posts, blocks, and patterns. - **Core Program Team:** Facilitate cross-team discussions on “AI-ready WordPress” while preserving editorial UX. - Mobile: Explore how mobile apps could surface AI-assisted editing or refactoring for posts. - Playground: Provide labs showing migrations from wp-admin to MDX/Next.js and vice versa. - Community: Add meetup/WC talks around “AI-friendly content architectures” and migrations. - Training: Build lessons on WordPress + headless + AI vs MDX-only setups. - Marketing: Frame WordPress’s AI roadmap in light of these file-based experiments. - Support: Prepare docs for users considering moving off WordPress or hybridizing. - Design: Audit how block patterns and design tools can be surfaced to AI agents. - Documentation: Document best practices for organizing content so external tools can consume it. - Photos: Explore file-based media workflows compatible with WordPress for AI consumption. - TV: Produce videos/tutorials on AI-supported authoring and migration case studies. - Polyglots: Consider how multilingual content can remain AI-readable across locales. - Accessibility: Ensure AI-generated templates respect WCAG guidelines. - Meta: Investigate .org tooling that can generate AI-friendly mirrors of WordPress content. - CLI: Provide commands to export posts and media into MDX-friendly structures. - Hosting: Offer patterns for hosting hybrid WordPress + static MDX deployments. - Tide: Examine how AI tooling might integrate with plugin/theme quality scoring. - Openverse: Explore AI assistance in attribution and content discovery workflows. - Themes: Document how theme structure can be exposed to AI tools. - Plugins: Encourage plugins to document their structures and APIs for AI readability. #### The WPOCC - Programs: Fund experiments that compare AI-first file-based blogs to classic WordPress setups. - Projects: Facilitate governance discussions on when AI tools can safely commit or publish content. - Funding experiments: Pilot microgrants for maintainers building CLAUDE.md-style docs and skills for popular WP projects. ### FAIR - Technical independence: Encourage storing content in formats that remain usable without particular AI vendors. - Policies and covenants: Define transparent funding and data-use policies for AI infrastructure around WordPress and MDX. - Productized governance artifacts: Publish templates for CLAUDE.md-like specs, contribution guidelines, and AI usage scorecards. ## 🧪 Hypotheses - H1: For individual developer blogs, MDX + Git + AI skills yields faster iteration than WordPress. - H2: Co-locating content, assets, and components in a single repo significantly improves AI agents’ effectiveness. - H3: A small, well-documented codebase reduces the learning curve for both humans and AI assistants. - H4: Loss of CMS features (comments, built-in search) is acceptable for many personal/technical sites in exchange for AI flexibility. - H5: Community skill ecosystems (e.g., Skills.sh) can standardize best-practices checks across diverse projects. ### 📊 Methodology - Compare time-to-publish and time-to-implement-changes between WordPress and MDX setups across a sample of technical blogs. - Measure AI effectiveness (accuracy of changes, number of corrections) when given full-repo vs partial/opaque context. - Survey developers using CLAUDE.md-style docs about perceived productivity and understanding of project structure. - A/B test sites with and without classic CMS features to gauge impact on reader engagement. - Track adoption and reuse of shared skills across multiple projects and assess their quality impact. ### ❓ Questions - Under what conditions does WordPress remain clearly superior to MDX + AI for content teams? - How can WordPress expose richer, AI-friendly representations of its content without sacrificing UX? - What conventions should become standard for “AI-ready” repos (docs layout, metadata, skills naming)? - How do we ensure AI-generated changes remain accessible, secure, and maintainable? - Can skill ecosystems be governed to avoid fragmentation and security issues? ### 🔮 Future Research - Longitudinal studies on the maintenance burden of AI-assisted MDX sites vs traditional CMS. - Patterns for hybrid setups: WordPress for editorial teams, static MDX mirrors for AI workflows. - Reference architectures for CLAUDE.md-like project documentation across languages and frameworks. - Governance models for giving AI agents partial commit or deploy rights safely. - UX research on how readers perceive AI-refactored or AI-generated content. ### 💡 Implications - Practice: Teams may adopt file-based content and AI skills for internal docs, pattern libraries, and dev blogs. - Policy: Organizations must define when AI agents can modify code/content and how to audit those changes. - Security: Skills and agent workflows need strict permission models and review gates. - Education: Curriculum should cover designing AI-readable codebases and documentation. - Funding: Open-source experiments like Nick’s site can guide investment in standard patterns and tooling. ### 🧠 Learning Styles Assessment - Reading level estimate: Approx. Flesch–Kincaid Grade 10–11 (developer audience, moderate jargon). #### 👀 Visual learners - Present: Code-like directory examples, simple structural descriptions. - Improve: Add architecture diagrams of the stack, data flow, and AI workflows; before/after views of posts and CMS UI. #### 🔊 Aural learners - Present: None mentioned. - Improve: Provide an audio summary or short screencast walkthrough explaining the migration and skills. #### 🗣️ Verbal learners - Present: Clear narrative, definitions via examples (e.g., how skills work, how files are organized). - Improve: More analogies comparing CMS vs flat-file models in everyday terms. #### 🧩 Kinesthetic learners - Present: Invitation to browse the open-source repo and experiment. - Improve: Step-by-step “try this yourself” tasks and small labs for setting up CLAUDE.md and basic skills. #### 🧠 Logical learners - Present: Reasoned tradeoff discussion, explicit listing of gaps and alternatives. - Improve: Tables comparing WordPress vs MDX + AI on features, complexity, and maintenance costs. #### 🧑‍🤝‍🧑 Social learners - Present: Invitation to share similar experiments, public repo for collaboration. - Improve: Guided discussion prompts, community calls, or study groups around AI-friendly content architectures. #### 🧘‍♀️ Solitary learners - Present: Reflective narrative; repo allows self-paced exploration. - Improve: Reflection questions about readers’ own stacks and how AI fits into them. #### 🌿 Naturalistic learners - Present: No direct environmental analogies. - Improve: Use ecosystem metaphors (e.g., CMS as managed habitat vs file-based wildlands) and consider sustainability (build times, hosting). ### 📊 Accessibility Assessment #### Screen reader semantics - Present: Likely standard HTML with headings (inferred from Next.js/Tailwind norms). - Improve: Ensure proper landmark roles, descriptive alt text for images, and language attributes. #### Keyboard navigation - Present: Framework likely provides basic focus handling. - Improve: Verify no keyboard traps, logical tab order, and visible focus outlines throughout. #### Contrast and readability - Present: Tailwind encourages configurable design tokens; likely adequate but unverified. - Improve: Confirm 4.5:1 contrast ratios, check line height, and avoid low-contrast code blocks. #### Text resizing and reflow - Present: Responsive layout from Next.js/Tailwind. - Improve: Validate up to 200% zoom, handle prefers-reduced-motion, and avoid layout shifts. #### Media and captions - Present: Code examples; mention of images and videos via components. - Improve: Ensure captions/transcripts for any media, no autoplay by default. #### Forms and interactions - Present: Minimal interactive elements (no comments). - Improve: any forms should have labels, clear error states, and large touch targets. #### Standards reference - Map identified improvements to WCAG 2.2 AA: focus visible (2.4.7), contrast (1.4.3/1.4.11), reflow (1.4.10), non-text content (1.1.1), etc. ### 🌍 DEIB Assessment #### Cultural breadth - Present: Technical, neutral, no strong cultural framing. - Improve: Include examples from diverse regions or contexts when discussing hosting and tooling choices. #### Inclusive language - Present: Generally neutral, jargon-heavy but defined in context. - Improve: Add plain-language summaries and glossaries for non-experts. #### Neurodiversity support - Present: Clear structure, short sections, bullet points where needed. - Improve: More consistent headings, optional summaries, and reduced cognitive load via visual organization. #### Representation - Present: Single-author narrative; no imagery described. - Improve: Use diverse examples and imagery when demonstrating sites or personas. #### Psychological safety - Present: Respectful, non-confrontational tone; acknowledges tradeoffs. - Improve: Add explicit invitations for differing approaches and constructive critique guidelines. ### ✅ Logical Validity #### Strong reasoning - Inductive/causal: Observes that when content is in flat files with colocated assets and docs, AI tools become more capable; supports with concrete examples (code-block refactor, `/new-post`). - Comparative: Contrasts WordPress’s abstraction layers with MDX’s transparency, making the tradeoff explicit (editorial UX vs AI visibility). - Framing: Explicitly states this is a personal-site experiment, not universal prescription, which narrows claims appropriately. #### Fallacies - No major fallacies detected; the author avoids overgeneralizing by repeatedly limiting scope to his personal blog and mentioning alternatives (Astro, ongoing WordPress AI work). #### Tone of voice - Tone: Pragmatic, exploratory, and modestly enthusiastic. - Uses phrases like “This is still very much an experiment” and “It’s also not the only way to approach this,” which keep the tone open and non-dogmatic. ### 🛡️ DARVO Analysis - Deny: No denial or minimization of others’ concerns; WordPress strengths are acknowledged. - Attack: No attacks on WordPress, its community, or alternative tools. - Reverse victim/offender: No attempt to portray the author or AI tools as victims; the piece is framed as a voluntary experiment. - Overall: The article is informational and reflective, not defensive or adversarial. ## 🎯 Conclusion Nick’s migration from WordPress to an MDX-based Next.js site demonstrates how flattening content into files, colocating assets, and documenting project conventions can unlock powerful AI-assisted workflows. For personal or developer-focused blogs, this tradeoff can yield faster iteration and richer automation at the cost of traditional CMS features. Next steps for readers include examining their own content architectures, experimenting with CLAUDE.md-style documentation, and piloting small, reversible migrations or prototypes. ## 🧱 Refactor Appendix (append after 🎯 Conclusion) ### 📚 Literature Split Pad - Purpose: Stage Konik CEE units that become per-source Literature notes. - Split level: **H3**. - Include verbatim quotes under 25 words and a [view highlight] link. ### [H1] 5–10-word present-tense claim > [!quote] [Migrating from WordPress to MDX](https://nickdiego.com/migrating-from-wordpress-to-mdx) by [[Nick Diego]] via [[nickdiego.com]]. Published [MISSING]. Accessed 2026-01-30. > “This entire site is now about 5,200 lines of code, excluding posts.” Two lines: context and use. Cite data if relevant. [view highlight](https://nickdiego.com/migrating-from-wordpress-to-mdx#H1) #xref #articleseed ID:rw_[MISSING] ### [H2] 5–10-word present-tense claim > [!quote] [Migrating from WordPress to MDX](https://nickdiego.com/migrating-from-wordpress-to-mdx) > “Skills are reusable prompts you invoke with a slash / command.” Two lines: context and use. [view highlight](https://nickdiego.com/migrating-from-wordpress-to-mdx#H2) #xref ID:rw_[MISSING] --- ### 🔖 Atomic Split Pad (Zettel Candidates) - Purpose: Promote reusable claims into Atomic notes. - Split level: **H4**. - Each item: one idea, present tense, specific, testable. #### [Z1] Flat-file MDX improves AI content workflows - Scope/condition in one line. - Pointer to page/time or dataset. - Links: [[AI-Ready-Repos]] [[Content-Architecture]] #### [Z2] CLAUDE.md guides AI agents effectively - Scope/condition in one line. - Pointer to page/time or dataset. - Links: [[Project-Documentation]] [[AI-Agents]] --- ### ✏️ Fleeting Queue (Extract by Selection) - Purpose: Capture quick actions or sparks for Fleeting notes. - Extraction: **Select one line** → “Refactor: Extract selection to new note (content only).” - Keep each line short and self-contained. - [F1] Try a CLAUDE.md-style file for my main repo — context/https://nickdiego.com/migrating-from-wordpress-to-mdx #fleeting #inbox - [F2] Prototype `/new-post` and `/commit`-style skills for my blog — context/https://nickdiego.com/migrating-from-wordpress-to-mdx #fleeting #inbox - [F3] Compare WordPress headless vs MDX + AI for my docs — context/https://nickdiego.com/migrating-from-wordpress-to-mdx #fleeting #inbox --- <!-- deep-read:sections end -->