Markdown to HTML: a clean publishing workflow

A publishing pipeline needs a master format that survives tools, hosts, and redesigns. Plain-text Markdown is that master: readable in any editor, diffable in version control, and independent of whatever HTML template renders it this year.

The discipline that makes it work is one-directional flow: Markdown is edited by hand, HTML is produced by the converter, and nobody patches the output manually. The moment exported HTML gets hand edits, there are two masters, and they will drift apart.

• PortablePortability: a Markdown file opens in every editor and converts to HTML, PDF, slides, or a documentation system without a migration project.
• DiffableReviewability: prose changes show up as clean line diffs, while an HTML master buries a one-word edit inside tags and attributes.
• Structure, not styleSeparation of concerns: the source carries structure—headings, lists, quotes—while the theme decides typography, so a redesign never touches the archive.

Deliberate converters support a subset on purpose, because every supported construct is one more way to smuggle in markup nobody reviewed. Know where your content sits relative to that line before you rely on the conversion.

In Markdown-to-HTML mode, image syntax keeps only the alt text, not the image or its URL; raw HTML is escaped as text. In HTML-to-Markdown mode, a pasted table becomes a fenced text block and loses its grid. Check the converted output before publishing.

• Clean conversionsConverts cleanly: headings up to six levels, paragraphs, bold, italic, strikethrough, inline code, fenced code blocks, ordered and unordered lists, block quotes, horizontal rules, and inline links.
• Known lossesOutside the supported subset, results depend on direction: Markdown image syntax keeps only alt text, raw HTML in Markdown is escaped as text, and HTML tables become fenced text blocks when converted back to Markdown. Check footnotes and task lists in the output rather than assuming they survive.
• Test a real articleThe test is simple: convert a representative article and read the output. Anything missing from the result was never in the contract.

Converted HTML may be inserted into a page, so the workspace sanitizes it by default. Active elements are removed, unknown tags are unwrapped, and attributes are stripped except for permitted link URLs and valid ordered-list starts.

The preview pane renders the sanitized output and never loads remote resources, so even pasting hostile markup cannot make the tool itself phone home.

• Active content removedElements carrying active behavior—script, style, iframe, object, embed, svg, form, video, audio, img—are removed with their contents, not merely neutralized.
• Attributes strippedInline styles, event handlers, and source classes are removed. Safe anchors keep href, and valid ordered lists keep start.
• Reported, not silentThe workspace reports what it removed—counts of dropped nodes and stripped attributes—so sanitization is a visible event, not a silent mutation.

A rendered document is mostly links, and links are where sanitization gets specific. The converter accepts http, https, and mailto URLs plus in-page #fragments; anything else—javascript:, data:, protocol-relative tricks—loses its href and renders as plain text.

Check the allowlist against your content before standardizing on a converter: a documentation set that legitimately links to ftp mirrors or custom application schemes needs those links preserved by hand, because no sane sanitizer will pass them automatically.

• Scheme allowlistSurviving links are stamped with rel="noreferrer noopener", so a followed link cannot see or script the page it was opened from.
• noopener noreferrerThe same rule applies in both directions: links written in Markdown are checked on conversion, and hrefs found in pasted HTML are re-checked after sanitization.
• Labels surviveWhen a link loses its scheme, the label text stays—broken navigation is visible immediately instead of shipping a silent javascript: payload.

Converting HTML to Markdown is recovery, not round-tripping. Supported headings, paragraphs, emphasis, lists, quotes, and code come back as Markdown. Other structure may be simplified or removed by sanitization and conversion.

Treat HTML-to-Markdown as a way to pull prose out of a page you no longer control—an old CMS export, a document that only exists as rendered HTML. Then repair what the round trip cannot: re-add the images, rebuild the tables, and from then on keep the Markdown as the master.

• Tables collapseTables lose their grid and become a fenced text block, so tabular data needs re-authoring or a CSV export instead.
• Media is removedImages, video, and interactive embeds are gone by design—the sanitizer removed them as active content before the Markdown was built.
• Text outlives stylingFormatting outside the subset—spans, divs, classes, anchor targets—leaves no trace; the text survives, the presentation does not.

The conversion step runs at publish time, once per article: draft and review in Markdown, convert to sanitized HTML, verify the rendered result, and ship. Everything happens in the browser tab—the draft is never uploaded, which matters when the content is an unannounced launch.

• Publish-time stepThe workspace accepts up to 256 KiB of source and produces up to 512 KiB of output—comfortably book-chapter scale—and reports an explicit error past those limits instead of truncating silently.
• Explicit limitsCopy the output into your CMS field or download it as a file; both paths take the same sanitized document the preview showed you.
• Re-convert, don’t patchKeep the Markdown in version control next to the code it documents, and re-convert after every edit instead of patching old HTML.