Markdown Basics

Master the fundamental syntax and core concepts of Markdown formatting

Reading Time

20 minutes

Difficulty

Beginner Friendly

Prerequisites

None

Table of Contents 📑

Introduction to Markdown 📝

Markdown is a lightweight markup language created by John Gruber in 2004. It's designed to be easy to read and write, while being convertible to structurally valid HTML. With its simple syntax and wide adoption, Markdown has become the go-to format for documentation, README files, and content creation.

Why Learn Markdown? 🤔

✨
Simple and Intuitive Syntax
Easy to learn and remember, with minimal special characters
📱
Platform Independence
Write once, use anywhere - from websites to documentation
🚀
Wide Platform Support
Used on GitHub, Discord, Notion, and countless other platforms
📄
Perfect for Documentation
Industry standard for technical documentation and README files
✍️
Content Creation
Ideal for blog posts, technical writing, and note-taking

Common Use Cases 🎯

Documentation

• Project README files
• API documentation
• User guides

Content Creation

• Blog posts
• Technical articles
• Tutorial writing

Quick Tip

Throughout this tutorial, you'll see examples with both the Markdown syntax and its rendered output. We encourage you to practice by typing out these examples in your own Markdown editor. The best way to learn is by doing!

Popular Markdown Tools 🛠️

Online Editors

• StackEdit
• Dillinger
• HackMD

Desktop Apps

• Visual Studio Code
• Typora
• Obsidian

Headers and Document Structure 📚

Headers in Markdown create a clear document hierarchy and structure. They're essential for organizing content and making it easy to navigate. Markdown supports six levels of headers, each denoted by a different number of hash symbols (#).

Header Syntax Examples

# Heading Level 1

Heading Level 1

## Heading Level 2

Heading Level 2

### Heading Level 3

Heading Level 3

Alternative Header Syntax

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

Heading Level 1

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

Heading Level 2

Header Best Practices 📋

