How to Convert Markdown to HTML and Back

Markdown is what people write; HTML is what browsers render. Converting between them is mechanical, but each direction has a few behaviours that surprise people the first time: a line break that disappears, raw HTML passed through untouched, an underline with nowhere to go. The examples below are actual output from the converters on this site.

Markdown to HTML

Input:

## Release 2.4

Fixes the **export bug** and adds [CSV import](https://example.com/docs "Docs").
This line has no blank line before it.

| Plan | Seats |
|---|---|
| Pro | 5 |

- [x] Migrate DB
- [ ] Update docs

~~Old flag~~ removed.

Output (lightly trimmed):

<h2>Release 2.4</h2>
<p>Fixes the <strong>export bug</strong> and adds <a href="https://example.com/docs" title="Docs">CSV import</a>.
This line has no blank line before it.</p>
<table>
<thead><tr><th>Plan</th><th>Seats</th></tr></thead>
<tbody><tr><td>Pro</td><td>5</td></tr></tbody></table>
<ul>
<li><input checked="" disabled="" type="checkbox"> Migrate DB</li>
<li><input disabled="" type="checkbox"> Update docs</li>
</ul>
<p><del>Old flag</del> removed.</p>

Three things to notice:

A single line break isn't a line break. The two lines of the first paragraph end up in one <p>, and a browser displays them as one line. Markdown only starts a new paragraph after a blank line. To force a line break inside a paragraph, end the line with two spaces (or a backslash). If lines you typed separately came out joined, this is why.

GitHub-flavored extras are supported. Tables, task lists (rendered as disabled checkboxes), strikethrough (<del>), and bare URLs that become links all convert. So does fenced code, which keeps its language as a class such as language-bash for your syntax highlighter to pick up.

Raw HTML passes straight through. Markdown allows inline HTML, so a <details> block, an <iframe>, or an onclick attribute in the source appears unchanged in the output. For your own documents, that's a feature. If you're converting Markdown that other people wrote (comments, user profiles) and putting the result on a web page, run the HTML through a sanitizer such as DOMPurify first. The converter doesn't sanitize, because it can't know which HTML you meant to keep.

HTML to Markdown

Here's similar content going the other way, from HTML that also includes a <br>, a nested list, a code block, an image, and some styled text. This is exactly what the HTML to Markdown Converter produces:

## Release 2.4

Fixes the **export bug** and adds [CSV import](https://example.com/docs "Docs").  
Second line.

*   [x]  Migrate DB
*   Nested
    *   child

```bash
npm run build
```

![Logo](/logo.png) red text underlined

| Plan | Seats |
| --- | --- |
| Pro | 5 |

What maps cleanly:

• Headings, bold, italic, links (including titles), images, and nested lists.
• <br> becomes a hard line break: the two trailing spaces after "CSV import".
• Code blocks become fenced blocks with the language kept (bash, from class="language-bash").
• Tables become pipe tables, and checked or unchecked checkboxes become [x] / [ ].
• <script>, <style> and <noscript> are removed entirely. Otherwise their contents would show up as stray text.

What Markdown can't hold, and so is dropped:

• Underline, colour and inline styles. <u>underlined</u> and <span style="color:red"> become plain text, because Markdown has no syntax for them.
• Formatting inside table cells. Cells are written as plain text, since a pipe table cell can't hold a list or a paragraph.
• Merged cells. A pipe table can't merge cells, so a cell with colspan or rowspan has its text repeated in every position it covered. The other values stay in their correct columns.
• Layout. Divs, classes and IDs disappear, leaving only the content.

The list markers come out as * followed by three spaces. That looks unusual, but every Markdown renderer accepts it. Your editor's formatter can switch it to - if you prefer.

Stripping Markdown to plain text

Sometimes you want neither format: an email subject, a notification, a meta description, a search index, or a character-limited field. The Markdown to Text tool removes the syntax and keeps the words:

Release 2.4

Fixes the export bug in file_name_here and really adds CSV import.

item one
item two

Plan  Seats
Pro  5

The details that make this safe to use on technical writing: underscores inside words are left alone, so file_name_here survives. Code keeps its content without the backticks. Link text is kept but the URL is dropped. Table rows become plain lines with cells separated by two spaces. Bullets and task checkboxes are removed, numbered steps keep their numbers, and paragraph spacing is preserved. Inline HTML tags go too, and entities such as & are decoded.

Picking the tool

• Writing docs or a README in Markdown and pasting into a CMS or email template that wants HTML: Markdown ⇄ HTML Converter.
• Moving existing HTML (a CMS export, a saved web page, a rich-text editor's output) into a Markdown-based docs site or repository: HTML to Markdown Converter. Expect to fix underlines and styled text by hand.
• Producing a clean excerpt or preview from Markdown: Markdown to Text.

All three run in your browser, so unpublished drafts and internal docs aren't uploaded.