What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It uses simple text formatting syntax — like # for headings, ** for bold, and - for lists — to create structured documents. Markdown is widely used on GitHub, Stack Overflow, Reddit, and many CMS platforms because it is easy to write, easy to read, and converts cleanly to HTML. The CommonMark specification standardizes the syntax across platforms.

Common use cases for HTML to Markdown conversion

Developers and writers often convert HTML to Markdown when migrating blog content to static site generators like Hugo, Jekyll, or Astro. It is also essential when importing web content into documentation systems like Docusaurus or MkDocs, cleaning up rich text editor output for storage in Git repositories, or extracting content from existing websites into a portable text format that can be version-controlled and diffed.

HTML elements and their Markdown equivalents

Most HTML elements have direct Markdown counterparts. <h1> through <h6> become # through ######. <strong> and <b> become **bold**. <em> and <i> become *italic*. <a href> becomes [text](url). <img> becomes . <ul>/<li> becomes - items. <ol>/<li> becomes numbered lists. <code> becomes backticks. <pre><code> becomes fenced code blocks with triple backticks. <blockquote> becomes > prefixed lines. <table> converts to pipe-separated Markdown tables in GFM flavor.

// JavaScript — HTML to Markdown with Turndown
import TurndownService from 'turndown';
const turndown = new TurndownService();
const html = '<h1>Title</h1><p>Hello <strong>world</strong></p>';
console.log(turndown.turndown(html));
// # Title\n\nHello **world**

# Python — HTML to Markdown with markdownify
from markdownify import markdownify
html = '<h1>Title</h1><p>Hello <strong>world</strong></p>'
print(markdownify(html))
# # Title\n\nHello **world**

Limitations and edge cases

Some HTML features have no Markdown equivalent and are either dropped or preserved as raw HTML. These include custom CSS styling, iframes, form elements, video/audio embeds, SVG content, and complex table layouts with colspan or rowspan. Nested lists with mixed types can also be tricky — the converter handles standard nesting but deeply nested or irregular structures may need manual adjustment. Inline styles and class attributes are always stripped since Markdown is a content format, not a presentation format.

Why Markdown is better for documentation

Markdown files are plain text, making them ideal for version control with Git. You can diff changes, review in pull requests, and merge without conflicts caused by formatting artifacts. Markdown also separates content from presentation — the same .md file can be rendered as HTML, PDF, slides, or EPUB by different tools. This portability makes Markdown the standard for READMEs, API docs, wikis, and technical writing across the software industry.