Converting HTML to Markdown: Supported Elements, Pitfalls, and When to Edit by Hand

The contents of a web page are written in HTML, but for blog posts, documentation, and READMEs, Markdown is often easier to handle. Maybe you want to move existing web content to another CMS, or reuse an HTML announcement as an article. That is where converting HTML to Markdown helps. This article walks through why you convert, which elements are supported, which cases tend to break, and how to balance it with manual editing.

Why Convert HTML to Markdown

HTML can describe structure in fine detail with tags, but it tends to be verbose and is not ideal for people to read and write directly. Markdown, by contrast, is a lightweight markup language that expresses headings, lists, and emphasis with just a few symbols and stays readable as plain text. GitHub, many blog services, and documentation tools support Markdown out of the box, which greatly improves how easily content can be moved around.

Common situations where you want to convert HTML to Markdown include the following.

• CMS migration: moving HTML from an old site or WordPress into a Markdown-based static site generator or headless CMS.
• Republishing and reuse: reusing the body of an HTML email or announcement page as a draft for a blog post or knowledge base.
• Version control: managing drafts in Git as Markdown, where diffs are easy to read, for multi-person review.
• Input for AI / LLMs: stripping away extra tags so you can feed just the body text to a generative AI.

To see what the result looks like, it is easiest to paste your HTML into HTML to Markdown and try it. You can feel how a string full of tags is tidied into clean Markdown.

Elements That Convert: Headings, Links, Lists, Tables, Code, Images

HTML and Markdown share many elements with clear correspondences, so the basic document structure converts directly. The table below summarizes the main mappings.

Headings, links, lists, emphasis, and code map especially cleanly and come out almost exactly as intended. Tables can be expressed with pipes ("|") using extended syntax such as GitHub Flavored Markdown, and simple tables convert without trouble. Images keep their alt text and URL, so they are easy to reuse as-is.

If you want to rewrite or fine-tune the converted Markdown while previewing it, paste it into the Markdown Editor and adjust while checking the rendered view.

Cases That Cannot Convert or Tend to Break

Most elements convert cleanly, but because Markdown covers a narrower range than HTML, some things inevitably break or lose information. Knowing these in advance makes the post-conversion check much easier.

• Complex tables: tables with merged cells (colspan / rowspan) or with lists and line breaks inside cells cannot be fully expressed in Markdown table syntax and tend to break.
• Styling and layout: color, font size, centering, and other styles have no Markdown equivalent and are generally lost. Fine layouts built with div or span are the same.
• Deeply nested structures: nesting such as a table inside a list, or a list inside a table, often produces varying results depending on the tool.
• Leftover inline HTML: elements Markdown cannot express may remain as raw HTML tags in the result, since most Markdown allows mixed-in HTML.
• Forms and scripts: input, button, script, and iframe have no concept in Markdown and are either removed or left as raw HTML.

In short, remember that conversion is good at "text plus basic structure" but weak at "visual polish and special layouts." The more decorated a page is, the more touch-up it needs afterward.

Balancing Automatic Conversion and Manual Editing

The realistic and efficient approach is to build the rough draft with automatic conversion and finish it by hand. Rewriting everything manually takes far too long, while expecting perfection from automatic conversion alone risks publishing something still broken.

Concretely, first generate the base Markdown with HTML to Markdown and review any leftover inline HTML or broken tables. Then do the fine adjustments and preview checks in the Markdown Editor. This two-step setup balances quality and speed. When a table is too complex, deliberately keeping the HTML table tags instead of forcing it into a Markdown table can also be a valid choice.

How to Proceed and What to Check

Finally, here is the basic flow for converting HTML to Markdown, along with checkpoints that are easy to miss.

• 1. Convert: prepare the target HTML and paste it into the tool to generate Markdown. Check that no unneeded headers, footers, or navigation got mixed in along with the body.
• 2. Check links and images: verify that relative-path links and image URLs still open correctly at the destination, and rewrite them to absolute URLs if needed.
• 3. Inspect tables and code: see whether merged table cells broke and whether code-block language hints or symbols shifted.
• 4. Final check in preview: confirm that heading levels and list nesting render as intended, and clean up any leftover HTML tags.

Convert HTML to Markdown and your content becomes lighter, easier to port, and easier to track in diffs. Start by trying your HTML in HTML to Markdown, then refine the result while checking it in the Markdown Editor. Once you understand the mechanism and its strengths and weaknesses, conversion becomes far less stressful.

Please note that this article is intended to provide general information. Markdown syntax support varies by environment (GitHub, various CMSs, editors). For an actual migration, make your decision after checking the latest official documentation of the service you use.