Migrating from WordPress.com to VeloCMS (full playbook)
WordPress.com doesn't give you raw database access, but its XML export contains everything you need. This playbook covers the full migration — posts, images, comments, and redirects — without data loss.
Migrating from WordPress.com to VeloCMS takes about two hours for a blog with 100 posts. The process uses WordPress's built-in WXR XML export, a conversion script that transforms WXR into VeloCMS's import format, and a 301 redirect setup in Cloudflare to preserve your SEO. Nothing requires database access — the entire migration happens through WordPress.com's export tool and VeloCMS's import endpoint.
Step 1 — Export your WordPress.com content
In your WordPress.com dashboard, go to Tools Export. Select 'All content' and click Download Export File. WordPress generates a .xml file (the WXR format) containing every post, page, comment, tag, category, and image URL. Save this file — it's the source of truth for your entire migration.
WordPress.com exports image URLs pointing to i0.wp.com or yoursite.wordpress.com. The import script downloads and re-uploads each image to your VeloCMS Cloudflare R2 bucket automatically — as long as the WordPress.com site is still live during import.
Step 2 — Convert WXR to VeloCMS import format
Install the VeloCMS migration CLI globally with npm i -g @velocms/migrate. Then run velocms-migrate wxr-to-json --input export.xml --output posts.json. The converter parses each post, strips WordPress shortcodes, converts embedded HTML to the VeloCMS block AST, and outputs a JSON array of post objects ready for the import endpoint. Review the output for any shortcodes the converter flagged as unsupported — these will need manual editing after import.
Step 3 — Import into VeloCMS
In Admin Tools Import, upload the posts.json file. The importer processes posts in batches of 10, showing a progress bar and a log of any posts that encountered errors. Successfully imported posts land as drafts — review and publish them on your own schedule.
Step 4 — Set up 301 redirects
If your old WordPress.com blog was at yourname.wordpress.com and your new VeloCMS blog is at yourname.velocms.org (or a custom domain), you need 301 redirects for every old URL. WordPress.com doesn't let you set server-level redirects, but you can use Cloudflare's Page Rules or Redirect Rules to catch requests to the old URLs and redirect them. The migration CLI generates a redirects.json file — upload it to Cloudflare's Bulk Redirect feature to set up all redirects in one step.
Step 5 — Verify and clean up
After import, run velocms-migrate verify --site yoursite.velocms.org --source export.xml to compare post counts, check for broken image links, and validate that redirects are returning 301. The verify command prints a table of any mismatches. Fix them before announcing the migration publicly. Once verified, update your email newsletter, social profiles, and any external links you control to point to the new URLs.