We all know the basics: **bold**, *italic*, # Headings. But Markdown (especially GitHub Flavored Markdown) has some lesser-known tricks that can make your READMEs, docs, and PR descriptions much more polished. Here are five I use constantly.
1. Collapsible Sections with <details>
Got a long README? Hide secondary content behind expandable sections:
<details>
<summary>Click to see the full changelog</summary>
- v2.1: Added dark mode
- v2.0: Complete rewrite
- v1.0: Initial release
</details>
This renders as a clickable toggle. Perfect for changelogs, setup instructions, or verbose examples you don't want cluttering the main view. GitHub, GitLab, and most static site generators support this.
2. Auto-Linking to Headings
GitHub auto-generates anchor links for every heading. You can link to any section with a simple relative link:
See the [Installation](#installation) section for setup instructions.
The rule: lowercase everything, replace spaces with hyphens, remove punctuation. So ## API Reference (v2) becomes #api-reference-v2.
Bonus: This works across files too — [See docs](docs/API.md#authentication).
3. Task Lists in PR Descriptions
GFM supports interactive checkboxes:
- [x] Add unit tests
- [x] Update documentation
- [ ] Bump version number
- [ ] Deploy to staging
These render as actual checkboxes on GitHub Issues and PRs. Use them in PR templates to create a checklist the author can tick off before merging. They also show up in project boards as trackable items.
4. Escaping Backticks Inside Inline Code
Sometimes you need to show a literal backtick character inside inline code. The trick? Use double backticks as delimiters:
To display a variable, use `` `varname` `` in your template.
Renders as: To display a variable, use `varname` in your template.
The outer double-backtick pair lets you nest single backticks inside. Add a space before/after the inner backtick for readability.
5. Mermaid Diagrams in Fenced Code Blocks
Many platforms (GitHub, GitLab, Notion) support Mermaid diagrams directly in Markdown. Just use mermaid as the language tag:
```
mermaid
graph TD
A[User] --> B[Login Page]
B --> C{Valid?}
C -->|Yes| D[Dashboard]
C -->|No| E[Error Message]
```
```
`
This renders a flowchart directly in your README — no external tools, no image exports. Mermaid supports flowcharts, sequence diagrams, Gantt charts, class diagrams, and more.
---
## The Best Way to Learn? Preview in Real Time
The fastest way to get comfortable with Markdown is to see it render as you type. I use [CodeToolbox Markdown Preview](https://codetoolbox.pro/tools/markdown-preview.html) when drafting READMEs — it's free, runs entirely in the browser (nothing gets uploaded), and supports full GFM including tables, task lists, and syntax-highlighted code blocks.
What Markdown tricks do you use that aren't in the standard cheat sheet? Drop them in the comments 👇
