DocumentationJanuary 28, 202411 min read

Markdown Syntax Complete Guide for Developers

Master Markdown formatting for documentation, README files, and technical writing. Learn basic and advanced syntax with practical examples.

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. It allows you to write formatted text using simple plain-text syntax that's easy to read and write. Markdown is widely used for README files, documentation, blog posts, and comments on platforms like GitHub.

Basic Markdown Syntax

Headings

Create headings using hash symbols (#). More hashes mean smaller headings:

# H1 Heading
## H2 Heading
### H3 Heading
#### H4 Heading
##### H5 Heading
###### H6 Heading

Emphasis

*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
~~strikethrough text~~

Lists

Unordered Lists

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

* You can also use asterisks
* Or plus signs
+ Like this

Ordered Lists

1. First item
2. Second item
   1. Nested item 2.1
   2. Nested item 2.2
3. Third item

1. You can use any numbers
1. And Markdown will auto-number
1. In sequence

Links

[Link text](https://www.example.com)
[Link with title](https://www.example.com "Hover text")

<!-- Reference-style links -->
[Link text][reference]
[reference]: https://www.example.com

<!-- URLs and emails -->
<https://www.example.com>
<email@example.com>

Images

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

<!-- Reference-style images -->
![Alt text][image-ref]
[image-ref]: image.jpg "Image title"

Code and Syntax Highlighting

Inline Code

Use `backticks` for inline code like `const x = 5;`

Code Blocks

```javascript
function greet(name) {
  console.log(`Hello, ${name}!`);
}
```

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

```
Plain code block without syntax highlighting
```

Blockquotes

> This is a blockquote
> It can span multiple lines

> You can nest blockquotes
>> Like this
>>> And even deeper

Horizontal Rules

---
Three or more hyphens

***
Three or more asterisks

___
Three or more underscores

Tables

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

<!-- Alignment -->
| Left aligned | Center aligned | Right aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |

<!-- You don't need perfect spacing -->
| Header | Another Header |
|--------|----------------|
| Content | More content |

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task
  - [x] Nested completed task
  - [ ] Nested incomplete task

Advanced Markdown Features

Footnotes

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Definition Lists

Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

Escaping Characters

Use backslash to escape special characters:
\* Not a bullet point
\# Not a heading
\[Not a link\](not-a-url)

GitHub Flavored Markdown (GFM)

GitHub extends standard Markdown with additional features:

Username Mentions

@username will notify that user

Issue References

#123 links to issue 123
user/repo#123 links to another repo's issue

Emoji

:smile: :heart: :+1: :rocket:
Renders as: 😄 ❤️ 👍 🚀

Collapsible Sections

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

Hidden content goes here.
Can include **Markdown** too!

</details>

Best Practices for Technical Documentation

  • Use clear headings: Structure your document with a logical hierarchy
  • Keep paragraphs short: Break up long text for better readability
  • Use code blocks: Always specify the language for syntax highlighting
  • Add alt text to images: Improves accessibility and SEO
  • Use relative links: For internal documentation links
  • Include a table of contents: For longer documents
  • Test your Markdown: Preview before publishing

Common README Structure

# Project Name

Brief description of what this project does

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

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

## Usage

```javascript
const project = require('project-name');
```

## API Documentation

### method()

Description of what the method does

## Contributing

Instructions for contributing

## License

MIT License information

Markdown Tools and Editors

  • VS Code: Built-in Markdown preview
  • Typora: WYSIWYG Markdown editor
  • StackEdit: Online Markdown editor
  • Obsidian: Knowledge base with Markdown
  • GitHub: Preview Markdown in pull requests

Try Our Text Processing Tools

Format and process text with our developer-friendly tools:

Use Text Tools