Writing Markdown for Open Source: A Practical Guide

So you want to contribute to open source projects, but you're staring at that Pull Request description box wondering how to make your changes look professional? Let me teach you Markdown—the simple formatting language that'll make your PRs shine.

What is Markdown?

Markdown is a lightweight markup language that lets you format text using simple symbols. It's everywhere in open source: README files, documentation, issue reports, and especially PR descriptions. The beauty? You can write it in plain text, and it renders beautifully on GitHub, GitLab, and most platforms.

The Basics You'll Use Every Day

Headers

Headers organize your content. Use the hash symbol # followed by a space:

# This is an H1 (Main Title)
## This is an H2 (Section)
### This is an H3 (Subsection)
#### This is an H4

Links

Links connect your PR to related issues, documentation, or external resources. The syntax is:

[Link Text](URL)

Examples you'll actually use:

Fixes [#123](https://github.com/project/repo/issues/123)
See [documentation](https://docs.example.com/api)
Related to [this discussion](https://github.com/project/repo/discussions/456)

Emphasis (Bold and Italic)

Make important points stand out:

*This is italic* or _this is also italic_
**This is bold** or __this is also bold__
***This is bold and italic***

In PRs, use bold for things like Breaking Change or Important to catch reviewers' attention.

Lists

Lists keep your changes organized and scannable.

Unordered lists use -, *, or +:

- Fixed authentication bug
- Updated dependencies
- Improved error messages
  - Added context to validation errors
  - Clarified timeout messages

Ordered lists use numbers:

1. Clone the repository
2. Install dependencies
3. Run the tests
4. Submit your PR

Code

Code formatting is crucial for technical PRs.

Inline code uses backticks:

The `getUserData()` function now handles `null` values correctly.

Code blocks use triple backticks with an optional language:

```javascript
function getUserData(id) {
  if (!id) return null;
  return database.query(id);
}
```

Essential Markdown for PR Descriptions

Here's a realistic PR description structure:

## Summary

Fixes #247 - Users were unable to log in with special characters in passwords.

## Changes Made

- Updated password validation regex in `auth/validator.js`
- Added URL encoding for password transmission
- Implemented additional test cases for edge cases

## Testing

Tested with passwords containing: `@`, `#`, `$`, `%`, `&`, and Unicode characters.

**Before:** Login failed with special characters
**After:** All character types now work correctly

## Breaking Changes

None

## Screenshots (if applicable)

![Login form with special characters](url-to-screenshot.png)

Other Useful Elements

Blockquotes for highlighting important notes:

> **Note:** This change requires Node.js version 18 or higher.

Horizontal rules to separate sections:

---

Tables for comparisons or data:

| Before | After |
|--------|-------|
| Slow query | Optimized query |
| 2.3s | 0.4s |

Task lists for tracking work:

- [x] Write tests
- [x] Update documentation
- [ ] Get review from @maintainer

GitHub-Specific Features

GitHub extends standard Markdown with helpful features:

Mentioning users: @username notifies them

Referencing issues/PRs: #123 links to issue 123

Emoji: :tada: becomes 🎉 (use sparingly!)

Collapsible sections:

<details>
    <summary>Click to expand full error log</summary>
</details>

Error: Connection timeout
  at Database.connect (db.js:45)

A Complete PR Description Template

Here's everything together:

## Summary

Fixes #156 - Implements user profile caching to improve page load times.

## Problem

Profile pages were making redundant API calls on every render, causing slow load times (avg 3.2s).

## Solution

- Added Redis caching layer for user profiles
- Implemented 5-minute cache TTL
- Added cache invalidation on profile updates

## Changes

- `src/services/userService.js` - Added caching logic
- `src/config/redis.js` - New Redis configuration
- `tests/userService.test.js` - Added cache tests

## Testing

- [x] Unit tests pass
- [x] Integration tests pass
- [x] Tested cache invalidation manually
- [x] Load tested with 1000 concurrent users

## Performance Impact

| Metric | Before | After |
|--------|--------|-------|
| Avg page load | 3.2s | 0.8s |
| API calls/render | 5 | 1 |

## Breaking Changes

None - changes are backward compatible

## Additional Notes

Cache can be disabled by setting `ENABLE_PROFILE_CACHE=false` in environment variables.

---

**Reviewers:** @backend-team

Quick Reference Cheat Sheet

# Headers
## Use # through ######

# Links
[Text](URL) or just paste URLs

# Emphasis
*italic* **bold** ***both***

# Lists
- Unordered with - or *
1. Ordered with numbers

# Code
`inline code`

```language
code blocks


# Images
![Alt text](image-url)

# Quotes
> Quoted text

# Mentions & Issues

@username #123

Practice Makes Perfect

The best way to learn? Start writing:

1. Edit your GitHub profile README
2. Open a practice issue on your own repo
3. Write a detailed PR description for your next contribution

Now go write that PR! Your future collaborators will thank you.