Markdown Syntax: The Complete Reference

March 31, 2026 · 12 min read

Understanding Markdown Syntax

Markdown has become the de facto standard for writing formatted text in plain text editors. Created by John Gruber in 2004, this lightweight markup language was designed with a simple philosophy: readability above all else. Unlike HTML or other markup languages, Markdown documents remain readable even in their raw form.

The beauty of Markdown lies in its simplicity. You don't need specialized software or complex syntax to create well-formatted documents. A basic text editor is all you need to start writing. This accessibility has made Markdown the preferred choice for developers, technical writers, bloggers, and content creators worldwide.

Markdown is ubiquitous across modern platforms. GitHub uses it for README files and issue discussions. Reddit employs Markdown for comment formatting. Static site generators like Jekyll, Hugo, and Gatsby rely on Markdown for content management. Documentation platforms, note-taking apps, and content management systems have all embraced Markdown as their primary formatting language.

The core principle behind Markdown is that formatting should be intuitive. When you want to emphasize text, you surround it with asterisks. When you want a heading, you prefix it with hash symbols. These conventions mirror how people naturally format plain text emails and documents, making the learning curve remarkably gentle.

Basic Formatting Techniques

Mastering basic Markdown formatting is your foundation for creating professional documents. These fundamental techniques cover 90% of everyday formatting needs, from simple text emphasis to structural elements like headings and paragraphs.

Text Emphasis and Inline Styling

Text emphasis in Markdown uses intuitive symbols that visually suggest their purpose. Bold text uses double asterisks or underscores: **bold text** or __bold text__ both render as bold text. The double symbol creates visual weight even in the raw text.

Italic text employs single asterisks or underscores: *italic text* or _italic text_ produces italic text. Italics work perfectly for emphasis, book titles, foreign phrases, or technical terms that need subtle highlighting.

Strikethrough text uses double tildes: ~~removed text~~ creates removed text. This formatting proves invaluable for showing edits, deprecated features, or content that's been superseded but remains relevant for context.

Inline code snippets use backticks: `let x = 5;` renders as let x = 5;. This monospace formatting distinguishes code from regular text, making technical documentation clearer and more scannable.

Headings for Document Structure

