HTML to Markdown

From Web Markup to Clean Plain Text Format

HTML is verbose by nature: <h2>Title</h2> requires 21 characters to express what Markdown does in 10 (## Title). <a href="url">click here</a> in HTML becomes [click here](url) in Markdown. <strong>bold</strong> becomes **bold**. This converter transforms HTML into equivalent Markdown syntax: headings become # symbols with the appropriate count for their level, links become [text](url), bold becomes **text**, italic becomes *text*, unordered lists become dashes, ordered lists become numbers, images become , code blocks are wrapped in backticks, and blockquotes are prefixed with >. Paste any HTML above and receive clean, readable Markdown output that preserves the content's semantic structure while stripping all XML-style tag verbosity.

Where Markdown Is the Standard Format

GitHub README files, wikis, pull request descriptions, issue comments, and discussions all render Markdown natively. GitLab documentation and CI/CD configuration descriptions use Markdown. Notion pages, Obsidian and Logseq personal knowledge bases, Bear and Typora note-taking apps, and Jupyter Notebook text cells all use Markdown as their authoring format. Reddit posts and comments, Stack Overflow questions and answers, Discord messages with formatting, Slack messages with mrkdwn (Slack's Markdown variant), and Telegram formatted messages all support Markdown or Markdown-derived syntax. Static site generators including Jekyll, Hugo, Gatsby, Astro, and Eleventy use Markdown files as content source. When migrating content from a website, CMS, or HTML-based system to any of these Markdown-native platforms, converting to Markdown first produces cleaner, more maintainable results than importing raw HTML and relying on the platform to handle the translation, which often produces inconsistent or bloated output.

Markdown Flavors and Compatibility

CommonMark is the standardized Markdown specification that defines baseline syntax unambiguously. GitHub Flavored Markdown (GFM) extends CommonMark with tables (using pipe characters), strikethrough (~~text~~), task lists (- [ ] and - [x]), autolinked URLs, and fenced code blocks with language-specific syntax highlighting. Obsidian adds wiki-style internal links ([[page]]), callout blocks, and embedded file references. Pandoc's extended Markdown supports footnotes, definition lists, metadata headers (YAML front matter), and mathematical notation (LaTeX). Each platform renders its flavor slightly differently, and features from one flavor may not work in another. This converter produces CommonMark-compatible output that works correctly across all platforms. Platform-specific extensions (like GitHub task lists or Obsidian wiki links) must be added manually after conversion because the corresponding HTML structures are ambiguous and platform-dependent.

Tables: The Conversion Challenge

HTML tables convert to Markdown pipe tables, but the conversion has inherent limitations. Markdown tables do not support colspan or rowspan (merged cells), which are common in complex HTML tables. Nested tables, a pattern frequently used in email HTML templates, have no Markdown equivalent. Tables with more than 5-6 columns become nearly unreadable in Markdown because the pipe syntax requires each column to have visual alignment. The converter handles standard rectangular tables (uniform rows and columns) cleanly. For complex tables with merged cells, nested structures, or many columns, the output may need manual restructuring or the table may need to be represented differently (as a definition list, a series of subsections, or an embedded HTML block, since most Markdown renderers allow inline HTML as a fallback for structures that Markdown cannot express natively).

Content Migration Workflow

When migrating an entire website from a CMS (WordPress, Drupal, Joomla) to a static site generator (Hugo, Jekyll, Astro) or a Markdown-based documentation platform (GitBook, Docusaurus, MkDocs), the typical workflow is: export all content as HTML from the source CMS, convert each page's HTML body to Markdown using a conversion tool or library (Turndown for JavaScript, html2text or markdownify for Python), add YAML front matter (title, date, tags, categories) at the top of each Markdown file, organize files into the directory structure expected by the target platform, and fix any conversion artifacts (broken links, missing images, malformed tables). Batch conversion libraries handle the HTML-to-Markdown step programmatically, but manual review of the output is always necessary because automated conversion cannot perfectly handle every HTML pattern, especially custom shortcodes, embedded widgets, and CMS-specific markup that has no Markdown equivalent.

Frequently asked questions