JSPM

Migrate anything text-shaped to WordPress — powered by GitHub Copilot CLI.

Point it at a Jekyll / Hugo / Eleventy / Gatsby / Next / Astro / Hexo / Docusaurus / MkDocs site, a WordPress WXR export, a Medium or Substack export, a folder of Word documents, a spreadsheet of rows, a library of PDFs, an EPUB, a GitHub repo README, a pile of markdown notes, or plain .txt files. Walk away. Come back to a fully working, pixel-close WordPress under wp-env with a custom theme, a site plugin, imported content and media, preserved permalinks (where they existed), and a self-verified build.

Install · Quick start · How it works · Supported sources · CLI · FAQ

Why

Moving a content-heavy static site to WordPress by hand is a week of template translation, shortcode rewrites, data shuffling, and URL remapping. to-wordpress collapses that into one command: a deterministic TypeScript pipeline drives GitHub Copilot CLI (copilot -p) in a hybrid orchestration — the tool owns phase transitions, file I/O, and verification; Copilot handles the creative parts (Liquid → PHP, custom-block generation, edge-case normalization, auto-fix).

What lands in wp-content/:

• A bespoke classic WordPress theme with template-parts/… mirroring your source includes one-to-one.
• A site plugin owning non-theme concerns — CPTs, newsletter, giscus, analytics, cookie banner, redirects, options page.
• Posts, pages, terms, menus, users, featured images — imported via wp-cli with original permalinks preserved by default.
• A self-written WORDPRESS_MIGRATION.md that documents every decision so you can audit or replay the run.

Install

to-wordpress is meant for one-shot runs, so use npx — no global install needed:

npx to-wordpress ./path/to/your-site

Or install globally if you iterate on the same source:

npm install -g to-wordpress
to-wordpress ./path/to/your-site

Requirements

• Node.js ≥ 20
• Docker (for wp-env and the Jekyll prerender container)
• GitHub Copilot CLI: brew install --cask github-copilot-cli then copilot login

The tool is self-contained otherwise — no Ruby, no PHP, no wp-cli on the host. wp-env runs WordPress in Docker and the tool talks to wp-cli through it.

Quick start

# 1. Clone or cd into any static site
git clone https://github.com/you/your-jekyll-site
cd your-jekyll-site

# 2. Run the migration (interactive TUI, asks a few URL questions)
npx to-wordpress .

# 3. Open the result
open http://localhost:8888

When it finishes you'll have:

your-jekyll-site/
├── .wp-env.json              # theme + plugin + content mounted into WordPress
├── WORDPRESS_MIGRATION.md    # the plan + per-phase status + state block
└── WORDPRESS_MIGRATION/
    ├── theme/                # your generated classic theme
    ├── plugin/               # your site plugin
    ├── content/              # canonical markdown for every post & page
    ├── media/                # collected image assets
    ├── rendered/             # Jekyll/Hugo/Eleventy build output (ground truth)
    ├── import-manifest.json  # exact payload fed to wp-cli
    ├── redirects.json        # old-path → new-path map
    └── verify-report.json    # url parity + count diff from the last run

Want non-interactive? Add --yes (uses defaults for every prompt):

npx to-wordpress ./my-site --yes

How it works

flowchart LR
    src[Source site] --> D[Detect]
    D --> P[Plan]
    P --> B[Boot wp-env]
    B --> T[Theme]
    T --> PL[Plugin]
    PL --> N[Normalize]
    N --> I[Import]
    I --> V[Verify]
    V -->|issues| F[Fix]
    F --> V
    V -->|clean| WP["Working WordPress @ localhost:8888"]

Every phase is implemented in TypeScript with a deterministic fallback, then optionally enriched by copilot -p running in autopilot mode. Copilot streams JSONL events back to the tool's Ink TUI, which renders a live phase dashboard, activity log, and approval prompts.

Supported sources

to-wordpress ships detectors for every shape of content we've seen — from real SSGs down to "a folder of PDFs". Each detector emits a detector briefing that steers the theme, plugin, plan, and normalize phases; binary/tabular formats are first routed through a per-format conversion prompt (see src/prompts/convert-*.md) that turns the raw source into canonical markdown before the rest of the pipeline runs.

Static-site generators

Documentation frameworks

CMS / platform exports

Raw documents / text piles

Code repos

Fallback

Per-format conversion prompts

Formats that aren't already markdown are routed through a Copilot prompt before normalize runs. Each prompt lives in src/prompts/ and is self-contained:

• convert-docx.md — Word documents
• convert-xlsx.md — Excel workbooks
• convert-csv.md — CSV / TSV
• convert-pdf.md — PDFs
• convert-epub.md — EPUB books
• convert-txt.md — plain text / RST
• convert-html.md — generic HTML pages
• convert-wxr.md — WordPress WXR
• convert-medium-html.md — Medium export
• convert-substack.md — Substack export
• convert-readme.md — GitHub README → landing page

Adding a new source type

~60 lines of code and one prompt:

