The Complete Markdown Guide: Learn Markdown Syntax and Features

Markdown is a lightweight markup language created by John Gruber in 2004 that transforms plain text into beautifully formatted HTML. It's now the standard format for technical documentation, README files, online forums, note-taking tools, and content management systems.

This comprehensive Markdown guide will walk you through everything from basic syntax to advanced features, helping you create well-formatted documents efficiently.

Table of Contents

• Why Learn Markdown?
• Basic Markdown Syntax
  • Headings
  • Paragraphs and Line Breaks
  • Emphasis (Bold and Italic)
  • Strikethrough
• Lists
  • Unordered Lists
  • Ordered Lists
  • Nested Lists
• Links and Images
  • Links
  • Reference Links
  • Automatic Links
  • Images
• Code
  • Inline Code
  • Code Blocks
• Tables
  • Table Alignment
• Blockquotes
• Horizontal Rules
• Advanced Features
  • Task Lists
  • Footnotes
  • Definition Lists
  • Abbreviations
• HTML in Markdown
  • Escaping Characters
• Best Practices
  • Writing Tips
  • Common Mistakes to Avoid
• Markdown Flavors
• Tools and Editors
  • Online Editors
  • Desktop Applications
  • Text Editors with Markdown Support
• Conclusion

Why Learn Markdown?

Markdown has become the preferred formatting language for millions of writers, developers, and content creators for several compelling reasons:

• Simplicity: Learn the basics in just a few minutes
• Readability: Easy to write and read in its raw form
• Portability: Works across platforms and applications
• Future-proof: Text-based format that will never become obsolete
• Versatility: Converts effortlessly to HTML, PDF, DOCX, and other formats
• Focus: Allows you to concentrate on content rather than formatting
• Speed: Write formatted content much faster than with WYSIWYG editors
• Universal: Used on GitHub, Reddit, Stack Overflow, Discord, and countless other platforms

Whether you're writing documentation, creating blog posts, taking notes, or communicating in online forums, Markdown skills are invaluable in today's digital landscape.

Basic Markdown Syntax

Headings

