HTML to Markdown: A Real Migration in 6 Easy Steps

Maya had 42 blog posts trapped in an old CMS and one weekend to move them. The new static site reads only Markdown, so the job was HTML to Markdown, and it had to keep every table, link and code sample. This is a made up but typical case, and it shows what really happens.

HTML to markdown questions from the field

The HTML to Markdown scenario: 42 posts, one weekend

The old CMS exported each post as an HTML file. Inside sat the article, wrapped in layout divs, with a navigation bar above it and a footer below. The posts used headings, bold text, lists, two or three tables, and now and then a code sample.

Maya did the sums first. Forty two posts at four minutes each is 168 minutes, a little under three hours. That left room for fixes. The risk was not time. It was a silent mistake repeated 42 times.

Step 1: pick one pilot post

She chose the most complicated post: six headings, nine links, two tables and one code block. If the converter handled that, the simple posts would be fine. Here is a cut down version of it.

Pilot post, trimmed (HTML)

Copy<div class="post">
  <h2>Our 2025 pricing</h2>
  <p>We now offer <strong>three</strong> plans. See the <a href="/pricing" title="Plans">pricing page</a>.</p>
  <ul><li>Starter</li><li>Team</li><li>Studio</li></ul>
  <table>
    <tr><th>Plan</th><th>Seats</th></tr>
    <tr><td>Starter</td><td>1</td></tr>
    <tr><td>Team</td><td>5</td></tr>
  </table>
  <pre><code class="language-bash">npm run build</code></pre>
</div>

Step 2: run the conversion and read the output

The converter does not use find and replace on the text. It hands the markup to the browser, which builds a real tree of elements, and then it walks that tree. Because the browser has already sorted out the nesting, the layout div simply disappears and its children are converted. No stray symbols are left behind.

Result (Markdown)

Copy## Our 2025 pricing

We now offer **three** plans. See the [pricing page](/pricing "Plans").

- Starter
- Team
- Studio

| Plan | Seats |
| --- | --- |
| Starter | 1 |
| Team | 5 |

```bash
npm run build
```

Every piece is where it should be. The heading became two hash marks. Bold became double asterisks. The link kept its title. The table gained a separator row of dashes, which Markdown needs to recognise a table. The code block kept its language, read from the class on the code element.

Step 3: fix the four problems the pilot revealed

The pilot looked good. Then Maya checked the rest of the post and found four things. Every migration meets some version of them.

If your source markup is messy or minified, run it through the HTML formatter first. Indented markup is far easier to trim down to the article container.

Step 4: set the options once

GitHub Flavored Markdown matters most. Plain Markdown has no table syntax, so the table support, the strikethrough and task lists all come from that extension. The specification requires the header row and the separator row to have the same number of cells, otherwise the table is not recognised. The converter builds the separator to match the header, including padding for short rows.

Step 5: run the batch and verify

Maya converted the posts one at a time and used the counters under the output as a check: words, lines, headings and links. Her rule was simple. The number of headings and links in the Markdown must equal the number in the source.

The third post failed on both counts. She had copied only part of the article, so the last section never reached the converter. She pasted the full container and converted again. The mismatch cost two minutes and prevented a cut off post from going live. The preview tab then rendered the Markdown so she could see headings and tables as a reader would.

1. Paste the article HTML onlyCut away navigation, footer and scripts before you paste.
2. Convert and open the previewLook at headings, tables and code blocks visually.
3. Compare countersHeadings and links in the output must match the source.
4. Download the fileSave it as an md file with the post slug as its name.
5. Log the resultNote pass or fix for each post so you can resume after a break.

Step 6: handle the small details

By post ten the routine was steady, and the remaining differences were small ones. Maya kept this list next to the keyboard so she knew what to expect rather than what to fear.

By Sunday afternoon all 42 files sat in the new site folder, each with a log line marked pass or fixed. The site build ran without a single warning, which was the real test. Nothing about the HTML to Markdown process was clever. It was repeated, counted and checked.

What the story teaches

Markdown is a smaller language than HTML. Conversion keeps meaning and drops styling. That is the right trade for text, and it is why you must decide what you can afford to lose.

If you need the reverse direction, for instance to preview how the Markdown will look on the web, the Markdown to HTML converter closes the loop.

Your own migration checklist

Sources: GitHub Flavored Markdown Spec