WordPress to Astro: Migrating a Production Site with AI-Assisted Infrastructure
41 WordPress articles, 187 images, a design-matched dark theme, and a Projects section — all extracted from a SQL backup file and rebuilt in Astro. This is the story of migrating dotzlaw.com from WordPress to a modern static site, and what the Bootstrap Framework actually contributed.
Figure 1 - Before and After: The WordPress Kicker dark theme (left) and the rebuilt Astro Fuwari site (right). Same near-black backgrounds, same teal accents, same full-bleed card layouts. The source material was a SQL backup file and a wp-content directory.
The Starting Point: A SQL Backup and a Dream
dotzlaw.com ran WordPress with the Kicker theme for years. A professional dark design: near-black backgrounds (#141414), teal accents, full-bleed card images, curated article carousels on the home page. It looked good. It worked. But it was WordPress — slow page generation, plugin compatibility issues on every PHP update, a hosting dependency that made every change feel risky, and a WYSIWYG editor that fought against the precise formatting technical articles demand.
The goal was straightforward: rebuild the site as a modern static site using Astro and the Fuwari template. Deploy on Vercel. Keep the design. Keep the content. Gain the speed, simplicity, and developer experience of static site generation.
There was one complication. The WordPress hosting had expired, which meant no live admin panel access for a standard WordPress XML export. No WP REST API to query. No “Tools > Export” menu sitting in a dashboard somewhere. What we had: a full MySQL backup (softsql.sql) downloaded before the hosting lapsed, and a wp-content directory with every media asset the site had ever used.
The question was simple: can we extract everything from a database dump and rebuild it as a production static site?
The target stack: Astro with the Fuwari template for the static site generator. Vercel for hosting and deployment. Markdown with YAML frontmatter for content. TypeScript for any custom components. The Fuwari template provides blog infrastructure out of the box — pagination, categories, tags, search, RSS, dark mode. What it does not provide is a design that looks anything like the Kicker theme.
The answer, 15 phases later: yes. But the path from “content extracted” to “site looks right” is where all the real work happens.
Figure 2 - The Extraction Pipeline: A SQL backup file enters the pipeline and emerges as fully-formed Astro pages with co-located images. Four transformation stages: SQL parsing extracts raw content, HTML-to-Markdown converts the body, frontmatter generation maps WordPress metadata, and image co-location restructures media assets from flat directories to per-article folders.
Phase 1-4: Extraction and Initial Setup
Backup-Based Content Extraction
The MySQL backup contained everything WordPress knows about a site. The relevant tables:
wp_posts— all content (posts, pages, attachments, revisions)wp_postmeta— metadata per post (featured image IDs, SEO fields, Elementor data)wp_termsandwp_term_taxonomy— categories and tags with their hierarchical relationshipswp_term_relationships— the many-to-many mapping between posts and taxonomy termswp_options— site configuration, active theme, permalink structure
The extraction involved parsing SQL INSERT statements to reconstruct the data. WordPress dumps are not clean CSV — they contain escaped strings, serialized PHP arrays, and multi-value INSERT batches. The parsing needed to handle all of these formats correctly.
WordPress stores post content as HTML. Astro expects Markdown. The conversion pipeline handled standard HTML elements (<h2> to ##, <p> to plain text, <a> to [text](url), <img> to ), but some posts used the Elementor page builder, which stores layout data as serialized JSON blobs within post content. Those required separate parsing to extract the actual text and image references from Elementor’s nested widget structure. An Elementor “text-editor” widget wraps HTML in a JSON object with styling metadata that needed to be stripped.
Image path mapping was the most mechanical but error-prone step. WordPress stores images at /wp-content/uploads/YYYY/MM/filename.ext — a flat chronological structure organized by upload date, not by article. Astro with Fuwari uses co-located images: each article lives in its own directory with its images alongside it. Every image reference in every article needed rewriting from absolute WordPress URLs to relative ./filename.ext paths. A single missed rewrite means a broken image in production.
Frontmatter Generation
WordPress metadata mapped cleanly to Astro frontmatter, with some translation:
post_titlebecametitlepost_datebecamepublished(reformatted to YYYY-MM-DD)post_excerptor Yoast SEO meta description becamedescriptionwp_term_taxonomyjoins producedcategory(Servoy Mastery, AI & Modern Development, Software Engineering Fundamentals)wp_termstag associations becametagspost_namebecame the directory slug
41 articles successfully extracted with complete frontmatter. Zero data loss — every article that existed on the live WordPress site was accounted for in the extraction.
The CMS Content Migration skill from the Bootstrap Framework guided this extraction methodology — the structured approach to SQL-based extraction, frontmatter mapping, and image handling came directly from the skill’s documented patterns. The skill’s emphasis on “verify extracted count matches source count” caught a parsing issue early where 3 draft posts were being included in the extraction. Filtering to post_status = 'publish' resolved it.
Image Co-location
187 images moved from the flat wp-content structure to per-article directories. This was not a simple copy operation. Each image needed to be matched to the article that referenced it, renamed where filenames collided, and verified that the Markdown references pointed to the correct relative path.
Figure 3 - Image Co-location: WordPress stores all images in a flat /wp-content/uploads/YYYY/MM/ structure (left). Astro expects images co-located with their articles (right). 187 images were redistributed from chronological folders to per-article directories, with every Markdown reference updated to relative paths.
Cover images required special handling. WordPress stores the featured image as a _thumbnail_id in wp_postmeta, which references an attachment post ID. That attachment post lives in wp_posts with post_type = 'attachment', and its guid field contains the original upload URL. The actual file path is derived from the URL, which includes the /wp-content/uploads/YYYY/MM/ prefix.
Following that three-table chain (wp_postmeta -> wp_posts attachment -> file path) for 41 articles was tedious but necessary. WordPress also generates multiple image sizes (thumbnail, medium, large, full) for each upload, stored as serialized PHP arrays in _wp_attachment_metadata. Choosing the correct size — full resolution for cover images, not WordPress’s auto-generated thumbnails — required parsing that serialized metadata.
Without cover images, the Fuwari card layouts would render with empty placeholders, making the entire site look incomplete.
Phase 8: The Design Match
This was the hardest phase. By a significant margin. It consumed more calendar time than all extraction phases combined.
The Fuwari template ships with a pleasant purple-blue aesthetic — hue 250 in OKLCH color space, light backgrounds, rounded cards, a friendly blog feel. It is designed for personal blogs and light reading. The WordPress Kicker theme is the opposite: near-black backgrounds, sharp contrasts, teal accents, full-bleed imagery. It is designed for professional portfolios and dark-mode-first experiences. Making one look like the other required touching every layer of the design system.
The work fell into three categories: color system overhaul, custom component building, and navigation restructuring. Each category had its own challenges.
Color Overhaul
Fuwari uses OKLCH (Oklab Lightness, Chroma, Hue) for its color system, with a single hue variable driving the entire palette. The first change was straightforward: hue 250 (purple-blue) to hue 180 (teal). That got the accent color right but left the backgrounds completely wrong.
The background required direct OKLCH lightness overrides:
- Initial attempt: lightness 0.10 (near-black), card-bg 0.13, float-panel 0.15
- After living with it for a day: 0.17/0.22/0.20 for better readability
The lesson: matching a screenshot is not the same as matching a usable design. The original WordPress theme had years of micro-adjustments for readability. Going too dark made text strain the eyes on long articles. The final values were darker than Fuwari’s defaults but lighter than the initial “match the screenshot exactly” attempt.
Additional color work included: teal link hover states, card border opacity adjustments, tag badge backgrounds that remained readable against the dark cards, and code block backgrounds that were distinguishable from the page background without being distractingly bright. Every surface needed individual attention.
Figure 4 - Color Palette Evolution: Three stages of the color system. The WordPress original (left) with its near-black backgrounds and teal accents. The Fuwari default (center) with purple-blue hue and light backgrounds. The final tuned values (right) that balance the Kicker aesthetic with readability — darker than Fuwari, lighter than the initial attempt.
Component Rebuilding
The Kicker theme’s home page is not a blog index. It is a curated landing page with distinct visual sections. Reproducing that layout required building custom Astro components from scratch:
HomeFeatureCards.astro — A 2x2 grid of cards with full-bleed background images and overlay text. Each card links to a category landing page. The overlay uses a CSS gradient from transparent at the top to rgba(0,0,0,0.8) at the bottom, ensuring text readability over any background image regardless of image brightness. The cards respond to hover with a subtle scale transform and increased overlay brightness.
NextGenSection.astro — Gradient cards showcasing Katrina and Ryan’s personal sites as part of the family team’s web presence. Each card displays tech stack badges (React, Vite, .NET, Blazor), a brief description, a screenshot preview, and links to external URLs. The gradient backgrounds use the teal-to-dark palette, giving each card a distinct identity while maintaining the overall dark theme. This component was unique to the Astro site — the WordPress version had no equivalent “family portfolio” section.
FeaturedArticlesCarousel.astro + FeaturedCarousel.svelte — An auto-advancing carousel showing featured articles with cover images, titles, and excerpts. The carousel advances every 5 seconds, pauses on hover, supports keyboard navigation (left/right arrows), and shows dot indicators for position. The Svelte component handles the client-side interactivity (timer management, transition animations, touch swipe on mobile) while the Astro component manages data fetching and static rendering of the initial state. This split is idiomatic Astro — static HTML for the initial render, hydrated JavaScript only for interactive behavior.
LatestInsightsGrid.astro — A 3-column responsive grid displaying the 9 most recent articles. Each card shows the cover image (with lazy loading), publication date, truncated description (3 lines max with CSS clamping), and a “Read Article” pill button with a teal hover effect. The grid collapses to 2 columns on tablet and 1 column on mobile. The 9-article limit was chosen to fill the visual space without requiring pagination — readers who want more can navigate to the full Insights page.
Navigation Rename
The WordPress site used “Articles” and “Skills” in its navigation. The Astro rebuild renamed these to “Insights” and “Focus” respectively. A seemingly simple change that cascaded through:
- i18n translation files (English and any future language support)
- Link preset configurations that control navigation rendering
- Page directory names (
src/pages/articles/tosrc/pages/insights/) - URL structures affecting all internal links and series cross-navigation
- Redirect rules in
vercel.jsonto prevent broken bookmarks from search engine indexes
This is the kind of change that looks trivial in a requirements document and takes half a day to execute correctly. Every internal link in every article’s series navigation pointed to the old /articles/ path. Missing even one creates a broken link that only surfaces when a reader clicks through a specific series.
KEY INSIGHT: Design matching is the most time-consuming phase of any migration. Functional completion — content renders correctly — happens relatively fast. Visual parity takes 3-4x longer. Budget accordingly, and accept that “close enough” may be the right target for the first release.
Figure 5 - Home Page Component Map: The rebuilt home page is composed of four custom Astro components, each handling a distinct visual section. HomeFeatureCards provides the hero-level category navigation. FeaturedArticlesCarousel auto-advances through highlighted content. LatestInsightsGrid shows the 9 most recent articles. The layout matches the WordPress Kicker theme’s curated landing page approach.
Phase 9: The Projects Section
The WordPress site displayed articles. The Astro rebuild added something new: a Projects content collection for showcasing production systems with real metrics. Not blog posts about projects — structured data cards with stack badges, metric pills, and cover images.
The WordPress site had no equivalent — it was purely a blog. The Projects section was a net-new addition enabled by the migration. Since we were rebuilding the site anyway, adding a new content type was incremental effort rather than a major WordPress plugin installation.
Four projects launched the section:
Text-to-SQL Dashboard — A natural language interface to business data. 92-95% SQL accuracy across 3 databases, sub-30-second response time, $45/month infrastructure cost. Stack: Python, FastAPI, Claude, Metabase, Qdrant.
YouTube to Obsidian Pipeline — An AI-powered knowledge extraction system. 1,000+ atomic notes generated, 2,757 bidirectional links, 2.5-second RAG chatbot response time, $1.50 total API cost for the entire corpus. Stack: Python, Claude, Qdrant, Obsidian.
Bootstrap Framework — The agent swarm that builds agent swarms. 3 validated migrations, 17 skills, 17 hook templates, 12-step pipeline. Stack: Claude Code, Python, JSON Schema.
Job Search Agent — Automated job market intelligence. 1,975 companies tracked, 58,807 jobs processed per weekly run, 311 matches found, $5.04 per execution. Stack: Python, Claude, Playwright, Qdrant.
Each project card (ProjectCard.astro) displays the stack as colored badges and key metrics as pill elements. The card layout includes a cover image, a title with link, a description paragraph, the stack badges row, and a metrics section with pill-shaped value displays. The design emphasizes quantitative results — readers see real numbers, not vague claims.
FeaturedProjectsSection.astro surfaces the projects on the home page, presenting them as a horizontal row of cards below the latest articles. This section adds a “what we build” dimension to a site that previously only showed “what we write.”
The content collection uses a Zod schema with typed fields for stack (string array), metrics (array of {label, value} objects), coverImage, projectUrl, and githubUrl. This structure ensures every project card renders consistently and validates at build time.
The site grew from 63 to 68 pages.
Phase 10: Content Explosion
The WordPress migration covered the 41 articles that existed on dotzlaw.com. But five complete article series had been written as standalone Markdown files in a local articles/ directory, used for LinkedIn publication and portfolio reference, but never added to the WordPress site. They existed as content without a home. Phase 10 gave them one.
28 new articles from 5 series:
- Series 13: Text-to-SQL + Metabase (7 articles) — from experiment design through production deployment
- Series 14: Obsidian Notes Pipeline (6 articles) — building an AI knowledge extraction system
- Series 15: Job Search Agent (9 articles) — automated job market intelligence at scale
- Articles 15.5-19: Claude Code Series (5 articles) — agent patterns, skills, hooks, and framework evolution
- Article 21: Bootstrap Framework (1 article) — the agent swarm origin story
Each series required its own set of adaptations:
- Frontmatter adaptation to Fuwari’s schema — each article needed
title,published,description,category,tags,series,seriesOrder, and author credits in the exact YAML format Fuwari expects - Image co-location — ranging from 63 PNGs (Obsidian series) to 182 PNGs (Job Search series), each needing to move from the source article directories into the Astro content structure
- Series metadata —
seriesandseriesOrderfields enabling previous/next navigation between articles in the same series - Co-author credits — Katrina and Ryan contributed to several series, requiring the
authorsarray in frontmatter - Description generation — many source articles lacked descriptions, requiring manual writing of SEO-friendly summaries
The volume was significant. The Job Search Agent series alone had 9 articles with 182 images. Each image path needed verification — a single broken reference means a missing image in production, and missing images in technical articles destroy credibility.
Two new categories were added: “AI Projects” and “Claude Code”, joining the existing “Servoy Mastery”, “AI & Modern Development”, and “Software Engineering Fundamentals”. The category taxonomy was intentionally kept flat — no subcategories, no hierarchy. Readers can browse by series for depth or by category for breadth.
The build grew from 68 to 85 pages. Build time remained under 30 seconds — one of Astro’s core strengths. A WordPress site with 85 pages takes minutes to generate a full static export. Astro does it in 24 seconds, with full image optimization included.
Figure 6 - Content Growth Timeline: The site started with 41 articles extracted from WordPress. Phase 10 added 28 articles from 5 unpublished series. Combined with project pages, about page, and category pages, the final site builds 85 pages in 24 seconds.
Phase 15: The Polish Pass
Seven targeted fixes from visual review and user testing. This is the phase that separates hobby projects from production sites. Each fix is small individually. Collectively, they are the difference between “technically works” and “I would show this to a client.”
Missing cover images on 2 articles that had WordPress featured images pointing to external URLs (not the local wp-content directory) that no longer resolved. The original images were hosted on a third-party service that had expired or changed URLs. Replaced with representative screenshots taken from the Wayback Machine captures of the original articles.
Project card visuals upgraded from text-only cards to cards with cover images. The initial ProjectCard implementation rendered stack badges, metrics, and description text, but had no visual hero element. Adding a cover image to each project card transformed the section from a text-heavy list into a visual portfolio. The cover images were screenshots of each project’s primary interface — the SQL dashboard, the Obsidian graph view, the framework’s pipeline diagram, and the job search results page.
NextGenSection relocation from the Projects page to the About page. On the Projects page, Katrina and Ryan’s personal site cards competed visually with the production project cards, creating confusion about whether their sites were “projects” in the same sense as the Text-to-SQL dashboard. On the About page, the NextGenSection provides natural context — “here’s the team, here’s what each person builds.”
WordPress image duplication fix — the most interesting bug of the entire migration. WordPress displays the featured image separately from the post body via the theme’s template. But many article authors (including past-me) also included the same image as the first element in the body content, often with an attribution caption. In WordPress, the theme’s featured image display sits above the content area, and the duplicate in the body is visually redundant but not obviously wrong because WordPress themes often style them differently.
In Astro, both render with identical styling: the cover image at the top of the article AND the same image as the first body element, creating an obvious and ugly duplication. This affected 9 Servoy Mastery articles — nearly all of the original WordPress content from that category.
The fix was a Python script that compared the first body image’s filename to the cover image and removed the duplicate when they matched. But removing the image also removed the attribution caption that had been stored in the image’s alt text or a <figcaption>. A new imageCredit field was added to the Astro content schema, allowing cover image attribution to live in the frontmatter where it belongs rather than in a body image element.
Publication backdating for 21 articles to maintain timeline consistency. Articles written in late 2025 but published to the Astro site in February 2026 needed their published dates adjusted to reflect when the content was actually created. Without backdating, the “Latest Insights” grid would show 21 articles all dated February 2026, burying the actually-recent content under a wall of backdated imports. The dates were set to match the original writing dates, preserving the chronological narrative of each series.
Series navigation link fixes across all 8 job-search articles. The series had been written before the navigation rename. Every “Previous” and “Next” link in the series pointed to /articles/series-15-job-search/... instead of /insights/series-15-job-search/.... Eight articles, each with up to two navigation links, all broken. A find-and-replace across the series directory fixed them, but only after a manual review discovered the issue during a read-through of the deployed site.
KaTeX dollar sign rendering — remark-math was parsing currency values like “$45/month” as LaTeX math expressions. Text like “costs $45/month for infrastructure” would render as a garbled math formula. The fix was configuring the plugin to require double-dollar delimiters ($$...$$) for math mode, leaving single dollar signs as literal text. This was a particularly insidious bug because it only appeared in articles that mentioned costs — which turned out to be most of the AI project articles.
Figure 7 - Phase Timeline: 15 phases from initial extraction through final polish. The extraction phases (1-4) moved quickly. The design match phase (8) consumed more time than any other single phase. Content addition (10) was mechanical but high-volume. Polish (15) caught the edge cases that only surface in real usage.
What the Bootstrap Framework Actually Contributed
Honest assessment time. This article is published alongside a series about the Bootstrap Framework — an agent swarm that generates Claude Code infrastructure for any project. It has 17 skills, 17 hook templates, and a 12-step pipeline. It would be easy to claim the framework did all the heavy lifting. That would be dishonest. Here is what actually happened.
What helped directly:
The CMS Content Migration skill provided the extraction methodology. The structured approach to SQL-based content extraction, frontmatter field mapping, image path rewriting, and category taxonomy translation came from documented patterns in the skill. Without it, the extraction phase would have involved more trial and error.
The Visual State Capture skill guided the screenshot-based design matching process. The approach of capturing the WordPress site’s visual state as reference screenshots, then systematically matching each element in the Astro rebuild, prevented the design phase from becoming an aimless “make it look right” exercise.
The SSG/Astro archetype from the project-type-patterns skill informed the initial Fuwari setup: directory structure, content collection configuration, build tooling, and deployment target.
What did not help:
Most of the work was manual component building, visual tuning, and content wrangling. The framework does not generate Astro components. It does not know what the Kicker theme looks like. It cannot adjust OKLCH lightness values based on readability testing. It does not write Python scripts to detect duplicate images.
The framework’s pipeline is designed for generating Claude Code infrastructure (agents, hooks, skills, CLAUDE.md). A CMS migration needs infrastructure generation only at the beginning. The remaining 80% of the effort is content transformation and visual design — domains where the framework provides methodology but not automation.
KEY INSIGHT: The framework’s biggest value in this migration was methodology, not automation. Having a structured approach — phases, tracking docs, incremental verification (
pnpm buildafter every phase), defined completion criteria — prevented the project from becoming an unbounded “make it work” exercise. The 15-phase structure emerged from the framework’s emphasis on decomposition and checkpoint validation.
What a dedicated CMS-to-SSG pipeline could look like:
The gap between “content extracted” and “site looks right” is where all the effort concentrates. Future framework work could address:
- Automated theme customization from reference screenshots — given a screenshot of the source site, generate OKLCH overrides for Fuwari’s color system
- Component generation from design specifications — analyze the source site’s layout sections and generate corresponding Astro components
- Automated image co-location scripts that handle the WordPress
/wp-content/uploads/YYYY/MM/to Astro per-article path mapping without manual intervention - Duplication detection for featured images that appear in body content, with automatic removal and
imageCreditextraction - Series metadata inference from WordPress category and date patterns, reducing manual frontmatter creation
These are the steps that consumed the most manual effort. Automating even half of them would cut the migration timeline significantly. The framework’s strength is infrastructure generation — agents, hooks, skills, validation. The WordPress-to-Astro migration revealed that CMS migration needs a parallel track: content transformation tooling that operates alongside the infrastructure generation, not instead of it.
Figure 8 - WordPress Image Duplication Fix: WordPress displays featured images separately from post body (left, simulated). When both the cover and the first body image are the same file, Astro renders it twice. The fix removes the body duplicate and moves any attribution to a new imageCredit schema field (right). This affected 9 Servoy Mastery articles.
By the Numbers
The final tally for the dotzlaw.com migration:
| Metric | Value |
|---|---|
| WordPress articles migrated | 41 |
| Additional articles added | 28 |
| Total articles | 69 |
| Images from WordPress | 187 |
| Total images across all articles | 400+ |
Pages built (pnpm build) | 85 |
| Build time | 24 seconds |
| Phases of work | 15 |
| Production projects showcased | 4 |
| Series with cross-navigation | 6 |
| Custom Astro components built | 6 |
| Categories | 5 |
| Navigation sections | 4 (Insights, Focus, Projects, About) |
| Deployment target | Vercel (free tier) |
| Source material | 1 SQL backup + 1 wp-content directory |
The six custom components: HomeFeatureCards, NextGenSection, FeaturedArticlesCarousel (+ FeaturedCarousel.svelte), LatestInsightsGrid, FeaturedProjectsSection, and ProjectCard.
The five categories: Servoy Mastery (the original WordPress content about enterprise application development), AI & Modern Development (cross-cutting articles on AI-assisted workflows), Software Engineering Fundamentals (timeless practices), AI Projects (the Text-to-SQL, Obsidian, and Job Search series), and Claude Code (agent patterns, skills, and framework articles).
The design match: near-black theme (#141414 base), teal accents (OKLCH hue 180), full-bleed card images, Kicker-style layouts. Deployed on Vercel with sub-second page loads and automatic preview deployments on every git push.
What stayed the same between WordPress and Astro: the visual identity, the content, the dark aesthetic, the professional tone. What changed: build time dropped from minutes to 24 seconds. Hosting moved from managed WordPress to Vercel’s free tier. Content editing moved from a browser-based WYSIWYG to Markdown files in VS Code. Deployment moved from FTP uploads to git push.
The starting point: a SQL backup file and a wp-content directory. The ending point: a production static site that matches the original design, adds a Projects section, includes 28 articles that never existed on the WordPress site, and builds in 24 seconds.
The migration is complete. The site is live. And the SQL backup file that started it all still sits in the project archive — a reminder that data outlives the platforms that created it.
KEY INSIGHT: The WordPress-to-Astro migration validates a broader pattern: backup-based extraction works when live admin access is unavailable. A SQL dump contains everything — content, metadata, taxonomy, media references. The tooling to parse it is straightforward. The hard part is not extraction. The hard part is making the result look like it was designed, not generated.
The Series
This is Part 4 of a 4-part series on Building the Bootstrap Framework:
- An Agent Swarm That Builds Agent Swarms — Case study migrating two production apps with generated Claude Code infrastructure
- From Prototype to Platform — How the framework learned from every migration and improved itself
- Securing Agentic AI — Building security-conscious agent systems with Claude Code
- WordPress to Astro (this article) — Migrating a production site with AI-assisted infrastructure
Related Reading
These companion articles from the Claude Code series provide deep dives into the primitives this framework builds on:
- The Anatomy of a Domain Skill — Progressive disclosure, skill extraction, and 140x token efficiency
- Hooks, Agents, and the Deterministic Control Layer — How hooks enforce what prompts cannot, and why agent file ownership prevents chaos