The Complete Markdown Guide - From Basics to Advanced

Introduction: What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Its primary goal is to be as readable as possible in its raw form while still being convertible to structurally valid HTML. Today, Markdown has become the de facto standard for writing content on the web -- from documentation and README files to blog posts, comments, and messaging platforms.

If you are a developer, technical writer, blogger, or anyone who writes content for the web, learning Markdown is one of the most valuable skills you can develop. It is simple enough to learn in minutes but powerful enough to handle complex documentation.

Want to practice as you read this guide? Try our Markdown Preview tool to see your Markdown rendered in real-time.

Why Use Markdown?

Before diving into syntax, it is worth understanding why Markdown has become so popular:

• Readability: Raw Markdown is easy to read, even without rendering
• Portability: Markdown files are plain text and work everywhere
• Simplicity: The syntax is intuitive and easy to learn
• Wide support: Used by GitHub, GitLab, Reddit, Stack Overflow, Notion, Obsidian, and many more
• Version control friendly: Being plain text, Markdown works perfectly with Git
• Convertible: Markdown can be converted to HTML, PDF, DOCX, and many other formats
• Focus on content: Markdown lets you focus on writing rather than formatting

Basic Syntax

These are the fundamental Markdown elements that are supported by virtually every Markdown processor.

Headings

Headings are created by adding one to six # symbols before the heading text. The number of # symbols corresponds to the heading level.

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

Best practices for headings:

• Always put a space between the # and the heading text
• Use only one H1 per document (usually the title)
• Do not skip heading levels (go from H2 to H3, not H2 to H4)
• Keep headings concise and descriptive

Alternative Heading Syntax

For H1 and H2, you can use an alternative syntax:

Heading 1
=========

Heading 2
---------

Paragraphs

Paragraphs are separated by blank lines. A single line break within a paragraph is treated as a space.

This is the first paragraph. It can span
multiple lines but will be rendered as one paragraph.

This is the second paragraph. It is separated by a blank line.

Line Breaks

To create a line break without starting a new paragraph, end a line with two or more spaces, or use the <br> HTML tag.

This is the first line.
This is the second line (note the two spaces above).

This is the first line.<br>
This is the second line.

Emphasis (Bold and Italic)

*italic text* or _italic text_

**bold text** or __bold text__

***bold and italic*** or ___bold and italic___

~~strikethrough text~~

Rendered result:

• italic text
• bold text
• bold and italic
• strikethrough text

Best practice: Use asterisks (*) rather than underscores (_) for emphasis, as asterisks work more consistently in the middle of words.

Blockquotes

Blockquotes are created with the > character:

> This is a blockquote.
>
> It can span multiple paragraphs.

> Blockquotes can be nested.
>
>> This is a nested blockquote.
>>
>>> And a third level.

Lists

Unordered lists use -, *, or +:

- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
    - Deeply nested item
- Item 3

Ordered lists use numbers followed by periods:

1. First item
2. Second item
3. Third item
   1. Nested item 3.1
   2. Nested item 3.2
4. Fourth item

Important note: The actual numbers do not matter in ordered lists. Markdown will automatically number them sequentially. However, it is good practice to use correct numbers for readability.

Horizontal Rules

Create a horizontal rule with three or more hyphens, asterisks, or underscores:

---

***

___

Links and Images

Links

