Markdown Tricks for Cleaner Docs
Markdown is everywhere: READMEs, docs sites, issue trackers, even internal wikis. But most people only use the basics: headings, bold, italics, links. That's fine, but you're leaving a lot of readability on the table. Here are a few tricks I use daily to keep my docs clean and scannable.
1. Use Tables, Not ASCII Art
We've all seen those hand-drawn tables with pipes and dashes. They work, but they're painful to maintain. Markdown tables are cleaner and render beautifully on GitHub, GitLab, and most doc sites.
| Feature | Status | Notes |
|---------|--------|-------|
| Auth | Done | OAuth2 |
| API | WIP | v2 in progress |
Pro tip: align columns with spaces for readability in source, but don't obsess over it. Most renderers don't care.
2. Add Collapsible Sections
Long docs bury important details. Use <details> and <summary> to hide advanced or optional content. This works on GitHub and many other platforms.
<details>
<summary>Click to see the full config</summary>
yaml
debug: true
log_level: verbose
</details>
markdown
Readers get the gist without scrolling past walls of code. It's like an accordion for your docs.
3. Use Blockquotes for Callouts
A simple > is great for quotes, but you can level up with bold labels to create callouts for warnings, tips, and notes.
> **Note:** This feature is deprecated in v2.
> **Warning:** Do not run this in production.
> **Tip:** Use `--dry-run` first to preview changes.
It adds visual hierarchy without any extra syntax. Many platforms also support custom callout syntax, but this works everywhere.
4. Task Lists for Checklists
Task lists are native to GitHub and many other renderers. They're perfect for step-by-step guides, onboarding docs, or release checklists.
- [x] Set up CI
- [ ] Add tests
- [ ] Update README
You can even nest them with indentation. It turns a flat list into an interactive progress tracker.
5. Use Relative Links in Repos
When linking between files in a repo, use relative paths instead of absolute URLs. This makes your docs portable and version-controlled. If you move the repo, links still work.
See [the setup guide](./docs/setup.md) for details.
For headings, you can link to anchors like #tricks but be careful: the anchor ID depends on the renderer. Test before relying on it.
6. Escape Underscores and Asterisks
When writing about code, underscores and asterisks can trigger formatting. Use backticks for inline code, or escape with a backslash.
Use `foo_bar` not foo\_bar.
The regex is `a\*b` to match a star.
This prevents accidental italics or bold in the middle of words.
7. Keep Line Length Short
Markdown is source code. Long lines are hard to review and diff. Wrap paragraphs at around 80-100 characters. It makes git diffs cleaner and editing easier.
This is a short line.
This is another short line.
Some editors auto-wrap, but it's worth doing manually for consistency.
8. Use Horizontal Rules Sparingly
--- creates a horizontal rule. It can break up sections, but overuse makes docs feel choppy. Use headings for structure and rules only when you need a visual break, like before a footer or appendix.
9. Add Alt Text to Images
Images in docs often get ignored, but alt text matters for accessibility and when images fail to load. Use the standard syntax:
Keep it descriptive: "Architecture diagram showing the API gateway and services" is better than "diagram".
10. Prefer Lists Over Paragraphs
When you have multiple points, use a bullet list instead of a paragraph. It's easier to scan and less intimidating. For processes, use numbered lists.
- Install dependencies
- Run tests
- Deploy
Final Thought
Clean docs are a form of respect for your readers and your future self. These tricks take seconds to apply but save minutes of confusion. Start with one or two, and you'll notice the difference immediately.
What's your favorite markdown trick? I'd love to hear it.
Happy documenting!
