Markdown File (.md): What It Is, How It Works + Sample Files

The basics

What is a Markdown file?

A Markdown file is a text file written so that it reads well as it is, and can also be turned into a formatted page. John Gruber designed the syntax in 2004, with feedback from Aaron Swartz and others, together with a Perl script that converted it to HTML. The goal was text that can be published as it is, without looking as if it has been marked up.

Markdown is now the default way to write documentation for software: most projects on GitHub and GitLab have a README.md, and wikis, issue trackers, chat apps, note apps such as Obsidian, static site generators and AI assistants all use it. When an AI chat shows headings, bullet points and code blocks, the answer was usually written in Markdown.

It's plain text. Any editor opens it, version control can compare two versions line by line, and it will still be readable in fifty years.
It's not a layout format. Markdown describes structure (headings, lists, emphasis, links), not fonts, colours or page size. The app that renders it decides how it looks.
It's not one standard. The original description left many cases open, so tools added their own rules and extensions. The same file can render differently in two apps.

Anatomy

What's inside a Markdown file

Markdown is plain text with a few conventions, most of them borrowed from how people already formatted email. Here is a short README, part by part, with the HTML each piece becomes.

README.md

# Project Atlas

A **tiny** tool that turns *notes* into a website.
See the [guide](https://example.com/guide) or run `atlas --help`.

## Install

1. Download the latest release
2. Run the installer
   - On Linux, use the `.tar.gz` file

```bash
atlas build notes/
```

> **Note:** Atlas is a fictional example.

| Command | What it does   |
| ------- | -------------- |
| `build` | Makes the site |

![Atlas logo](images/logo.png)

---

Made by Ada Example.

1# Project Atlas
A heading
One # and a space make a level-1 heading (<h1>). ## is level 2, down to ######. Without the space, CommonMark treats it as ordinary text.
2**tiny** … *notes*
Bold and italic
Double asterisks give <strong>, single ones <em>. Underscores work too, but not in the middle of a word, so snake_case stays as it is.
3into a website. See the
A soft line break
A single line break inside a paragraph is joined into a space. Leave a blank line to start a new paragraph.
4[guide](https://example.com/guide)
A link
The text in square brackets, the address in round ones. A relative address like docs/setup.md links to another file in the same project.
5`atlas --help`
Inline code
Backticks mark code: shown in a monospace font, and nothing inside them is treated as Markdown.
61. Download the latest release
A numbered list
Becomes <ol>. Only the first number matters: 1. 1. 1. still renders as 1, 2, 3.
7 - On Linux, use …
A nested list
Indented so it lines up with the text of the item above (three spaces under 1. ). Too little indentation and it becomes a separate list.
8```bash … ```
A fenced code block
Three backticks open and close a block of code. The word after them names the language, which renderers use for syntax highlighting.
9> **Note:** …
A blockquote
Lines starting with > become <blockquote>. Other Markdown works inside.
10| Command | What it does |
A table
Pipes separate the columns and the row of dashes marks the header. Tables are a GitHub Flavored Markdown extension, not part of CommonMark.
11![Atlas logo](images/logo.png)
An image
Like a link with ! in front. The image is a separate file: the Markdown only points to it, and the bracketed text becomes the alt text.
12---
A horizontal rule
Three or more hyphens, asterisks or underscores on a line of their own draw a line (<hr>). Directly under a line of text, --- turns that text into a heading instead.

Under the hood

How Markdown becomes HTML

A Markdown renderer reads the file in two passes. First it splits the text into blocks (headings, paragraphs, lists, quotes, code blocks, tables) using line starts and blank lines. Then it parses the inline syntax inside each block: emphasis, links, code. The result is HTML, which a browser or app displays with its own styles.

You write	You get (HTML)
`# Title`	`<h1>Title</h1>`
`bold` or `__bold__`	`<strong>bold</strong>`
`italic` or `_italic_`	`<em>italic</em>`
`[text](https://…)`	`<a href="https://…">text</a>`
`![alt](pic.png)`	`<img src="pic.png" alt="alt">`
`- item` or `* item`	`<ul><li>item</li></ul>`
`1. item`	`<ol><li>item</li></ol>`
`> quote`	`<blockquote>`
code	`<code>code</code>`
Three backticks on their own lines	`<pre><code>`
`---` on its own line	`<hr>`

HTML is allowed inside Markdown

Most renderers pass raw HTML through untouched, so you can use tags Markdown has no syntax for, like <details> or <sup>. HTML comments () are hidden from the rendered page, which is how the sample files below carry their numbered notes. Sites that show other people's Markdown, like GitHub, strip anything dangerous.

Versions

Markdown flavours: CommonMark, GFM and the rest

Flavour	What it is	Adds
Original Markdown (2004)	Gruber's syntax description and `Markdown.pl`	The core: headings, emphasis, lists, links, images, code, quotes. Many edge cases undefined.
CommonMark	A precise specification with hundreds of examples, current version 0.31.2 (January 2024)	No new features; it pins down exactly how the core syntax is parsed.
GitHub Flavored Markdown (GFM)	CommonMark plus extensions, with its own spec	Tables, task lists `- [ ]`, strikethrough `~~text~~`, automatic links for bare URLs, and filtering of risky HTML tags.
GitHub extras	Features of github.com beyond the GFM spec	Footnotes, alerts (`> [!NOTE]`), maths with $…$ , Mermaid diagrams.
Pandoc Markdown	The flavour of the Pandoc converter	Footnotes, citations, definition lists, maths, metadata blocks, heading IDs.
MultiMarkdown, Markdown Extra	Early extended flavours	Tables, footnotes, definition lists, metadata.
MDX (`.mdx`)	Markdown mixed with JSX components	Interactive components in documentation sites built with React.

If a file has to look the same everywhere, stick to the core syntax that CommonMark defines; our sample-commonmark.md uses nothing else. Tables, task lists and strikethrough are safe on GitHub, GitLab and most modern apps. Anything else, check in the tool that will display it.

The registered media type, text/markdown, has an optional variant parameter for naming the flavour, for example text/markdown; charset=UTF-8; variant=CommonMark. Few servers send it.

Troubleshooting

Why doesn't my Markdown render the way I expected?

My line breaks disappeared. In a Markdown file, a single line break is a space. Leave a blank line for a new paragraph, or end the line with a backslash or two spaces for a line break. (GitHub comments and some chat apps do keep single breaks, which adds to the confusion.)
My table shows as pipes and dashes. The renderer doesn't support GFM tables, or the table lacks the | --- | row under the header, or there's no blank line before it.
My nested list isn't nested. The sub-items must line up with the text of the parent item: two spaces under - , three under 1. . Our sample-edge-cases.md shows both.
My numbers changed. Ordered lists are renumbered from the first number, so 1. 1. 1. shows 1, 2, 3, and a list starting at 3. counts on from 3.
A line starting with a year became a list. A number followed by a full stop at the start of a line can start a list. Escape it: 1984\.
Underscores vanished or turned text italic. Wrap code and file names in backticks, or escape the underscore as \_.
The image is broken. Image paths are relative to the Markdown file, and the image file must be uploaded alongside it. The same goes for links to other .md files.
The front matter shows at the top. A block between --- lines at the start of the file is YAML metadata for site generators. A plain Markdown renderer shows it as text with a rule and a heading.
My HTML disappeared. The app filters raw HTML for safety. GitHub, for example, filters out <script>, <style> and <iframe>.

Related formats

.md vs .markdown, and formats that look similar

.md and .markdown are the same format; both are registered for text/markdown. .md is far more common, and it's the one most tools and templates expect.

Extension	What it is
`.md`, `.markdown`	Markdown.
`.mdx`	Markdown with JSX components, for React-based documentation sites. Needs a build step.
`.Rmd`, `.qmd`	R Markdown and Quarto: Markdown with code chunks that run and insert their output.
`.txt`	Plain text with no markup rules. A Markdown file renamed to `.txt` is just shown as text.
`.rst`	reStructuredText, a different lightweight markup used by Python's documentation tools.
`.html`	What Markdown is usually converted into for the web.

How to

How to open, edit and convert a Markdown file

Read the source: any text editor (Notepad, TextEdit, nano) opens it. It's meant to be readable as it is.
See it rendered: in VS Code, open the file and press Ctrl+Shift+V (Cmd+Shift+V on a Mac) for a preview. Obsidian, Typora and iA Writer edit and display it together. On GitHub and GitLab, any .md file in a repository is shown formatted.
On a phone: note apps such as Obsidian, or a Markdown editor app; a plain file viewer shows the source.
Convert to HTML, Word or EPUB: with Pandoc, for example pandoc README.md -o README.docx or -o README.html. For PDF, Pandoc needs a PDF engine such as LaTeX installed, or you can convert to HTML and print that to PDF.
Convert Word to Markdown: pandoc report.docx -o report.md keeps headings, lists, links and tables, and extracts images with --extract-media.
Publish it as a web page: convert it to HTML, then put the HTML online.

Security

Is Markdown safe?

As text, a Markdown file is harmless. The risk appears when it's turned into HTML and shown to other people, because Markdown allows raw HTML and links:

Cross-site scripting. A <script> tag, an onerror attribute or a link to javascript:… in user-written Markdown can run code in a reader's browser if the renderer passes it through. Apps that display other people's Markdown must sanitise the HTML output, not just the Markdown input; the Markdown media type registration (RFC 7763) recommends the same.
Hidden content. HTML comments, reference links and long link targets don't show in the rendered view. Read the source before you trust a Markdown file, or paste one into a tool, such as an AI assistant, that will act on everything in it.

Free downloads

Sample Markdown files to download

Free sample Markdown files for testing renderers, editors, converters and uploads. Each one renders cleanly with Pandoc (CommonMark and GFM readers) and markdown-it.

sample-readme.md · 2.7 KBDownload Open

Loading…

What's inside sample-readme.md

The file is commented: open it in a text editor and each numbered HTML comment marks one of these parts. The comments disappear when it's rendered.

Comments 1 to 3: headings and paragraphs
A level-1 heading, inline formatting (bold, italic, code, strikethrough, a link), a soft line break that joins two lines, and a backslash that forces a hard break.
Comment 4: lists
A bulleted list with a nested item and a numbered list.
Comment 5: a task list
- [x] and - [ ] render as check boxes on GitHub and in other GFM renderers, and as plain text in strict CommonMark.
Comment 6: a fenced code block
Python code with the language named after the backticks, for syntax highlighting.
Comment 7: a quotation and an alert
An ordinary blockquote, then a > [!NOTE] alert that GitHub renders as a coloured note box and other renderers as a plain quote.
Comment 8: a table
A GFM table whose second row aligns the columns left, centre and right.
Comment 9: a missing image
Points to images/screenshot.png, which isn't included, so you can see how your renderer shows a broken image and its alt text.
Comments 10 to 12: footnote, escapes and HTML
A footnote and a horizontal rule, backslash escapes that stop * and # from being formatting, and a raw HTML <details> block with Markdown inside it.

All sample Markdown files

README-style sample with comments
sample-readme.md · 2.7 KB (2,717 bytes)
A typical README using core syntax plus GitHub extensions: lists, a task list, code, a table, an alert, a footnote and raw HTML, with numbered comments explaining each part.
- Checking a Markdown renderer or previewer
- Teaching Markdown syntax
Download Open
CommonMark core syntax only
sample-commonmark.md · 1.6 KB (1,638 bytes)
Uses only syntax defined by CommonMark 0.31.2: both heading styles, emphasis, hard breaks, inline, reference and autolinks, tight and loose lists, indented and fenced code, nested quotes, entities and escapes.
- Comparing renderers: the HTML should be identical
- Conformance checks
Download Open
Edge cases between flavours
sample-edge-cases.md · 2.9 KB (2,992 bytes)
Twelve cases that render differently in CommonMark, GFM and other flavours, each with a comment saying what to expect: line breaks, intraword underscores, tables, bare URLs, list indentation, maths, raw HTML and more.
- Finding out which flavour a tool uses
- Regression tests for Markdown parsers
Download Open
Markdown with YAML front matter
sample-front-matter.md · 1.1 KB (1,096 bytes)
Starts with a YAML block (title, author, date, tags) as used by Jekyll, Hugo, Eleventy and Obsidian.
- Testing static site generators and importers
- Checking how a renderer treats front matter
Download Open
100 KB Markdown file
sample-100kb.md · 100 KB (102,400 bytes)
Numbered sections with headings, formatting and lists, padded with an HTML comment to exactly 102,400 bytes.
- Upload and size-limit tests
- Renderer performance
Download Open
1 MB Markdown file
sample-1mb.md · 1 MB (1,048,576 bytes)
The same structure at exactly 1,048,576 bytes (1 MiB).
- Upload limits and timeouts
- Parser and editor performance
Download Open

Ways to test with them

Renderer comparison: render sample-commonmark.md in two tools. A CommonMark-compliant pair must produce the same HTML; any difference is a bug or a non-standard flavour.
Which flavour is this? Open sample-edge-cases.md in the app you're testing and compare each section with the comment above it.
Sanitising: check what happens to the <script> and inline style in section 11 of sample-edge-cases.md. In a public app, the script must not run.
Upload limits: the 100 KB and 1 MB files have exact sizes, so you can test a limit at the boundary.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Put it online

Have a Markdown file? Give it a link.

Drop a Markdown file on 99helpers and it gets its own web address, so you can share notes, a README or documentation without sending an attachment.

Put a Markdown file online

Questions

Markdown files, frequently asked

What is an .md file?

A Markdown file: plain text that uses symbols such as # for headings and ** for bold. Apps like GitHub, VS Code and Obsidian display it as formatted text.

How do I open a Markdown file?

Any text editor opens it as text. To see it formatted, use VS Code's preview (Ctrl+Shift+V), a Markdown app such as Obsidian or Typora, or upload it to GitHub.

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

None. They're two extensions for the same format. .md is the usual choice.

Is Markdown the same as HTML?

No. Markdown is a simpler syntax that's converted into HTML. You can include HTML inside Markdown, but not the other way round.

What is GitHub Flavored Markdown?

CommonMark plus extensions GitHub added: tables, task lists, strikethrough, automatic links and filtering of unsafe HTML. GitHub.com adds further features such as footnotes and alerts.

How do I convert Markdown to Word or PDF?

Use Pandoc: pandoc notes.md -o notes.docx. For PDF, Pandoc needs a PDF engine such as LaTeX, or convert to HTML and print it to PDF from a browser.

Why don't my line breaks show up?

Markdown joins lines within a paragraph. Leave a blank line to start a new paragraph, or end a line with a backslash or two spaces to force a line break.

Who invented Markdown?

John Gruber, in 2004, with feedback from Aaron Swartz and others. Version 1.0.1 of his Markdown.pl converter came out in December 2004.

Related formats

Other file types explained

HTML file TXT file DOCX file All file types

Keep going

Host a Markdown file

Put a Markdown file online at its own address.

Share a Markdown file

Send a Markdown file as a link instead of an attachment.

Host a website

Publish Markdown converted to HTML as a site.

Sources

Last reviewed 27 October 2026.