How to Export a WordPress Site to Markdown

There’s a reason developers keep pulling content out of WordPress and into Markdown: a folder of .md files is the closest thing content has to a universal format. It drops into Astro, Hugo, 11ty, Jekyll, Gatsby, and Next.js with zero translation, it lives happily in Git, it diffs cleanly in code review, and it’s the ideal input for feeding your content into an LLM or a RAG pipeline. No database, no lock-in, no builder shortcodes, just text.

The catch is that getting clean Markdown out of WordPress is harder than it looks. This guide covers what a real export needs, what the front matter should contain, when to choose MDX over Markdown, and how to drop the result into whatever you’re building.

Why Markdown wins

Moving your content to Markdown buys you things WordPress can’t:

• Portability: the same files work in any static site generator, and in the next one you switch to.
• Version control: content lives in Git alongside code; every edit is tracked and reviewable.
• Speed: static Markdown builds to plain HTML with no database queries at request time.
• AI-ready: clean Markdown is the preferred input for embeddings, RAG, and LLM fine-tuning. Raw WordPress HTML is not.
• Longevity: plain text outlives every CMS. You’ll still be able to read these files in twenty years.

Why a clean export is actually hard

WordPress’s own tools don’t give you usable Markdown. The built-in WXR export hands you an XML dump of raw post content, and if your pages are built with Elementor, WPBakery, Divi, Bricks, or Oxygen, that raw content is a soup of shortcodes that only render inside WordPress. Convert that to Markdown and you get pages full of [vc_row] and empty <div>s.

A usable Markdown export has to do four things WordPress won’t:

• Render the page first, running the builder, then convert the resulting HTML to Markdown, so a heading is ##, a link is [text](url), and nothing is left as a shortcode.
• Attach front matter to every file (title, description, dates, slug, and SEO fields) so your SSG has something to work with.
• Keep the metadata most exporters drop: the theme-rendered <title>, the permalink (for redirects), and your Yoast / Rank Math SEO fields.
• Produce one file per item, named and foldered sensibly, ready to drop straight into a content directory.

The front matter that matters

Front matter is the YAML block at the top of each Markdown file, it’s how your SSG knows a page’s title, date, and URL. A weak export gives you a title and nothing else; a good one carries everything you need to rebuild the page and preserve its SEO. Here’s what a clean exported file looks like:

---
title: "Corneal Cross-Linking"
description: "A minimally invasive treatment that strengthens the cornea."
slug: corneal-cross-linking
permalink: https://example.com/services/corneal-cross-linking/
date: 2024-03-12
modified: 2025-01-08
type: services
canonical: https://example.com/services/corneal-cross-linking/
---

## What is corneal cross-linking?

Corneal cross-linking is a procedure that uses riboflavin and UV light
to strengthen the collagen fibers in the cornea…

Two fields do the heavy lifting when you care about search rankings. The permalink is your map for building 301 redirects from the old WordPress URLs, and the description plus canonical let your new site reproduce the exact search snippet Google already indexed. Don’t settle for an export that throws them away.

Markdown or MDX, which should you export?

Plain Markdown (.md) is the right default. It’s universal, every SSG reads it, and it stays simple. Choose MDX (.mdx) only if your target framework lets you embed components inside content, Astro, Next.js, and Docusaurus do, and you plan to replace some blocks with interactive components (a callout, a chart, an embed).

Drop it into your static site generator

Once you have a content/ folder of Markdown, wiring it into a generator is a few lines. A couple of the most popular:

Astro

Astro reads a content folder through a typed collection. Point the glob loader at your exported files and define a schema that matches your front matter:

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const services = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/services' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    permalink: z.string(),
    date: z.coerce.date(),
  }),
});

export const collections = { services };

Then render with getCollection() and Astro’s <Content /> component. Full walkthrough in our WordPress → Astro guide.

Hugo & 11ty

These are even simpler: drop the files into content/ (Hugo) or your input folder (11ty) and they’re picked up on the next build. Both read the same YAML front matter shown above, map date and slug to their conventions and you’re done.

Next.js

Next has no built-in Markdown loader, so read the files with a library like gray-matter to parse the front matter and next-mdx-remote or remark to render the body. If Next.js is your destination and rankings matter, follow the SEO-safe path in our WordPress → Next.js guide.

Handling images

Markdown references images by URL, ![alt](src), so by default your exported files still point at /wp-content/uploads/ on the old server. The moment you take WordPress down, every image 404s. You have two options: keep the old media host alive, or bundle the images with your content and rewrite the URLs to local paths. Bundling is the clean answer, it makes your export fully self-contained. Migratik Pro’s one-click media bundle downloads every referenced image, mirrors the folder structure, and rewrites the Markdown URLs to the local copies, so you can serve them through your SSG’s image pipeline.

Common pitfalls (and how to avoid them)

• Shortcode soup: exporting raw content instead of rendered HTML leaves builder shortcodes in your Markdown. Always render first.
• Bare front matter: a title-only export forces you to rebuild metadata by hand. Insist on descriptions, dates, slugs, and SEO fields.
• Broken MDX builds: unescaped { or < in prose. Escape them (or export Markdown, not MDX).
• Dead image links: URLs still pointing at the old uploads folder. Bundle and rewrite.
• Lost redirects: no permalink in the front matter means no way to map old URLs to new ones. Keep the permalink.

Every one of these is a data-capture problem, not a conversion problem. Get a complete, rendered export with rich front matter and the rest is easy.

Frequently asked questions

How do I export a WordPress site to Markdown?

Use an exporter that renders each page first (so builder shortcodes execute), converts the HTML to Markdown, and writes one file per item with YAML front matter, metadata and images. A tool like Migratik does this for the whole site in one step.

How do I convert WordPress to a static site?

Export your content to Markdown, then feed the files into a static site generator like Astro, Hugo, 11ty or Next.js. Keep your URLs, 301-redirect anything that changes, and carry over your SEO metadata so you don’t lose rankings.

What is the difference between Markdown and MDX export?

Plain Markdown (.md) is universal and read by every generator. MDX (.mdx) lets you embed components inside content, but it treats { and < as code, so those characters must be escaped or the build fails. Export MDX only if your framework supports it.

Can I export WordPress images with my Markdown?

Yes. Bundle the referenced images alongside the Markdown and rewrite the URLs to local paths so nothing 404s when the old WordPress uploads folder disappears. Migratik Pro’s media bundle does this in one click.