What Is Markdown? A Beginner's Guide

Published on Wed Feb 25 2026 10:00:00 GMT-0500 (Eastern Standard Time) by MD HD Team

Markdown is everywhere. It’s how developers write documentation on GitHub. It’s how writers draft blog posts. It’s how students take notes. It’s the format behind Obsidian, Notion exports, Jekyll blogs, and millions of README files. And yet, if you’ve never used it, the name alone tells you nothing about what it is.

This guide explains markdown from the beginning — what it is, where it came from, why it matters, and how to start using it today.

Markdown in One Sentence

Markdown is a way to format text using simple symbols that are easy to read even before they’re rendered.

That’s it. When you write **bold** in markdown, it becomes bold when rendered. When you write # Heading, it becomes a large heading. The syntax is designed so that even the raw, unrendered text is readable — unlike HTML, where <strong>bold</strong> is cluttered with tags.

A Brief History

Markdown was created in 2004 by John Gruber, with help from Aaron Swartz. Gruber’s goal was simple: create a format that could be converted to HTML but was pleasant to read and write as plain text.

The original Markdown spec was intentionally minimal. Over the years, different implementations added their own features — tables, task lists, footnotes — which led to fragmentation. In 2014, a group of developers created CommonMark, a standardized specification that resolved ambiguities in the original syntax. Today, most markdown tools follow CommonMark, often with extensions like GitHub Flavored Markdown (GFM) that add tables, strikethrough, and task lists.

Why Markdown Matters

Markdown has grown far beyond Gruber’s original blog-writing use case. Here’s why it’s become the default for so many workflows:

It’s Plain Text

Markdown files are plain text with a .md extension. They work in every text editor on every operating system. There’s no proprietary format, no compatibility issues, and no software lock-in. A markdown file you write today will be readable in 50 years.

It’s Portable

Move your markdown files between Dropbox, Google Drive, iCloud, or a USB stick. Open them in VS Code, Obsidian, iA Writer, or a basic text editor. The files don’t belong to any app — they belong to you.

It’s Version-Control Friendly

Because markdown is plain text, it works perfectly with Git and other version control systems. You can track changes, see diffs, merge edits, and collaborate through pull requests. This is why virtually all software documentation is written in markdown.

It’s Fast

No mouse-driven formatting. No hunting through ribbon menus for the right button. In markdown, you type ## for a heading, ** for bold, and - for a list item. Your hands never leave the keyboard.

It Converts to Anything

Markdown can be converted to HTML, PDF, DOCX, EPUB, slides, and more. Tools like Pandoc make this trivial. Write once in markdown, publish everywhere.

Basic Markdown Syntax

Here are the building blocks. If you learn nothing else, these six elements cover 90% of what most people need.

Headings

Use # symbols to create headings. More # symbols mean smaller headings:

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

Emphasis

Wrap text in asterisks or underscores:

*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic***
~~strikethrough~~

Lists

Create unordered lists with -, *, or +. Create ordered lists with numbers:

- First item
- Second item
  - Nested item
  - Another nested item
- Third item

1. Step one
2. Step two
3. Step three

Links and Images

Links use [text](url) syntax. Images are the same with a ! prefix:

[Visit MD HD](https://mdhd.app)
![Alt text for image](https://example.com/image.png)

Code

Use backticks for inline code and triple backticks for code blocks:

Use the `print()` function to output text.

For multi-line code, use triple backticks with an optional language name:

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

Blockquotes

Prefix lines with >:

> This is a blockquote.
> It can span multiple lines.
>
> And have multiple paragraphs.

Extended Syntax

Beyond the basics, most modern markdown tools support these extensions:

Tables

| Name    | Role       | Department |
|---------|------------|------------|
| Alice   | Engineer   | Backend    |
| Bob     | Designer   | Product    |
| Charlie | Manager    | Operations |

Task Lists

- [x] Write the draft
- [x] Review with team
- [ ] Publish to blog

Footnotes

This claim needs a source[^1].

[^1]: Here is the source for the claim.

Horizontal Rules

Three or more dashes, asterisks, or underscores:

---

Where Markdown Is Used

The list of platforms and tools that use markdown is enormous, but here are the most notable:

GitHub/GitLab: README files, issues, pull requests, wikis
Obsidian: Personal knowledge management
Notion: Import/export (though it uses its own format internally)
Jekyll, Hugo, Astro: Static site generators that turn markdown into websites
Jupyter Notebooks: Documentation cells
Slack and Discord: Message formatting
Reddit: Post and comment formatting
Stack Overflow: Questions and answers
R Markdown: Statistical reports and papers

How to Read Markdown Files

Writing markdown is straightforward — any text editor works. But reading markdown files with proper formatting, especially on mobile, requires a tool that renders the syntax into visual formatting.

MD HD is designed specifically for this. It connects to your cloud storage, discovers your markdown files, and renders them with PDF-quality formatting on your phone. If you have markdown files scattered across Dropbox or Google Drive, MD HD turns your phone into a beautiful markdown reader.

For a complete reference of every markdown syntax element, see our Markdown Syntax Cheat Sheet.

Getting Started with Markdown

Here’s the fastest way to start:

Open any text editor — VS Code, Sublime Text, Notepad, TextEdit, or even a notes app
Create a new file and save it with a .md extension
Write using the syntax above — start with headings and lists, then add emphasis and links
Preview your work — most code editors have a built-in markdown preview (in VS Code, press Ctrl+Shift+V or Cmd+Shift+V)
Save to cloud storage — put your files in Dropbox or Google Drive, and you can read them anywhere with MD HD

Markdown’s beauty is that you don’t need special software to start. You already have everything you need. The syntax takes about 15 minutes to learn, and after a week of use, it becomes second nature.

Markdown Is for Everyone

Markdown started as a tool for tech bloggers. Today it’s used by developers, writers, students, researchers, project managers, and anyone who values portable, future-proof writing. It’s one of those rare tools that gets simpler the more you use it.

Whether you’re writing your first README or organizing a decade of notes, markdown is a foundation you can build on forever.

Written by MD HD Team

← Back to blog