DEV Community

Binary Journal
Binary Journal

Posted on

Markdown Tricks for Cleaner Docs

#markdown #webdev #tutorial #writing

Markdown Tricks for Cleaner Docs

I write a lot of documentation, and I've picked up some Markdown tricks that make my docs cleaner and more maintainable. Here are my top ones.

1. Use Definition Lists

Instead of bullet points for key-value pairs, use a definition list. It's cleaner and more semantic.

Term 1
: Definition 1

Term 2
: Definition 2
Enter fullscreen mode Exit fullscreen mode

Renders as:

Term 1
: Definition 1

Term 2
: Definition 2

This is great for API parameters or configuration options.

2. Task Lists for Checklists

Task lists are perfect for step-by-step guides or progress tracking.

- [x] Step 1: Install dependencies
- [ ] Step 2: Configure settings
- [ ] Step 3: Run the app
Enter fullscreen mode Exit fullscreen mode

Renders as:

  • [x] Step 1: Install dependencies
  • [ ] Step 2: Configure settings
  • [ ] Step 3: Run the app

3. Collapsible Sections

Long docs can be overwhelming. Use collapsible sections to hide details.

<details>
<summary>Click to expand</summary>

Hidden content here.

</details>
Enter fullscreen mode Exit fullscreen mode

Renders as a clickable expand/collapse block.

4. Tables with Alignment

Tables are great for structured data. Align columns for readability.

| Left | Center | Right |
| :--- | :----: | ----: |
| 1    |   2    |     3 |
| 4    |   5    |     6 |
Enter fullscreen mode Exit fullscreen mode

Renders as:

Left Center Right
1 2 3
4 5 6

5. Footnotes

Footnotes keep the main text flowing while providing additional context.

Here is a statement that needs explanation[^1].

[^1]: This is the footnote content.
Enter fullscreen mode Exit fullscreen mode

Renders with a superscript link and the footnote at the bottom.

6. Strikethrough for Deprecation

When something is deprecated, use strikethrough to indicate it's outdated but keep the text visible.

~~This feature is deprecated. Use the new API instead.~~
Enter fullscreen mode Exit fullscreen mode

Renders as: This feature is deprecated. Use the new API instead.

7. Inline HTML for Extra Control

Sometimes Markdown isn't enough. Use inline HTML for custom styling or structure.

<span style="color:red;">Warning:</span> This is important.

<div align="center">
  Centered content
</div>
Enter fullscreen mode Exit fullscreen mode

This works on most platforms, including GitHub and Dev.to.

8. Escape Characters

If you need to display a Markdown character literally, escape it with a backslash.

\*This is not italic\*
Enter fullscreen mode Exit fullscreen mode

Renders as: *This is not italic*

9. Code Blocks with Titles

Add a title to your code blocks for context.

Enter fullscreen mode Exit fullscreen mode


javascript:example.js
console.log('Hello');

Enter fullscreen mode Exit fullscreen mode


markdown

On some platforms, this renders with a tab showing the filename.

10. Emoji Shortcodes

Emojis add personality. Use shortcodes like :smile: or :warning:.

:smile: This is a friendly note.
Enter fullscreen mode Exit fullscreen mode

Renders as: 😄 This is a friendly note.

These tricks have made my documentation cleaner and more user-friendly. Give them a try in your next project.

Top comments (0)