Markdown Tricks for Cleaner Docs

Markdown Tricks for Cleaner Docs

Markdown is everywhere: READMEs, docs, comments, even this very post. But most people stick to the basics: headings, bold, lists, links. That's fine, but you're leaving a lot on the table. Here are a few tricks that make your docs cleaner, more readable, and easier to maintain.

1. Use Task Lists for Progress Tracking

Task lists aren't just for GitHub issues. They're great for documenting multi-step processes or tracking your own work-in-progress. The syntax is simple:

- [x] Write the intro
- [ ] Add examples
- [ ] Proofread

Rendered, they show checkboxes. In a README, they signal what's done and what's pending. In a design doc, they can outline implementation steps. Just remember to keep them updated or they become stale.

2. Tables: Align and Keep Them Narrow

Tables are powerful but can get ugly fast. Use alignment colons to keep numbers readable:

| Feature | Status | Priority |
|:--------|:------:|---------:|
| Auth    |  Done  |      High |
| Billing |  WIP   |    Medium |
| Admin   |  TODO  |       Low |

Notice the colons: left-align text, center-align status, right-align numbers. This makes scanning easier. Also, keep tables under 8 columns; anything wider becomes a horizontal scroll nightmare on mobile.

3. Collapsible Sections for Long Content

When docs get long, use collapsible sections to hide details until needed. This works on GitHub and many other renderers:

<details>
  <summary>Click to expand the full changelog</summary>

  ## v2.0.0
  - Added new API
  - Fixed bug #123

  ## v1.0.0
  - Initial release
</details>

This is perfect for changelogs, troubleshooting steps, or optional deep dives. It keeps the main doc clean while still making the content available.

4. Anchors for Deep Linking

Every heading in Markdown gets an auto-generated anchor. Use that to link to specific sections, especially in long docs:

## Installation
...

See [Installation](#installation) for details.

The anchor is the heading text in lowercase, spaces replaced with hyphens. For non-ASCII characters, you might need to check how your renderer handles them. This is great for a table of contents or cross-referencing within a doc.

5. Blockquotes for Callouts

Blockquotes are usually used for quotes, but they work brilliantly for callouts like warnings, tips, or notes. Combine with bold to make them pop:

> **Warning:** This API is deprecated. Use `v2` instead.

> **Tip:** Run `npm test` before pushing.

Some renderers support custom callout syntax (like GitHub's > [!NOTE]), but plain blockquotes are universally supported and still effective.

6. Code Blocks with Language and Highlights

Always specify the language for syntax highlighting. It's a small thing that makes a huge difference in readability:

const greet = (name) => `Hello, ${name}!`;

Also, in many renderers you can highlight specific lines by appending {1,3-4} after the language, though this is not universal. Check your platform's docs. Even without line highlighting, just using the right language tag is a win.

7. Escaping the Pipe in Tables

Pipes inside table cells break the table. If you need a literal pipe, escape it with a backslash:

| Command | Description |
|---------|-------------|
| `\\|`   | Pipe char   |

This is a common gotcha, and knowing it saves you from weirdly broken tables.

8. Use Relative Links for Local Files

When documenting a codebase, link to files relative to the current file. This works on GitHub and most code hosts:

See [the config file](./config/settings.json) for defaults.

This keeps links working even if the repo is moved or cloned elsewhere. Avoid absolute paths like /docs/readme.md.

9. Keep Lines Short in Source

Even though Markdown wraps text, keeping source lines under 80 characters makes diffs cleaner and editing easier. Some editors do this automatically, but it's a habit worth forming. It also helps when viewing raw files on mobile.

10. Use HTML for Advanced Layout

When Markdown isn't enough, you can drop in raw HTML. This is handy for things like aligning images or adding custom styling:

<p align="center">
  <img src="logo.png" width="200">
</p>

But use HTML sparingly. It breaks the portability of Markdown. If you need heavy layout, consider a proper documentation generator.

Wrapping Up

These tricks aren't exotic, but they're often overlooked. Start with task lists and collapsible sections; they immediately improve clarity. Tables with alignment and proper language tags make code docs look professional. And always remember: the goal is readability for your future self and your collaborators.

What's your go-to Markdown trick? I'd love to hear in the comments.