A .md file is a plain-text file that uses Markdown syntax for lightweight formatting — headings written as # Heading, bold as **bold**, links as [text](url), and so on. Because it is plain text, you can open and edit it in any text editor. Renderers like GitHub, Obsidian, VS Code, and most static-site generators turn that source into formatted HTML.

Why use markdown instead of Word or Google Docs?

Three reasons. First, it is plain text, so it diffs cleanly in Git, survives copy-paste, and never gets locked in a proprietary binary. Second, the syntax is small enough to write fluently without taking your hands off the keyboard. Third, every modern note-taking tool, documentation site, and LLM input speaks Markdown — there is no conversion friction.

What is the difference between Markdown and GFM?

Markdown is the original 2004 spec by John Gruber. GFM — GitHub-Flavored Markdown — is GitHub's superset that added tables, fenced code blocks with language hints, task lists ([ ]/[x]), strikethrough, and autolinks. CommonMark is a separate, more rigorous spec that GFM builds on top of. In practice, when people say 'Markdown' today they usually mean GFM, because GitHub, Reddit, Discord, and most documentation tools follow that dialect.

Can I write markdown in any text editor?

Yes. A .md file is just text, so Notepad, TextEdit, vim, Notepad++, or any code editor will do. Editors built around Markdown — VS Code, Obsidian, Typora, iA Writer — add live preview and syntax highlighting, but they are not required. The syntax was designed to be readable in raw form.

How do I view a rendered markdown file?

Drop the .md file into VS Code and press Ctrl/Cmd+Shift+V for a preview. Or open it in Obsidian, a Markdown-aware browser extension, or push it to a GitHub repo and view the rendered version in the file browser. You can also convert it to HTML or PDF if you need to share the rendered result outside a Markdown editor.

Does ChatGPT or Claude output markdown by default?

Yes — both ChatGPT and Claude format responses in Markdown by default. Headings, bold, lists, code blocks, and tables in their replies are real Markdown. That is why feeding clean Markdown back into an LLM works well: the model already thinks in this format, so there is no parsing tax.

Is markdown the same as readme.md?

A README.md is just a Markdown file named README, conventionally placed at the root of a project. GitHub, GitLab, and similar platforms render that specific file on the repo's landing page. There is nothing magic about the .md extension here — it is the same Markdown syntax used everywhere else.

Can I include HTML inside markdown?

In most flavors, yes. Inline HTML tags pass through untouched, which is useful for things Markdown does not natively support — collapsible sections with , custom attributes, embedded video. Some renderers sandbox or strip HTML for security (GitHub allows a small allowlist), so do not rely on arbitrary HTML when the output will be rendered by a third party.

What does GFM stand for?

GFM stands for GitHub-Flavored Markdown. It is the dialect of Markdown that GitHub renders, with extensions for tables, task lists, strikethrough, fenced code blocks, autolinked URLs, and emoji shortcodes. mdstill produces GFM-compatible output by default.

Where is markdown used?

Everywhere developer-adjacent: GitHub and GitLab READMEs and issues, Reddit posts, Discord messages, Stack Overflow answers, Obsidian and Notion notes, Jekyll/Hugo/Astro static sites, Jupyter notebooks, Docusaurus docs, MkDocs, Hashnode and Dev.to blog posts, and LLM prompts. It has quietly become the default plain-text format of the web.

The Markdown Guide

syntax · cheat sheet · .md file format

Markdown is a plain-text format for writing formatted documents. You type a few unobtrusive characters — # for a heading, **bold**, - item for a list — and a renderer turns the result into headings, bold text, and lists. This guide covers the full markdown syntax, the rules, an at-a-glance cheat sheet, and what makes a .md file different from HTML or Word.

What is Markdown?

Markdown is a lightweight markup language created by John Gruber and Aaron Swartz in 2004. The idea was to design a plain-text format that reads naturally as-is — so the source of a document already looks like a document — and that converts cleanly to HTML. A file written in this format is saved with the .md extension (sometimes .markdown), and any text editor can open it.

The original Markdown spec was deliberately small. Over time the ecosystem fragmented: CommonMark formalised the parsing rules, and GFM (GitHub-Flavored Markdown) added the parts most people now consider standard — tables, fenced code blocks with language hints, task lists, strikethrough, and autolinks. When someone says "Markdown" today, they usually mean GFM, because GitHub, Reddit, Discord, Obsidian, and most documentation tools render that dialect. mdstill outputs GFM-compatible Markdown by default.

