Markdown is the backbone of technical writing, allowing you to create rich, formatted content with simple syntax. This guide covers everything you need to know about Markdown, with examples showing both the syntax and the rendered output.

Headers

Markdown supports six levels of headers using the # symbol:

markdown

# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header

Rendered output:

H1 Header

H2 Header

H3 Header

H4 Header

H5 Header

H6 Header

Text Formatting

Basic Text Styling

markdown

**Bold text**
*Italic text*
***Bold and italic***
~~Strikethrough~~
`Inline code`

Rendered output:

Bold text
Italic text
Bold and italic
~~Strikethrough~~
Inline code

Paragraphs and Line Breaks

markdown

This is a paragraph. To create a new paragraph,
leave a blank line between text blocks.

This is another paragraph.

To create a line break without a new paragraph,  
end a line with two spaces.
This line appears directly below.

Rendered output:

This is a paragraph. To create a new paragraph,
leave a blank line between text blocks.

This is another paragraph.

To create a line break without a new paragraph,
end a line with two spaces.
This line appears directly below.

Lists

Unordered Lists

markdown

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

* Alternative syntax
* Using asterisks
* Works the same way

Rendered output:

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

Alternative syntax
Using asterisks
Works the same way

Ordered Lists

markdown

1. First item
2. Second item
   1. Nested numbered item
   2. Another nested item
3. Third item

1. You can use any numbers
5. The actual numbers don't matter
2. Markdown will auto-number them

Rendered output:

First item
Second item
1. Nested numbered item
2. Another nested item
Third item
You can use any numbers
The actual numbers don't matter
Markdown will auto-number them

Links and Images

Links

markdown

[Link text](https://example.com)
[Link with title](https://example.com "This is a title")
[Reference-style link][1]
<https://example.com>

[1]: https://example.com "Reference link"

Rendered output:

Link text
Link with title
Reference-style link
https://example.com

Images

markdown

![Alt text](./image.png)  
![Alt text with title](./image.png "Image title")  
[![Image as link](./image.png)](https://example.com)

Rendered output:

Image title

Link Cards

When you paste a URL on its own line, it automatically renders as a rich link card with metadata:

markdown

https://react.dev/

Rendered output:

You can also include multiple link cards:

markdown

https://react.dev/

https://tailwindcss.com/

https://github.com/

Rendered output:

Code Blocks

Inline Code

markdown

Use `backticks` for inline code snippets.
You can also use `console.log()` or `npm install` inline.

Rendered output:

Use backticks for inline code snippets.
You can also use console.log() or npm install inline.

Fenced Code Blocks

markdown

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

greet('World');
```

```typescript
interface User {
  id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: 'John Doe',
  email: 'john@example.com'
};
```

```bash
npm install react
cd my-project
npm start
```

Rendered output:

javascript

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

greet('World');

typescript

interface User {
  id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: 'John Doe',
  email: 'john@example.com'
};

bash

npm install react
cd my-project
npm start

Blockquotes

markdown

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

> **Note**: You can use other Markdown elements inside blockquotes.
> 
> ```javascript
> console.log('Even code blocks!');
> ```

> Nested blockquotes
>> Are also possible
>>> And can go deeper

Rendered output:

This is a blockquote.
It can span multiple lines.

Note: You can use other Markdown elements inside blockquotes.
javascript
console.log('Even code blocks!');

Nested blockquotes

Are also possible

And can go deeper

Tables

markdown

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

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

Rendered output:

Header 1	Header 2	Header 3
Row 1	Data	More data
Row 2	Data	More data

Left-aligned	Center-aligned	Right-aligned
Left	Center	Right
Text	Text	Text

Horizontal Rules

markdown

---

***

___

Rendered output:

Task Lists

markdown

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

Rendered output:

Advanced Features

HTML Elements

markdown

You can use HTML elements when Markdown isn't enough:

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

This content is hidden by default and can be expanded.

```javascript
console.log('Code works inside HTML too!');
```

</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd> for keyboard shortcuts.

<mark>Highlighted text</mark> using HTML tags.

Rendered output:

You can use HTML elements when Markdown isn't enough:

Click to expand

This content is hidden by default and can be expanded.

javascript

console.log('Code works inside HTML too!');

Ctrl + C for keyboard shortcuts.

Highlighted text using HTML tags.

Escaping Characters

markdown

Use backslashes to escape special characters:

\*This won't be italic\*
\`This won't be code\`
\# This won't be a header

Literal backticks in code: `` `backtick` ``

Rendered output:

Use backslashes to escape special characters:

*This won't be italic*
`This won't be code`
# This won't be a header

Literal backticks in code: `backtick`

Best Practices for Tech Blogs

1. Code Documentation

Always include language identifiers for syntax highlighting:

markdown

```typescript
// Good: Language specified
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}
```

```
// Bad: No language specified
const data = await fetch('/api/users');
```

2. Consistent Formatting

markdown

Use consistent formatting throughout your articles:

- **Bold** for important terms
- *Italic* for emphasis
- `Code` for technical terms and file names
- > Blockquotes for important notes or warnings

3. Structured Content

markdown

## Use clear section headers

Break up long content with headers, lists, and code blocks.
This makes your content scannable and easier to read.

### Subsections help organize complex topics

Each section should focus on a single concept or feature.

Common Pitfalls to Avoid

1. Missing Blank Lines

markdown

<!-- Wrong -->
Here's some text.
```javascript
console.log('code');
```
More text immediately after.

<!-- Correct -->
Here's some text.

```javascript
console.log('code');
```

More text with proper spacing.

2. Inconsistent List Formatting

markdown

<!-- Wrong -->
- Item 1
* Item 2
- Item 3

<!-- Correct -->
- Item 1
- Item 2
- Item 3

3. Broken Links and Images

markdown

<!-- Always test your links -->
[Working link](https://example.com)
![Alt text for accessibility](./existing-image.png)

Conclusion

Mastering Markdown syntax is essential for creating professional technical documentation and blog posts. The key is to:

Practice regularly - Use Markdown for all your documentation
Keep it simple - Don't overcomplicate your formatting
Be consistent - Establish and follow formatting conventions
Test your output - Always preview your rendered Markdown

With these fundamentals, you'll be able to create clear, well-formatted technical content that's both readable and maintainable.

Pro tip: Most modern editors have Markdown preview features. Use them to check your formatting as you write!

Remember, good Markdown is about clarity and readability, not just fancy formatting. Focus on making your content accessible and easy to understand.