DEV Community

zhihu wu
zhihu wu

Posted on • Originally published at codetoolbox.pro

5 Markdown Tricks Every Developer Should Know (That Aren't in the Cheat Sheet)

#markdown #github #documentation #webdev

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>
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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 👇
Enter fullscreen mode Exit fullscreen mode

Top comments (0)