Migrating from WordPress to Jekyll (and static site generators in general)

DemandSphere migrated their site from WordPress to Jekyll. The core reasons were speed, ease of modification, and a simpler operating model suited to a fast-moving team.

Static site generators (SSGs) work around HTML templates, includes, layouts, config, and markdown instead of a database and application server. Post metadata goes into frontmatter YAML at the top of the file, and posts start in _drafts before being moved to _posts for publishing.

The migration target was 288 WordPress posts plus other pages. Rather than moving the entire 15-year archive, they filtered which pages to keep based on GSC data and indexing value, removing or noindexing low-value pages. They used WordPress's XML export to move content and images.

The real accelerator for this work was Claude Code. The team used multiple sessions along with several .md files and CLAUDE.md to maintain work context, letting the agent handle analysis and cleanup that would have taken a lot of human time.

Within the repo, they built 9 dev tools for operations. Notable ones include:

• Site Structure: detects sitemap omissions, duplicate metadata, and misplaced folders
• Lighthouse Auditor: checks quality from an SEO perspective as well as performance
• Schema Auditor / Schema Details: checks basic structured data coverage and page-level enhancement opportunities
• AEO Auditor: basic checks for answer engine optimization
• Open Graph Preview: preview sharing on Facebook, LinkedIn, X, Slack
• Content Similarity tools: embedding-based topic clusters, similar documents, semantic core analysis
• Internal Linking: improves internal links between topics based on embeddings
• Redirects: prevents missing redirects after cutover

The entire site was vectorized using the all-MiniLM-L6-v2 embedding model running locally via @xenova/transformers. This was extended into topic tables, similarity reports, and semantic core analysis.

On the SEO side, JSON-LD was applied across all pages from the start. Organization, WebSite, BreadcrumbList, FAQPage, BlogPosting, SoftwareApplication, and others were auto-generated via templates and frontmatter, with FAQ handled automatically from the faq_schema block in YAML. The sitemap was generated with the jekyll-sitemap plugin.

Also, tuning the CSP took a lot of time. Blocking issues arose in turn with the Cloudflare analytics beacon, Google Ads conversion tracking, and Leaflet maps, going through about 6 rounds of policy updates.

Deployment was done on Cloudflare Pages. main runs as production while other branches run as preview, with JEKYLL_ENV switched based on CF_PAGES_BRANCH. Production excludes dev-tools and keeps the sitemap, while staging removes the sitemap and applies noindex. DNS was also managed on Cloudflare, which made the cutover smooth.

After the cutover, a few follow-up fixes were made. For example, the favicon wasn't showing up in Google search results, caused by a /favicon.ico 404 and having only a 32x32 PNG. This was fixed with a 96x96 PNG, 48x48 PNG, web manifest, and multi-size ICO.

There's still work left to do. About 65 images over 100KB still need further optimization, and tagging for the 288 migrated posts needs to be refined further. Still, overall they now have a foundation for producing new content faster and at higher quality.