What file extension do Markdown files use?

Every extension you might meet

You will run into older and more specialised extensions from time to time. This is the full picture.

Two of these are not really Markdown

• .mdx is Markdown with JSX components mixed in. The syntax overlaps, but an ordinary renderer chokes on the component tags.
• .rmd and .qmd mix Markdown with executable code chunks. Each one needs its own toolchain to produce output.

Just use .md

Unless a tool demands otherwise, pick .md every time. It is the shortest. It is the most widely known. And it is the one every editor maps to a Markdown mode. Every example in our complete guide assumes it.

Why README.md is a special filename

One filename carries extra weight. GitHub, GitLab and Bitbucket render a file called README.md as the front page of a repo or folder. That one habit is why Markdown became the default format for docs. Every project's landing page is a Markdown file. Millions of coders learned the syntax without ever deciding to.

my-project/
├── README.md        rendered as the repo homepage
├── CONTRIBUTING.md  linked from GitHub's UI
├── LICENSE.md       shown in the sidebar
├── docs/
│   └── setup.md     a regular documentation page
└── src/

Uppercase, lowercase and subfolders

The uppercase name is a habit, not a rule. Lowercase readme.md renders the same way. Even so, the uppercase form is common enough that lowercase looks odd to a trained eye. A README dropped into any subfolder is rendered on that folder's page too. It is a quiet way to document a directory.

What goes inside one

A title, a short description, install steps and a table or two cover most READMEs. If you write them often, the GFM guide covers the extras GitHub layers on top: tables, task lists, alerts and autolinks.

What is actually inside a .md file

Open one in Notepad or TextEdit and you see your own words, plus punctuation. There is no hidden structure, and no app owns the file. Save it as UTF-8, which every modern editor does by default. Accented letters, Traditional Chinese and emoji then survive intact.

Why plain text keeps paying off

• Git compares a Markdown file line by line, so a pull request shows exactly which sentence changed.
• Full-text search finds your notes without opening an app first.
• A ten-year-old backup still opens, because no single program owns the format.
• The same file can be rendered as a web page, a PDF or a printed handout, with no proprietary container in between.

That portability is the real argument for the format, and what Markdown is makes the longer version of it. For the comparison with writing tags by hand, see Markdown vs HTML.

Creating and opening .md files

1. Write in our editor and click .md in the toolbar to download the file with the right extension.
2. Or use Save As in any text editor and type the full name yourself, for example meeting-notes.md.
3. On Windows, set the save type to "All files" first, or Notepad adds .txt behind your back.
4. On macOS, choose Format then Make Plain Text in TextEdit before saving, or you get a rich-text file wearing an .md name.

Broken                       Fixed
notes.md.txt                 notes.md
(Notepad appended .txt       (choose "All files" as the
 to the filename)             save type, then type the name)

The hidden extension trap on Windows

File Explorer hides known extensions by default. So notes.md.txt shows up as notes.md. The double name goes unnoticed until a tool refuses to render it. Turn on "File name extensions" in the View tab and save yourself an hour.

Opening one is the easy direction

Any text editor handles .md, because it is just text. To see the formatted version, paste the contents into the editor and read the preview pane. There is more in how to open a .md file, and the cheat sheet is there whenever the syntax needs a refresher.