Create headings by using hash symbols (#) at the beginning of a line. The number of hash symbols indicates the heading level:

1# Heading Level 1
2## Heading Level 2
3### Heading Level 3
4#### Heading Level 4
5##### Heading Level 5
6###### Heading Level 6
MARKDOWN

Alternatively, for heading levels 1 and 2, you can use the "underline" style:

Heading Level 1
==============

Heading Level 2
--------------
MARKDOWN

Paragraphs and Line Breaks

To create paragraphs, simply leave a blank line between lines of text:

This is the first paragraph.

This is the second paragraph.
MARKDOWN

For line breaks within the same paragraph, end a line with two or more spaces, or use the HTML <br> tag:

This is the first line.  
This is the second line.

Or use a break tag:<br>
This is the second line.
MARKDOWN

Emphasis (Bold and Italic)

Make text italic by enclosing it with single asterisks or underscores:

*This text is italic*
_This text is also italic_
MARKDOWN

Make text bold by enclosing it with double asterisks or underscores:

**This text is bold**
__This text is also bold__
MARKDOWN

Combine bold and italic by using three asterisks or underscores:

***This text is bold and italic***
___This text is also bold and italic___
MARKDOWN

You can also mix and match:

**Bold and _italic_ combined**
*Italic and __bold__ combined*
MARKDOWN

Strikethrough

Create strikethrough text using two tildes:

~~This text is crossed out~~
MARKDOWN

Lists

Unordered Lists

Create unordered (bulleted) lists using dashes (-), asterisks (*), or plus signs (+):

1- Item 1
2- Item 2
3- Item 3
4
5* Item A
6* Item B
7* Item C
8
9+ First item
10+ Second item
11+ Third item
MARKDOWN

Ordered Lists

Create ordered (numbered) lists using numbers followed by periods:

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

The actual numbers don't matter; Markdown will automatically number them correctly:

1. First item
1. Second item
1. Third item
MARKDOWN

Nested Lists

Create nested lists by indenting items with spaces or tabs:

11. First main item
2   - Sub-item 1
3   - Sub-item 2
4     - Sub-sub-item A
5     - Sub-sub-item B
62. Second main item
7   1. Numbered sub-item
8   2. Another numbered sub-item
93. Third main item
MARKDOWN

Links and Images

Links

Create links using square brackets for the link text and parentheses for the URL:

[Link text](https://example.com)
[Link with title](https://example.com "This is a title")
MARKDOWN

Reference Links

For cleaner text, use reference-style links:

[Link text][reference]
[Another link][ref2]

[reference]: https://example.com
[ref2]: https://another-example.com "Optional title"
MARKDOWN

Automatic Links

URLs and email addresses can be made into links automatically:

<https://example.com>
<email@example.com>
MARKDOWN

Images

Images use similar syntax to links, but with an exclamation mark at the beginning:

![Alt text](image.jpg)
![Alt text](image.jpg "Optional title")
MARKDOWN

Reference-style images:

![Alt text][image-ref]

[image-ref]: image.jpg "Optional title"
MARKDOWN

Code

Inline Code

Use backticks for inline code:

Use the `print()` function to display output.
MARKDOWN

Code Blocks

Create code blocks using triple backticks or by indenting with four spaces:

undefined
MARKDOWN

function hello() {
console.log("Hello, world!");
}

With syntax highlighting (specify the language):

```javascript
function hello() {
  console.log("Hello, world!");
}
MARKDOWN

Indented code blocks:

```markdown
    function hello() {
      console.log("Hello, world!");
    }

Tables

Create tables using pipes (|) to separate columns and dashes (-) to create headers:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1    | Data     | More     |
| Row 2    | Data     | More     |
MARKDOWN

Table Alignment

Use colons (:) to align columns:

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

Blockquotes

Create blockquotes using the greater than symbol (>):

> This is a blockquote.
> It can span multiple lines.
MARKDOWN

Nested blockquotes:

> This is a blockquote.
>> This is a nested blockquote.
> Back to the first level.
MARKDOWN

Horizontal Rules

Create horizontal rules using three or more dashes, asterisks, or underscores:

---
***
___
MARKDOWN

Advanced Features

Task Lists

Create interactive checkboxes (supported by many Markdown processors):

- [x] Completed task
- [ ] Incomplete task
- [ ] Another incomplete task
MARKDOWN

Footnotes

Add footnotes to your text:

This text has a footnote[^1].

[^1]: This is the footnote content.
MARKDOWN

Definition Lists

Create definition lists (not supported by all processors):

1Term 1
2:   Definition 1
3
4Term 2
5:   Definition 2a
6:   Definition 2b
MARKDOWN

Abbreviations

Define abbreviations:

HTML is a markup language.

*[HTML]: HyperText Markup Language
MARKDOWN

HTML in Markdown

Markdown allows you to use HTML tags when needed:

This is <em>emphasized</em> text.

<div style="color: red;">
This text is red.
</div>
MARKDOWN

Escaping Characters

Use backslashes to escape special characters:

\* This asterisk won't create emphasis
\# This won't be a heading
\[This won't be a link\]
MARKDOWN

Best Practices

Writing Tips

1. Keep it simple: Use Markdown's simplicity to your advantage
2. Be consistent: Stick to one style for similar elements
3. Use whitespace: Add blank lines for better readability
4. Preview your work: Always check how your Markdown renders
5. Learn your tools: Different processors support different features

Common Mistakes to Avoid

• Forgetting blank lines between elements
• Mixing different list markers in the same list
• Not escaping special characters when needed
• Using HTML when Markdown syntax would work
• Inconsistent indentation in nested lists

Markdown Flavors

Different platforms support different "flavors" of Markdown:

• CommonMark: The standardized specification
• GitHub Flavored Markdown (GFM): Adds tables, task lists, strikethrough
• MultiMarkdown: Supports footnotes, tables, metadata
• Pandoc Markdown: Extended syntax for academic writing
• Kramdown: Ruby-based processor with additional features

Tools and Editors

Online Editors

• MarkdownPaste: Create and share Markdown documents
• Dillinger: Online Markdown editor with live preview
• StackEdit: In-browser Markdown editor

Desktop Applications

• Typora: WYSIWYG Markdown editor
• Mark Text: Real-time preview Markdown editor
• Obsidian: Knowledge management with Markdown

Text Editors with Markdown Support

• VS Code: With Markdown extensions
• Vim: With Markdown plugins
• Sublime Text: Markdown editing packages
• Atom: Built-in Markdown preview

Conclusion

Markdown is a powerful yet simple tool that can significantly improve your writing workflow. Whether you're a developer documenting code, a writer crafting articles, or anyone who needs to create formatted text quickly, mastering Markdown will save you time and help you focus on what matters most: your content.

Start with the basics—headings, emphasis, lists, and links—then gradually incorporate more advanced features as you become comfortable. With practice, Markdown will become second nature, and you'll wonder how you ever lived without it.

Remember: the best way to learn Markdown is to use it. Start writing your next document in Markdown today!

---

Ready to start creating? Try our Markdown editor and put your new skills to work!