guides
How to Migrate a WordPress Site to Markdown
Expertise: Documentation and static site workflows
WordPress
Markdown
static site
Jekyll
Hugo
Astro
Next.js
Moving a WordPress site to a static generator—Gatsby, Next.js, Hugo, Jekyll, Astro, or similar—is a common modernization path. The easy part is choosing the framework; the hard part is getting years of posts, pages, and custom fields into clean, portable files. This guide focuses on the **Markdown conversion step**: how to get WordPress content out and into
Keep that export under version control or backup storage before you transform it. If the site is large, exports can time out; in that case use CLI exporters (WP-CLI
Before you convert, decide what **belongs in Markdown** at all. Custom post types, landing pages built with page builders, and shortcode-heavy layouts often translate poorly to
1. WP to Hugo Exporter (Hugo-specific)
If your target is Hugo, the Hugo Exporter plugin exports posts with front matter aligned to Hugo’s expectations. Fast if you are all-in on Hugo; not ideal for other stacks.
**2.
The [
Typical flow:
3. Manual HTML → Markdown
Export HTML for a page (or copy from the rendered post), then convert with a dedicated converter. For one-off pages or odd CPTs, use the free HTML to Markdown converter: paste HTML or fetch from a URL, then copy the Markdown. Pair with Paste to Markdown when you are pasting rich text from the block editor instead of raw HTML.
Download the **Media Library** (FTP, hosting backup, or plugins that zip uploads). Place files in your static repo—e.g.
Rename files if you are standardizing on lowercase, hashes, or content-addressable names—just keep a mapping if old URLs must redirect. For srcset-heavy themes, your Markdown will usually collapse to a single image per figure; pick the best resolution and delete duplicates from the bundle so you are not shipping five sizes of the same hero image.
If SEO matters, plan 301 redirects from high-traffic WordPress URLs to the new paths before you decommission PHP. Your static host (Netlify, Vercel, CloudFront, nginx) can read a simple map file generated from the same spreadsheet you used to fix Markdown links.
For individual pages that still look wrong, round-trip through the HTML to Markdown converter after exporting clean HTML for that page. For quick cleanup of pasted blocks, Paste to Markdown saves time.
Migration is iterative: export once, convert, fix images and links, rebuild, repeat until diffs stop moving. Once Markdown lives in Git, previews, reviews, and rollbacks get dramatically easier—which is usually why you left WordPress in the first place.
Document the commands you used (package version, flags, date of export) in the repo so the next maintainer can reproduce or extend the migration without archaeology.
.md you can commit to Git and ship without PHP or a database.Export your WordPress content
In wp-admin, go to Tools → Export and choose All content. WordPress downloads a WXR file (XML) containing posts, pages, comments, terms, and authors. That file is your canonical snapshot: it does not include the media binaries themselves—only URLs and metadata pointing at uploads—so you will treat images separately.Keep that export under version control or backup storage before you transform it. If the site is large, exports can time out; in that case use CLI exporters (WP-CLI
wp export) or split by post type/date.Before you convert, decide what **belongs in Markdown** at all. Custom post types, landing pages built with page builders, and shortcode-heavy layouts often translate poorly to
.md; sometimes you keep them as MDX, React components, or a handful of static HTML fragments. Tag the exceptions early so your automated pass does not pretend everything is a blog post.Convert WordPress posts to Markdown
You have three practical paths:1. WP to Hugo Exporter (Hugo-specific)
If your target is Hugo, the Hugo Exporter plugin exports posts with front matter aligned to Hugo’s expectations. Fast if you are all-in on Hugo; not ideal for other stacks.
**2.
wordpress-export-to-markdown (recommended for most teams)** The [
wordpress-export-to-markdown](https://www.npmjs.com/package/wordpress-export-to-markdown) npm package reads the WXR and emits Markdown files plus downloaded images. It is stack-agnostic and works well for Jekyll, Astro, Next.js content collections, Eleventy, and Gatsby’s file-based sources.Typical flow:
1.Install Node.js, then run
npx wordpress-export-to-markdown (or install globally) and point it at your .xml export.2.Configure options: output folder, whether to preserve permalinks as filenames, image download behavior, and front matter fields (title, date, slug, categories).
3.Run the tool and inspect a handful of posts in your target SSG before automating the rest of the pipeline.
4.Drop the generated
If you use **content collections** (Astro, Contentlayer-style setups, or Next.js with a .md files into your project’s content directory and wire routes the way your framework expects.content/ tree), align front matter keys with your schema: title, date, draft, tags, and slug should match what your loaders expect so you do not chase type errors after migration. Commit a small subset first—ten posts spanning different eras of the site—and run your production build; fix templates before scaling to the full export.3. Manual HTML → Markdown
Export HTML for a page (or copy from the rendered post), then convert with a dedicated converter. For one-off pages or odd CPTs, use the free HTML to Markdown converter: paste HTML or fetch from a URL, then copy the Markdown. Pair with Paste to Markdown when you are pasting rich text from the block editor instead of raw HTML.
Handle images
WordPress usually serves images from/wp-content/uploads/ on the same host or from a CDN. After migration, those URLs still point at the old site unless you rewrite them.Download the **Media Library** (FTP, hosting backup, or plugins that zip uploads). Place files in your static repo—e.g.
public/images/ or static/ depending on the framework—and **replace image URLs** in Markdown so they use relative paths () or your new asset pipeline. The npm exporter above can download remote images while converting; if you skipped that step, batch-find https://oldsite.com/wp-content/uploads/ in .md files and replace consistently.Rename files if you are standardizing on lowercase, hashes, or content-addressable names—just keep a mapping if old URLs must redirect. For srcset-heavy themes, your Markdown will usually collapse to a single image per figure; pick the best resolution and delete duplicates from the bundle so you are not shipping five sizes of the same hero image.
Handle internal links
WordPress permalinks (/2024/01/my-post/) rarely match static-site URLs (/blog/my-post/ or /posts/my-post). Expect a manual or scripted pass: build a map from old paths to new paths, then search-and-replace in Markdown. Relative links survive hostname changes better than absolute ones; normalize to relative where possible. Broken anchors and pagination URLs are common—grep for your old domain after migration.If SEO matters, plan 301 redirects from high-traffic WordPress URLs to the new paths before you decommission PHP. Your static host (Netlify, Vercel, CloudFront, nginx) can read a simple map file generated from the same spreadsheet you used to fix Markdown links.
Validate the output
Before DNS cutover, open a representative sample of Markdown in your editor and in the built site: headings, lists, code fences, tables, and shortcodes that became raw text. Fix systematic issues in the converter config and re-run rather than hand-editing hundreds of files.For individual pages that still look wrong, round-trip through the HTML to Markdown converter after exporting clean HTML for that page. For quick cleanup of pasted blocks, Paste to Markdown saves time.
Migration is iterative: export once, convert, fix images and links, rebuild, repeat until diffs stop moving. Once Markdown lives in Git, previews, reviews, and rollbacks get dramatically easier—which is usually why you left WordPress in the first place.
Document the commands you used (package version, flags, date of export) in the repo so the next maintainer can reproduce or extend the migration without archaeology.
About the author
SiteSupport Team
Cross-functional team of product specialists and support operators publishing practical guidance on AI support, SEO, and knowledge-base workflows.
View full author profileRelated Articles
guides
How to Use Markdown in Your GitHub README
GitHub renders README.md as Markdown automatically. Here are the elements that matter most—syntax you can copy, tables, badges, and a simple table of contents pattern.
guides
Best HTML to Markdown Converters in 2025
Need to convert HTML to Markdown? Here is a direct comparison of strong options—what each does well, limits, and whether it is free—plus what to evaluate before you commit.
Continue Exploring This Topic
Tool
HTML to Markdown Converter
Paste HTML or provide a URL and get clean, formatted Markdown output. Handles all standard HTML elements — free, no signup.
Tool
Paste to Markdown Converter
Paste formatted text, rich text, or HTML and get clean Markdown instantly. Handles headings, lists, links, images, and more — free.
Tool
File to Markdown Converter
Upload any document — PDF, DOCX, HTML, RTF, or TXT — and get clean, well-structured Markdown output with preserved formatting.
Want AI-powered customer support?
Deploy a custom AI chatbot trained on your website in minutes. No code required.