HTML to Markdown Converter
Turn HTML into destination-ready Markdown with dialect and table controls plus warnings when complex structure may not survive conversion.{{ summaryTitle }} {{ summaryValue }} {{ summaryLine }} {{ profileLabel }} {{ scopeLabel }} {{ sourceElementCount }} elements
{{ workflowFeedback }}{{ computation.ok ? computation.values.markdown_document : '' }}
| Check | Value | Detail | Copy |
|---|---|---|---|
| {{ row.label }} | {{ row.value }} | {{ row.detail }} |
HTML describes a document with nested elements and attributes. Markdown uses a much smaller set of plain-text conventions. Moving content between them is therefore a selective rewrite: headings, paragraphs, lists, links, and code often transfer well, while layout, classes, styling, forms, and complex tables do not have direct Markdown equivalents.
The destination dialect matters as much as the source. CommonMark defines a portable core, while GitHub Flavored Markdown (GFM) adds features such as pipe tables, task-list items, and strikethrough. A document that looks correct in one editor may render differently in another when those extensions are unavailable.
| HTML structure | Typical Markdown result | Main limitation |
|---|---|---|
| Headings, paragraphs, emphasis | Native Markdown markers | CSS presentation is discarded |
| Links and images | Inline, reference-style, or readable plain text | Relative URLs may need rebasing at the destination |
| Simple table | GFM pipe table, retained HTML, or text rows | Pipe tables cannot represent row or column spans |
| Code block | Fenced or indented block | The chosen renderer may handle language hints differently |
Content scope is another source of surprises. A full saved page can contain navigation, footers, hidden templates, scripts, and styles around the article a reader actually wants. Selecting the article, main content, body, or entire document changes what becomes the Markdown document.
Conversion should end with a rendered preview in the destination system. Markdown has no universal error state, so unsupported syntax can remain visible as punctuation or silently lose structure. Tables with merged cells, nested lists, hard line breaks, and links are especially worth checking.
How to Use This Tool:
Set the destination profile before tuning individual Markdown markers.
- Choose Markdown profile and HTML scope. GFM suits GitHub-style destinations; CommonMark avoids relying on GFM extensions; Plain readable text removes most Markdown formatting.
- Paste HTML source or load one HTML, HTM, or text file. Keep Script and style content removed unless retaining their inert text is intentional.
- Select link and table handling. For merged cells, choose retained HTML, readable text, or a pipe-table approximation instead of assuming a lossless conversion.
- Review Markdown document and Conversion ledger. Resolve every merged-cell or unsafe-content note, then render the copied or downloaded Markdown in its actual destination.
Interpreting Results:
The output line count and structure mix show how much source structure was recognized, but they do not prove visual equivalence. Use the conversion ledger to confirm the selected content root, profile, link style, table policy, and detected warnings.
Pay particular attention to a merged-cell warning or a note that GFM tables were selected under the CommonMark profile. Preview the final text in the target editor because its Markdown renderer, URL base, and sanitization rules decide the visible result.
Technical Details:
The transformation builds a tree from the supplied markup, selects one content root, and walks that tree into Markdown. Output cleanup normalizes line endings, trims outer blank lines, and reduces long runs of blank lines without executing source markup.
Transformation Core:
| Stage | Rule |
|---|---|
| Parse | Tokenize comments, declarations, opening and closing tags, attributes, text, and common void elements into a nested tree. |
| Select scope | Auto uses the first <article>, then <main>, then <body>, and finally the fragment root. Document scope also prepends the page title when present. |
| Map elements | Convert supported block and inline structures according to the profile, link, table, heading, list, code, emphasis, and line-break policies. |
| Finalize | Append numbered link definitions for reference-style links, normalize whitespace, and report structures that require review. |
Rule Core:
| Source case | Mapping behavior |
|---|---|
| Headings | ATX markers are available for all six levels; Setext form applies only to levels one and two. |
| Lists | Ordered numbering honors the source start value. GFM task items are produced only when a list item contains a checkbox. |
| Links and images | Inline mode writes the URL beside the label; reference mode appends numbered definitions; plain mode writes readable text and the URL. |
| Simple tables | The first row becomes the pipe-table header. Missing cells are padded and literal pipe characters are escaped. |
| Merged table cells | Any cell with a row or column span follows the selected fallback: retained HTML, plain text rows, or a pipe approximation. |
| Code | Inline code chooses a longer backtick delimiter when needed. Block code uses the selected fence or four-space indentation and retains a recognized language class. |
| Script, style, template, or noscript | These elements are removed by default. When removal is disabled, their text is retained as inert text rather than executed. |
The source limit is 100,000 characters; a loaded file may be no larger than 1 MB. This parser targets practical content migration and does not reproduce every error-recovery rule of a full web browser. Malformed or highly dynamic pages should be cleaned or exported as stable HTML before conversion.
Privacy Notes:
HTML source is converted in the browser and is not uploaded. The markup is treated as text and is never executed during conversion. Removing script, style, template, and noscript content is the safer default for ordinary article or documentation migration, but the generated Markdown can still contain links, image URLs, or sensitive text from the source.
Worked Examples:
Moving release notes to GitHub
An article with task checkboxes, a simple table, and fenced code uses the GFM profile. The task items and table remain native Markdown, while the final file is previewed in the repository to confirm relative links and the language hint.
Migrating a table with merged headings
A table uses column spans for grouped headings. Retained HTML is selected for merged cells because a GFM pipe table cannot express that relationship; the rest of the article still becomes ordinary Markdown.
References:
- CommonMark Specification 0.31.2, CommonMark, January 28, 2024.
- GitHub Flavored Markdown Specification 0.29-gfm, GitHub, April 6, 2019.
- HTML parsing, WHATWG HTML Living Standard.