[Link text](https://example.com)

[Link with title](https://example.com "Link Title")

<https://example.com> (automatic link)

<email@example.com> (email link)

Reference-Style Links

For documents with many links, reference-style links keep the text readable:

Check out [ToolBox Hub][1] for free developer tools.
You can use our [JSON Formatter][json] or [Regex Tester][regex].

[1]: https://toolboxhubs.com
[json]: https://toolboxhubs.com/en/tools/json-formatter
[regex]: https://toolboxhubs.com/en/tools/regex-tester

Images

![Alt text](image-url.png)

![Alt text](image-url.png "Image title")

[![Clickable image](image.png)](https://example.com)

Image Best Practices

• Always include descriptive alt text for accessibility
• Use relative paths for images in the same repository
• Consider image size and loading performance
• Use appropriate image formats (WebP for web, SVG for diagrams)

Code

Inline Code

Wrap inline code with single backticks:

Use the `console.log()` function to debug.
The `<div>` element is a block-level container.

Code Blocks

Use triple backticks (```) with an optional language identifier for syntax highlighting:

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

```python
def greet(name):
    return f"Hello, {name}!"
```

```css
.container {
  display: flex;
  justify-content: center;
  align-items: center;
}
```

Supported Languages

Most Markdown processors support syntax highlighting for a wide range of languages. Common identifiers include:

Language	Identifier	Language	Identifier
JavaScript	javascript or js	Python	python or py
TypeScript	typescript or ts	Java	java
HTML	html	CSS	css
JSON	json	YAML	yaml
Bash	bash or shell	SQL	sql
C	c	C++	cpp
Go	go	Rust	rust
Ruby	ruby	PHP	php
Swift	swift	Kotlin	kotlin
Markdown	markdown or md	Diff	diff

You can test and format code snippets using our JSON Formatter for JSON data or Markdown Preview for rendered output.

Indented Code Blocks

You can also create code blocks by indenting with four spaces or one tab:

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

However, fenced code blocks (with backticks) are preferred because they support language specification and are easier to manage.

Tables

Tables are created using pipes (|) and hyphens (-):

| Feature | Free Plan | Pro Plan | Enterprise |
|---------|-----------|----------|------------|
| Users | 1 | 10 | Unlimited |
| Storage | 1 GB | 100 GB | 1 TB |
| Support | Community | Email | 24/7 Phone |
| API Access | Limited | Full | Full |

Rendered result:

Feature	Free Plan	Pro Plan	Enterprise
Users	1	10	Unlimited
Storage	1 GB	100 GB	1 TB
Support	Community	Email	24/7 Phone
API Access	Limited	Full	Full

Column Alignment

Use colons to align columns:

| Left-aligned | Center-aligned | Right-aligned |
|:------------|:-------------:|-------------:|
| Left | Center | Right |
| Data | Data | Data |

Left-aligned	Center-aligned	Right-aligned
Left	Center	Right
Data	Data	Data

Table Tips

• You do not need to align the pipes perfectly (but it looks nicer in raw form)
• Tables cannot contain block-level elements (headings, lists, code blocks)
• Use HTML tables if you need more complex layouts
• Keep tables simple -- complex tables are hard to maintain in Markdown

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown extends standard Markdown with features commonly needed by developers. GFM is supported by GitHub, GitLab, and many other platforms.

Task Lists

- [x] Complete project setup
- [x] Write documentation
- [ ] Add unit tests
- [ ] Deploy to production
- [ ] Monitor performance

Rendered result:

• Complete project setup
• Write documentation
• Add unit tests
• Deploy to production
• Monitor performance

Task lists are particularly useful in GitHub issues and pull request descriptions.

Autolinked References

In GitHub, certain references are automatically linked:

Issue: #42
Pull Request: #123
Commit: a1b2c3d
User: @username
Organization: @org-name

Emoji

GFM supports emoji shortcodes:

:smile: :rocket: :bug: :white_check_mark: :warning:
:thumbsup: :thumbsdown: :heart: :star: :fire:

Footnotes

This claim needs a source[^1].

Another referenced fact[^note].

[^1]: Source: Journal of Computer Science, 2026.
[^note]: This is a longer footnote with multiple paragraphs.

    Indent to include additional paragraphs in the footnote.

Alerts / Admonitions (GitHub)

GitHub supports special blockquote-based alerts:

> [!NOTE]
> Useful information that users should know, even when skimming.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

Advanced Markdown Techniques

Definition Lists

Some Markdown processors support definition lists:

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

Abbreviations

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Math Equations (LaTeX)

Many platforms support LaTeX-style math equations:

Inline math: $E = mc^2$

Block math:
$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

$$
f(x) = \int_{-\infty}^{\infty} \hat{f}(\xi) e^{2\pi i \xi x} d\xi
$$

Diagrams with Mermaid

GitHub and many documentation platforms support Mermaid diagrams in Markdown:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
```

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Database
    Client->>API: POST /users
    API->>Database: INSERT user
    Database-->>API: User created
    API-->>Client: 201 Created
```

HTML in Markdown

When Markdown syntax is not sufficient, you can use raw HTML:

<details>
<summary>Click to expand</summary>

This content is hidden by default.

- You can use Markdown inside HTML blocks
- Just make sure to leave blank lines around the Markdown content

</details>

<div align="center">
  <img src="logo.png" alt="Logo" width="200">
  <p><em>Centered content with HTML</em></p>
</div>

<kbd>Ctrl</kbd> + <kbd>C</kbd> to copy

This is <mark>highlighted</mark> text.

H<sub>2</sub>O is water.

x<sup>2</sup> is x squared.

Markdown Variants and Processors

Different platforms and tools support different Markdown variants:

Variant	Platform	Notable Features
CommonMark	Standard	Strict, well-defined spec
GFM	GitHub, GitLab	Task lists, tables, autolinks
MDX	React/Next.js	JSX components in Markdown
R Markdown	RStudio	Code execution, reports
MultiMarkdown	Various	Footnotes, citations, metadata
Kramdown	Jekyll	Definition lists, abbreviations
Obsidian Markdown	Obsidian	Wiki links, graph view

MDX: Markdown + JSX

MDX extends Markdown with JSX support, allowing you to use React components directly in your content. This blog post you are reading is written in MDX.

---
title: "My Blog Post"
date: "2026-03-10"
---

import { Chart } from '../components/Chart'
import { CodePlayground } from '../components/CodePlayground'

## Introduction

Here's an interactive chart:

<Chart data={salesData} type="bar" />

And a live code example:

<CodePlayground language="javascript">
{`console.log("Hello, World!")`}
</CodePlayground>

Markdown Best Practices

Document Structure

1. Start with a single H1: This is usually the document title
2. Use headings hierarchically: H2 for main sections, H3 for subsections
3. Add a table of contents: For long documents, include a TOC at the top
4. Keep paragraphs short: Aim for 3-5 sentences per paragraph

Writing Style

1. Be consistent: Choose one style for emphasis (asterisks vs. underscores) and stick with it
2. Use blank lines generously: Separate different elements with blank lines
3. Indent nested content properly: Use 2 or 4 spaces consistently
4. Break long lines: While not required, line breaks at 80-100 characters improve raw readability

Code in Markdown

1. Always specify the language: Use fenced code blocks with language identifiers
2. Keep code examples short: Focus on the relevant code
3. Add comments: Explain complex code within the code block
4. Test your code: Make sure code examples actually work

Links and References

1. Use descriptive link text: Avoid "click here" -- use meaningful text
2. Check for broken links: Regularly verify all links work
3. Use reference-style links: For documents with many links
4. Link to relevant resources: Help readers find additional information

Common Markdown Use Cases

README Files

Every GitHub repository should have a README.md with:

# Project Name

Brief description of the project.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

\`\`\`bash
npm install project-name
\`\`\`

## Usage

\`\`\`javascript
import { tool } from 'project-name';
tool.execute();
\`\`\`

## Contributing

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License.

API Documentation

## POST /api/users

Create a new user account.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User's email address |
| name | string | Yes | User's full name |
| password | string | Yes | Minimum 12 characters |

### Response

\`\`\`json
{
  "id": "usr_123abc",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2026-03-10T12:00:00Z"
}
\`\`\`

### Error Codes

| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 409 | Email already exists |
| 500 | Internal server error |

Use our JSON Formatter to format and validate JSON examples in your API documentation.

Technical Blog Posts

---
title: "Building a REST API with Node.js"
date: "2026-03-10"
tags: ["nodejs", "api", "tutorial"]
---

## Introduction

In this tutorial, we will build a complete REST API...

## Prerequisites

- Node.js 20 or later
- Basic knowledge of JavaScript
- A code editor (VS Code recommended)

## Step 1: Project Setup

First, create a new directory and initialize the project:

\`\`\`bash
mkdir my-api && cd my-api
npm init -y
npm install express zod
\`\`\`

...

Meeting Notes and Knowledge Bases

# Sprint Planning - March 10, 2026

## Attendees

- @alice (Product)
- @bob (Engineering)
- @charlie (Design)

## Decisions

1. Prioritize feature X over feature Y
2. Defer bug #42 to next sprint

## Action Items

- [ ] @bob: Estimate effort for feature X
- [ ] @charlie: Create wireframes by Thursday
- [ ] @alice: Update stakeholders on timeline change

Markdown Tools and Editors

Desktop Editors

• VS Code with Markdown extensions (most popular)
• Obsidian for personal knowledge management
• Typora for a seamless WYSIWYG experience
• MarkText for a free, open-source alternative

Online Editors

• ToolBox Hub Markdown Preview -- our free online Markdown preview tool
• HackMD for collaborative editing
• StackEdit for a full-featured browser-based editor

Conversion Tools

• Pandoc -- the Swiss Army knife of document conversion
• markdown-pdf -- convert Markdown to PDF
• remark -- JavaScript Markdown processor

Markdown Quick Reference

Here is a comprehensive quick reference table:

Element	Syntax	Notes
Heading	# H1 to ###### H6	Space after #
Bold	**text**	Or __text__
Italic	*text*	Or _text_
Strikethrough	~~text~~	GFM feature
Blockquote	> text	Nestable
Ordered list	1. item	Numbers auto-increment
Unordered list	- item	Also * or +
Code (inline)	`code`	Single backticks
Code block	```	Triple backticks
Link	[text](url)	Optional title
Image		Optional title
Horizontal rule	---	Also *** or ___
Table	| col | col |	GFM feature
Task list	- [x] done	GFM feature
Footnote	text[^1]	Not universal

Conclusion

Markdown is a powerful yet simple tool that every developer and technical writer should know. Its plain-text format makes it perfect for version-controlled documentation, blog posts, README files, and much more. With the extended features of GitHub Flavored Markdown and MDX, you can create rich, interactive content while keeping your source files clean and readable.

To practice writing Markdown and see your work rendered instantly, try our free Markdown Preview tool. You can also use our Word Counter to check the length of your Markdown documents and our Case Converter to quickly format headings and text.

Related Resources

• Markdown Preview Tool -- Preview your Markdown in real-time
• Word Counter -- Count words in your Markdown documents
• Case Converter -- Convert text case for headings
• JSON Formatter -- Format JSON for code examples
• Regex Guide for Beginners -- Learn regex for text processing