You will encounter md files in README files on GitHub, notes in Obsidian, static-site sources (Jekyll, Hugo, Astro, Docusaurus), Jupyter notebook cells, and as the native output format of LLMs like ChatGPT and Claude. If you already have a .md file and just want to view it rendered, see how to open a .md file.

Headings

Headings start with one to six # characters, followed by a space and the heading text. One # is an H1, two is an H2, all the way to six for H6. Put a blank line before each heading to avoid the next line being read as part of a paragraph.

Markdown

# H1 — page title
## H2 — section
### H3 — subsection
#### H4
##### H5
###### H6

Rendered

H1 — page title

H2 — section

H3 — subsection

H4

H5

H6

Markdown rules: pick one H1 per document (treat it as the page title) and use H2/H3 for the structure underneath. Skipping levels — H2 directly to H4 — works syntactically but hurts accessibility and document outlines.

Emphasis: bold, italic, strikethrough

Wrap text in delimiters: one asterisk or underscore for italic, two for bold, three for both, and two tildes (a GFM extension) for strikethrough.

Markdown

*italic* or _italic_
**bold** or __bold__
***bold italic***
~~strikethrough~~ (GFM)

Rendered

italic or italic
bold or bold
bold italic
~~strikethrough~~ (GFM)

A common gotcha: snake_case_words can accidentally turn into italic. Most modern parsers (CommonMark, GFM) ignore underscores inside words, but if a renderer is picky, use asterisks for emphasis.

Lists in Markdown

A list in markdown is either unordered (each item starts with -, *, or +) or ordered (each item starts with a number followed by .). Indent by two or four spaces to nest.

Markdown

- Apples
- Pears
  - Bartlett
  - Anjou
- Plums

1. Wake up
2. Write markdown
3. Push to GitHub

Rendered

Apples
Pears
- Bartlett
- Anjou
Plums

Wake up
Write markdown
Push to GitHub

The actual numbers in an ordered list do not matter — every parser renumbers them. You can write 1. 1. 1. and the renderer will output 1, 2, 3. That makes it easy to reorder items without renumbering.

Links and images

A link is [text](url). An image is the same syntax with a leading !. Autolinks wrap a bare URL in angle brackets, and reference-style links let you put the URL once at the bottom of the document and reuse a label.

Markdown

