LOVEMarkdown

What is Markdown? A Complete Beginner's Guide

Markdown is a lightweight plain-text formatting syntax created by John Gruber in 2004. It lets you write formatted documents using simple, readable symbols — like # for headings and **bold** for bold text — without touching complex markup like HTML.

Today, Markdown is used by millions of developers, writers, students, and bloggers worldwide. It's the default formatting language on GitHub, Reddit, Stack Overflow, Discord, Slack, and many other platforms.

What is a .md File?

A .md file is a plain-text file that contains Markdown syntax. The .md extension stands for "Markdown." You might also see .markdown as an extension, though .md is far more common.

Since .md files are plain text, you can open them with any text editor — Notepad, TextEdit, VS Code, or even a web browser. The formatting only appears when the file is rendered by a Markdown-aware application.

Why Was Markdown Created?

John Gruber designed Markdown with one goal: be readable as plain text. Unlike HTML or LaTeX, a Markdown document looks perfectly readable even without being rendered. Compare:

## HTML version
<h2>My Title</h2>
<p>This is a <strong>bold</strong> word.</p>

## Markdown version
## My Title
This is a **bold** word.

Both produce the same output, but the Markdown version is immediately readable in its source form.

Who Uses Markdown?

  • Developers — README files, documentation, code comments
  • Technical writers — API docs, user guides, wikis
  • Bloggers — Blog posts on platforms like Ghost, WordPress, Jekyll
  • Students — Notes, papers, presentations
  • Data scientists — Jupyter notebooks, R Markdown reports
  • Project managers — GitHub/GitLab issues, Confluence pages

Where is Markdown Used?

Markdown is everywhere. Here are some of the most popular platforms that support it:

  • GitHub / GitLab — README files, issues, pull requests, wikis
  • Stack Overflow — Questions and answers
  • Reddit — Comment formatting
  • Discord / Slack — Message formatting
  • Notion / Obsidian / Bear — Note-taking apps
  • Ghost / Jekyll / Hugo — Static site generators and blogs
  • VS Code / Atom — Documentation and preview

Basic Markdown Syntax

Here are the most commonly used Markdown elements:

Headings

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

Bold & Italic

**bold text**
*italic text*
***bold and italic***

Lists

- Unordered item
- Another item

1. Ordered item
2. Another item

Links & Images

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

Code

Inline `code` with backticks.

```javascript
// Code block with syntax highlighting
console.log("Hello, Markdown!");
```

Blockquotes & Tables

> This is a blockquote.

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

For a complete reference, see our Markdown Cheat Sheet.

Markdown Flavors

The original Markdown has several extended versions, called "flavors":

  • CommonMark — A standardized, unambiguous specification of Markdown
  • GitHub Flavored Markdown (GFM) — Adds tables, task lists, strikethrough, and syntax highlighting
  • Markdown Extra — Adds footnotes, definition lists, and abbreviations
  • R Markdown — Extends Markdown for data science with R code execution
  • MultiMarkdown — Adds tables, footnotes, and metadata support

Most modern tools support GFM or CommonMark, which cover 95% of everyday use cases.

How to Start Writing Markdown

  1. Open any text editor — VS Code, Notepad, TextEdit, or even a web app
  2. Write your content using Markdown syntax
  3. Save as .md — Your file is a valid Markdown document
  4. Preview or convert — Use a Markdown viewer to see the rendered output, or convert to PDF/HTML/Word

Converting Markdown to Other Formats

One of Markdown's biggest strengths is how easily it converts to other formats. You can turn a single Markdown file into:

Frequently Asked Questions

Is Markdown the same as HTML?

No. Markdown is much simpler than HTML. Markdown uses **bold** while HTML uses <strong>bold</strong>. Markdown is designed for readability; HTML is designed for web structure. You can embed HTML inside Markdown if needed.

Can I use Markdown for professional documents?

Yes. Markdown is widely used for professional documentation, technical writing, and publishing. Many companies (GitHub, Stripe, Twilio) use Markdown for their official docs. You can convert Markdown to PDF or Word for polished final documents.

Is Markdown free?

Markdown is completely free and open-source. The syntax is free to use, and there are hundreds of free editors and tools available.

What's the difference between .md and .txt?

Both are plain text files. The difference is that .md files use Markdown formatting syntax. A .txt file has no formatting. If you open a .md file in a Markdown-aware editor, you'll see formatted text; in a plain text editor, you'll see the raw syntax.