Markdown Tricks for Cleaner Docs
Markdown Tricks for Cleaner Docs I write a lot of documentation. Over the years, I've picked up a handful of Markdown tricks that make my docs cleaner, more readable, and easier to maintain. Here are my favorites.
Markdown Tricks for Cleaner Docs
I write a lot of documentation. Over the years, I've picked up a handful of Markdown tricks that make my docs cleaner, more readable, and easier to maintain. Here are my favorites.
1. Strikethrough for Deprecation
When you need to mark something as outdated without removing it, use strikethrough:
~~This feature is deprecated.~~ Use the new API instead.
This feature is deprecated. Use the new API instead.
2. Task Lists for Checklists
Task lists are great for progress tracking or step-by-step instructions:
- [x] Implement login
- [ ] Add error handling
- [ ] Write tests
- [x] Implement login
- [ ] Add error handling
- [ ] Write tests
3. Collapsible Sections for Long Content
In GitHub Flavored Markdown, you can use <details> and <summary> to hide verbose details:
<details>
<summary>Click to expand</summary>
This is hidden until you click.
Click to expand
This is hidden until you click.
### 4. Tables with Alignment
Align columns using colons in the separator row:
markdown
| Left | Center | Right |
| :--- | :----: | ----: |
| A | B | C |
| Left | Center | Right |
| :--- | :----: | ----: |
| A | B | C |
### 5. Code Blocks with Language Tags
Always specify the language for syntax highlighting:
markdown
def hello():
print("Hello, world!")
### 6. Footnotes for References
Some Markdown processors support footnotes (like Pandoc or GitHub? Actually, GitHub doesn't. But if your platform does, use them):
markdown
Here's a statement with a footnote1.
(Check your platform's support.)
### 7. Emoji Shortcodes
Emojis add personality: `:smile:` becomes :smile:, `:warning:` becomes :warning:. Use sparingly.
### 8. Horizontal Rules for Section Breaks
Three dashes create a clean separation:
markdown
---
### 9. Inline HTML for Custom Styling
Sometimes Markdown isn't enough. Drop in HTML for inline spans or divs:
html
Important
But keep it minimal.
### 10. Relative Links for Repo Navigation
In GitHub, use relative links to jump between docs:
markdown
Installation Guide
### 11. Escaping Special Characters
To display literal Markdown characters, use backslash:
markdown
*This is not italic*
\*This is not italic\*
### 12. Nested Lists with Indentation
Indent four spaces for nested lists:
markdown
- First item
- Subitem
- Another subitem
- Second item
1. First item
- Subitem
- Another subitem
2. Second item
### 13. Definition Lists (Some Processors)
Some Markdown flavors support definition lists:
markdown
Term
: Definition
Term
: Definition
(Check if your platform supports it.)
### 14. Automatic Links
Wrap URLs in angle brackets to make them clickable:
markdown
https://example.com
<https://example.com>
### 15. Comments for Documentation Notes
Use HTML comments to leave notes for yourself or other writers:
html
These aren't rendered in the output.
---
These tricks have saved me time and made my documentation much cleaner. Try them out in your next project!
-
This is the footnote. ↩
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.