🎯
Single H1 Per Document
Use only one level 1 header (#) per document as the main title
📝
Concise and Descriptive
Keep headers clear and to the point, accurately describing the content
🔄
Proper Hierarchy
Maintain logical header levels (don't skip from H2 to H4)
🎨
Consistent Style
Use consistent capitalization and formatting across headers

Common Mistakes to Avoid

❌
##No space after hashes
Always include a space after the hash symbols
❌
Multiple H1 Headers
Avoid using multiple H1 headers in a single document
❌
## h2 ### h3 ##### h5
Don't skip header levels in your hierarchy

Paragraphs and Line Breaks ✍️

Paragraphs are the fundamental building blocks of Markdown documents. Understanding how to properly format paragraphs and create line breaks is essential for creating well-structured content.

Basic Paragraphs

This is the first paragraph.
                
This is the second paragraph.

This is the third paragraph with
no line break in between.

This is the first paragraph.

This is the second paragraph.

This is the third paragraph with no line break in between.

Key Points About Paragraphs

•
Paragraphs are separated by blank lines
•
Single line breaks within paragraphs are ignored
•
Leading spaces/tabs are typically ignored

Line Breaks

There are three ways to create line breaks in Markdown:

1. Two Spaces Method

First line··↵ Second line

(· represents a space)

First line
Second line

2. Backslash Method

First line\ Second line

First line
Second line

3. HTML Break Tag

First line Second line

First line
Second line

Common Mistakes

❌
Single Line Break Without Marking
A single line break in your Markdown file won't create a line break in the output unless properly marked
❌
Missing Blank Line Between Paragraphs
Paragraphs need a blank line between them to be rendered separately
❌
Multiple Blank Lines
Multiple blank lines are treated the same as a single blank line

Best Practices

✨
Consistency is Key
Choose one line break method and stick to it throughout your document
📝
Use Blank Lines Deliberately
Separate paragraphs with a single blank line for clarity
🎯
Keep Lines Readable
Aim for lines around 80 characters for optimal readability

Text Emphasis and Formatting 🎨

Text formatting in Markdown allows you to emphasize your content in various ways. Whether you need to highlight important points, mark technical terms, or add emphasis to your writing, Markdown provides several options for text styling.

Basic Text Formatting

Italic Text

*This text is italic using asterisks*
_This text is italic using underscores_

This text is italic using asterisks

This text is italic using underscores

💡 Use italics for:

Emphasis within sentences
Book titles or publication names
Technical terms or foreign words
Variable names in technical writing

Bold Text

**This text is bold using asterisks**
__This text is bold using underscores__

This text is bold using asterisks

This text is bold using underscores

💡 Use bold for:

Important points or warnings
Key terms in documentation
UI element names
Section headers within paragraphs

Combined Formatting

***Bold and italic text***
___Also bold and italic___
**Bold text with *italic* inside**
*Italic text with **bold** inside*

Bold and italic text

Also bold and italic

Bold text with italic inside

Italic text with bold inside

Advanced Text Formatting

Strikethrough

~~Strikethrough text~~

~~Strikethrough text~~

Highlighting

Highlighted text

Highlighted text

Subscript and Superscript

H2O
X2

H₂O

X²

Real-World Examples

Technical Documentation:

The **`fontSize`** property accepts values in *px*, *em*, or *rem* units.

The `fontSize` property accepts values in px, em, or rem units.

Content Writing:

I 'really' can't emphasize this "important point" enough!

I really can't emphasize this important point enough!

Best Practices

🎯
Choose One Style
Stick to either asterisks (*) or underscores (_) consistently throughout your document
📏
Mind Your Spaces
Avoid spaces between formatting marks and text: use **bold** not ** bold **
🎨
Use Sparingly
Too much emphasis can make text harder to read. Use formatting thoughtfully
📚
Semantic Usage
Use formatting to convey meaning, not just for visual effect

Common Mistakes

❌
* Incorrect spacing *
Don't add spaces between markers and text
❌
**_Mixing styles_**
Stick to one style for consistency
❌
***Nested formatting without spaces***
Use spaces when nesting different formatting styles

Lists (Ordered and Unordered) 📝

Lists in Markdown help organize information in a clear, scannable format. Whether you need numbered steps, bullet points, or nested items, Markdown's list syntax provides flexible options for structuring your content.

Unordered Lists

Unordered lists can be created using asterisks (*), plus signs (+), or hyphens (-) as bullet points.

* First item
* Second item
* Third item

- Another item
- Yet another item

+ Also works
+ With plus signs

First item
Second item
Third item

Another item
Yet another item

Also works
With plus signs

Nested Lists

* Main item 1
  * Nested item 1.1
  * Nested item 1.2
    * Even deeper item
    * Another deep item
* Main item 2
  * Nested item 2.1
  * Nested item 2.2

Main item 1
- Nested item 1.1
- Nested item 1.2
  - Even deeper item
  - Another deep item
Main item 2
- Nested item 2.1
- Nested item 2.2

Ordered Lists

1. First step
2. Second step
3. Third step

1. Numbers don't matter
1. Markdown will count
1. For you automatically

First step
Second step
Third step

Numbers don't matter
Markdown will count
For you automatically

Nested Ordered Lists

1. First level
   1. Second level
   2. Another second level
      1. Third level
      2. Another third level
2. Back to first level
   1. Second level again

First level
1. Second level
2. Another second level
  1. Third level
  2. Another third level
Back to first level
1. Second level again

Mixed Lists

1. First ordered item
2. Second ordered item
   * Unordered sub-item
   * Another sub-item
3. Third ordered item
   1. Ordered sub-item
   2. Another ordered sub-item
      * Mixed nesting

First ordered item
Second ordered item
- Unordered sub-item
- Another sub-item
Third ordered item
1. Ordered sub-item
2. Another ordered sub-item
  - Mixed nesting

Task Lists

- [x] Completed task
- [ ] Uncompleted task
- [x] Another completed task
  - [ ] Nested task
  - [x] Completed nested task

Best Practices

🎯
Consistent Markers
Use the same marker type (* or - or +) throughout your document
📏
Proper Indentation
Use 2 or 4 spaces for each level of nesting
↔️
Line Spacing
Add blank lines before and after lists for better readability
🔄
List Continuity
Keep list items of the same type together

Common Mistakes

❌
Inconsistent spacing
Keep indentation consistent for all nested items
❌
Missing line breaks
Separate lists from other content with blank lines
❌
Mixing marker types
Don't mix different bullet point styles in the same list

Links and References 🔗

Links are essential for connecting your content to other resources. Markdown provides several ways to create links, from simple inline links to more maintainable reference-style links.

Inline Links

Basic Link Syntax

[Link text](URL)
[Visit our website](https://example.com)
[Contact support](mailto:support@example.com)

Visit our website

Contact support

Links with Titles

[Link text](URL "Title text")
[Documentation](https://docs.example.com "View our docs")

Documentation

Hover over the link to see the title

Reference-style Links

Reference-style links use a two-part syntax, making content more readable and maintainable.

[React][1] is a popular framework.
[Vue][2] is another great option.
[Angular][3] has strong typing support.

[1]: https://reactjs.org
[2]: https://vuejs.org "Vue.js"
[3]: https://angular.io 'Angular'

React is a popular framework.

Vue is another great option.

Angular has strong typing support.

Collapsed Reference Links

[GitHub][] is a development platform.
[VS Code][] is a popular editor.

[github]: https://github.com
[vs code]: https://code.visualstudio.com

GitHub is a development platform.

VS Code is a popular editor.

Special Link Types

Automatic Links

<https://example.com>
<contact@example.com>

https://example.com

contact@example.com

Relative Links

[Read More](./docs/readme.md)
[Go Back](../)

Go Back

Advanced Features

Handling Special Cases

[Link with spaces](path%20with%20spaces.html)
[Link with (parentheses)](<path(with)parentheses>)

URLs with spaces should be encoded using %20
URLs with special characters can be wrapped in <angle brackets>

Best Practices

🎯
Descriptive Text
Use meaningful link text instead of "click here" or "read more"
🔄
Reference Style
Use reference-style links for URLs that appear multiple times
🌐
Protocol Inclusion
Always include http:// or https:// in URLs
📝
Title Attributes
Add titles to provide additional context when helpful

Common Mistakes

❌
[Link text] (URL)
Don't put spaces between brackets and parentheses
❌
[Click here](URL)
Avoid non-descriptive link text
❌
[Link](example.com)
Don't forget the protocol (http:// or https://)

External Link Tips

When linking to external sites, consider:

• Indicating when links open in new windows/tabs
• Verifying that links are still active
• Using HTTPS URLs when available
• Adding relevant title attributes for context

Images and Media 🖼️

Images in Markdown follow a syntax similar to links, with an added exclamation mark (!) at the beginning. This section covers everything from basic image insertion to advanced techniques and best practices.

Basic Image Syntax

![Alt text](image-url.jpg)
![Cat photo](cat.jpg "A cute cat")

Basic image with alt text and title

The syntax consists of:

! - Indicates an image
[] - Contains alt text (for accessibility)
() - Contains the image URL
"" - Optional title shown on hover

Reference-style Images

![Company Logo][logo]
![Profile Picture][avatar]

[logo]: company-logo.png "Our Logo"
[avatar]: profile.jpg 'Profile Picture'

Reference-style images help maintain cleaner, more organized Markdown

Image Dimensions and HTML Attributes

<img src="image.jpg" width="300" height="200" alt="Sized image" />
<img src="image.jpg" align="right" alt="Right-aligned image" />

Note: Some Markdown processors support HTML for advanced image formatting

Clickable Images

[![Alt text](thumbnail.jpg)](full-image.jpg)
<a href="link.html">![Alt text](image.jpg)</a>

Click to view full image (example)

Advanced Features

Image Paths

![Relative](./images/local.jpg)
![Absolute](/images/absolute.jpg)
![External](https://example.com/image.jpg)

• Relative paths for local repository images
• Absolute paths for root-relative images
• Full URLs for external images

Best Practices

🎯
Meaningful Alt Text
Always provide descriptive alternative text for accessibility
📏
Optimize Images
Compress images and use appropriate dimensions for web use
📁
Organized Structure
Keep images in a dedicated directory with clear naming
🔒
Secure Sources
Use HTTPS URLs for external images when available

Accessibility Guidelines

• Use descriptive alt text that conveys the image's purpose
• Make decorative images empty alt="" to avoid screen reader noise noise
• Ensure sufficient color contrast in images with text
• Provide text alternatives for complex infographics

Common Mistakes

❌
![](image.jpg)
Missing alt text reduces accessibility
❌
![Alt text] (image.jpg)
Space between brackets and parentheses breaks the image
❌
![Image of a cat]
Missing image source URL

Blockquotes 💭

Blockquotes in Markdown are perfect for highlighting quotes, excerpts, or important notes. They help break up text and draw attention to key information using simple > syntax.

Basic Blockquotes

> This is a simple blockquote in Markdown.
> It can span multiple lines.
> Each line needs a '>' character.

> You can also write a blockquote
on multiple lines without repeating
the '>' character on each line.

This is a simple blockquote in Markdown.
It can span multiple lines.
Each line needs a > character.

You can also write a blockquote on multiple lines without repeating the > character on each line.

Nested Blockquotes

> First level quote
>> Nested quote
>>> Deeper nested quote
> Back to first level

First level quote
Nested quote
Deeper nested quote
Back to first level

Blockquotes with Other Elements

> ### Header in blockquote
> 
> * List item in quote
> * Another item
> 
> **Bold text** and *italic text* in quote
> 
> `code` in blockquote

Header in blockquote
List item in quote
Another item
Bold text and italic text in quote
code in blockquote

Common Use Cases

Citations

> The only way to do great work is to love what you do.
> 
> -- Steve Jobs

The only way to do great work is to love what you do.
-- Steve Jobs

Note Callouts

> **Note:** This is an important callout.
> Please pay attention to these details.
> They are crucial for understanding.

Note: This is an important callout.
Please pay attention to these details.
They are crucial for understanding.

Best Practices

🎯
Proper Spacing
Add blank lines before and after blockquotes for clarity
📝
Consistent Formatting
Maintain consistent quote marker style throughout your document
🔍
Clear Attribution
Always cite sources when quoting external content
🎨
Meaningful Usage
Use blockquotes purposefully, not just for visual effect

Common Mistakes

❌
>No space after marker
Always add a space after the > symbol
❌
Missing blank lines
Separate blockquotes from other content
❌
Inconsistent markers
Use the same number of > symbols for each nesting level

Code Blocks and Syntax Highlighting 👨‍💻

Markdown makes it easy to display both inline code and code blocks with optional syntax highlighting. Whether you're writing documentation, tutorials, or sharing code snippets, Markdown provides flexible options for code formatting.

Inline Code

Use `backticks` for inline code
The `console.log()` function outputs to the console

Use backticks for inline code

The console.log() function outputs to the console

Basic Code Blocks

Indent with 4 spaces or 1 tab:

    function greet(name) {
        console.log("Hello, " + name + "!");
    }
    
    greet("World");

function greet(name) {
    console.log("Hello, " + name + "!");
}

greet("World");

Fenced Code Blocks

Fenced code blocks use triple backticks and optionally specify the programming language:

```javascript
const calculateArea = (width, height) => {
    return width * height;
};

console.log(calculateArea(5, 3));  // 15
```

const calculateArea = (width, height) => {
    return width * height;
};

console.log(calculateArea(5, 3));  // 15

```python
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

print(factorial(5))  # 120
```

def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

print(factorial(5))  # 120

Syntax Highlighting

Common language identifiers include:

• javascript, js
• python, py
• html
• css
• typescript, ts
• jsx, tsx
• json
• bash, shell
• sql
• yaml
• markdown, md
• diff

Advanced Features

Line Highlighting

```javascript {2-4} showLineNumbers
function example() {
    // This line is highlighted
    const x = 42;
    return x;
}
```

Diff Blocks

```diff
- const oldFunction = (x) => x;
+ const newFunction = (x) => x * 2;
```

Best Practices

🎯
Specify Language
Always specify the programming language for proper syntax highlighting
📏
Maintain Indentation
Keep code properly indented for readability
💡
Add Comments
Include relevant comments to explain complex code sections
✂️
Keep it Concise
Show only relevant parts of the code for examples

Common Mistakes

❌
Missing language identifier
Always specify the programming language for proper highlighting
❌
Inconsistent spacing
Maintain consistent indentation throughout code blocks
❌
Missing closing backticks
Ensure code blocks are properly closed with triple backticks

Documentation Tips

• Include example input and output
• Show error cases and handling
• Provide context with comments
• Use meaningful variable names
• Break down complex examples

Tables 📊

Markdown tables allow you to organize data in rows and columns. While the syntax is straightforward, it supports features like column alignment and text formatting within cells.

Basic Tables

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

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

Note: The number of hyphens in the separator row doesn't matter, but there must be at least three hyphens for each column.

Column Alignment

Control alignment using colons in the separator line:

| Left | Center | Right |
|:-----|:------:|------:|
| 1    | 2      | 3     |
| 4    | 5      | 6     |

Left	Center	Right
1	2	3
4	5	6

:---- (Left align - default)
:---: (Center align)
----: (Right align)

Formatting Within Tables

| Format | Example | Description |
|---------|---------|-------------|
| **Bold** | Text | Strong emphasis |
| *Italic* | Text | Emphasis |
| `Code` | Text | Inline code |
| [Link](url) | Text | Hyperlink |

Format	Example	Description
Bold	Text	Strong emphasis
Italic	Text	Emphasis
`Code`	Text	Inline code
Link	Text	Hyperlink

Table Organization Tips

📏
Consistent Column Widths
Keep cell content and separator lines aligned for better readability
🔍
Clear Headers
Use descriptive column headers that explain the data
📊
Logical Grouping
Organize related data in adjacent columns
↔️
Appropriate Alignment
Use left align for text, right align for numbers

Common Mistakes

❌
Missing header row
Always include a header row for clarity
❌
Inconsistent columns
Ensure each row has the same number of columns
❌
Missing separators
Include proper separator rows with at least three hyphens

Best Practices

🎯
Keep Tables Simple
Use tables for data that naturally fits a grid format
📏
Consistent Formatting
Maintain consistent alignment and spacing throughout the table
📊
Use Headers Effectively
Make column headers clear and descriptive
🔍
Readable Content
Keep cell content concise and easy to scan

Best Practices and Tips 💡

Following consistent Markdown practices ensures your documents are readable, maintainable, and accessible. Here's a comprehensive guide to writing effective Markdown content.

Document Structure

📑
Consistent Headers
Start with a single H1 (#), followed by logical heading levels. Don't skip levels.
📏
Clear Sections
Use headers to create distinct sections. Add blank lines between sections.
📚
Table of Contents
For longer documents, include a table of contents with anchor links.

Formatting Guidelines

✨
Consistent Formatting
Choose one style for emphasis (* or _) and stick to it throughout.
↔️
Line Length
Keep lines under 80 characters for better readability.
🔤
Lists Formatting
Use consistent list markers and proper indentation for nested lists.

Accessibility Considerations

🎯
Descriptive Links
Use meaningful link text instead of "click here" or "read more".
🖼️
Alt Text
Provide descriptive alt text for all images and diagrams.
📝
Heading Structure
Maintain proper heading hierarchy for screen readers.

Content Management

📁
File Organization
Use clear file names and organize content in logical folders.
🔄
Version Control
Use Git or similar tools to track document changes.
🔍
Regular Review
Periodically review and update content for accuracy.

Tools and Workflow

Recommended Editors

• Visual Studio Code with Markdown extensions
• Typora for WYSIWYG editing
• Obsidian for note-taking
• StackEdit for online editing

Useful Tools

• Markdown linters for consistency
• Preview tools for rendering
• Image optimization tools
• Git for version control

Common Pitfalls to Avoid

❌
Inconsistent Formatting
Mixing different styles for emphasis or lists
❌
Poor Organization
Lack of clear structure or logical flow
❌
Neglecting Accessibility
Missing alt text or proper heading structure

Pro Tips

• Preview your content before publishing
• Use keyboard shortcuts for common formatting
• Keep a reference guide handy
• Practice writing Markdown regularly
• Join Markdown communities for tips