Markdown Preview

About Markdown Preview

Markdown Syntax Reference

Markdown uses plain text formatting that converts to HTML. John Gruber introduced the original syntax in March 2004 on Daring Fireball with the goal that a Markdown document should be readable as plain text, without looking marked up. Aaron Swartz collaborated on the early design. The original Perl reference script (Markdown 1.0.1) was released in December 2004 and is still available at daringfireball.net.

Element	Markdown Syntax	HTML Output
Heading 1	# Heading	<h1>Heading</h1>
Heading 2	## Heading	<h2>Heading</h2>
Heading 3	### Heading	<h3>Heading</h3>
Bold	**bold text**	<strong>bold text</strong>
Italic	*italic text*	<em>italic text</em>
Bold + Italic	***both***	<strong><em>both</em></strong>
Inline code	`code here`	<code>code here</code>
Link	[text](url)	<a href="url">text</a>
Image		<img src="url" alt="alt">
Blockquote	> quoted text	<blockquote>quoted text</blockquote>
Horizontal rule	---	<hr>
Unordered list	- item	<ul><li>item</li></ul>
Ordered list	1. item	<ol><li>item</li></ol>

Code Blocks

Fenced code blocks use triple backticks (```) on the lines before and after the code. You can optionally specify a language after the opening backticks for syntax highlighting hints, though this tool renders code blocks as plain <pre><code> without language-specific highlighting. Indented code blocks (four spaces at the start of a line) are part of the original Gruber spec but are generally discouraged in modern writing because fenced blocks are clearer and support language hints.

Markdown	HTML
```\ncode here\n```	<pre><code>code here</code></pre>
```js\nconsole.log("hi")\n```	<pre><code class="language-js">...</code></pre>

Where Markdown Is Used

Markdown is the default writing format across most developer tooling, documentation platforms, and note-taking apps. Each platform has its own flavour with slightly different syntax extensions:

Platform/Tool	Markdown Variant	Notable Extensions
GitHub	GitHub Flavored Markdown (GFM)	Tables, task lists, autolinks, strikethrough
GitLab	GFM + extensions	Mermaid diagrams, math blocks, footnotes
Stack Overflow	CommonMark variant	Snippets, spoiler blocks
Reddit	Custom variant	Spoiler tags, superscript
Notion	Markdown-like	/ commands, databases, toggles
Obsidian	CommonMark + extensions	Wiki links, callouts, dataview
Jekyll / Hugo	CommonMark or Goldmark	Front matter, shortcodes
Jupyter Notebooks	CommonMark	LaTeX math, HTML embedding
Discord / Slack	Subset	Bold, italic, code, strikethrough, block quotes

Markdown Specifications

The original Markdown spec left many edge cases unspecified, which led to incompatible implementations. CommonMark was started in 2014 to address this with a rigorous, testable specification. The latest version is CommonMark 0.31.2, released on 28 January 2024 at spec.commonmark.org. GitHub Flavored Markdown builds on CommonMark with tables, task lists, strikethrough, and autolinks.

Spec	Status	Key Differences from Original
Original Markdown (Gruber)	2004, no formal spec	Ambiguous edge cases, no tables
CommonMark	Active standard, version 0.31.2 (January 2024)	Strict rules for edge cases, well-defined behaviour, ~650 test cases
GitHub Flavored Markdown	CommonMark superset (current)	Adds tables, task lists, strikethrough, autolinks, disallowed raw HTML
MultiMarkdown	Extended spec	Footnotes, citations, math, metadata
Pandoc Markdown	Extended spec	Definition lists, superscript, subscript, inline HTML

This tool implements a lightweight parser covering core Markdown syntax. It is not a full CommonMark or GFM implementation, so complex nesting edge cases may differ. For most writing tasks - READMEs, documentation, blog posts, notes - the supported syntax is more than sufficient. If you need strict CommonMark compliance, use a library like markdown-it, marked, or remark in your own build.

Markdown Best Practices

Consistency matters more than perfect adherence to any single flavour. These conventions tend to produce the cleanest source files and the most portable output:

Practice	Why
Use ATX headings (# style) not Setext (underline)	Consistent, supports h1-h6, easier to scan
Leave a blank line before and after headings	Some parsers require it, and it improves source readability
Use fenced code blocks, not indented blocks	Clearer boundaries, supports language hints
Use - for unordered lists (not * or +)	Most common convention, consistent rendering
Use reference links for long URLs	[text][ref] keeps paragraphs readable
One sentence per line in source	Better git diffs when editing prose
Escape pipes inside table cells with \|	Prevents breaking the column layout
Keep table cells short	Long cells force horizontal scroll on mobile

Common Markdown Pitfalls

Most rendering bugs come from a handful of predictable mistakes. The table below covers the ones that catch writers out most often.

Problem	Cause	Fix
Heading not rendering	Missing space after the # character	Write "# Heading" not "#Heading"
List items running together	No blank line before the list	Add a blank line before and after the list block
Bold inside a word not working	Underscore emphasis in mid-word is intra-word in most parsers	Use asterisks: some**bold**word renders correctly
Underscores in variable names showing as italic	snake_case_names trigger emphasis	Wrap in backticks: `my_variable_name`
Angle brackets vanishing	Parser treats them as autolinks or HTML	Escape with backslash: \< or wrap in backticks
Nested lists not indenting	Inconsistent indentation (tabs vs spaces)	Use 2 or 4 spaces consistently
Inline code with backticks inside	Single backtick can't wrap a backtick	Use double backticks: ``code with ` inside``

How Popular Is Markdown?

Markdown has become the near-universal format for developer and writer-facing text. GitHub alone hosts hundreds of millions of README.md files, and Stack Overflow, Reddit, and most issue trackers use a Markdown variant. Every major static site generator (Jekyll, Hugo, Eleventy, Astro, Gatsby, Docusaurus) treats Markdown as the primary content format. Note-taking apps that ship with Markdown as the canonical storage format include Obsidian, Logseq, Bear, Ulysses, and iA Writer. Most AI chat interfaces (ChatGPT, Claude, Gemini) also render Markdown-formatted responses by default, which means writing prompts and notes in Markdown pays dividends across the entire developer toolchain.

Category	Examples	Why Markdown
Code hosting	GitHub, GitLab, Bitbucket, Codeberg	Issues, PRs, READMEs, wikis all use MD
Static site generators	Jekyll, Hugo, Eleventy, Astro, Next.js, Docusaurus	Content as plain files in git
Note apps	Obsidian, Logseq, Bear, Ulysses, iA Writer	Plain text files outlive proprietary formats
Chat platforms	Slack, Discord, Teams, Matrix	Lightweight formatting without WYSIWYG
AI interfaces	ChatGPT, Claude, Gemini, Copilot	Structured output that renders in the client
Documentation	Read the Docs, MkDocs, GitBook, Docusaurus	Versioned, diff-friendly, easy to contribute to

Popular Markdown Parsers

When you need strict specification compliance or advanced features, choose a mature parser rather than rolling your own. The landscape has consolidated around a few well-maintained implementations, each with different trade-offs between speed, compliance, and extensibility.

Parser	Language	Best For
markdown-it	JavaScript	CommonMark compliance with plugin ecosystem
marked	JavaScript	Speed, minimal dependencies
remark (unified)	JavaScript	AST-based transforms, static site pipelines
Goldmark	Go	Default parser for Hugo, CommonMark-compliant
commonmark.py / markdown-it-py	Python	Jupyter, MkDocs, Python tooling
league/commonmark	PHP	Laravel, WordPress plugins, PHP CMS
Pandoc	Haskell	Cross-format conversion (MD to PDF, DOCX, LaTeX)

Markdown to HTML Conversion

The "Copy HTML" button copies the rendered HTML for pasting into content management systems, email templates, or static sites. This makes the tool useful not just for previewing but also for converting Markdown to production HTML.

Use Case	Workflow
CMS content entry	Write in Markdown, copy HTML, paste into rich text editor
Email templates	Draft content in Markdown, copy HTML for the email body
Static site content	Preview rendering before committing to repo
Documentation	Check formatting of README.md before pushing
AI prompt drafting	Preview how ChatGPT or Claude will render your formatted prompt
Issue templates	Pre-check bug reports before pasting into GitHub/Jira

Is Markdown Accessible?

Markdown that converts to semantic HTML (headings, lists, tables, blockquotes) is inherently more accessible than a wall of text or a visual WYSIWYG document. Screen readers rely on the heading outline to navigate, so using proper heading levels (# for the page title, ## for sections, ### for sub-sections) without skipping levels is essential. The W3C WCAG 2.2 guidelines specifically recommend a logical heading hierarchy. Tables should have header rows (the pipe-dash-pipe separator line in GFM), and images must include alt text inside the square brackets of the image syntax.

Accessibility Practice	Markdown Pattern
Use a single H1 per page	Only one # line at the top of the document
Don't skip heading levels	Go #, then ##, then ### - never # then ###
Always add alt text to images	 - never 
Write link text that makes sense alone	[2024 financial report] not [click here]
Keep tables simple	Avoid merged cells and complex layouts - flat tables read better

Security Considerations When Rendering Markdown

Untrusted Markdown is not safe HTML. Any parser that allows raw HTML pass-through can be a vector for XSS if you render user-submitted Markdown. GitHub Flavored Markdown explicitly disallows a set of raw HTML tags (script, style, iframe, embed, object, and others) for this reason. When building a system that renders third-party Markdown, either disable raw HTML entirely or run the output through a sanitiser like DOMPurify. URL schemes in links should be restricted to http, https, and mailto to prevent javascript: URIs. This tool validates link protocols and escapes HTML entities before parsing, so pasted content cannot inject scripts into the preview.

If the HTML output needs cleanup, run it through the HTML Prettifier. For checking word and character counts in your Markdown content, the Word Counter gives character, word, and sentence counts. If you need to escape special characters like < and > before embedding in HTML, the HTML Entity Encoder / Decoder handles that. All processing runs in your browser - your content stays private.

Sources

• CommonMark Specification (current version 0.31.2)
• Daring Fireball - Original Markdown by John Gruber
• GitHub Flavored Markdown Spec
• GitLab Flavored Markdown Reference
• Pandoc Markdown Manual