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.

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.

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

• [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.

Enter fullscreen mode Exit fullscreen mode

Click to expand

This is hidden until you click.

### 4. Tables with Alignment

Align columns using colons in the separator row:

Enter fullscreen mode Exit fullscreen mode

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:

Enter fullscreen mode Exit fullscreen mode

markdown

def hello():
    print("Hello, world!")

Enter fullscreen mode Exit fullscreen mode

### 6. Footnotes for References

Some Markdown processors support footnotes (like Pandoc or GitHub? Actually, GitHub doesn't. But if your platform does, use them):

Enter fullscreen mode Exit fullscreen mode

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:

Enter fullscreen mode Exit fullscreen mode

markdown

---

### 9. Inline HTML for Custom Styling

Sometimes Markdown isn't enough. Drop in HTML for inline spans or divs:

Enter fullscreen mode Exit fullscreen mode

html
Important

But keep it minimal.

### 10. Relative Links for Repo Navigation

In GitHub, use relative links to jump between docs:

Enter fullscreen mode Exit fullscreen mode

markdown
Installation Guide

### 11. Escaping Special Characters

To display literal Markdown characters, use backslash:

Enter fullscreen mode Exit fullscreen mode

markdown
*This is not italic*

\*This is not italic\*

### 12. Nested Lists with Indentation

Indent four spaces for nested lists:

Enter fullscreen mode Exit fullscreen mode

markdown

1. First item
   • Subitem
   • Another subitem
2. Second item

1. First item
    - Subitem
    - Another subitem
2. Second item

### 13. Definition Lists (Some Processors)

Some Markdown flavors support definition lists:

Enter fullscreen mode Exit fullscreen mode

markdown
Term
: Definition

Term
: Definition

(Check if your platform supports it.)

### 14. Automatic Links

Wrap URLs in angle brackets to make them clickable:

Enter fullscreen mode Exit fullscreen mode

markdown
https://example.com

<https://example.com>

### 15. Comments for Documentation Notes

Use HTML comments to leave notes for yourself or other writers:

Enter fullscreen mode Exit fullscreen mode

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!

Enter fullscreen mode Exit fullscreen mode

1. This is the footnote. ↩