I've reviewed hundreds of GitHub READMEs while contributing to open source, and the difference between a forgettable one and one that makes people stop scrolling often comes down to a few small Markdown tricks.
1. Collapsible Sections for Long Content
Nobody wants to scroll through 2,000 lines of setup instructions. Use HTML <details> tags to hide secondary content:
<details>
<summary>Advanced Configuration</summary>
Your long config docs here...
</details>
This renders as a clickable expandable section that keeps your README scannable.
2. Task Lists for Roadmaps
GFM task lists aren't just for personal to-dos. Use them as a public roadmap:
- [x] Core API (v1.0)
- [x] Webhook support
- [ ] GraphQL endpoint
- [ ] Multi-region deployment
Users instantly see what's done and what's coming.
3. Reference-Style Links for Cleaner Source
Inline links make raw Markdown hard to read. Reference-style links keep paragraphs clean:
Check the [contributing guide][contrib] for details.
[contrib]: CONTRIBUTING.md
4. Mermaid Diagrams Inside Code Blocks
GitHub renders Mermaid diagrams in fenced code blocks. Show architecture without uploading an image:
```mermaid
graph LR
Client-->API-->Database
API-->Cache
```
5. Align Tables with Consistent Column Widths
Tables are Markdown's weakest feature. Make them maintainable by aligning columns:
| Parameter | Type | Default | Description |
|-----------|--------|---------|--------------------|
| timeout | number | 5000 | Request timeout ms |
| retries | number | 3 | Max retry attempts |
Adding spaces so the pipes align makes the raw source readable.
The fastest way to test any of these is a live preview. I use this free Markdown previewer when drafting READMEs or blog posts — it renders GFM tables, task lists, and diagrams in real time without touching a server.