Markdown to HTML: Safe Rendering Guide

Markdown is popular because authors can write quickly without touching raw HTML. That convenience is also the trap: most teams treat Markdown as harmless text, then discover that the rendered HTML can contain unsafe links, unexpected headings, broken tables, or inline HTML that bypasses the design system.

A reliable Markdown workflow has three separate steps: parse the Markdown, sanitize the generated HTML, and preview it with production-like styles. The Markdown to HTML Converter helps with the conversion step, but safe publishing depends on the checks around it.

Markdown Output Is HTML, Not Plain Text

Once Markdown is rendered, the browser sees HTML. Headings become <h1> through <h6>, links become <a> tags, code blocks become <pre>elements, and tables become a nested structure that can overflow narrow screens.

# API Notes

Use [production](https://api.example.com) for real requests.

```json
{ "status": "ok", "version": 2 }
```

The rendered result needs the same level of review as hand-written HTML. That review should include heading structure, links, code block wrapping, table width, and any raw HTML the parser allows.

Sanitize After Rendering

Sanitization removes dangerous tags and attributes from the rendered HTML. Escaping Markdown input is not enough, because many Markdown parsers intentionally allow raw HTML. If your app accepts user-submitted Markdown, sanitize the HTML output before inserting it into the DOM.

<!-- Input that should never become executable page HTML -->
<img src=x onerror="alert('xss')" />
<a href="javascript:alert('xss')">click me</a>

<!-- Safe output keeps the intent but removes dangerous behavior -->
<img src="x" />
<a>click me</a>

A sane allowlist usually includes paragraphs, headings, lists, links, images, blockquotes, tables, and code blocks. It should reject scripts, event handler attributes, dangerous URL schemes, and inline styles unless the product has a very specific reason to keep them.

Check Links Before Publishing

Markdown makes links easy to write, which means it also makes bad links easy to ship. During review, inspect every generated anchor for destination, protocol, and visible text.

• Internal links should use the current canonical path instead of old redirects.
• External links should use HTTPS unless there is a documented exception.
• Links generated from user content should reject javascript: and unknown protocols.
• Link text should describe the destination; repeated "click here" anchors are bad for accessibility and search.

If a link contains query parameters, encode those values separately. The URL Encoder and Decoder is useful when Markdown links contain redirect URLs, UTM parameters, or copied API examples.

Keep Preview Styles Close to Production

A Markdown preview that uses different CSS from the published page creates false confidence. The most common failures are tables that overflow mobile screens, code blocks that do not wrap, and heading levels that look fine in preview but break the page hierarchy.

/* Minimum rules worth matching between preview and production */
.markdown-body pre {
  overflow-x: auto;
}

.markdown-body table {
  display: block;
  max-width: 100%;
  overflow-x: auto;
}

.markdown-body img {
  max-width: 100%;
  height: auto;
}

Preview the same content at mobile and desktop widths. Long URLs, wide tables, nested lists, and code snippets are the fastest way to find layout differences before readers do.

Preserve SEO Signals While Rendering

Markdown often powers documentation, changelogs, and blog posts, so rendered output should preserve search and accessibility signals. Use one clear H1 per page, keep headings in order, add alt text to images, and avoid turning every paragraph into generic divs.

# One page title

## Section

### Subsection

![Dashboard showing API latency by region](./latency-dashboard.png)

If the rendered HTML feeds a larger page template, make sure the template owns the page title and canonical URL while the Markdown owns the article body. This avoids duplicate H1 tags and inconsistent metadata.

A Safe Markdown Publishing Checklist

1. Convert Markdown to HTML with a parser configuration the product actually uses.
2. Sanitize the rendered HTML with an allowlist for tags, attributes, and URL protocols.
3. Verify heading order, image alt text, link destinations, and code block readability.
4. Test mobile width, especially for tables, long words, and copied terminal output.
5. Use a pattern check with the Regex Tester only for review helpers such as finding old domains; do not use regex as the HTML sanitizer itself.

Markdown is a great authoring format, but publishing systems should treat it as a source format, not a safety boundary. Parse it, sanitize it, preview it, then ship the HTML with the same care as any other page.

Official References

• CommonMark Specification — the baseline Markdown syntax reference used by many parsers.
• OWASP Cross Site Scripting Prevention Cheat Sheet — defensive guidance for rendering untrusted content safely.
• MDN HTML Reference — practical documentation for the HTML elements Markdown renderers produce.