1. Drop a detector file in src/detectors/, implement match() + detect().
2. Register it in src/detectors/index.ts.
3. If the source isn't already markdown, declare rawSources[] on the DetectedContext, pick (or add) a RawSourceFormat in src/types.ts, and write a src/prompts/convert-<format>.md.

CLI

Usage: to-wordpress [options] [source]

Migrate any codebase to WordPress. Hybrid orchestration with GitHub Copilot CLI.

Arguments:
  source                    path to the source site to migrate (default: ".")

Options:
  -v, --version             print version
  --skip-boot               skip wp-env start (assumes already running)
  --skip-copilot            use deterministic fallbacks only, don't invoke copilot
  -y, --yes                 auto-answer all prompts with defaults
  --only <phase>            run only this phase (advanced)
  --from <phase>            start from this phase (skip earlier ones)
  --until <phase>           stop after this phase (skip later ones)
  --max-fix-iterations <n>  max Verify→Fix iterations (default: 3)
  -h, --help                display help

<phase> is one of: detect, plan, boot, theme, plugin, normalize, import, verify, fix.

Re-running just the theme

Iterating on theme fidelity? The state is persisted inside WORDPRESS_MIGRATION.md, so you can resume any later phase:

npx to-wordpress ./my-site --yes --from theme --skip-boot

Non-interactive in CI

npx to-wordpress ./my-site --yes --skip-copilot --until normalize

Skipping Copilot means every Copilot-driven step uses the deterministic fallback — you still get detect, plan, normalize, and import, just without the pixel-perfect theme transforms.

The migration doc

to-wordpress writes a live, human-readable WORDPRESS_MIGRATION.md inside your source repo. It contains:

• The phase table with status + timestamps.
• Overview of the migration and permalink strategy.
• A template-mapping table (every source layout/include → WP file).
• A feature-to-output mapping (theme vs plugin vs external plugin).
• Risks & open questions.
• Acceptance criteria the Verify phase checks against.
• A WPIFY:STATE JSON block at the bottom the tool reads back on resume.

You can commit this file — re-running to-wordpress updates it in place rather than re-planning from scratch.

Prompts

Every Copilot-driven phase runs with a rigorously structured prompt in src/prompts/. A shared preamble (_shared.md) gives every phase the same autonomy + fidelity contract; each phase adds:

• Explicit Scope (which dirs may be written).
• Explicit Required output (every file that must exist).
• Non-negotiable rules (e.g. never esc_html(get_the_title()) in a template).
• Banned anti-patterns (no TODOs, no Lorem ipsum, no hard-coded localhost URLs, no silenced PHP errors).
• A self-check the model walks before stopping.

The prompts are intentionally opinionated about WordPress best practices: escaping, text-domain consistency, activation hooks, idempotent wp-cli, options API, rewrite rules.

FAQ

Is my data safe? The tool writes everything under WORDPRESS_MIGRATION/ inside your source repo and to a local wp-env Docker volume. No network calls except to the GitHub Copilot API and Docker Hub. Nothing is sent to your live WordPress until you decide to deploy the generated theme/plugin.

Why wp-env? It pins WordPress + PHP versions, runs wp-cli in-container, and tears down cleanly. You can export the database afterwards with npx wp-env run cli wp db export.

What about pixel-perfect? The theme phase builds your Jekyll/Hugo site into HTML first (inside a Ruby 3.2 container so host Ruby version doesn't matter), then feeds that ground-truth DOM to Copilot as the exact target. Verify re-fetches your local WP and diffs structure + titles + status — any drift goes back to a scoped Fix loop.

Can I use a live WordPress instead of wp-env? Not yet — the import uses wp eval-file inside the wp-env cli container. Remote WP-via-REST-API is a planned target.

Does it migrate comments? Comments stay wherever they live (giscus/disqus/commento). The plugin re-attaches the same integration in WordPress so threads keep working.

What's the Copilot bill? Expect 3–5 Copilot sessions per full run (plan, theme, plugin, per-post normalize edge cases, fix loop). A ~40-post Jekyll site runs in ~20 minutes end-to-end.

Development

git clone https://github.com/f/to-wordpress
cd to-wordpress
npm install
npm run build
node dist/cli.js ./fixtures/unknown --skip-boot --skip-copilot --yes --until normalize

Run type checks and build in watch mode:

npm run typecheck
npm run dev

The codebase is:

• src/cli.tsx — commander entry + Ink TUI bootstrap.
• src/copilot/run.ts — spawn copilot -p, parse JSONL events.
• src/detectors/ — one detector per SSG + freestyle fallback.
• src/phases/ — one file per phase.
• src/prompts/ — markdown templates + loader.
• src/tui/ — Ink app, event bus, headless logger.
• src/wp/ — thin wrappers around npx wp-env and wp-cli.

PRs welcome — especially new detectors, new Copilot prompts for specific frameworks, and verify rules that catch more drift.

License

MIT © Fatih Kadir Akın