Markdown syntax documentation

Markdown is a lightweight markup language that formats plain text using simple, readable symbols, so # Heading, **bold**, and - item become a heading, bold text, and a list. This reference documents every element with syntax, live examples, HTML output, and flavor differences, built for people working with AI-generated Markdown who need to move it accurately between tools.

This is the Markdown section of the Markdific documentation.

Markdown syntax at a glance

The core Markdown syntax in one table, with a link to the full reference for each element.

For every element, including extended and advanced syntax, use the full list below.

What is Markdown?

Markdown is a plain-text formatting syntax created by John Gruber in 2004. You write text with a few punctuation-based markers, and a parser converts it to HTML for display. It is designed to be easy to read as raw text and easy to write, which is why it powers README files, documentation, notes, chat apps, and the output of most AI assistants.

Because Markdown has several flavors, the same syntax can render differently across tools. Every page in this reference documents where behavior differs across CommonMark, GitHub Flavored Markdown, MultiMarkdown, Markdown Extra, and Pandoc, and notes how Markdific itself renders each element.

Find the right page for your task

• Write the basics: start with headings, paragraphs, emphasis, and lists.
• Add structured content: use links, images, tables, and fenced code blocks.
• Fix rendering problems: check escaping characters, line breaks, heading IDs, and Markdown flavors.
• Use platform extensions: see task lists, footnotes, LaTeX math, and Mermaid diagrams.

When one file must work in several applications, choose the destination renderer first. Core CommonMark syntax is the safest baseline; GFM, Pandoc, Obsidian, and other systems add different extensions.

How to use this reference

Each element page starts with the answer and a working example, then follows the questions that matter for that syntax. Pages include raw Markdown, rendered output, HTML where it helps, compatibility limits, and practical fixes. If you want everything on one screen, start with the Markdown cheat sheet. If you are comparing tools, read Markdown flavors compared.

You can try any syntax as you read it in the Markdific online editor.

Core and basic syntax

The everyday elements that make up almost every Markdown document.

• Headings: section titles from H1 to H6 using # or underlines.
• Paragraphs: plain text separated by blank lines.
• Line breaks: hard breaks with trailing spaces or a backslash.
• Emphasis: bold, italic, and bold italic with * or _.
• Blockquotes: quoted text with >, including nesting.
• Lists: ordered, unordered, and nested lists.
• Code: inline code and indented code blocks.
• Links: inline, reference-style, and titled links.
• Images: inline and reference-style images with alt text.
• Horizontal rules: thematic breaks with ---, ***, or ___.
• Escaping characters: backslash escapes for literal symbols.

Extended syntax

Widely used features added by GitHub Flavored Markdown and other flavors. Support varies, and each page documents exactly where.

• Tables: pipe tables with column alignment.
• Fenced code blocks: triple-backtick and triple-tilde code fences.
• Syntax highlighting: language hints that color code blocks.
• Task lists: checkbox items with - [ ] and - [x].
• Strikethrough: crossed-out text with ~~.
• Footnotes: reference-style notes with [^1].
• Definition lists: terms paired with definitions.
• Heading IDs: custom anchors and auto-generated slugs.
• Automatic links: URL and email autolinking.
• Emojis: Unicode emoji and :shortcode: conventions.
• Subscript and superscript: ~sub~ and ^super^ text.
• Highlight: highlighted text with ==.

Advanced and Markdific-specific

Rendering-heavy features. Markdific renders LaTeX math, Mermaid diagrams, fenced code with syntax highlighting, and inline images.

• LaTeX math: inline and block equations with $ and $$.
• Mermaid diagrams: flowcharts and diagrams inside code fences.
• Front matter: YAML metadata at the top of a file.
• Inline HTML: using raw HTML inside Markdown.

Reference and meta

• Markdown cheat sheet: every syntax on one dense page.
• Markdown flavors compared: the full CommonMark, GFM, MultiMarkdown, Markdown Extra, and Pandoc comparison.

Tools

• Markdown table generator: build a table visually and copy clean Markdown, which pairs well with the tables reference.

Primary specifications and references

• CommonMark specification 0.31.2
• GitHub Flavored Markdown specification
• Pandoc User's Guide
• Obsidian formatting syntax

These references define different Markdown targets. A feature documented by one source is not automatically supported by every renderer.

FAQ

What is Markdown? Markdown is a lightweight markup language that formats plain text using simple symbols such as # for headings and * for emphasis. A parser converts it to HTML, so it is easy to read as raw text and easy to publish.

What is Markdown syntax? Markdown syntax is the small set of punctuation-based markers you use to format text, such as # for a heading, **text** for bold, - item for a list, and [text](url) for a link. The syntax at a glance table above lists the core markers, and each element page documents the full rules.

Is there a Markdown cheat sheet? Yes. The Markdown cheat sheet puts every syntax on one dense page, which is handy as a quick reference while you write.

Is Markdown the same everywhere? No. Markdown has several flavors, including CommonMark, GitHub Flavored Markdown, MultiMarkdown, Markdown Extra, and Pandoc. Core elements like headings and lists are consistent, but extended features such as tables, footnotes, and highlighting vary. See Markdown flavors compared.

How do I open a .md file? A .md file is plain text, so any text editor can open it, and a Markdown viewer or editor will show the formatted result.

What is the difference between Markdown and HTML? Markdown is a shorthand that compiles to HTML. You write less, and the parser generates the HTML tags. Every element page shows the HTML equivalent of that element.

Where should I start if I am new to Markdown? Start with headings, emphasis, and lists, then keep the cheat sheet open as a quick reference.

Does Markdown work in AI tools and chat apps? Yes. Most AI assistants output Markdown, and chat and note apps such as Slack, Discord, Notion, and Obsidian render a subset of it. Behavior differs by tool, which each element page documents in its flavor and platform notes.

Try it

Paste or write Markdown and see it render live in the Markdific online editor.