Convert HTML to Markdown for GitHub README
You have HTML content and need it in Markdown for GitHub, a blog, or documentation. Manual conversion is tedious. Here's how to do it instantly.
Quick Answer
Paste your HTML into the HTML to Markdown converter at dotsapps.com. It outputs clean Markdown with proper headings, links, lists, and code blocks. Copy and use it anywhere Markdown is supported.
Why Convert HTML to Markdown?
Markdown is the standard for developer documentation. GitHub READMEs, GitLab wikis, Stack Overflow posts, Notion pages, and most blogging platforms use Markdown.
But sometimes your content starts as HTML — from a website, a CMS export, an email template, or a rich text editor. Converting HTML to Markdown lets you reuse that content in Markdown-based platforms.
Markdown is also simpler to maintain. Instead of wading through <p> tags and <a href="..."> links, you get clean text with # headings and [links](url). It's faster to read, edit, and version-control.
How HTML Tags Map to Markdown Syntax
Here's how common HTML elements convert to Markdown:
- <h1> to <h6> → # to ###### (heading levels)
- <p> → plain text with blank lines between paragraphs
- <strong> / <b> → **bold text**
- <em> / <i> → *italic text*
- <a href="url"> → [link text](url)
- <img src="url"> → 
- <ul> / <ol> → - or 1. list items
- <code> → `inline code`
- <pre><code> → ``` code blocks ```
- <blockquote> → > quoted text
The converter handles all of these automatically. It preserves the structure and meaning of your content while simplifying the syntax.
Handle Complex HTML Elements
Not all HTML has a direct Markdown equivalent. Here's how edge cases are handled:
Tables: HTML tables convert to Markdown pipe tables. They work on GitHub and most Markdown renderers. Complex tables with colspan or rowspan may need manual adjustment.
Inline styles: Markdown doesn't support inline CSS. Colored text, custom fonts, and other styling gets stripped. The text content is preserved.
Divs and spans: These structural elements are removed. Their text content is kept. If they have meaningful classes, you might need to add Markdown formatting manually.
Iframes and scripts: These are removed during conversion since Markdown doesn't support them.
Best Practices for GitHub README Files
After converting your HTML to Markdown, follow these tips for great GitHub READMEs:
- Start with a clear title. Use a single # heading with your project name.
- Add badges early. Build status, version, license badges go right after the title.
- Keep paragraphs short. 2-3 sentences per paragraph. Walls of text get skipped.
- Use code blocks with language tags. Write ```javascript instead of just ``` for syntax highlighting.
- Include a table of contents for READMEs longer than 3 sections.
The Markdown output from the converter is a great starting point. Clean it up following these guidelines and your README will look professional.
How to Do It: Step-by-Step
- 1
Open the HTML to Markdown converter at dotsapps.com.
- 2
Paste your HTML content into the input area.
- 3
The tool converts all HTML tags to Markdown syntax.
- 4
Review and clean up the output if needed.
- 5
Copy the Markdown and paste it into GitHub, your blog, or docs.
Frequently Asked Questions
Can I convert an entire HTML page to Markdown?
Yes, but the converter works best with the content portion of the page. Header, footer, navigation, and script tags get stripped. The main content converts to clean Markdown.
Does the converter handle HTML tables?
Yes. HTML tables convert to Markdown pipe tables with header rows. Simple tables convert perfectly. Complex tables with merged cells may need manual adjustment.
What happens to images in HTML when converting to Markdown?
Image tags convert to Markdown image syntax: . The src and alt attributes are preserved. You may need to update relative URLs to absolute ones.
Can I convert Markdown back to HTML?
Yes. Most Markdown renderers (including GitHub) convert Markdown to HTML automatically. You can also use online tools to convert Markdown to HTML directly.
What Markdown flavor does the converter output?
The output uses CommonMark / GitHub Flavored Markdown (GFM), which is the most widely supported syntax. It works on GitHub, GitLab, Bitbucket, and most Markdown editors.
Ready to Try It?
HTML to Markdown is free, private, and works right in your browser. No sign-up needed.
Open HTML to Markdown