Migrate WordPress / Drupal HTML to Markdown

Gutenberg paragraph block

WordPress wraps every block in HTML comments. They are dropped, leaving clean Markdown — no manual cleanup needed.

HTML in:
<!-- wp:paragraph -->
<p>Welcome to the <strong>new</strong> site.</p>
<!-- /wp:paragraph -->

Markdown out:
Welcome to the **new** site.

WordPress image figure with caption

A wp-block-image figure becomes a Markdown image followed by the caption as a plain paragraph. The /wp-content/uploads/ path stays as-is and must be rewritten for your SSG.

HTML in:
<figure class="wp-block-image">
  <img src="/wp-content/uploads/2023/05/hero.jpg" alt="Hero"/>
  <figcaption>Our launch event</figcaption>
</figure>

Markdown out:
![Hero](/wp-content/uploads/2023/05/hero.jpg)

Our launch event

Code block from a docs post

If the source uses a language-* class, the fence keeps the language for highlighting on your new theme.

HTML in:
<pre class="wp-block-code"><code class="language-php">echo 'hi';</code></pre>

Markdown out:
```php
echo 'hi';
```

Body conversion plus front matter (two-step)

The tool gives you the body; you prepend front matter from your CMS export. This is the standard Hugo/Astro post shape.

Step 1 — convert body HTML to Markdown (this tool):
## Introduction

Text of the post...

Step 2 — prepend front matter (md-frontmatter-builder):
---
title: "My Post"
date: 2023-05-01
slug: my-post
tags: [migration, hugo]
---

## Introduction

Text of the post...

A YouTube embed disappears

oEmbeds become empty output. Note the URL from the source HTML and re-add it as an SSG shortcode after conversion.

HTML in:
<figure class="wp-block-embed">
  <iframe src="https://www.youtube.com/embed/abc123"></iframe>
</figure>

Markdown out:
(empty — the iframe produces nothing)

Fix: re-add as a Hugo/Astro shortcode, e.g.
{{< youtube abc123 >}}

This tool converts body HTML only — there is no YAML/TOML front matter in the output. Your SSG needs title, date, slug, and tags. Pull those from the CMS export and prepend them with md-frontmatter-builder.

<img> becomes ![alt](src) referencing the original /wp-content/uploads/... URL. The binary is never downloaded. Sync media separately and rewrite the paths with md-image-path-rewriter.

WordPress auto-embeds render as <iframe>, which has no Markdown equivalent and produces empty output. Record the embed URLs from the source HTML and re-add them as your SSG's shortcodes.

Older WordPress posts often have tables built from <tr><td> with no header row. The GFM table rule needs <thead>/<th>, so a header-less table is left as raw <table> HTML. Add a header or repair it with md-table-repair.

If you copy a full page (with inline <style> from the theme) instead of just the post body, the CSS becomes visible text in the Markdown. Always isolate the .entry-content/<article> element before converting.

Unprocessed shortcodes like [gallery ids="1,2"] or [caption] that weren't rendered to HTML pass through as plain text. Convert the rendered HTML (content.rendered) rather than the raw post_content, or clean shortcodes manually.

Drupal's WYSIWYG often adds inline style attributes (font sizes, colors). These are dropped — which is the desired outcome for a clean Markdown migration. The text content is preserved.

CMS HTML is verbose. A long article with many figures can exceed the Free 500,000-character cap. The tool reports the count and limit. Convert the body field (not the full page) or upgrade for the 5,000,000-character Pro limit.

Internal links keep their original CMS URLs (/2023/05/01/old-slug/). If your SSG uses a different URL scheme, these will 404. Validate and remap them with md-link-validator after migrating.