WordPress Static Migration Toolkit

A validation toolkit for WordPress-to-Static migrations, covering HTML Completeness, Broken Links, Missing Assets, Root-Relative URL correctness, Canonical URLs, Redirects, Sitemaps, Robots.txt, and Structural Comparison against the original source.

Purpose

Static exports of WordPress sites are a common architecture choice for Performance, Security, and Hosting simplicity. They are also easy to get wrong in ways that are not visible from a quick browse or an HTTP status check: broken internal links, missing assets, links that escape the intended deployment directory when the site moves to a subdirectory, and pages that export incompletely while still returning a 200 response.

This toolkit exists to make those failure modes checkable, not just avoidable in theory. It documents a generic Migration Workflow and provides scripts that validate an export before it is deployed, and the deployment itself once it is live.

Key Features

• A documented, platform-agnostic WordPress-to-Static Migration Workflow.
• Explicit documentation and automated enforcement of the Subdirectory Deployment rule for root-relative URLs (see docs/subdirectory-deployment.md).
• Scripts covering HTTP Status, Broken Internal Links, Missing Assets, Root-Relative URL correctness, Canonical URLs, Redirect mapping integrity, Sitemap and Robots.txt validation, HTML Completeness, and basic Structural Comparison against a source snapshot.
• A single orchestrator script that runs the full checklist against a project configuration file and produces a pass/fail summary.
• Working example fixtures, including a deliberately flawed static export used to demonstrate that the checks actually catch real issues.

Technical Approach

Every script in this toolkit is read-only: none of them modify the static export or the WordPress source. Each script is independently runnable and also composed by scripts/run-all-checks.sh, so the toolkit can be used as a full pre-deployment gate or as individual targeted checks during development.

The central technical position of this toolkit is that an HTTP 200 response does not confirm a successful migration. Validation is split across two categories accordingly: pre-deployment checks that inspect the static export directly, and post-deployment checks that verify the live result. See docs/validation-checklist.md for the full breakdown.

Requirements

• A Bash-compatible shell (Git Bash or WSL on Windows, native on macOS and Linux).
• curl, used by the HTTP status check.
• No paid APIs or external services are required.

Usage

Run an individual check directly:

cd scripts
./check-broken-links.sh ../examples/static-site
./check-root-relative-urls.sh ../examples/static-site-with-issues /project

Run the full checklist against a project configuration:

cp examples/migration.env.example my-project.env
# Edit my-project.env to point at the real export directory and domain.
cd scripts
./run-all-checks.sh ../my-project.env

Each script exits with a non-zero status when it finds issues, so they can be used directly in a CI pipeline or a pre-deployment step.

Project Structure

README.md
LICENSE
.gitignore
docs/
  migration-workflow.md          Full migration workflow, stage by stage
  subdirectory-deployment.md     The root-relative URL rule and why it matters
  validation-checklist.md        Pre- and post-deployment checklist
scripts/
  check-http-status.sh
  check-broken-links.sh
  check-missing-assets.sh
  check-root-relative-urls.sh
  check-canonical-and-redirects.sh
  check-sitemap-robots.sh
  check-html-completeness.sh
  compare-structure.sh
  run-all-checks.sh
examples/
  static-site/                   A clean example export (passes all checks)
  static-site-with-issues/       A deliberately flawed export (fails several checks)
  reference-site/                A source snapshot used for structural comparison
  urls.txt, redirects.csv, migration.env.example

Security / Safety Notes

• All scripts are read-only checks. None of them write to, delete, or modify the static export, the source WordPress installation, or any deployed environment.
• Example fixtures use only the reserved documentation domain example.com and a placeholder static.example.com. No real infrastructure, hosting details, or client data is referenced anywhere in this repository.
• The Redirects and Sitemap/Robots.txt checks validate structure and self-consistency; they do not test a live server configuration. Use check-http-status.sh against the deployed URLs to confirm redirects behave correctly once live.

Disclaimer

This toolkit performs technical checks against a static export. It does not replace professional Technical SEO analysis, a manual visual review of key templates, or judgment specific to a given project's requirements. Treat a passing result as a precondition for deployment sign-off, not as sign-off itself.

Professional Context

This toolkit reflects a working position on WordPress-to-Static migrations developed through practical Website Migration and Technical SEO work: that correctness has to be validated at the content and structure level, not assumed from a status code. It was built by Didac Soria (https://didacsoria.com), and is part of the broader Web Development, Technical SEO, and Web Infrastructure practice at StudioDDC (https://studioddc.com).

License

Released under the MIT License. See LICENSE for details.