Markdown Syntax Guide — Everything You Need to Know in 2026

A few rules that trip people up:

• You must include a space after the # symbols. ##Heading without a space will not render as a heading in most parsers.
• There is no heading level 7. Six levels is the maximum, matching HTML's <h1> through <h6>.
• Most style guides recommend using only one # (H1) per document — it serves as the title. Use ## and ### for sections and subsections.
• Leave a blank line before and after headings. Some parsers require it, and it improves readability in the source.

Alternative Heading Syntax

For H1 and H2 only, there is an underline syntax:

This is called "Setext-style" headings. It looks elegant in plain text but offers no advantage over the # syntax and only supports two levels. Most writers stick with # exclusively.

Paragraphs and Line Breaks

Paragraphs are the simplest element in Markdown. Just write text. Separate paragraphs with a blank line.

To create a line break within a paragraph (a <br> tag) without starting a new paragraph, end a line with two or more spaces, or use a backslash:

The trailing-spaces method is invisible and error-prone — editors often strip trailing whitespace. The backslash method is cleaner and recommended.

Text Emphasis and Formatting

Bold and Italic

Renders as: italic text, bold text, bold and italic.

Best practice: use asterisks (*) rather than underscores (_). Underscores inside words like some_variable_name can cause unexpected rendering in some parsers. Asterisks never have this problem.

Strikethrough

Renders as: This text is crossed out.

Strikethrough is technically a GitHub Flavored Markdown (GFM) extension, not part of the original spec. But it's supported virtually everywhere now.

Combining Emphasis

You can nest formatting:

Blockquotes

Use the > character to create blockquotes. They're perfect for callouts, citations, or highlighting important information.

Markdown is intended to be as easy-to-read and easy-to-write as is feasible.

— John Gruber

Nested Blockquotes

First level of quoting.

Nested blockquote.

Back to the first level.

Blockquotes can contain any other Markdown element — headings, lists, code blocks, and more. They are essentially a container.

Lists

Unordered Lists

Use -, *, or + followed by a space:

• First item
• Second item
• Third item

Pick one marker and stick with it throughout your document. - is the most common convention.

Ordered Lists

Use numbers followed by a period and a space:

1. First item
2. Second item
3. Third item

A useful quirk: the actual numbers don't matter. Markdown will render them sequentially regardless:

This still renders as 1, 2, 3. Many writers use 1. for every item so they don't have to renumber when reordering.

Nested Lists

Indent with two or four spaces (or one tab) to create sublists:

• Main item
  • Sub-item
  • Another sub-item
    • Third level
• Another main item

Mixed Lists

You can combine ordered and unordered:

1. First step
   • Detail about first step
   • Another detail
2. Second step
   • Detail about second step

Task Lists (GFM)

GitHub Flavored Markdown adds interactive checkboxes:

• Write the introduction
• Add code examples
• Proofread the article
• Publish

Task lists are incredibly useful in GitHub issues and pull request descriptions for tracking progress.

Links

Inline Links

The title in quotes is optional — it appears as a tooltip on hover.

Reference Links

For documents with many links, reference-style keeps the text clean:

The reference labels are case-insensitive and don't appear in the rendered output.

Autolinks

Most Markdown parsers automatically convert URLs and email addresses into clickable links:

Wrapping in angle brackets (< >) is more reliable across parsers. Plain URL autolinks are a GFM feature.

Images

Images use the same syntax as links, prefixed with !:

The alt text is critical for accessibility and SEO. Always write meaningful alt text that describes what the image shows.

Images with Links

Wrap an image in a link by nesting the syntaxes:

Reference-Style Images

Just like reference links:

Code

Inline Code

Wrap text in single backticks for inline code:

Use the console.log() function to debug.

If your code contains backticks, use double backticks:

Fenced Code Blocks

Triple backticks create code blocks. Add a language identifier for syntax highlighting:

Supported languages vary by renderer, but common ones include javascript, python, typescript, html, css, bash, json, yaml, sql, rust, go, java, c, cpp, and dozens more.

Indented Code Blocks

Indent lines by four spaces or one tab:

This older syntax has no language highlighting support. Fenced code blocks are superior in every way.

Horizontal Rules

Three or more hyphens, asterisks, or underscores on a line by themselves:

All three produce the same result. --- is most common. Use horizontal rules sparingly to separate major sections — headings are usually a better choice for structure.

Tables (GFM)

Tables are a GitHub Flavored Markdown extension. They use pipes and hyphens:

Column Alignment

Use colons in the separator row:

Tips for working with tables:

• The columns don't need to be perfectly aligned in the source — but aligning them makes the source much more readable.
• You can use inline formatting (bold, italic, code, links) inside table cells.
• Tables cannot contain block-level elements like lists, code blocks, or headings.
• For complex tables, consider using HTML directly inside your Markdown.

Footnotes

Footnotes let you add references without cluttering the main text:

