I write every post on this blog in Markdown. It’s simple, clean, and lets me focus on writing without fussing over formatting buttons or HTML tags.

If you’ve never used Markdown before, it might look weird at first - you’re literally typing asterisks and hash marks into a text file. But after about 10 minutes, it becomes second nature. And once you get it, you’ll find yourself wishing every text box supported Markdown.

What is Markdown?

Markdown is a way to write formatted text using plain text. Instead of clicking “Bold” or selecting “Heading 1” from a dropdown, you just type **bold** or # Heading 1. When your Markdown file gets processed (by Hugo, Jekyll, GitHub, etc.), it converts these markers into proper HTML.

The beauty? You can write Markdown in any text editor - VS Code, Sublime, even Notepad. No special software needed.

Basic Formatting

Headings

Use hash marks for headings. More hashes = smaller heading.

1
2
3
4

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Emphasis

Bold text with double asterisks or underscores:

1
2

**This is bold**
__This is also bold__

Italic text with single asterisks or underscores:

1
2

*This is italic*
_This is also italic_

Bold and italic together:

1

***Bold and italic***

Lists

Unordered lists with dashes, asterisks, or plus signs:

1
2
3

- Item one
- Item two
- Item three

Ordered lists with numbers:

1
2
3

1. First item
2. Second item
3. Third item

Nested lists? Just indent:

1
2
3
4

- Main item
  - Sub item
  - Another sub item
- Another main item

Links and Images

Links use brackets and parentheses:

1
2

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")

Images are just like links with an exclamation mark in front:

1
2

![Alt text](/path/to/image.jpg)
![Image with title](/path/to/image.jpg "Image title")

Code

Inline code uses backticks:

1

Use the `hugo server` command to start the dev server.

Code blocks use triple backticks with optional language:

1
2
3
4

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

Blockquotes

Use the greater-than symbol:

1
2

> This is a blockquote.
> It can span multiple lines.

Horizontal Rules

Three or more dashes, asterisks, or underscores:

1

---

Tables

Tables use pipes and dashes:

1
2
3
4

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
| Data 4   | Data 5   | Data 6   |

Which renders as:

Align columns with colons:

1
2
3
4

| Left | Center | Right |
|:-----|:------:|------:|
| L1   | C1     | R1    |
| L2   | C2     | R2    |

What I Actually Use

I don’t use all of Markdown’s features in every post. Here’s what I use most:

1. Headings - Structure every article with ## and ###
2. Bold and italic - Emphasis where it matters
3. Code blocks - Command examples and code snippets
4. Lists - Breaking down steps or options
5. Links - Connecting to related articles or references

I rarely use blockquotes or tables unless the content really calls for it.

Hugo-Specific Features

Since this blog runs on Hugo, I also use:

Front Matter

Every post starts with YAML front matter:

1
2
3
4
5
6
7
8

---
title: "Your Post Title"
date: 2025-01-14T10:00:00-08:00
draft: false
tags: ["tag1", "tag2"]
categories: ["category"]
description: "Short description for SEO and previews"
---

Mermaid Diagrams

For diagrams, I use Mermaid with standard markdown code blocks. This is a feature I added to the blog more recently - you can create flowcharts, sequence diagrams, and more right in your Markdown files.

1
2
3
4
5

```mermaid
graph LR
    A[Write Markdown] --> B[Run Hugo]
    B --> C[Get HTML]
```

Which renders as:

I wrote a whole post about using Mermaid diagrams in Hugo if you want to see more examples and learn how to add it to your own Hugo site.

Tips for Writing

Use a Markdown-aware editor - VS Code, Typora, or iA Writer all have live preview. You can see formatting as you type.

Keep it simple - Don’t overthink formatting. Focus on writing. Add formatting after.

Preview before publishing - Run hugo server -D locally to see how your post looks before publishing.

Learn as you go - Start with headings, bold, and code blocks. Add more formatting techniques as you need them.

Common Mistakes

Extra spaces in lists - Markdown is picky about indentation. Use consistent spacing.

Forgetting the blank line - Always put a blank line before and after code blocks, lists, and headings. Makes Markdown parsers happy.

Not escaping special characters - If you need a literal asterisk or underscore, escape it with a backslash: \* or \_.

That’s It

Markdown isn’t complicated. It’s just a few symbols that make sense once you use them a few times. Write a couple of posts and you’ll have it down.

The reason I like Markdown is that my content is just text files. No proprietary formats, no databases, no vendor lock-in. Just .md files I can open in any editor, now or 10 years from now.

That’s powerful.