On this page
- What this converter does and why fragments beat full documents
- Complete Markdown syntax reference and exact HTML output
- How two-pass parsing and HTML entity escaping prevent XSS bugs
- Markdown dialects compared: Gruber, CommonMark, GFM, and MDX
- Step-by-step publishing workflows for CMS platforms and HTML email
- Three worked examples from raw Markdown to production HTML
- Wrapping a converted HTML fragment into a standalone web page
- Semantic HTML, WCAG accessibility, and search engine optimization
- Cleaning drafts pasted from Notion, Google Docs, and Obsidian
- Troubleshooting common Markdown conversion mistakes
- Where this tool stops and when to use a build compiler
- Sources and technical specifications
What this converter does and why fragments beat full documents
This tool takes plain-text drafts written in Markdown syntax and converts them immediately into clean, semantic HTML elements. Every heading, paragraph, bulleted list, numbered sequence, link, lazy-loaded image, inline code span, fenced code snippet, and blockquote in your source is translated into its corresponding HTML tag. As you type or paste, the output updates simultaneously in two panels: a Rendered preview that shows how a browser lays out the hierarchy, and a Generated HTML source box ready for one-click copying or file download. Every step runs locally inside your browser tab, so confidential drafts never travel across the network.
Markdown remains the standard drafting format for software engineers, technical writers, newsletter editors, and content strategists because plain text stays readable even before it is rendered. Typing ## Deployment Checklist or **Required** keeps your hands on the keyboard without opening and closing angle brackets, hunting for mismatched closing tags, or fighting hidden rich-text styles copied out of word processors. Yet almost every publishing destination on the web ultimately expects HTML.
Crucially, this converter produces an HTML body fragment rather than a full standalone document. That means the generated source starts directly with structural elements such as <h2>, <p>, and <ul> instead of wrapping the output in <!DOCTYPE html>, <html>, <head>, and <body> tags. When you paste markup into a WordPress Custom HTML block, a Ghost HTML card, a Shopify product description, a help-center editor, or an email marketing template, the host platform already supplies the outer document shell. Pasting a duplicate <head> or <body> tag inside an existing page breaks DOM validation and can strip surrounding styles, whereas a clean HTML fragment drops neatly into any content slot.
If you choose to press the optional Get AI insight button below the conversion summary, only anonymous structural counts leave your browser: input length, output length, heading count, paragraph count, list item count, link count, code block count, and whether multiple <h1> headings exist. Neither your Markdown prose nor your generated HTML is ever transmitted or stored.
Complete Markdown syntax reference and exact HTML output
Core Markdown is intentionally compact so you can master every token in a single sitting. The reference table below shows each construct recognized by this converter alongside the exact HTML markup it emits and the spacing rule required for reliable detection.
| Markdown syntax | Exact HTML output | Spacing and boundary rule |
|---|---|---|
# Heading 1 to ###### Heading 6 | <h1>Heading 1</h1> to <h6>Heading 6</h6> | Requires 1 to 6 leading hashes followed by at least one space before the heading text. |
| Plain text line | <p>Plain text line</p> | Any non-empty line outside a code fence that does not start with a block marker becomes a paragraph. |
**bold** or __bold__ | <strong>bold</strong> | No space immediately inside the opening or closing double markers; conveys strong importance. |
*italic* or _italic_ | <em>italic</em> | Single asterisk or underscore hugging the words on the same line; conveys stress emphasis. |
`inline code` | <code>inline code</code> | Wrap variable names, CLI flags, file paths, or HTTP status codes in single backticks. |
- item, * item, or + item | <ul><li>item</li></ul> | Leading marker plus space; consecutive bullet lines merge into one <ul> until a blank or non-bullet line. |
1. First then 2. Second | <ol><li>First</li><li>Second</li></ol> | Digits followed by a period and a space; browser numbers items sequentially in the rendered list. |
> Quoted note | <blockquote>Quoted note</blockquote> | Starts with > (optional single space); each quoted line outputs a clean <blockquote> element. |
[Label](https://example.com) | <a href="https://example.com">Label</a> | Square brackets hold visible anchor text; parentheses hold a whitespace-free destination URL. |
 | <img loading="lazy" src="/chart.webp" alt="Alt text"> | Exclamation mark before brackets; automatically adds native loading="lazy" for faster page loads. |
```js ... ``` | <pre><code>...</code></pre> | Line starting with three backticks opens or closes a literal block; inline Markdown inside is not parsed. |
Line breaks, list grouping, and code fence boundaries
Understanding three structural rules will save you nearly all post-conversion cleanup. First, leave one blank line between headings, paragraphs, lists, and code blocks. In this converter, consecutive unordered list lines (-, *, or +) are collected into a single <ul> container, and consecutive numbered lines (1., 2.) are collected into a single <ol> container; as soon as a blank line or another block marker appears, the open list closes cleanly. Second, write each paragraph as a single unwrapped line rather than hard-wrapping lines at 80 columns with the Enter key, because line-oriented converters wrap each standalone prose line in its own <p> tag. Third, inside triple-backtick code fences (```), asterisks, underscores, and hashes are preserved verbatim rather than turned into bold text or headings, making fenced blocks safe for shell scripts, SQL queries, Python comments, and configuration files.
How two-pass parsing and HTML entity escaping prevent XSS bugs
Converting human-written text into HTML carries a subtle security and rendering trap: what should happen when a technical article mentions literal angle brackets such as Array<string>, mathematical inequalities like x < 10 && y > 0, or an untrusted snippet such as <script>alert(1)</script>? If a naive converter leaves raw angle brackets untouched, the browser treats <string> as an unknown invisible HTML tag (swallowing the word in the preview) and executes <script> tags as live JavaScript — a classic Cross-Site Scripting (XSS) vulnerability.
To keep the generated markup both visually accurate and safe to paste into third-party systems, this converter processes your source through a deterministic four-stage pipeline:
- Line-ending normalization: Windows carriage-return pairs (
\r\n) and legacy Mac returns (\r) are normalized to Unix newlines (\n) so pasted text behaves identically regardless of operating system. - Block-level classification: The scanner inspects each line in order to detect triple-backtick code fences first, followed by ATX headings (
#to######), unordered list items, ordered list items, blockquotes, and fallback paragraphs. - Character entity escaping (
esc): Before any HTML wrapper or inline tag is inserted, raw text characters with special meaning in HTML are converted to named or numeric entities:&becomes&,<becomes<,>becomes>, double quotes become", and single quotes become'. - Inline token transformation (
inline): Only after raw characters are escaped does the inline pass convert image tokens, link tokens, backtick code spans, strong markers, and emphasis markers into controlled HTML tags. Fenced code blocks skip the inline pass completely so code syntax remains untouched.
Here is a concrete trace showing how a single line containing bold formatting, an ampersand, inline code, and a raw script tag moves through the pipeline:
One publishing check still belongs to you: inspect the URL schemes inside your Markdown links before publishing user-submitted content. Always use https://, root-relative paths like /pricing, fragment anchors like #section-2, or mailto: addresses, and never publish untrusted javascript: pseudo-URLs inside anchor tags.
Markdown dialects compared: Gruber, CommonMark, GFM, and MDX
Writers switching between GitHub, Notion, Reddit, Slack, Obsidian, and static site frameworks often notice that the same Markdown file renders slightly differently on each platform. That happens because Markdown began in 2004 when John Gruber and Aaron Swartz released an informal syntax guide and a Perl script (Markdown.pl) without a formal grammar. Different developers resolved edge cases — such as how many spaces indent a nested list or whether blank lines are required before blockquotes — in incompatible ways.
In 2014, a group of engineers led by John MacFarlane published CommonMark, an unambiguous specification backed by hundreds of conformance tests, alongside IETF registrations RFC 7763 and RFC 7764 establishing the text/markdown media type. GitHub subsequently built GitHub Flavored Markdown (GFM) as a strict superset of CommonMark, adding four developer-focused extensions: pipe tables, task checklists, tilde strikethrough, and bare URL autolinking. Static site generators (Astro, Hugo, Eleventy, Next.js MDX) add a third outer layer for build-time metadata such as YAML frontmatter and embedded UI components.
| Feature / Syntax | Gruber (2004) | CommonMark Core (This Tool) | GitHub Flavored (GFM) | Static Site / MDX |
|---|---|---|---|---|
ATX headings (# to ######) | Supported | Supported | Supported | Supported |
| Emphasis, inline code, links, images | Supported | Supported (adds loading="lazy") | Supported | Supported |
Fenced code blocks (```) | Not in original | Supported | Supported (syntax highlight) | Supported |
Pipe tables (| Col A | Col B |) | Not supported | Rendered as plain <p> | Supported | Via GFM plugin |
Task checklists (- [x] Done) | Not supported | Rendered as bullet item | Supported | Via GFM plugin |
Strikethrough (~~removed~~) | Not supported | Kept as literal tildes | Supported (<del>) | Via GFM plugin |
YAML frontmatter (--- header) | Not supported | Treated as prose/list marker | Metadata table on GitHub | Parsed as page data |
Practical workaround for GFM tables: If a GitHub README you paste here contains a pipe table, convert the surrounding prose and headings first, paste the HTML fragment into your CMS, and insert the table using your CMS's native Table block or semantic <table><thead>...</thead><tbody>...</tbody></table> markup.
Step-by-step publishing workflows for CMS platforms and HTML email
How you paste the generated HTML fragment determines whether it renders cleanly on the first try or displays raw angle brackets to readers. Different publishing environments apply very different CSS inheritance and tag-sanitization rules.
1. WordPress (Gutenberg Block Editor and Classic Editor)
- Omit a duplicate top-level
#title: WordPress automatically wraps your post title field in an<h1>tag. Start your Markdown body headings at##(<h2>) so the published page maintains a single<h1>. - Insert a Custom HTML block: In the Block Editor, type
/htmlon an empty line and select Custom HTML, then click Copy HTML on this page and paste into that block. Do not paste raw HTML into a standard Paragraph block, or WordPress will escape your tags and display literal<h2>text on the live post. (In the Classic Editor, switch from the Visual tab to the Text / Code tab before pasting.) - Convert to native blocks if desired: Click the three-dot menu on the WordPress Custom HTML block and choose Convert to Blocks if you want editors to adjust images or headings visually afterward.
2. Ghost, Webflow, Shopify, and Help-Center Portals
In Ghost, type /html in the editor to open an HTML card and paste the copied fragment; Ghost's theme stylesheet immediately formats all <h2>, <blockquote>, and <pre><code> elements to match your publication. In Shopify product descriptions, Webflow rich-text embeds, and customer support portals such as Zendesk or Intercom, click the Show HTML (<>) toggle in the toolbar before pasting. Review any external <img> URLs in preview mode, as strict enterprise help desks sometimes strip third-party image domains until they are uploaded to the platform's own media library.
3. HTML Email Newsletters and Transactional Emails
Email clients do not behave like modern web browsers. Desktop Microsoft Outlook uses Word's layout engine, and Gmail strips unsupported properties or class selectors depending on how the message is clipped or forwarded. When pasting converted HTML into an email builder (Mailchimp, Brevo, ConvertKit, Postmark, or Amazon SES):
- Inline critical typography styles: Bare
<p>and<h2>tags work immediately inside visual newsletter "Code" blocks that wrap your fragment in template defaults, but for raw transactional HTML emails you should add inlinefont-family,font-size,line-height,margin, and linkcolorattributes (or run the fragment through a CSS inliner) before sending. - Use absolute HTTPS image paths: Relative image paths such as
/images/diagram.pngfail inside an inbox because the reader is viewing the message onmail.google.comor an iOS Mail client rather than on your domain. Always write fullhttps://yourdomain.com/images/diagram.pngURLs in Markdown destined for email. - Send a real inbox test: Preview the rendered message on both mobile dark mode and desktop webmail, especially if your Markdown includes
<pre><code>blocks with long unbreakable lines.
Three worked examples from raw Markdown to production HTML
Seeing exact input-to-output pairs makes it easier to structure your drafts before pressing Convert. Each worked example below reflects the exact markup produced by this tool.
Converting a product changelog update for an in-app widget and customer newsletter
Suppose a product manager drafts version 2.8.0 release notes in Markdown so engineering can review them in Git before marketing pastes the HTML into an announcement widget:
The converter outputs 6 total elements (1 heading, 1 paragraph, 3 list items grouped inside 1 <ul>, and 1 link) with zero wrapper bloat:
Preserving shell commands and angle brackets inside fenced code blocks
A developer documenting an API webhook needs both an installation command and a curl payload containing quotes and ampersands:
Notice two intentional details in the generated HTML below: the language hint bash after the opening backticks is stripped cleanly rather than leaking into the code body, and the double ampersand && plus quotes inside the code fence are entity-escaped so every character copies cleanly out of the rendered documentation page:
Combining hierarchical headings, blockquotes, and lazy-loaded images
An editor preparing a case study includes a section heading, an image with descriptive alt text, and a customer quote:
The converter outputs semantic tags and automatically injects loading="lazy" on the <img> element so below-the-fold illustrations defer network downloads until the reader scrolls near them:
Wrapping a converted HTML fragment into a standalone web page
When you click Download HTML, the browser saves a file named converted-markdown.html containing only your converted fragment. If you double-click that file directly on your desktop, two things often surprise first-time users: accented characters, em-dashes, or currency symbols may appear garbled (such as —) because no UTF-8 character encoding was declared, and mobile browsers zoom out to a tiny desktop viewport because no responsive viewport meta tag is present.
Whenever you want to host or share the converted file as a standalone web page on Netlify, Cloudflare Pages, GitHub Pages, or S3, wrap your copied fragment inside this minimal, standards-compliant HTML5 shell:
Once wrapped, you can optionally pass the finished file through AfriWidget's HTML Minifier to strip whitespace and comments before deploying to a static server.
Semantic HTML, WCAG accessibility, and search engine optimization
Clean Markdown produces accessible, search-friendly HTML only when the author uses Markdown tokens for their structural meaning rather than their visual size. Both assistive technologies (under W3C WCAG 2.2 Success Criteria 1.3.1 Info and Relationships and 2.4.6 Headings and Labels) and search engine crawlers rely on the DOM tree your Markdown generates to understand how topics relate on the page.
<h1>–<h6> elements and descriptive link anchors, ignoring paragraphs merely styled in bold.- Maintain a single
<h1>and sequential subheadings: Screen-reader users frequently press theHshortcut key (in NVDA and JAWS) or open the VoiceOver Headings rotor to scan a page's outline before reading paragraphs. Reserve#(<h1>) for the single primary page title — or omit#altogether if your CMS template already outputs the post title as<h1>. Nest major topics under##(<h2>) and subsections under###(<h3>) without jumping straight from<h1>to<h4>. Watch the Headings use the correct hierarchy order row in the Conversion checks panel above, which flags multiple<h1>tags automatically. - Never fake headings with standalone bold lines: Writing
**Installation Steps**on its own line outputs<p><strong>Installation Steps</strong></p>. Visually it may look heavy, but assistive technology and automated table-of-contents scripts treat it as ordinary body prose. Use## Installation Stepsor### Installation Stepsinstead. - Write self-describing link anchor text (WCAG 2.4.4): Screen readers can list all links on a page out of context, and search engines weight anchor words heavily when indexing destination URLs. Replace vague phrases like
[click here](https://example.com/pricing)or[read more](/security)with specific destinations such as[compare annual API pricing tiers](https://example.com/pricing). - Supply functional
alttext and check LCP images: Write concisedescriptions that convey the takeaway of an informational chart or screenshot to someone who cannot see it. For purely decorative dividers, leave the brackets empty () so the converter outputsalt=""and screen readers skip it cleanly. Note that this converter addsloading="lazy"to every<img>; if an image sits at the very top of your viewport as the page's Largest Contentful Paint (LCP) hero banner, removeloading="lazy"on that single first image in your CMS so the browser fetches it immediately.
Cleaning drafts pasted from Notion, Google Docs, and Obsidian
Many writers draft inside knowledge-management apps or cloud word processors and export to Markdown right before publishing. Those exports frequently contain platform-specific tokens or invisible Unicode characters that trip up standard HTML converters:
- YAML frontmatter at the top of static-site files: Markdown files from Astro, Hugo, Jekyll, Docusaurus, or Obsidian vaults often start with a metadata block between two
---lines containingtitle:,date:, andtags:. Strip that top block before converting, or those metadata lines will appear as visible paragraphs at the top of your HTML output. - Obsidian and Roam
[[WikiLinks]]and callouts: Internal double-bracket links ([[Project Roadmap]]), embedded transclusions (![[diagram.png]]), and callout headers (> [!WARNING]) are proprietary vault syntax rather than CommonMark. Convert internal links to standard[Project Roadmap](/project-roadmap)format and replace callout tags with bold lead-ins such as> **Warning:**before exporting. - Non-breaking spaces (
U+00A0) from Google Docs or Word: Copying Markdown markers out of rich-text documents or PDFs sometimes substitutes a non-breaking space or zero-width space after#or-, or converts straight backticks and quotes inside code examples into curly typographic quotes (“ ”). If a heading or code snippet refuses to format, run the raw text through AfriWidget's Text Case & Cleanup tool first or retype the space after the marker. - Notion toggle blocks and database exports: Notion exports toggle lists and multi-column layouts using either indented plain text or embedded raw
<details>/<aside>tags. Because this converter escapes raw HTML tags for safety, replace Notion toggles with standard##/###subsections before converting.
Troubleshooting common Markdown conversion mistakes
If an element in the Rendered preview does not match what you intended, check the symptom against this diagnostic reference:
| Observed symptom | Underlying cause | Exact fix in Markdown source |
|---|---|---|
#Introduction renders as a plain paragraph | Missing space between the hash symbol and heading text. | Add a single space after the hashes: # Introduction. |
** bold ** shows literal asterisks | Spaces sit immediately inside the opening or closing emphasis markers. | Tighten the asterisks directly against the characters: **bold**. |
| Link breaks mid-URL or shows raw brackets | The URL contains an unencoded space or unescaped closing parenthesis (common in Wikipedia links). | Replace spaces with %20 and closing parentheses inside URLs with %29. |
| Half the document turns into a black code box | An opening triple-backtick fence (```) was never closed, or has leading spaces on the closing line. | Add a standalone ``` line flush with the left margin right after the code snippet. |
GitHub pipe table renders as lines with | bars | Pipe tables are a GFM extension outside the CommonMark core supported here. | Convert prose here, then add the table natively in your CMS or with HTML <table> tags. |
| Sub-bullets flatten into one bullet level | This lightweight line parser groups consecutive bullets into a flat <ul> or <ol>. | Rewrite deep outlines as ### subheadings with flat lists, or nest <ul> inside <li> in HTML. |
| Manual edits to HTML vanish later | Team members edited the exported HTML instead of updating the master .md file. | Keep the .md file in Git or notes as the single source of truth and regenerate HTML on release. |
Where this tool stops and when to use a build compiler
This converter is built for speed, privacy, and zero-configuration clarity on core CommonMark documents: headings, paragraphs, bold and italic emphasis, inline code, fenced code blocks, links, lazy-loaded images, unordered lists, ordered lists, and blockquotes. It intentionally omits GitHub Flavored Markdown tables, task lists, footnotes, definition lists, strikethrough, bare URL autolinking, Setext underline headings, math typesetting, and raw HTML passthrough. It also does not crawl your links to confirm HTTP 200 responses or validate whether your destination CMS strips specific attributes.
For single blog posts, README previews, product changelogs, help-center articles, academic notes, and newsletter fragments — and especially when pairing word-count checks with the Reading Time & Speech Estimator — an instant in-browser converter is the fastest, safest tool for the job. Once you are maintaining dozens or hundreds of interlinked Markdown pages that require automated GFM tables, syntax-highlighted AST transforms, YAML frontmatter routing, and automatic sitemap generation, graduate to a dedicated build-time compiler such as unified (remark + rehype), markdown-it, Astro, Hugo, or Eleventy.
Sources and technical specifications
- MacFarlane, J. CommonMark Spec — A strongly defined, highly compatible specification of Markdown. spec.commonmark.org
- GitHub. GitHub Flavored Markdown (GFM) Formal Specification. github.github.com/gfm
- Gruber, J. (2004). Markdown: Syntax and Original Documentation. Daring Fireball. daringfireball.net
- WHATWG. HTML Living Standard — Grouping Content and Text-Level Semantics. html.spec.whatwg.org
- MDN Web Docs. HTML Elements Reference & Lazy Loading Guide. Mozilla. developer.mozilla.org
- Leonard, S. (2016). IETF RFC 7763 — The text/markdown Media Type. Internet Engineering Task Force. rfc-editor.org/rfc/rfc7763
- Leonard, S. (2016). IETF RFC 7764 — Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations. rfc-editor.org/rfc/rfc7764
- W3C (2023). Web Content Accessibility Guidelines (WCAG) 2.2 — Info and Relationships (1.3.1), Headings and Labels (2.4.6), and Link Purpose (2.4.4). w3.org/TR/WCAG22
- OWASP Foundation. Cross Site Scripting (XSS) Prevention Cheat Sheet — Output Encoding Rules. cheatsheetseries.owasp.org