Here is a sentence with a footnote.¹

Multi-line footnotes use indentation:

Footnotes are supported in most modern Markdown parsers, though they are not part of the original specification or GFM. They are part of the PHP Markdown Extra and CommonMark extensions.

Definition Lists

Some parsers support definition lists:

Definition lists are not part of GFM. Support varies by platform — they work in PHP Markdown Extra, Pandoc, and several static site generators.

Escaping Special Characters

If you need to display a character that Markdown would normally interpret as formatting, prefix it with a backslash:

Characters you can escape: \, `, *, _, { }, [ ], ( ), #, +, -, ., !, |.

HTML in Markdown

Markdown was designed to coexist with HTML. You can drop raw HTML into any Markdown document:

Important: Markdown formatting is not processed inside block-level HTML elements (<div>, <table>, <pre>, etc.). If you open a <div>, everything inside it is treated as raw HTML until the closing </div>.

Markdown is processed inside inline HTML elements (<span>, <em>, <a>, etc.).

GitHub Flavored Markdown (GFM) Extensions

GitHub Flavored Markdown builds on the CommonMark spec with several practical extensions. Since GitHub is where most developers encounter Markdown, understanding GFM is essential.

Autolinked References

GitHub automatically links certain references:

These only work on GitHub itself, not in general Markdown renderers.

Syntax Highlighting in Code Blocks

GFM supports syntax highlighting for hundreds of languages. This feature alone makes GFM-compatible renderers worth using. Here are examples in several languages:

Alerts (Admonitions)

A more recent GFM addition — alert blocks for callouts:

These render as styled callout boxes on GitHub. They're incredibly useful for documentation. Not all Markdown renderers support this syntax yet, but adoption is growing.

Collapsed Sections

Use HTML <details> for collapsible content:

This is technically HTML, not Markdown, but it's so commonly used in GitHub issues and READMEs that it's become part of the GFM ecosystem.

Advanced Formatting Patterns

Nested Blockquotes with Code

Here is a quote with code:

python

print("Hello from a blockquote!")

And the quote continues.

Complex List Items

List items can contain multiple paragraphs, code blocks, and other elements. Indent continuation content by the same amount as the list text:

2. Second step with a sub-list:
   • Sub-item one
   • Sub-item two

Common Mistakes and How to Avoid Them

Forgetting blank lines. Many Markdown issues come from missing blank lines before and after block elements. Always put a blank line before headings, lists, code blocks, blockquotes, and tables.

Inconsistent list markers. Mixing -, *, and + within the same list can cause unexpected behavior. Pick one and stick with it.

Not escaping special characters. If your text contains characters like *, _, #, or |, and you don't want them interpreted as Markdown, escape them with a backslash.

Broken indentation in nested lists. Nested list items must be indented to the content start position of the parent item, not just by a tab. This is the single most common source of list rendering bugs.

Using tabs vs. spaces inconsistently. Some parsers handle tabs differently. Spaces are safer and more predictable.

Missing language identifiers on code blocks. Always specify the language after the opening triple backticks. Without it, you lose syntax highlighting, which makes code much harder to read.

Markdown Editors and Tools

Writing Markdown is easy in any text editor, but a good tool makes the experience significantly better. Here's what's available in 2026:

Browser-based editors are the fastest way to start. The Markdown Editor on akousa.net gives you a live split-pane preview as you type, supports GFM extensions, and requires no installation. It's particularly useful when you need to quickly draft a README or check how your Markdown will render.

Desktop editors like VS Code (with the Markdown All in One extension), Obsidian, Typora, and Zettlr offer deeper integration with your file system and workflow.

CLI tools like markdownlint and prettier can lint and format your Markdown files as part of a CI/CD pipeline, catching formatting issues before they reach production.

Markdown vs. Alternatives

Why Markdown over other lightweight markup languages?

Markdown wins on simplicity and ecosystem size. If you need more power (cross-references, includes, custom directives), AsciiDoc or reStructuredText might serve you better. But for 90% of documentation and writing needs, Markdown is the right choice.

Quick Reference Cheat Sheet

Here's a condensed reference you can bookmark:

Keep this reference handy. Better yet, keep the akousa.net Markdown Editor bookmarked for when you need to test syntax quickly.

Wrapping Up

Markdown is deceptively simple. The basics take five minutes to learn. But the full specification — with GFM extensions, nested structures, and HTML escape hatches — gives you enough power to write anything from a quick comment to comprehensive technical documentation.

The key to getting good at Markdown is the same as any tool: use it. Write your notes in Markdown. Write your README files by hand instead of copying templates. Experiment with tables and nested lists until the syntax becomes muscle memory.

If you found this guide useful, you might also want to explore other developer-focused tools on akousa.net — from JSON formatters and regex testers to the Markdown editor mentioned throughout this post. Every tool runs entirely in your browser with nothing to install.