Migration Path: From Local MDX Blog to Strapi in Production

Moving from file-based MDX to Strapi gives you a proper CMS and draft workflow. Doing it in a planned way keeps URLs stable and content intact.

Align the content model

Design a Strapi collection type (e.g. “Post”) that matches what you have in MDX: title, slug, excerpt, date, author, tags, body. For the body, you can use Strapi’s rich text (which outputs HTML or Markdown depending on config) or a long text field that stores Markdown. If you need components inside content (e.g. custom blocks), use a dynamic zone or a Markdown/MDX string and render it on the front end. The goal is one-to-one mapping: one MDX file → one Strapi entry with the same slug and equivalent fields.

Export and transform

Write a script that reads your MDX files (e.g. from content/blog/), parses frontmatter (e.g. with gray-matter), and extracts body and metadata. Map frontmatter to Strapi fields (title → title, slug → slug, etc.). Handle images: either upload them to Strapi (via the upload API) and replace relative paths in the body with Strapi media URLs, or keep images elsewhere and update URLs in the body. Generate a JSON or use Strapi’s API to create entries. Run the script in batches if you have many posts and add idempotency (e.g. skip or update by slug) so you can re-run safely.

// Concept: migration script
const files = fs.readdirSync("content/blog");
for (const file of files) {
  const raw = fs.readFileSync(path.join("content/blog", file), "utf8");
  const { data, content } = matter(raw);
  await strapiCreate("post", {
    title: data.title,
    slug: data.slug ?? file.replace(/\.mdx?$/, ""),
    excerpt: data.excerpt,
    publishedAt: data.date,
    content: content,
    // ... map tags, author if you have them
  });
}

URLs and redirects

Use the same slug in Strapi as in your MDX so URLs don’t change (e.g. /blog/my-post stays /blog/my-post). If your old site had a different structure (e.g. /posts/my-post), add redirects in Next.js or at the host so old links point to the new path. Set canonicals in Next.js to the new URL so search engines consolidate to one version.

Cutover and cleanup

Once content is in Strapi, switch the Next.js app to fetch from Strapi instead of the file system. Keep the same page routes and components; only change the data source. Test listing and single post pages, images, and metadata. After cutover, you can archive or remove the old MDX files; keep a backup until you’re confident. With this path, migration from local MDX to Strapi is predictable and production-ready.

Summary

Model Strapi to match your MDX frontmatter and body; script the export and creation of entries; preserve slugs and fix image URLs. Keep URLs the same or add redirects, then switch the app to Strapi and test. That’s a clear migration path from MDX to Strapi.