Why convert HTML to Markdown?
Markdown has become the standard format for developer documentation, README files, technical blog posts, and CMS content in tools like Ghost, Notion, and Contentful. When content exists in HTML — scraped from a web page, exported from a CMS, copied from a rich text editor — converting it to clean Markdown makes it portable, readable in plain text, and compatible with the vast ecosystem of Markdown-based tools.
Common conversion scenarios include: migrating content from a WordPress blog (which stores content as HTML) to a Markdown-based static site generator like Hugo or Jekyll, converting rich text editor output to Markdown for storage in a Git repository, extracting content from web pages for use in documentation, and cleaning up pasted HTML from email clients or word processors.
What gets converted
The converter handles all standard HTML elements: headings (h1–h6 become # through ######), paragraphs (p tags become separated text blocks), emphasis (strong/b becomes **bold**, em/i becomes *italic*, del/s becomes ~~strikethrough~~), links (a tags become [text](url)), images (img tags become ), unordered lists (ul/li become - items), ordered lists (ol/li become 1. 2. 3. numbered items), blockquotes (blockquote becomes > quoted text), code (inline code becomes `backtick`, pre/code blocks become fenced ``` blocks), and tables (converted to Markdown pipe table syntax). HTML comments are stripped.
Fenced code blocks
The fenced code block option wraps pre/code content in triple backticks (```). If the code element has a class like "language-javascript", the language identifier is preserved in the fence (```javascript). This enables syntax highlighting in Markdown renderers that support it, including GitHub, GitLab, and most static site generators. The alternative is 4-space indented code blocks, which are compatible with more parsers but do not support language identifiers.
Table conversion
HTML tables are converted to GitHub Flavored Markdown pipe table syntax. The first table row is treated as the header row and separated from the data rows by a separator line (| --- | --- |). Not all Markdown parsers support tables — they are part of GitHub Flavored Markdown (GFM) and extended Markdown specifications but are not in the original Markdown spec. If your target parser does not support tables, the converter is best used with simpler HTML.
Limitations
Markdown is less expressive than HTML. Certain HTML features have no Markdown equivalent: CSS styling (colours, fonts, custom sizes), HTML attributes beyond href and src, nested lists beyond simple indentation, complex table features (colspan, rowspan, header groups), and embedded media beyond images. The converter strips these elements and keeps only the content. If your HTML uses extensive inline styling or complex layouts, the Markdown output will be structurally correct but visually simpler.