Headings create hierarchy and improve document navigation. Markdown uses hash symbols (#) to denote heading levels, with more hashes indicating lower-level headings:

# Heading 1 (H1)
## Heading 2 (H2)
### Heading 3 (H3)
#### Heading 4 (H4)
##### Heading 5 (H5)
###### Heading 6 (H6)

Each heading level serves a specific purpose in document structure. H1 typically represents the document title and should appear only once. H2 marks major sections, while H3 through H6 create subsections with decreasing importance.

Proper heading hierarchy improves accessibility for screen readers and helps search engines understand your content structure. Always maintain logical progression—don't jump from H2 to H5 without intermediate levels.

Paragraphs and Line Breaks

Paragraphs in Markdown are separated by blank lines. Simply leave an empty line between text blocks to create distinct paragraphs. This natural spacing makes raw Markdown files highly readable.

For a line break within a paragraph (without creating a new paragraph), end a line with two spaces and press Enter. Alternatively, use the HTML <br> tag for explicit line breaks. This distinction matters when you need precise control over text flow.

Organizing Content with Lists

Lists transform dense information into scannable, digestible chunks. Markdown supports both unordered (bulleted) and ordered (numbered) lists, plus nested combinations of both types.

Unordered Lists

Create unordered lists using asterisks (*), plus signs (+), or hyphens (-) as bullet markers. All three produce identical results, so choose based on personal preference or project conventions:

* First item
* Second item
* Third item
  * Nested item
  * Another nested item
* Fourth item

Nested lists require consistent indentation—typically two or four spaces. The indentation level determines the nesting depth, allowing you to create complex hierarchical structures.

Ordered Lists

Ordered lists use numbers followed by periods. Interestingly, Markdown doesn't require sequential numbering—it automatically renumbers items in the rendered output:

1. First step
2. Second step
3. Third step
   1. Sub-step A
   2. Sub-step B
4. Fourth step

This auto-numbering feature means you can use 1. for every item during drafting, making it easier to reorder items without manually renumbering. The rendered output will display correct sequential numbers.

List Best Practices

Keep list items concise and parallel in structure. If one item is a complete sentence, make all items complete sentences. If items are fragments, keep them all as fragments. This consistency improves readability and professionalism.

Use lists strategically to break up long paragraphs. When you find yourself writing "first," "second," "third" in paragraph form, that's a signal to convert the content into a list. Your readers will thank you for the improved scannability.

Incorporating Links and Images

Links and images connect your content to external resources and visual elements. Markdown provides clean, readable syntax for both inline and reference-style links.

Creating Hyperlinks

Inline links use brackets for link text and parentheses for URLs: [link text](https://example.com). This format keeps the link and its destination together, making it easy to see what you're linking to while editing.

Add optional title text that appears on hover: [link text](https://example.com "Hover title"). Title text provides additional context and improves accessibility for users who rely on assistive technologies.

Reference-style links separate the link text from the URL, improving readability in long documents:

[link text][reference-id]

[reference-id]: https://example.com "Optional title"

This approach shines when you reference the same URL multiple times. Define the URL once at the bottom of your document, then reference it throughout. Updates become trivial—change one line instead of hunting through the entire document.

Embedding Images

Image syntax mirrors link syntax with an exclamation mark prefix: ![alt text](image-url.jpg). The alt text is crucial for accessibility and SEO—describe what the image shows for users who can't see it.

Include optional title text for hover tooltips: ![alt text](image-url.jpg "Image title"). This additional context helps users understand the image's relevance before clicking or when images fail to load.

Reference-style images work identically to reference-style links:

![alt text][image-ref]

[image-ref]: /path/to/image.jpg "Optional title"

Linking to Internal Sections

Create anchor links to headings within your document using heading IDs. Most Markdown processors automatically generate IDs from heading text: [Jump to section](#section-heading). The ID typically converts heading text to lowercase and replaces spaces with hyphens.

Internal links improve navigation in long documents, letting readers jump directly to relevant sections. This technique works particularly well in documentation, tutorials, and comprehensive guides.

Advanced Markdown Formatting

Beyond basic formatting, Markdown offers powerful features for technical writing, code documentation, and complex content structures. These advanced techniques elevate your documents from simple text to professional-grade documentation.

Code Blocks and Syntax Highlighting

Fenced code blocks use triple backticks to create multi-line code sections. Specify the programming language immediately after the opening backticks for syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Syntax highlighting dramatically improves code readability by colorizing keywords, strings, comments, and other language elements. Most Markdown processors support dozens of languages, from Python and JavaScript to SQL and YAML.

Indented code blocks offer an alternative syntax—indent every line by four spaces or one tab. This method works universally but lacks syntax highlighting capabilities:

    function example() {
        console.log("Indented code block");
    }

Horizontal Rules

Create visual separators using three or more hyphens, asterisks, or underscores on a line by themselves:

---
***
___

Horizontal rules break content into distinct sections, providing visual breathing room in long documents. Use them sparingly—too many dividers fragment your content and reduce cohesion.

Escaping Special Characters

Backslashes escape Markdown special characters, displaying them literally instead of as formatting: \*not italic\* renders as *not italic* instead of not italic.

Common characters requiring escaping include: \ ` * _ { } [ ] ( ) # + - . !. This technique proves essential when discussing Markdown syntax itself or when special characters appear in technical content.

Utilizing Blockquotes and Task Lists

Blockquotes and task lists add semantic meaning to your content. Blockquotes highlight quotations or important callouts, while task lists track progress and action items.

Blockquotes for Emphasis

Create blockquotes using the greater-than symbol (>) at the start of lines:

> This is a blockquote.
> It can span multiple lines.
>
> And include multiple paragraphs.

Nested blockquotes use multiple > symbols:

> First level quote
>> Nested quote
>>> Deeply nested quote

Blockquotes work beautifully for pull quotes, testimonials, important warnings, or highlighting key takeaways. They create visual distinction that draws the reader's eye to critical information.

Task Lists for Project Management

Task lists combine list syntax with checkbox notation. Use - [ ] for unchecked items and - [x] for completed items:

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task
  - [x] Completed subtask
  - [ ] Pending subtask

Task lists shine in project documentation, meeting notes, and issue tracking. Many platforms like GitHub render these as interactive checkboxes, allowing users to check off items directly in the rendered view.

Working with Tables and Data

Tables organize structured data in rows and columns. While Markdown table syntax appears complex initially, it becomes intuitive with practice and dramatically improves data presentation.

Basic Table Syntax

Create tables using pipes (|) to separate columns and hyphens to define the header row:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

The rendered output creates a properly formatted HTML table with clear visual separation between headers and data rows. Column widths adjust automatically based on content.

Column Alignment

Control text alignment using colons in the separator row:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
| Text         | Text           | Text          |

Left alignment (:---) works best for text content. Center alignment (:---:) suits headers or short labels. Right alignment (---:) fits numerical data, especially currency or statistics.

Markdown Formatting Comparison Table

Common Markdown Flavors Feature Support

Boosting Efficiency with Markdown Tools

The right tools transform Markdown from a simple markup language into a powerful content creation ecosystem. Modern editors, converters, and utilities streamline your workflow and expand Markdown's capabilities.

Markdown Editors

Dedicated Markdown editors provide live preview, syntax highlighting, and export options. Popular choices include Typora (WYSIWYG editing), Obsidian (knowledge management), and Mark Text (open-source and cross-platform).

Visual Studio Code with Markdown extensions offers a developer-friendly environment with Git integration, multiple panes, and extensive customization. The built-in preview pane updates in real-time as you type, providing immediate feedback on formatting.

Online editors like StackEdit and Dillinger work entirely in the browser, requiring no installation. These tools excel for quick edits, collaborative writing, or working on devices where you can't install software.

Conversion and Processing Tools

Pandoc stands as the universal document converter, transforming Markdown into virtually any format: PDF, DOCX, HTML, LaTeX, EPUB, and dozens more. Its command-line interface enables automation and batch processing.

Our Markdown to HTML Converter provides instant browser-based conversion without installation. Simply paste your Markdown and receive clean, semantic HTML ready for web publishing.

For the reverse operation, the HTML to Markdown Converter extracts content from web pages and converts it to editable Markdown. This tool proves invaluable when migrating content from HTML-based systems to Markdown-based platforms.

Linters and Validators

Markdown linters enforce consistent style and catch common errors. Markdownlint checks for issues like inconsistent heading styles, trailing spaces, and improper list formatting. Integrating linters into your workflow ensures professional, consistent documentation.

Remark is a powerful Markdown processor with a plugin ecosystem for validation, transformation, and enhancement. Use it to enforce style guides, generate tables of contents, or automatically fix common issues.

Static Site Generators

Static site generators transform Markdown files into complete websites. Jekyll (Ruby), Hugo (Go), and Gatsby (React) each offer unique advantages for different use cases.

These tools combine Markdown content with templates to generate static HTML sites. The result is fast, secure, and easily deployed to any web host. Many developers use static site generators for blogs, documentation sites, and portfolio pages.

Best Practices and Common Pitfalls

Following established conventions and avoiding common mistakes ensures your Markdown documents remain readable, portable, and maintainable across different platforms and processors.

Consistency is Key

Choose one style for each element and stick with it throughout your document. If you use asterisks for emphasis, don't switch to underscores halfway through. If you prefer hyphens for unordered lists, use them consistently.

Establish a style guide for team projects. Document decisions about heading capitalization, list punctuation, code block languages, and link formats. Consistency across multiple authors creates a cohesive, professional appearance.

Whitespace Management

Blank lines separate block elements like paragraphs, lists, and code blocks. Missing blank lines can cause unexpected rendering—a list might merge with the preceding paragraph, or a code block might not render properly.

Avoid trailing spaces except when intentionally creating line breaks. Many editors can highlight or automatically remove trailing whitespace, preventing subtle formatting issues.

Heading Hierarchy

Maintain logical heading progression without skipping levels. Don't jump from H2 to H5—use H3 and H4 as intermediate levels. Screen readers and document outlines rely on proper hierarchy for navigation.

Use only one H1 per document, typically for the main title. This convention improves SEO and accessibility while creating clear document structure.

Link Maintenance

Broken links frustrate readers and damage credibility. Regularly audit external links, especially in documentation that references third-party resources. Consider using reference-style links for frequently updated URLs—you'll only need to update one line when links change.

Use descriptive link text instead of "click here" or bare URLs. Good link text improves accessibility and helps readers understand the destination before clicking.

Understanding Markdown Flavors

While John Gruber's original Markdown specification established the foundation, various "flavors" have emerged to address limitations and add features. Understanding these variations helps you choose the right flavor for your needs.

CommonMark

CommonMark aims to standardize Markdown with an unambiguous specification. It resolves edge cases and inconsistencies in the original Markdown, providing predictable behavior across implementations.

The CommonMark specification includes a comprehensive test suite, ensuring parsers produce consistent output. This standardization benefits developers building Markdown tools and users who need reliable cross-platform compatibility.

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown extends CommonMark with features essential for software development: tables, task lists, strikethrough text, and automatic URL linking. GFM also adds syntax highlighting for fenced code blocks.

GFM's widespread adoption makes it a de facto standard for technical documentation. Many Markdown processors support GFM extensions even outside GitHub, recognizing their utility for modern content creation.

MultiMarkdown and Markdown Extra

MultiMarkdown adds academic writing