Markdown is the closest thing to a universal documentation format. READMEs, wikis, blog posts, technical documentation — Markdown is the default choice. Here's a comprehensive reference for syntax, extensions, and conversion.
Core syntax quick reference
Headings →
``markdown
Heading 1
Heading 2
Heading 3
`
Emphasis → ,
<code>markdown
<em>italic</em> or _italic_
<strong>bold</strong> or __bold__
<strong><em>bold italic</strong></em>
</code>
Lists → , ,
`markdown
Unordered (dash)Unordered (asterisk)+ Unordered (plus)
- Ordered
- Ordered
1. Nested ordered
`
Links and images → , 
`markdown
Link
Link with title
!Alt text
!Alt text
<!-- Reference-style links -->
[link text][reference-id]
[reference-id]: https://example.com
`
Code → ,
`
<code>language
<p>fenced code block</p>
</code>
Blockquotes →
<code>markdown
<blockquote>Single-line quote</blockquote>
<p>></p>
<blockquote>Multi-paragraph blockquote continues here.</blockquote>
<blockquote>Still the same blockquote.</blockquote>
</code>
Horizontal rule →
<code>markdown
<hr>
<em>*</em>
<p>___</p>
</code>
GitHub Flavored Markdown extensions
Tables:
`markdown
| Name | Role | Team |
|----------|--------|-------------|
| Alice | Lead | Frontend |
| Bob | Senior | Backend |
<!-- Column alignment -->
| Left | Center | Right |
|:---------|:------:|-------:|
| left | center | right |
`
Task lists:
<code>markdown
<ul><li>[x] Completed item</li><li>[ ] Incomplete item</li><li>[ ] Another item</li></ul></code>
Strikethrough:
<code>markdown
<p>~~deleted text~~</p>
</code>
Autolinks:
<code>markdown
<p>https://example.com becomes clickable without brackets in GFM</p>
</code>
Fenced code blocks with language:
`<code>markdown
</code>javascript
const x = 42;
<code>
</code>`
GitHub applies syntax highlighting based on the language identifier.
Converting Markdown to HTML
For one-off conversions with a live preview, a Markdown to HTML converter shows the rendered output in a split panel and provides the HTML source for copying.
For programmatic conversion:
JavaScript (marked.js — used on snappytools.app):
`
javascript
import { marked } from 'marked'; // npm install marked
const html = marked.parse('# Hello\n\nThis is Markdown.');
`
For user-generated content, always sanitize:
`
javascript
import { marked } from 'marked';
import DOMPurify from 'dompurify';
const safeHtml = DOMPurify.sanitize(marked.parse(userContent));
element.innerHTML = safeHtml;
`
Python (mistune):
<code>python
<p>import mistune # pip install mistune</p>
<p>html = mistune.html('# Hello\n\nThis is <strong>Markdown</strong>.')</p>
</code>
Python (standard markdown
module):
<code>python
<p>import markdown</p>
<p>html = markdown.markdown(content, extensions=['tables', 'fenced_code', 'toc'])</p>
</code>
Command line (pandoc):
<code>bash
<p>pandoc README.md -o README.html</p>
<p>pandoc README.md -s -o README.html # standalone HTML document</p>
</code>
HTML output: what gets generated
| Markdown | HTML output |
|----------|-------------|
| # Heading
| Heading
|
| bold | bold |
| italic | italic |
| ~~strike~~
| strike |
| link | link |
| !
alt | 
|
| code
| code |
| > quote
| quote
|
| ---
|
|
| Blank line between paragraphs | elements |
| - item |
|
| 1. item
| - item
|
Embedding HTML in Markdown
Standard Markdown passes raw HTML through:
`
markdown
This is Markdown with inline HTML.
Block-level HTML in Markdown.
`
Most parsers preserve safe HTML. GitHub strips dangerous attributes (onclick, style in some cases) for security.
Where Markdown is used
GitHub/GitLab: README.md, issues, pull request descriptions, wikis, GitHub Pages.
Documentation platforms: Docusaurus, MkDocs, GitBook, Notion, Confluence (via plugins), Obsidian.
Static site generators: Jekyll, Hugo, Eleventh, Astro — all use Markdown as the primary content format.
Communication tools: Slack, Discord, many Jira fields, and Linear all render a subset of Markdown.
Blog platforms: Ghost, Hashnode, dev.to, Substack — all accept Markdown or Markdown-like input.
Jupyter notebooks: Markdown cells in notebooks support the full spec.
Markdown limitations
No semantic meaning for layout: Markdown produces content HTML, not layout HTML. You can't do multi-column layouts or complex positioning in Markdown alone.No standard tables-with-merged-cells: GFM tables don't support colspan
or rowspan`. Complex tables need raw HTML.
No custom styling without HTML: To apply specific colors, widths, or custom classes, you need inline HTML.
Parser inconsistencies: The original Markdown spec was ambiguous. CommonMark resolved most issues, but output can vary slightly between parsers for edge cases.
For content that needs significant custom HTML, consider MDX (Markdown with JSX components) or a template-based approach instead.
Markdown's longevity comes from its simplicity: it's plain text that looks readable even without rendering, converts to well-structured HTML, and is editable in any text editor. For documentation, blog posts, and README files, it remains the best default choice.
Originally published at https://snappytools.app/markdown-to-html/