Guides / Markdown to HTML

Markdown to HTML: the complete mapping

Markdown was designed from day one as a shorthand for HTML, so this is the most faithful conversion there is — every Markdown construct has an exact HTML equivalent. The subtleties are in the extensions (tables and strikethrough aren't in original Markdown), in how line breaks behave, and in what happens to raw HTML embedded in your Markdown.

Convert Markdown to HTML now →

Syntax mapping

Worked example

# Release notes

We fixed **two bugs** and added *one feature*:

- Faster startup
- [New docs site](https://example.com)

```js
console.log("hello");
```

converts to:

<h1>Release notes</h1>
<p>We fixed <strong>two bugs</strong> and added <em>one feature</em>:</p>
<ul>
<li>Faster startup</li>
<li><a href="https://example.com">New docs site</a></li>
</ul>
<pre><code class="language-js">console.log("hello");
</code></pre>

Gotchas worth knowing

Single line breaks disappear

In standard Markdown, a single newline inside a paragraph is treated as a space — the two lines join into one <p>. To force a real <br>, end the line with two spaces or a backslash, or leave a blank line to start a new paragraph. This is the single most common "why does my output look wrong" report.

Raw HTML gets sanitized

Markdown permits inline HTML, so a Markdown document can technically carry <script> tags or event handlers. Converticle runs all generated HTML through DOMPurify, which strips scripts, event attributes, and other XSS vectors while keeping legitimate formatting tags. If you're converting untrusted input anywhere else, always sanitize — Markdown parsers themselves generally don't.

Original Markdown vs. GitHub Flavored Markdown

Tables, strikethrough, task lists, and autolinked URLs are GFM extensions, not part of original Markdown or strict CommonMark. Converticle's parser (Marked) enables GFM by default, which matches what most people mean by "Markdown" today. If your target system is a strict CommonMark renderer, tables and ~~strikethrough~~ won't render there.

You get a fragment, not a document

The output is an HTML fragment — there's no <html>, <head>, or stylesheet. That's what you want for pasting into a CMS, email template, or component, but if you need a standalone page, wrap it in a document shell and add your own CSS. Markdown carries structure, never styling.

Where converted HTML typically goes

The destination shapes what you should check before pasting:

• Email templates. Email clients ignore external stylesheets and many CSS rules, so the fragment's semantic tags (<strong>, <ul>, <a>) are exactly what survives. Avoid relying on code blocks keeping their formatting — Outlook in particular collapses <pre> whitespace unless you add inline styles.
• CMS rich-text fields. Most CMS editors accept an HTML fragment directly in their "source" or "code" view. Paste into the source view, not the visual editor — pasting HTML as text into a visual editor double-escapes it.
• Web components and templates. The fragment drops straight into a template slot. Remember heading levels travel with the content: if your page already has an <h1>, demote the Markdown headings first (start the document at ##) rather than editing the output.

FAQ

Is the conversion reversible?

Mostly. HTML→Markdown (which Converticle also does, via Turndown) recovers all the standard elements, but HTML that has no Markdown equivalent — <div> soup, inline styles, <span> classes — is either dropped or passed through as raw HTML.

Are code block languages preserved?

Yes — a ```python fence becomes class="language-python" on the <code> element, the convention highlighters like highlight.js and Prism expect. The HTML itself isn't syntax-highlighted; that's a job for CSS/JS on the destination page.

Why did my <script> tag vanish?

Sanitization removed it, deliberately. If you're building a page where you control the input and genuinely need scripts, add them outside the converted content.

How are GFM tables converted?

A pipe table becomes a plain <table> with a <thead> row of <th> cells and <tbody> rows of <td>. Column alignment colons (:---:) become align attributes. Borders and striping are styling — bring your own CSS.

Do special characters need escaping?

Literal <, >, and & in your Markdown text are HTML-escaped automatically (<, >, &), so text like a < b renders correctly. The exception is anything Markdown itself interprets — asterisks, underscores, backticks — which you escape with a backslash in the source if you want them literal.

Try the Markdown to HTML converter →