Mastering Markdown: Tips, Tricks & Best Practices

Markdown is everywhere - GitHub, documentation sites, blogs, note-taking apps. Let’s explore how to use it effectively with practical examples.

Why Markdown?

Markdown offers the perfect balance:

• Simple syntax - Easy to read and write
• Portable - Plain text works everywhere
• Version control friendly - Git diffs are readable
• Fast - No formatting toolbar distractions

Basic Formatting

Text Emphasis

You can use italic, bold, or bold italic text. You can also use strikethrough.

*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~

Headings

Use # for headings - more symbols = smaller heading:

# H1 - Main Title
## H2 - Section
### H3 - Subsection
#### H4 - Minor Section

Lists

Unordered Lists

Shopping list:

• Apples
• Bananas
• Oranges
  • Valencia
  • Navel
• Grapes

- Item 1
- Item 2
  - Nested item
  - Another nested item

Ordered Lists

Recipe steps:

1. Preheat oven to 350°F
2. Mix dry ingredients
3. Add wet ingredients
4. Bake for 25 minutes

1. First step
2. Second step
3. Third step

Task Lists

Project checklist:

• Set up project structure
• Install dependencies
• Write tests
• Deploy to production

- [x] Completed task
- [ ] Pending task

Links and Images

Links

Check out my GitHub or visit SvelteKit docs.

You can also use reference-style links for cleaner text:

Visit GitHub and MDN for great resources.

[Link text](https://url.com)
[Reference link][ref]

[ref]: https://url.com

Images

Images work similarly to links with an exclamation mark:

![Alt text](/images/blog/example.jpg)

Example with caption:

Figure: Jagged mountain peak bathed in warm sunset light. (Photo credit: Unsplash)

Using HTML for more control:

<img src="/images/example.jpg" 
  alt="Jagged mountain peak bathed in warm sunset light. (Photo credit: Unsplash)" 
  width="400" style="border-radius: 8px; margin: 20px 0;" />

Best practices:

• Store images in /static/images/blog/ for organization
• Use descriptive alt text for accessibility
• Optimize image sizes (WebP format recommended)
• Consider using width/height attributes

Code

Inline Code

Use backticks for inline code like const x = 42 or npm install.

Code Blocks

For multi-line code, use triple backticks with a language identifier:

function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet('World'));

def calculate_sum(numbers):
    return sum(numbers)

result = calculate_sum([1, 2, 3, 4, 5])
print(f"Sum: {result}")

.button {
  background-color: #0066ff;
  color: white;
  padding: 12px 24px;
  border-radius: 8px;
  border: none;
  cursor: pointer;
}

Blockquotes

Use > for quotes:

“The best way to predict the future is to invent it.”

— Alan Kay

You can nest quotes:

This is a quote.

This is a nested quote.

And this is even deeper!

> Quote text
> 
> > Nested quote

Tables

Create tables with pipes and hyphens:

Feature	SvelteKit	Next.js	Remix
SSR	✅	✅	✅
SSG	✅	✅	❌
File routing	✅	✅	✅
Bundle size	Small	Medium	Medium

Align columns with colons:

Left aligned	Center aligned	Right aligned
Left	Center	Right
Text	Text	Text

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Horizontal Rules

Create dividers with three or more hyphens, asterisks, or underscores:

---

---

---

---
***
___

Advanced Tips

1. Escape Special Characters

Use backslash to escape Markdown syntax:

*This is not italic*

`This is not code`

2. HTML in Markdown

You can use HTML when Markdown isn’t enough:

3. Embedding Videos

YouTube embed:

<iframe 
  width="560" 
  height="315" 
  src="https://www.youtube.com/embed/VIDEO_ID" 
  frameborder="0" 
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
  allowfullscreen
  style="border-radius: 8px;">
</iframe>

Responsive video wrapper:

This maintains 16:9 aspect ratio and scales responsively!

4. Line Breaks

End a line with two spaces for a break
like this.

Or use a blank line for a new paragraph.

5. Keyboard Keys

Use <kbd> tags for keyboard shortcuts:

Press Ctrl + C to copy.

Writing Tips

Keep it simple - Markdown is meant to be readable as plain text.

Be consistent - Choose one style for lists, emphasis, etc.

Preview often - Check how your Markdown renders.

Use reference links - Keep long URLs out of reading flow.

Common Mistakes to Avoid

1. Forgetting blank lines - Separate paragraphs and elements
2. Inconsistent indentation - Use 2 or 4 spaces consistently
3. Not escaping special characters - Use \ when needed
4. Over-complicating - Markdown should be simple

Flavors of Markdown

Different platforms support different features:

• GitHub Flavored Markdown (GFM) - Tables, task lists, mentions
• CommonMark - Strict standard specification
• MDX - Markdown with JSX components
• Obsidian Markdown - Additional syntax for note-taking

Tools & Resources

• CommonMark Spec
• Markdown Guide
• GitHub Flavored Markdown Spec
• Dillinger - Online Markdown editor

Conclusion

Markdown is a powerful yet simple tool for writing. Whether you’re documenting code, writing blog posts, or taking notes, mastering these techniques will make you more efficient.

The beauty of Markdown is its simplicity - you can start with basics and gradually adopt advanced features as needed.

Happy writing! ✍️

---

Did I miss your favorite Markdown trick? Let me know!