Markdown to HTML: How Conversion Works and How to Get Clean Results

Markdown lets you write formatted text with plain characters: a hash sign for a heading, asterisks for bold, a dash for a list item. It is used in README files, documentation, forums, note-taking apps and static site generators. Sooner or later most of that text needs to become HTML, whether for a web page, a CMS or an email. This guide explains how the conversion works, which version of Markdown to use, and how to get HTML that is clean and safe.

Convert Markdown in three steps

1. Open the Markdown to HTML converter and paste or type your Markdown.
2. Check the live preview to make sure headings, lists and links look the way you expect.
3. Copy the HTML and paste it into your CMS, email template or page.

How Markdown maps to HTML

Each piece of Markdown syntax produces a specific HTML element. Knowing the pairs makes the output predictable:

• # Title becomes <h1>, ## Section becomes <h2>, and so on down to six levels.
• **bold** becomes <strong> and *italic* becomes <em>.
• Lines starting with - become a <ul> list; lines starting with 1. become an <ol> list.
• [text](https://example.com) becomes a link, and ![description](photo.jpg) becomes an image whose alt text is the description.
• Single backticks produce inline <code>; three backticks on their own lines produce a code block.
• A line starting with > becomes a <blockquote>, and --- on its own line becomes a horizontal rule.

CommonMark or GitHub Flavored Markdown?

The original Markdown description, published by John Gruber in 2004, left many details open, so different tools produced different HTML from the same text. CommonMark is a precise specification that most modern converters follow. GitHub Flavored Markdown, often shortened to GFM, is CommonMark plus a few popular extensions:

• Tables, with columns separated by | and a line of dashes under the header row.
• Task lists such as - [ ] to do and - [x] done.
• Strikethrough with ~~text~~.
• Automatic links for plain web addresses.

If your text uses any of these, convert it with a GFM-compatible tool. A plain CommonMark converter leaves them as ordinary text.

Keep the HTML safe

Markdown allows raw HTML inside it. That is useful in your own documents, but it becomes a security problem when you convert Markdown written by other people, such as comments, forum posts or support tickets. Anyone could include a script tag or an attribute like onclick that runs code in your visitors' browsers, a type of attack known as cross-site scripting.

• Sanitise the output with an allowlist sanitiser such as DOMPurify in JavaScript or HTML Purifier in PHP, which keeps safe elements and removes everything else.
• Turn off raw HTML in your converter if users do not need it.
• Check link addresses and block javascript: links.

Get the structure right for readers and search engines

• Use one H1. Many content systems already show the page title as the H1, so start your Markdown sections at ##.
• Do not skip heading levels. Go from ## to ###, not straight to ####. Screen readers use heading levels to move around a page, and a clear outline helps search engines understand it.
• Write descriptive link text such as "read the setup guide" instead of "click here".
• Add alt text to every image. The words inside the square brackets of an image become its alt attribute.

Converting Markdown in code

• JavaScript: the marked and markdown-it libraries, for example marked.parse(text).
• PHP: league/commonmark, for example (new League\CommonMark\CommonMarkConverter())->convert($text), or the lighter Parsedown.
• Python: the markdown package, with markdown.markdown(text).
• Command line: pandoc converts between many formats, for example pandoc input.md -o output.html.

Common problems

• Line breaks disappear. A single line break inside a paragraph is ignored. Leave a blank line to start a new paragraph, or end a line with a backslash to force a line break.
• Nested lists come out flat. Indent sub-items so they line up with the text of the item above, usually two to four spaces.
• Asterisks or underscores vanish. They were read as emphasis. Put a backslash in front of them, like \*, to show them literally.
• The HTML looks wrong in an email. Email clients support far less CSS than browsers, so stick to headings, paragraphs, lists and links.

Once you know how each symbol maps to HTML, conversion becomes predictable. Paste your text into the Markdown to HTML converter to see the result instantly, and use the word counter if you are writing to a length limit.