[mdstill homepage](https://mdstill.com)

![Logo alt text](/logo.png)

<https://github.com>

[reference link][gh]

[gh]: https://github.com "GitHub"

Rendered

mdstill homepage

[Logo alt text] (image)

https://github.com

reference link

Markdown code block

For inline code, wrap text in single backticks. A markdown code block is either four-space indented or, more commonly, fenced with three backticks. After the opening fence you can add a language hint — ```python — and renderers that support syntax highlighting will use it.

Markdown

Inline `console.log('hi')` works.

```python
def greet(name):
    print(f"Hello, {name}")
```

Rendered

Inline console.log('hi') works.

def greet(name):
    print(f"Hello, {name}")

Use fenced code blocks (three backticks) rather than indented ones — they preserve language hints, they round-trip through more tools, and they do not get confused with adjacent lists.

Blockquotes

Prefix a line with > for a blockquote. Stack them for nested quotes. A blockquote can contain other Markdown — paragraphs, lists, even code.

Markdown

> Writing is thinking.
>
> > Reading is thinking with someone else's brain.

> A quote with a **bold** word and a list:
> - first
> - second

Rendered

Writing is thinking.
Reading is thinking with someone else's brain.

A quote with a bold word and a list:
first
second

Markdown table syntax

Markdown table syntax is a GFM extension: pipes | separate columns and a row of dashes underneath the header sets alignment. Add a colon to the dashes to align left (:--), right (--:), or centre (:--:).

Markdown

| Format | Extension | Binary? |
| :----- | :-------: | ------: |
| Markdown | .md   |      No |
| Word     | .docx |     Yes |
| PDF      | .pdf  |     Yes |

Rendered

Format	Extension	Binary?
Markdown	.md	No
Word	.docx	Yes
PDF	.pdf	Yes

Outer pipes are optional but make the source easier to read. The separator row must contain at least three dashes per column. CommonMark itself does not specify tables — they are GFM.

Task lists and GFM extras

GitHub-Flavored Markdown adds a handful of useful features on top of CommonMark: task lists (checkboxes), strikethrough, autolinked URLs, and tables (covered above). Task lists are list items where the marker is replaced with - [ ] for an unchecked box or - [x] for a checked one.

Markdown

- [x] Write the guide
- [x] Add a cheat sheet
- [ ] Get hit by Google's next core update
- [ ] Profit

Rendered

Write the guide
Add a cheat sheet
Get hit by Google's next core update
Profit

Horizontal rules

Three or more dashes, asterisks, or underscores on a line by themselves render as a horizontal rule. Surround them with blank lines so they are not mistaken for a heading underline.

Markdown

Above the line.

---

Below the line.

Rendered

Above the line.

Below the line.

Escaping characters

To use a Markdown control character literally — when you want a real asterisk, not italics — precede it with a backslash. The escapable characters are roughly the ones the syntax uses: \ ` * _ {} [] () # + - . ! |.

Markdown

\*not italic\*
1\. Not a list item.
Use \` for a literal backtick.

Rendered

*not italic*

1. Not a list item.

Use ` for a literal backtick.

Markdown vs HTML

Markdown compiles to HTML. The two are not competitors — they are layers. Markdown is what you write; HTML is what the renderer emits. The reason Markdown exists is that HTML is verbose to type: <strong>bold</strong> vs **bold**. For 80% of formatting needs, Markdown is faster, easier to read in raw form, and easier to diff in version control.

Use Markdown when you are writing prose — docs, READMEs, notes, blog posts, LLM prompts. Use HTML directly when you need something Markdown does not cover — semantic elements like <details>, custom id / class attributes, embedded media. Most Markdown parsers let you mix HTML inline, so you rarely have to choose.

If you have an HTML document you want to convert in the other direction, see HTML to Markdown.

Markdown cheat sheet

Every common element in one table — markdown syntax on the left, rendered result on the right. Bookmark this section as your quick-reference markdown cheat sheet.

Element	Markdown	Rendered
H1	`# Heading`	Heading
H2	`## Heading`	Heading
H3	`### Heading`	Heading
Bold	`bold`	bold
Italic	`italic`	italic
Bold italic	`*both*`	*both*
Strikethrough	`~~gone~~`	~~gone~~
Inline code	`code()`	`code()`
Code block	``` code ```	`fenced block`
Link	`[text](url)`	text
Image	`![alt](url)`	(renders an image)
Autolink	`<https://x.com>`	https://x.com
Unordered list	`- item`	• item
Ordered list	`1. item`	1. item
Task list	`- [x] done`	done
Blockquote	`> quoted`	quoted
Horizontal rule	`---`
Table	`\| a \| b \| \| - \| - \|`	(GFM pipe table)
Escape	`\literal\`	literal

Markdown flavors: CommonMark, GFM, MultiMarkdown

The original Markdown spec from 2004 was ambiguous in enough edge cases that every parser made its own decisions. Three main dialects emerged.

CommonMark — a rigorous re-specification published in 2014 that pins down the parser behaviour for every corner case. It is the foundation modern parsers build on.
GFM (GitHub-Flavored Markdown) — CommonMark plus tables, task lists, strikethrough, autolinks, and disallowed raw HTML. This is the dialect rendered by GitHub, Reddit, Discord, and most documentation tools, and it is what people usually mean when they say "Markdown".
MultiMarkdown — a separate extension set with footnotes, citations, math, and metadata blocks. Niche but useful for academic writing.

mdstill produces GFM-compatible Markdown by default — tables, fenced code blocks with language hints, task lists where present in the source. That is the dialect every modern reader expects.

What can you do with a .md file?

Once you have a .md file, you can view it rendered, edit it in any text editor, or convert it to other formats for sharing. mdstill handles both directions:

The Markdown Guide

What is Markdown?

Headings

H1 — page title

H2 — section

H3 — subsection

H4

H5

H6

Emphasis: bold, italic, strikethrough

Lists in Markdown

Links and images

Markdown code block

Blockquotes

Markdown table syntax

Task lists and GFM extras

Horizontal rules

Escaping characters

Markdown vs HTML

Markdown cheat sheet

Markdown flavors: CommonMark, GFM, MultiMarkdown

What can you do with a .md file?

Frequently asked questions

Related