What Is a Markdown (.md) File?

You downloaded a project, double-clicked README.md, and Windows shrugged — or Notepad opened a wall of text full of hash marks and asterisks. Nothing is broken. You are looking at a Markdown file, and the symbols you are seeing are the formatting.

A .md file is a plain text file that uses a handful of punctuation marks to mean “this is a heading,” “this is bold,” “this is a link.” Software that understands Markdown turns those marks into formatted text. Software that does not simply shows you the marks.

Below: what a .md file is, five ways to open one, the full syntax reference, and the gotcha that trips up nearly everyone. To read your file right now, drop it into the free Markdown Viewer — it renders in your browser and never uploads the file.

A Markdown file is a text file, full stop. Open it in any editor and you see readable words. What makes it Markdown is a lightweight convention for marking those words up:

# Project Title

A short description with **bold text** and a [link](https://example.com).

- First item
- Second item

Feed that to any Markdown renderer and you get a real H1 heading, a paragraph with bold text and a clickable link, and a bulleted list. The source stays readable either way — that is the design goal. John Gruber, who created Markdown in 2004 with Aaron Swartz, wrote that it should be “publishable as-is, as plain text, without looking like it’s been marked up.”

Two extensions appear in the wild, and they mean the same thing:

• .md — by far the most common, and what GitHub, GitLab and most editors expect
• .markdown — the long form. Rarer but perfectly valid; some older tools and Jekyll sites still use it

You may also meet .mdown, .mkd, .mkdn and .mdtext. All are plain text; if a tool refuses one, renaming it to .md almost always fixes it.

In a filename, MD stands for Markdown. That is the only meaning that matters when you are looking at a file extension.

“MD” is an overloaded abbreviation — outside filenames it means Doctor of Medicine, Maryland or Managing Director. None relates to a .md file on your disk.

One near-collision worth knowing: .mdb is a Microsoft Access database and .mdf is a SQL Server file or disc image. Both are binary, not Markdown — if a Markdown viewer shows you garbage instead of text, that is the tell.

Because a .md file is plain text, everything can open it. The question is whether the formatting gets rendered or shown as raw symbols. Here are five options, fastest first.

1. Use an online viewer (no install). Drag your file onto the Markdown Viewer and it renders immediately, in your browser, with nothing uploaded. Best for a file you just want to read once.
2. Open it in VS Code. Free, cross-platform, and it has a Markdown preview built in. Open the file, then press Ctrl+Shift+V (Cmd+Shift+V on Mac) for a rendered preview, or Ctrl+K then V for a side-by-side view.
3. Push it to GitHub or GitLab. Both render .md automatically, and README.md is displayed on the repository home page.
4. Use a text editor. Notepad, TextEdit, Sublime Text or nano all open it. You see raw syntax rather than formatted output — which is what you want when editing rather than reading.
5. Use a dedicated Markdown app. Obsidian, Typora and Zettlr edit Markdown as formatted text. Worth installing only if you write it daily.

To edit rather than read, the Markdown Editor shows source on the left and live preview on the right, and downloads the result as a .md file.

Why does Windows not know what to do with .md?

Windows ships no file association for .md, so a fresh install does not know which program to use. Right-click the file, choose Open with → Choose another app, pick your editor, and tick Always use this app. macOS defaults to TextEdit, which shows raw syntax rather than rendered output.

This is the core syntax, and genuinely all most people need. Every example works in GitHub, GitLab, Reddit, Discord, Obsidian and every tool on this site.

Code blocks: the syntax people get wrong

A fenced block opens with three backticks plus an optional language name, and closes with three backticks alone on a line:

```javascript
const greeting = "hello";
console.log(greeting);
```

Two rules save most of the pain. The closing fence must be alone on its line — trailing text swallows the rest of your document into the block. If your code itself contains three backticks, open with four. The language name is only a colouring hint; whether you get colours depends on the renderer, not your file.

The two-space line break

Pressing Enter once inside a paragraph does nothing — Markdown joins the lines. To force a break without a new paragraph, put two spaces at the end of the line first. It is invisible in your editor, which is why it confuses people. A blank line starts a new paragraph and is far easier to spot; prefer it.

Original 2004 Markdown has no tables. GitHub added extensions called GitHub Flavored Markdown (GFM), now what most people mean by “Markdown.” They work on GitHub, GitLab, Reddit, Discord and every Markdown tool here.

Tables

| Column A | Column B |
| -------- | -------- |
| Value 1  | Value 2  |
| Value 3  | Value 4  |

The pipes need not line up — that is for your readability only. The separator row is mandatory, and colons set alignment: :--- left, :---: centre, ---: right.

One trap silently loses data: a pipe inside a cell splits that cell in two. Escape a literal | as \|, or the renderer reads it as a column boundary and discards whatever no longer fits. The Markdown Table Generator builds tables from a grid instead.

Task lists

- [x] Ship the feature
- [ ] Write the docs
- [ ] Tell the team

Renders as real checkboxes. On GitHub issues and pull requests they are clickable and update the source when ticked.

Strikethrough and autolinks

Two tildes each side give ~~struck through~~. A bare URL like https://example.com becomes a link automatically under GFM — under original Markdown it stays plain text.

Why README.md matters

README.md in a repository root is rendered automatically on the project page by GitHub, GitLab and Bitbucket. For most open-source projects it is the documentation, landing page and pitch. Keep the name capitalised — readme.md works on GitHub but breaks on case-sensitive tooling.

Markdown is not trying to replace Word. It solves a different problem, and the difference is worth understanding before you choose.

Version control decides it for most teams. Change one word in a .docx and Git records the whole file as changed; a reviewer cannot see what moved. Change one word in a .md and the diff shows exactly that word. That property is why nearly all software documentation lives in Markdown.

The trade-off is real: no page breaks, columns, headers or footers. If output must land precisely on a printed page, use Word or LaTeX.

Markdown converts cleanly into almost anything — a renderer has only a dozen rules to interpret. Each of these runs in your browser:

• Markdown to PDF — for sharing with someone who does not want a text file. Full walkthrough in our Markdown to PDF guide.
• Markdown to HTML — for pasting into a CMS, an email template or a web page.
• Markdown to Word — for someone who edits in Word and tracks changes.
• PDF to Markdown — the reverse trip, pulling text back out of a PDF.

On the command line, Pandoc handles far more formats than any browser converter: pandoc input.md -o output.docx. Worth installing if you need footnotes, citations or cross-references preserved.

Expect the same losses whichever route you take. Markdown carries no fonts, colours, margins or page size, so a converter invents all of them. Structure survives — headings, lists, tables, emphasis, links. Anything you never specified does not.

This is the one that catches people out — worth knowing before you blame your file.

Markdown lets you drop raw HTML into a document — a <details> block, a <br>, an <img> with a width. GitHub renders it. Many other renderers deliberately do not, and show the angle brackets as literal text.

Neither behaviour is a bug. Rendering arbitrary HTML from someone else's file is a real security risk, so many viewers escape it on purpose. It does mean the same README.md can look right on GitHub and broken elsewhere — the difference is the renderer, not your file.

Two practical consequences:

• If your document must render identically everywhere, avoid raw HTML. Stick to Markdown syntax and it will behave the same in every tool.
• If you are opening a .md file you did not write, prefer a viewer that escapes HTML. A Markdown file from an unknown source can carry active content in the same way a web page can.

The related trap: Markdown sanitises nothing by itself. It is a formatting convention, not a security boundary. Whether a file is safe depends on what you open it with — an argument for a viewer that runs locally in your browser rather than uploading to someone else's server.

1. Put a blank line between every block. Lists that will not render and headings that stay plain text are almost always a missing blank line above. The single most common Markdown mistake.
2. Use spaces, never tabs, for nesting. Tab handling differs between renderers; spaces behave identically everywhere.
3. Do not renumber ordered lists. Writing 1. on every line still renders as 1, 2, 3 — so inserting a step costs nothing.
4. Escape stray asterisks and underscores. A name like my_variable_name can turn into italics. A backslash fixes it, or wrap it in backticks.
5. Preview before you publish. One misplaced backtick can swallow the rest of a page. Paste it into the Markdown Editor first.
6. Keep the source readable. If your raw .md is hard to read as plain text, you have drifted from the point — usually a signal to stop nesting HTML inside it.
7. Bookmark a reference instead of memorising one. Nobody remembers the alignment colons. The Markdown Cheatsheet shows every rule beside its rendered output.