---
title: "Migrate from WordPress"
url: "https://docs.chinaski.net/en/guides/migrate-from-wordpress/"
type: "page"
language: "en"
description: "Migrate from WordPress using Chinaski's real import paths: Markdown with front matter, what is unsupported, and a practical order of work."
updated: "2026-09-29"
generated: "Markdown rendition of the HTML page at url, built by Chinaski"
---

# Migrate from WordPress

There is no resident WordPress importer in Chinaski: no WXR/XML export parser, no `wp_posts` migration script. Migration is a **prep-outside, import-inside exercise**, using the import surfaces the product genuinely ships. This page maps what works, what’s unsupported, and a practical migration order.

## What migrates cleanly today

Three verified landing surfaces accept structured content:

### Option A: Markdown files (the natural WordPress escape hatch)

The **Markdown importer** (`/admin/import-markdown`, linked from both Posts and Pages) accepts:

- A single `.md` file or a batch of up to **100 files** (40 MiB aggregate).
- Per-file YAML front matter: `title`, `slug`, `language`, `meta_title`, `meta_description`, `category`, `tags`, `date`.
- Graceful fallbacks: a missing title falls back to the file’s first `H1` heading, then a prettified filename.
- Imports create **drafts by explicit design**: nothing auto-publishes, scheduled publishing is never disturbed by an import.
- **Per-file error isolation**: failing files are named in the result without failing the whole batch.
- Markdown converts server-side via the optional CommonMark module; if your host lacks it, the route reports a clear admin error (install the module or use HTML content through the JSON/CSV/API paths).

Exporting WordPress content into `.md` files (title + front matter + body) is the lightest-tested path: many WP export plugins emit Markdown directly, or a small script can unroll `wp_posts` rows.

### Option B: JSON/CSV

The pages/posts list **export** routes emit the full column set in the order the import endpoint expects (OG metadata, canonical URL, scheduling datetimes in the site timezone, nesting, recurring). Build a converter that maps WordPress fields into those columns and `wp_content` HTML, feed it in as JSON/CSV, and reviews/imports land with the round-trip machinery doing the syntax-checking for you.

### Option C: The REST API (and MCP bulk)

For large/batch migrations the `/api/*` surface is the cleanest:

- **POST/PUT** for single items (pages, posts, blocks, snippets…).
- **`POST /api/jobs`** accepting `bulk_upsert_pages`, `bulk_upsert_posts`, `bulk_create_blocks` for large batches (upserts match on slug+language).
- If you’re already wired to the **MCP server**, `bulk_import` and its translation/audit tools ride the same surface.

## Media

There is no WordPress media importer. `wp-content/uploads` is re-uploaded through the media library (bulk upload works) or scripted per-asset via the API; then in-body references are patched (find/replace old upload-domain paths → new media paths). Media replacements elsewhere carry on the same filename, so any post-import reference can point the same place.

## What does NOT migrate

- **WordPress themes** (PHP template hierarchies); Chinaski has no PHP theming; redesign on Template Toolkit, optionally generated via the design-brief flow in the in-app docs.
- **WP plugins**: no hook architecture to map onto; plugin features become blocks, snippets, or editorial process.
- **Revisions, autosaves, approval history**: treat migration as “land the live content”, not as provenance; audit/review trails start fresh.
- **Forms plugins**: nothing maps automatically; rebuild forms in Chinaski’s forms editor and repoint shortcodes.
- **Comment systems**: no equivalent; cover separately if needed.

## The practical migration order

1. **Export from WordPress**: get `wp_posts` + categories/tags out (any WP export plugin or SQL).
2. **Convert offline** to either Markdown files with front matter or a JSON list in the import column order; put each language under its own directory/field.
3. **Upload media separately**: re-upload into the media library (bulk) or script the REST route; then patch the imported content’s internal references.
4. **Run the import**: the Markdown importer per file-batch or the API bulk for structured data; drafts arrive for content review.
5. **Spot-check**: verify slugs, timezone-sensitive dates, categories (each content row lands under the language configured in the import batch), and image references.
6. **Publish**: approve or publish drafts (the approval workflow may be off for admins; on for editors).
7. **Handle old URLs**: export the wp-URL→new-URL mapping and add redirects in the admin’s redirects section (patterns supported where the reverse proxy enforces them). Old search-engine links stay valid.

## What you’ll set up manually, not migrated

- **Users/admin accounts**: new logins per instance (WordPress users don’t carry across).
- **Theme**: Template Toolkit authoring with a choice of design systems (the docs’ LLM Theme Prompting prompt flow is the fastest setup for a custom design).
- **Form stacks**: every contact/feedback form is rebuilt under Chinaski’s Forms.
- **Any WP plugin without a direct Chinaski equivalent**: search, SEO, caching, security plugins: use the in-app relevant subsystems (SEO is built-in; caching is the static-build model).
- **Schedules**: the new instance’s cron/systemd activation points (deploy/backup/DB) as its own operational install. If your WordPress ran these from plugins, this install’s own services replace them.
