HTML to Markdown for Documentation

Why this conversion keeps happening

The ecosystems diverged: web content lives in HTML, but documentation pipelines — README files, static site generators, knowledge bases, note apps — standardized on Markdown. Content constantly needs to cross that border: articles being archived, docs being migrated, answers being saved. The conversion exists because both formats won, in different rooms.

What Markdown can and cannot represent

Markdown covers the semantic core: headings, paragraphs, emphasis, lists, links, images, code blocks, simple tables. It has no vocabulary for layout, color, positioning, or arbitrary nesting. The consequence that governs everything: converting HTML to Markdown preserves document semantics and discards presentation — by design, irreversibly. Content written semantically converts cleanly; content built from styled divs converts to its text skeleton.

The clean cases: articles and docs

Blog posts, documentation pages, and any content authored with semantic HTML convert almost perfectly: heading hierarchy maps to hash levels, lists map one-to-one, links and emphasis carry over, and code blocks keep their language hints. This is the sweet spot — when the HTML was written the way HTML should be written, the Markdown arrives ready to publish.

The hard cases: tables and deep nesting

Two areas degrade. Tables convert only when rectangular — merged cells have no Markdown equivalent, so complex tables arrive cell-by-cell or need manual repair. And deeply nested lists survive technically but read awkwardly past three levels. The honest workflow: convert, then review exactly these two structures rather than scanning the whole output.

Migrating a documentation site: the batch pattern

Real migrations involve dozens of pages, and the pattern that scales is pipeline thinking: convert each page, run the same review checklist (tables, nested lists, relative links), then assemble. Relative links deserve special attention — HTML anchors to sibling pages become Markdown links that may need path adjustment for the new structure. The teams that succeed at migrations treat links as a first-class review item, not an afterthought.

Archiving web content for personal knowledge

The individual use case: saving useful articles into a note system that speaks Markdown. The conversion preserves what matters for re-reading — text, structure, links — while stripping navigation, ads, and layout. Paired with trimming the header and footer first, it produces archive copies cleaner than bookmarks and more durable than screenshots.

What to trim before converting

Whole-page HTML carries chrome that pollutes the output: navigation, sidebars, footers, script tags. Selecting the content region first — article body only — produces Markdown that starts at the title instead of the site menu. Ten seconds of selection beats five minutes of stripping menu items out of converted output.

Links: the detail that decides archive quality

Converted links keep their targets, which raises the archive question: absolute links survive but depend on the source site living forever; downloaded-local links break on paths. The deliberate choice for archives: keep absolute URLs for reference material, knowing the source is the dependency. The Markdown format itself is neutral — the link strategy is yours.

Round-trips and their losses

HTML to Markdown to HTML is not identity: the return trip produces semantic but restyled output — original classes, colors, and layout do not resurrect. Treat the conversion as one-way for anything where presentation matters; treat it as round-trippable only for pure content workflows where stylesheets apply fresh at the destination.

Local conversion for private content

The material being converted is often internal: authenticated documentation, draft pages, client content. Browser-side conversion processes pasted markup without transmission — the migration stays inside whatever confidentiality envelope the content requires.

Edge cases: where the conversion needs judgment

The mapping is clean for paragraphs, headings, lists, links, and emphasis — and strained everywhere else. Nested lists depend on indentation depth surviving the conversion; tables only convert when the target renderer supports pipe tables; images carry alt text that must transfer or be written. Inline styles have no Markdown equivalent and drop silently. The professional review pass after any conversion: check list nesting, verify every link survived with its URL, and spot-check images. Five minutes of checking catches the conversions that look right but dropped structure.

The migration use case: legacy HTML to maintainable docs

The biggest legitimate use is migrating content estates: years of HTML blog posts or help-center articles that the new static site generator wants in Markdown. Converting in bulk preserves content while shedding markup boilerplate, and the output diffs cleanly in version control. The migration discipline: convert in batches, spot-check each batch against its source, and keep originals until the batch is verified. Migrations that convert everything at once and verify nothing accumulate silent losses — dropped tables, mangled entities — that surface months later as broken pages.

Round-trip fidelity: what never survives the trip

Markdown is a smaller language than HTML, so some information cannot survive: classes and IDs, custom data attributes, precise nesting of divs, and any interactive elements. This asymmetry should shape the decision: convert when the destination genuinely is Markdown content (documentation, articles), and keep HTML when structure carries meaning. Attempting to round-trip HTML through Markdown and back is lossy by construction — knowing the loss list up front prevents surprises, and the conversion stays the right tool for the jobs it fits.

What survives the trip to Markdown

Markdown was designed as a writeable subset of HTML, so conversion is lossy in one direction by design. Everything textual survives well: headings, paragraphs, emphasis, links, images, blockquotes, and simple lists convert cleanly and round-trip. What does not survive is structure that Markdown has no notation for: tables with merged cells, nested blockquotes several levels deep, custom attributes, classes, ids, and any inline HTML the source used for styling. A good conversion keeps those as raw HTML inside the Markdown rather than deleting them — which preserves content at the cost of portability to stricter Markdown renderers.

The practical decision is what your destination supports. GitHub-flavored Markdown adds tables, task lists, and strikethrough to the original spec; many CMS importers support less. If the target renderer is unknown, inspect the converted output for raw HTML blocks and decide per instance whether to simplify them. A converted table arriving as <table> inside Markdown is correct but useless in a renderer that strips HTML.

Link and image URLs deserve a specific check after conversion. Relative URLs that worked inside the original site's structure will not resolve in a README or a documentation system rooted elsewhere. Converting in bulk is the right moment to list every link target and fix the ones that point into the old site's internal paths.

Common mistakes with this tool

• Converting whole pages with navigation and footer included.
• Expecting styles and layout to survive into Markdown.
• Skipping the link review after a multi-page migration.
• Assuming Markdown-to-HTML round trips restore the original.

Frequently asked questions