HTML to Markdown Guide: Convert Pages to Clean Markdown

Markdown is a plain-text writing format that uses simple markers for structure: hashes for headings, asterisks for emphasis, brackets for links, and dashes for lists. It is popular for documentation, notes and content that moves between systems, because it is readable as plain text and renders into formatted output. HTML, by contrast, is verbose and precise, with tags for every element. Converting HTML to Markdown turns a web page into a portable document that can be edited in any text editor and published on platforms that accept Markdown.

The HTML to Markdown Converter tool performs that conversion. Headings map to hashes: h1 becomes a single hash, h2 two hashes, and so on. Paragraphs become plain text separated by blank lines. Links become bracketed text followed by a parenthesised address. Bold and italic map to asterisks or underscores. Lists map to dashes or numbers. The mapping is mostly clean, but it is not complete: Markdown has no native equivalent for every HTML feature, so complex tables, embedded media, forms and intricate layouts either convert approximately or drop features. Knowing what survives prevents disappointment.

Conversion quality depends heavily on the source markup. Clean, semantic HTML converts well, because its headings, lists and links map directly. Markup built from nested divs with classes converts poorly, because the converter sees generic containers rather than structure, and the resulting Markdown is a flat wall of text. Cleaning the source, or at least understanding its structure, before converting saves more time than fixing the output afterwards.

A worked example you can follow

Take a short HTML fragment: an h1 with the text Guide, a paragraph with the text See the tool for details where tool is a link to a page address, and a list of two items, Apples and Pears. The Markdown output is: a line reading number sign, space, Guide; a blank line; a line reading See the, bracketed tool, parenthesised address, for details; a blank line; then two lines starting with a dash, Apples and Pears. Counting lines gives 1 heading line, 1 blank line, 1 paragraph line, 1 blank line and 2 list lines, totalling 6 lines. The word count is unchanged in spirit: Guide (1), See (2), the (3), tool (4), for (5), details (6), Apples (7), Pears (8), totalling 8 words, since the address itself is not a word of the document.

Now consider a fragment with a table of 3 rows and 2 columns. Markdown supports simple tables with pipes and dashes, so a basic table survives, but merged cells, nested tables and styled cells do not: a merged header becomes an ordinary cell, and nested structure flattens. If the table carries the document's key data, verify the converted table cell by cell against the original, because a flattened table can silently misalign values with headers. For a 3 by 2 table, that check is 6 cells, quick to do and worth doing.

After conversion, clean the output: remove leftover HTML comments, fix heading levels that no longer nest sensibly, and check that links still point where they should. The Remove HTML Tags tool strips markup when plain text is wanted instead, and the Word Counter tool verifies the converted document's length.

Common mistakes to avoid

The first mistake is expecting a perfect conversion of complex layouts, which Markdown cannot represent. The second is converting markup built from generic divs and wondering why the structure vanished. The third is publishing converted output without checking tables and links, the two features most likely to degrade. The fourth is converting a page that contains scripts or forms and assuming the interactive parts survived. The fifth is losing the original HTML, which is the only version that can be converted again if the Markdown output proves inadequate.

For background on writing portable documentation, see Format and Validate JSON. Convert from clean source, verify tables and links, clean the result, and Markdown becomes a genuinely portable version of the page rather than a degraded copy.

Markdown flavours and portability

Markdown is not one standard but a family of flavours, and that matters for converted output. Basic Markdown covers headings, paragraphs, emphasis, links, lists and simple tables, and it works almost everywhere. Extended flavours add footnotes, definition lists, task lists, strikethrough and fenced code blocks with language names, but support for those extensions varies by platform: a document that renders perfectly on one platform may lose its footnotes or task checkboxes on another. When conversion targets a specific platform, check which extensions that platform supports, and simplify the output to the common subset when the document must travel between platforms.

Code blocks deserve a note, because they are where conversion most often disappoints. A code sample in HTML may use syntax highlighting markup with spans for each token, and a converter that handles that markup naively can produce Markdown littered with stray markers or flattened code that lost its indentation. Indentation inside code blocks is meaningful, and a converter that strips it destroys the sample. After conversion, read every code block against the original and restore indentation and structure by hand where needed. For documents where code samples are the point, that manual pass is not optional polish; it is the difference between a usable document and a corrupted one.

Images and media complete the picture. Markdown references images by address, so a converted document that pointed to images on the original site keeps those addresses, which break if the images move or the document is read offline. Decide deliberately whether images should be downloaded and re-hosted with the document, replaced with descriptions, or left as remote references. Each choice has consequences for portability, size and licensing, since an image's licence may not permit re-hosting even when it permitted linking. Conversion moves text easily; it moves media only with decisions attached.