Mastering Markdown

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Its goal is to allow people to write using plain text formatting that can be converted to structurally valid HTML. The syntax is designed to be readable as-is, without looking like it has been marked up with tags.

Today, Markdown is everywhere — GitHub readmes, documentation sites, note-taking apps, forums, and even email clients support it.

Basic Syntax

Headings

Use hash symbols for headings:

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

Emphasis

*italic* or _italic_
**bold** or __bold__
***bold italic***

Lists

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Another item

Links and Images

[Link text](https://example.com)
![Alt text](image.jpg)

Code

Inline code uses backticks: code

Code blocks use triple backticks with an optional language identifier:

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

Blockquotes

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

Horizontal Rules

---
***
___

Extended Syntax

Most Markdown renderers support additional syntax beyond the basics.

Tables

| Name     | Language | Year |
|----------|----------|------|
| Hugo     | Go       | 2013 |
| Jekyll   | Ruby     | 2008 |
| Eleventy | JS       | 2018 |

Task Lists

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Footnotes

This has a footnote[^1].

[^1]: Here is the footnote content.

Definition Lists

Term
: Definition of the term

Tips for Better Markdown

Use ATX Headings

ATX-style headings (# Heading) are preferred over Setext-style (underlined) because they are more explicit and work better with outline-based editors.

Keep Line Length Reasonable

While Markdown treats single newlines as spaces, keeping lines under 80 characters makes the raw text more readable and easier to review in version control.

Use Fenced Code Blocks

Always use fenced code blocks (triple backticks) with a language identifier instead of indented code blocks. The language hint enables syntax highlighting in most renderers.

Be Consistent with Emphasis

Pick either asterisks or underscores for emphasis and stick with it throughout your document. Asterisks are more common in practice.

Add Blank Lines

Place blank lines before and after headings, lists, and code blocks. This improves readability of the raw text and prevents rendering issues in some parsers.

Markdown in Practice

Documentation

Markdown is the de facto standard for technical documentation. Tools like MkDocs, Docusaurus, and GitBook all use Markdown as their primary authoring format.

README Files

Every well-maintained project on GitHub starts with a Markdown README. A good README includes a project description, installation instructions, usage examples, and contributing guidelines.

Note Taking

Apps like Obsidian, Typora, and VS Code’s built-in preview make Markdown a powerful format for personal note-taking. The plain text format ensures your notes remain readable and searchable for years.

Email

Some email clients and newsletter tools support Markdown, letting you write beautifully formatted emails without touching a WYSIWYG editor.

Tools

• Pandoc — Universal document converter, supports Markdown to almost anything
• Prettier — Code formatter that handles Markdown
• markdownlint — Linting for consistent Markdown style
• ** grip** — Preview Markdown files locally using GitHub’s styling

Conclusion

Markdown strikes the perfect balance between simplicity and capability. It is easy enough for a quick note yet powerful enough for a complete book. Mastering Markdown is a small investment that pays dividends across countless tools and platforms.