Convert an HTML article to GFM Markdown and verify it before publishing

Problem

CMS exports and saved pages mix useful prose with navigation, metadata, tracking scripts, forms, relative assets, and HTML structures that Markdown cannot represent faithfully. A converter can produce readable GFM while silently changing a headerless table, dropping a control, retaining a risky URL, or leaving links that only work on the old site. Migration is complete only when the source scope, conversion warnings, destination paths, renderer behavior, and final published result have all been checked.

When to use this

• A reviewed CMS article or knowledge-base entry must move into a Git repository, static-site generator, wiki, or documentation platform.
• HTML release notes contain headings, code, tables, links, and task items that should become editable GFM.
• A saved HTML fragment needs a readable archival copy while preserving evidence of structures that could not be converted.
• A documentation team wants a repeatable checklist for converting several articles without copying scripts, page chrome, or broken relative assets.

Steps

1. Step 1

   Isolate the article body and record its dependencies

   Select the smallest article, documentation section, or release note that is meaningful on its own. Exclude site navigation, cookie banners, related-content panels, footer links, and document metadata. Record every image, download, anchor, embedded media item, table, form, and stylesheet that affects the source. Remove secrets, unpublished customer details, internal hostnames, and analytics identifiers before placing the HTML in any migration fixture.

2. Step 2

   Capture a source baseline before conversion

   Open the original article and save a checklist of heading order, paragraph breaks, lists, quotations, code language labels, table headers, link targets, image captions, alt text, and any interactive behavior. Check both desktop and narrow-screen rendering. This baseline distinguishes intentional Markdown simplification from accidental data loss and gives reviewers something concrete to compare.

3. Step 3

   Convert the focused fragment and read every warning

   Open HTML to Markdown in Markup Conversion Workbench and run the focused fragment. Compare the result with the source, then inspect warnings for scripts and styles removed, document metadata omitted, inline event handlers, active URL schemes, controls or media with no Markdown equivalent, raw HTML preservation, node limits, and deep nesting. Do not clear a warning merely because the visible prose looks correct.

4. Step 4

   Resolve structures that Markdown cannot carry

   Rebuild forms, buttons, iframes, canvas, SVG, audio, and video as destination-native components or replace them with meaningful links and prose. Decide whether details, kbd, mark, sub, sup, and headerless tables may remain as raw HTML under the destination policy. Rework rowspan and colspan tables into simple header-row tables, lists, or multiple sections when exact layout cannot be retained.

5. Step 5

   Move assets and rewrite every destination path

   Copy approved images and downloads into their final repository or media location, preserving licenses and descriptive filenames. Rewrite relative href and src values, verify fragments and redirects, replace javascript or data-document URLs, and remove event attributes from any raw HTML. Confirm that remote images do not disclose private hosts or depend on an expiring CMS session.

6. Step 6

   Preview with the real renderer and publish from a reviewed diff

   Render the Markdown with the exact GitHub, wiki, documentation engine, or static-site build that will publish it. Test links, images, code fences, task markers, tables, raw HTML policy, heading navigation, keyboard access, and 390px mobile layout. Run the destination formatter, linter, link checker, accessibility checks, and production build, then review the source-to-output diff before merging or publishing.

Example

<article><h1>Release notes</h1><p>Read the <a href="/docs/setup">setup guide</a>.</p><table><tr><th>Version</th><th>Status</th></tr><tr><td>2.4</td><td>Ready</td></tr></table><script>trackDraft()</script></article>

# Release notes

Read the [setup guide](https://docs.example.com/docs/setup).

| Version | Status |
| --- | --- |
| 2.4 | Ready |

The script-removal warning is resolved in the review log, the relative link is rewritten for the destination, and the table is checked in the target renderer.

Common mistakes

FAQ