Markdown Tips & Best Practices

✓ Use Consistent Heading Hierarchy

Always start with # and don't skip levels.

# Main Title
## Section
### Subsection

# Main Title
### Skipped Level

✓ Add Blank Lines for Readability

Separate different elements with blank lines.

# Title

Paragraph text.

- List item
- List item

# Title
Paragraph text.
- List item
- List item

✓ Use Fenced Code Blocks with Language

Always specify the language for syntax highlighting.

```javascript
const x = 10;
```

```
const x = 10;
```

📋 Use Table of Contents for Long Documents

# Document Title

## Table of Contents

- [Introduction](#introduction)
- [Getting Started](#getting-started)
- [Advanced Topics](#advanced-topics)
- [Conclusion](#conclusion)

## Introduction

Content here...

## Getting Started

Content here...

📋 Group Related Information

Keep related content together under clear headings.

## Installation

### Prerequisites
- Node.js
- npm

### Steps
1. Clone repository
2. Install dependencies
3. Run application

### Troubleshooting
Common issues and solutions...

✍️ Keep Lines at Reasonable Length

Wrap lines at 80-120 characters for better version control and readability.

✍️ Use Descriptive Link Text

Check out our [Markdown guide](/guide)

Click [here](/guide) for guide

✍️ Use Alt Text for Images

Always provide descriptive alt text for accessibility.

![Screenshot of the dashboard showing user statistics](dashboard.png)

⚡ Optimize Image Sizes

Compress images and use appropriate formats (WebP, optimized PNG/JPG).

⚡ Use Reference Links for Repeated URLs

[First link][example]
[Second link][example]
[Third link][example]

[example]: https://example.com "Example Site"

⚡ Minimize HTML in Markdown

Use native Markdown syntax when possible. HTML should be a last resort.

👥 Use Consistent Style

Agree on conventions with your team:

• Use * or - for lists (pick one)
• Use ** or __ for bold (pick one)
• Heading case style (Title Case vs Sentence case)

👥 Write Clear Commit Messages

When editing Markdown in version control:

docs: update installation guide with new prerequisites
docs: fix typo in API documentation
docs: add troubleshooting section to README

👥 Use Comments for Notes

HTML comments work in Markdown and won't be rendered:

<!-- TODO: Add more examples here -->
<!-- NOTE: This section needs review -->

♿ Structure Content Logically

Use proper heading hierarchy for screen readers.

♿ Avoid Using Only Color

Don't rely solely on color to convey information. Use text labels too.

♿ Make Links Descriptive

Link text should make sense out of context for screen reader users.