What Is a Markdown File? The .md Format Explained

Every README on GitHub is one, yet the question keeps coming up. What is a markdown file? It's a plain text file, usually with the .md extension, whose contents use Markdown symbols such as # and ** to mark structure. Any text editor can open it, and a renderer turns it into formatted output. This guide covers the extension, the encoding, and how to open and convert one.

What Is an .md File, Exactly?

An .md file is a text file that a program can read two ways. Open it in Notepad and you see the source, with hashes before headings and asterisks around bold words. Open it on GitHub or in a Markdown editor and the same bytes appear as headings, bold text, lists, and links.

Nothing in the file records fonts, colours, or page sizes. The formatting lives in the symbols, which is the design John Gruber set out in 2004 when he released Markdown 1.0.1 as a Perl script for web writers. His stated goal was a document that reads fine as plain text and still converts to valid HTML.

That's the whole definition, and it answers what are markdown files in practice. The meaning people search for isn't a secret format; it's a naming convention on top of ordinary text. The plain-English introduction to Markdown explains the language and its syntax. This post stays on the file itself: its extension, what's inside, and what to do with one.

The .md File Extension and Its Variants

The markdown file extension is almost always .md. RFC 7763, the IETF document that registered the text/markdown media type in March 2016, lists .md and .markdown as the two file extensions. You'll also meet a few older spellings in the wild.

Extension	Where you see it	Notes
.md	GitHub, GitLab, Obsidian, VS Code, most tools	The default; use this
.markdown	Older Jekyll sites, some blogs	Same content, longer name
.mdown, .mkd, .mkdn, .mdwn	Legacy projects	Rare; GitHub's markup library still renders them
.mdx	Docusaurus, Next.js docs sites	Markdown plus JSX components, not plain Markdown
.Rmd, .qmd	R Markdown, Quarto	Markdown plus executable code chunks
.txt	Files written in Markdown but saved as text	Valid Markdown; renderers won't auto-render it

The extension is only a hint. GitHub looks for a README in the .github, root, or docs folder and, per its README documentation, surfaces it on the repository page. Name the file README.txt and GitHub shows the raw text instead. The bytes didn't change; the promise did.

One acknowledged limitation of that promise: .md says nothing about which Markdown flavour the author used. RFC 7763 defines an optional variant parameter for the media type, and its companion RFC 7764 registers CommonMark, GitHub Flavored Markdown, pandoc, MultiMarkdown, and PHP Markdown Extra among others. Almost no file system carries that parameter, so a .md file with GitHub-only syntax (task lists, tables) renders differently in a strict CommonMark tool.

Is a Markdown File Just a Text File?

Yes. A markdown file and a .txt file can be byte-for-byte identical. The difference is what the name tells the apps around it: editors switch on syntax highlighting and preview, hosts render it, and search indexes tag it as documentation. Here's how markdown files compare with the formats people confuse them with.

Format	What's inside	Opens in	Edit without the original app?
.md	Plain UTF-8 text with Markdown symbols	Any text editor, any renderer	Yes
.txt	Plain text, no agreed markup	Any text editor	Yes
.html	Text with HTML tags	Browsers render, editors show tags	Yes, but verbose
.docx	Zipped XML plus media	Word, LibreOffice, Google Docs	No, needs an importer
.pdf	Positioned text and graphics	PDF viewers	Not practically

The DOCX comparison comes up often, and for good reason. A Word file is a container: unzip it and you find a dozen XML files plus every embedded image. An .md file is one stream of characters with no container, so it works in Git diffs, in grep, and in a chat message.

That's why we prefer md files for anything technical. You can read the history of a .md file line by line, while a .docx diff is unreadable. The trade-off is layout: Markdown has no concept of page margins or fonts, so a printable document with strict styling still needs a conversion step.

What Is Inside an .md File?

Open one and you'll find text like this:

# Project Title

A one-line description of what this project does.

## Installation

1. Clone the repository
2. Run `npm install`

## Usage

Import the module and call `run()`. See [the docs](docs/index.md) for options.

- [x] Core features
- [ ] Documentation

Three technical details matter beyond the symbols.

Encoding. RFC 7763 makes the charset parameter required for text/markdown with no default, and UTF-8 is what every modern editor writes. The CommonMark spec (0.31.2) doesn't fix an encoding at all; it treats the input as a sequence of Unicode characters and leaves bytes to the implementation. A file saved as UTF-16 by an old Windows tool opens as garbage in most renderers, so stick to UTF-8 without a byte order mark.

Line endings. CommonMark accepts LF, CR, or CRLF as a line ending, so a file written on Windows renders the same on macOS. Git may still warn about mixed endings in a repository.

No metadata. A bare .md file has no title field, author, or date. Static site generators add a YAML front matter block at the top for that, but it's a convention of the tool, not part of the md file format.

Try a Sample .md File in the Editor

The editor below is loaded with a short .md file. The left pane is what the file contains; the right pane is what a renderer shows. Edit anything and the preview updates.

Switch to the Markdown to HTML converter to see the HTML a renderer generates from the same file. That output is what browsers, GitHub, and static site builders actually display.

How Do Apps Decide to Render a .md File?

Each app checks the file type by name, then applies its own parser. A plain text editor stops at step one and shows the source. GitHub, GitLab, Obsidian, and VS Code's preview run a Markdown parser and show the result. Web servers that know the format label it text/markdown; many still serve .md files as text/plain, so the browser shows raw text.

That's the reason the same document can look slightly different in two places. GitHub renders task lists and tables. A strict CommonMark renderer shows - [ ] as a bullet with literal brackets. Neither is wrong; they follow different variants of the same format.

AI tools follow the same convention. ChatGPT and Claude write their answers in Markdown. Coding assistants read project instructions from files such as CLAUDE.md or README.md, because a text file with light structure is the easiest thing for a model to parse. The Markdown in AI guide covers why those tools settled on this format.

How to Open, Edit, and Convert .md Files

Windows. Double-clicking a .md file either opens Notepad or asks which app to use. Notepad shows the source, which is fine for editing. For a rendered view, the Markdown viewer for Windows guide compares the options, from VS Code to browser extensions.

macOS. TextEdit opens .md files but may treat them as rich text. Apple's TextEdit user guide says to choose Format then Make Plain Text, or set Plain text as the default under TextEdit Settings, New Document. Save as plain text so the symbols stay symbols.

Phone or browser. Paste the contents into the online editor and preview it there. Nothing to install, and the preview matches what GitHub shows for standard syntax. If you'd rather start from scratch, the how to create a Markdown file tutorial covers the exact clicks on each system.

Converting. Because the file is structured text, converters have an easy job. Turn .md into a PDF with the Markdown to PDF tool or into a Word document with the Markdown to Word guide. The HTML converter above produces a standalone web page. Going the other way, .docx to .md, works too, though tables and images need a check afterwards.

Markdown File FAQ

What is a markdown file in one sentence: a plain UTF-8 text file, normally named .md, whose symbols a renderer turns into formatted output. The extension is a hint, the content is the truth, and every text editor can open it. Paste yours into the editor to see both views at once, then convert it to PDF, Word, or HTML from the same page.