You download a project template, unzip it, and there it sits: a file called README.md. You double-click it. Windows shrugs and asks which app you want to use. Nothing on the list looks right. Notepad opens it and shows you text full of pound signs and asterisks, which is not what you expected either.
So what is an MD file? The short version is that it is a Markdown file, and it is plain text. That is genuinely all it is. The confusing part is not the file, it is the fact that the symbols inside are instructions for how the text should look once something renders it. This guide covers what a Markdown file is, what one looks like inside, why so many tools now default to the format, where it falls short, and how to open, create, and safely handle one. There is also a real security question here that most guides skip, and in 2026 it matters more than it used to.
An MD file is a Markdown file: a plain text document that uses simple symbols like # and ** to mark headings, bold text, lists, and links. It opens in any text editor on any operating system. Software reads those symbols and renders the file as formatted text, which is why README.md files look styled on GitHub.
What is an MD file, exactly?
An MD file is a plain text file that contains writing formatted with Markdown, a lightweight markup language. The .md extension is a label. It tells your computer and other software that the text inside follows Markdown rules. There is nothing hidden in the file, no compression, no proprietary container, and no code that runs.
Markdown was created in 2004 by John Gruber, with help from Aaron Swartz. Gruber describes it as two separate things: a plain text formatting syntax, and a Perl tool that converts that text into HTML. That distinction explains most of the confusion beginners run into. The Markdown file is the writing. The formatting you see is something a program produced from it.
The format also has an official internet media type, text/markdown, registered by the IETF in RFC 7763 (March 2016). That registration describes Markdown as a family of plain-text formatting syntaxes that can optionally be converted into formal markup like HTML. The word “family” is doing real work in that sentence, and we come back to it later.
What the letters MD actually stand for
Here is a small correction worth making. Several popular guides state that MD stands for “Markdown documentation.” Go to the original Markdown project page and that expansion does not appear anywhere. Gruber only ever calls it Markdown. Some file databases label the type “Markdown Documentation File,” which is a category name they assigned, not what the two letters expand to. So MD is short for Markdown. Nothing more.
MD file compared to TXT, DOCX, and PDF
A Markdown file sits between a raw text file and a word processor document. It keeps the simplicity of one and borrows a little structure from the other.
| Format | What is inside | Formatting | Best for |
|---|---|---|---|
| .md | Plain text plus symbols | Headings, lists, links, code, tables | Docs, notes, drafts, AI instructions |
| .txt | Plain text only | None | Logs, raw notes, config dumps |
| .docx | Zipped XML and assets | Full page layout, tracked changes | Contracts, reports, anything a client edits |
| Fixed page description | Locked layout, fonts embedded | Final delivery, printing, signatures |
What an MD file looks like inside
Open any MD file in Notepad and you see ordinary sentences with a handful of punctuation marks doing extra work. A pound sign at the start of a line makes a heading. Two asterisks around a word make it bold. A hyphen at the start of a line makes a bullet. That is roughly ninety percent of the syntax people actually use.
A sample MD file you can copy
Here is a complete, working Markdown file. Copy it into a text editor, save it as notes.md, and you have a valid MD file.
# Weekly Notes
## Monday
Shipped the **pricing page** update. Still waiting on copy for the
*footer* section.
- Fixed the mobile nav bug
- Rewrote the FAQ block
- Pushed to staging
## Tuesday
Ran the migration script:
```
npm run migrate --env=staging
```
> Reminder from Dana: freeze deploys after Thursday.
### Open questions
1. Do we need a fallback for older browsers?
2. Who owns the changelog going forward?
See the [deploy guide](https://example.com/deploy) before Friday.
| Task | Owner | Status |
| ---- | ----- | ------ |
| Nav bug | Sam | Done |
| Copy | Dana | Waiting |Every symbol there has one job. The pound signs set heading levels. The asterisks handle bold and italic. The angle bracket makes a quote block. Numbers create an ordered list. Square brackets followed by parentheses make a link. Pipes and hyphens build a table.
Raw file versus rendered output
This is the single biggest source of beginner frustration. In Notepad, that sample looks like text with clutter. Open the same file on GitHub, in Obsidian, or in a Markdown editor with preview turned on, and the pound signs disappear, the headings get large, the list gets bullets, and the table draws borders.
Nothing changed in the file. The software read the symbols and drew the result. If your Markdown file looks like a mess, you are almost certainly looking at it in a tool that is not rendering it. That is a viewer problem, not a file problem.
What MD files are used for
Markdown files show up wherever people write structured text that other software needs to read. Documentation is the largest category by far, but note-taking apps, blogging systems, and AI tools have all adopted the format for the same underlying reason: it stays readable whether a human or a machine opens it.
README files and project documentation
The README.md file is the one most people meet first. It explains what a project does, how to install it, and how to use it. Nearly every software repository has one. Documentation systems like MkDocs and Jekyll are built to consume folders of Markdown files and publish them as websites.
Note apps, blogs, and static sites
Obsidian, Joplin, Bear, and Zettlr all store notes as .md files on your own disk. That means your notes outlive the app. Static site generators such as Hugo, Jekyll, and Eleventy turn Markdown files into full websites. Plenty of writers draft blog posts in Markdown first, then convert.
- Project docs and changelogs
- Personal knowledge bases and daily notes
- Blog and newsletter drafts
- Instruction files for AI coding assistants
- Research notes in R Markdown and Jupyter workflows
Why MD files are better than most document formats
Markdown files win on durability, portability, and size. Because the file is plain text, any editor on any operating system can open it, today and in twenty years. There is no version compatibility to worry about, no font substitution, and no proprietary reader. That combination is rare, and it is why the format keeps spreading.
Five advantages that hold up
- It opens anywhere. Notepad, TextEdit, Vim, VS Code, a phone, a browser. No install required.
- It is tiny. A long Markdown document is usually a few kilobytes. The same content as a .docx with images can be hundreds of times larger.
- It reads fine unrendered. Gruber’s stated design goal was that a Markdown document should be publishable as plain text without looking marked up.
- It diffs cleanly. Git tracks changes line by line, so you can see exactly what a colleague edited. Try that with a binary word processor file.
- It converts out easily. Markdown goes to HTML, PDF, or DOCX with standard tools. Getting out of a proprietary format is usually harder.
The staying power argument
There is one detail that says more about Markdown’s design than any feature list. Look at how little the original needed to change.
The original Markdown release, version 1.0.1, is dated December 17, 2004. Gruber has not updated it since.
Daring Fireball, Markdown project page, December 2004
A format that has gone twenty-plus years without a revision from its author, while adoption kept climbing, got something right at the start. That is also, as the next section shows, the source of its biggest problem.
The limitations of MD files
Markdown is a writing format, not a layout format. It cannot control page size, margins, columns, fonts, or where a page break falls. It has no tracked changes, no comment threads, and no built-in styling. If your document depends on any of those, a Markdown file is the wrong container and no amount of workarounds will fix that.
What Markdown genuinely cannot do
- Set fonts, colors, sizes, or spacing
- Control page breaks, headers, or footers
- Embed images inside the file itself, since it only stores links to them
- Support tracked changes, comments, or review workflows
- Guarantee that complex tables survive conversion intact
That last one catches people out. Because images live outside the file, moving a Markdown file without its image folder produces broken links. A Word document would have carried the pictures along.
Why the same file renders differently in different apps
This is the limitation nobody warns beginners about. Markdown is not one specification. It is a family of variants, and they disagree. The CommonMark project exists specifically because no unambiguous spec existed, implementations drifted apart over a decade, and the same document renders one way in a wiki and another way through a converter.
CommonMark’s current spec is version 0.31.2, dated January 28, 2024. GitHub Flavored Markdown builds on top of it. Other tools implement their own extensions. So a file using footnotes or task lists may render perfectly in one editor and show raw symbols in another. When that happens, you have hit a flavor mismatch, not a corrupt file.
Why AI tools default to Markdown files
Ask ChatGPT, Claude, or Gemini for a structured answer and you will usually get Markdown back, whether the interface shows it raw or rendered. The reason is practical. Markdown carries structure like headings and lists using a handful of characters, so a model can express hierarchy without spending many tokens on markup. HTML costs far more characters to say the same thing.
Context windows are finite and paid for by the token, so format efficiency turns into real money at scale. If you want a sense of how quickly those infrastructure costs compound, our breakdown of how KV cache pressure reshapes AI infrastructure covers the same economics from the hardware side.
What is an MD file in Claude, and what CLAUDE.md does
If you use Claude Code, you will run into CLAUDE.md. It is an ordinary Markdown file placed in a project folder that the tool reads at the start of a session, so the agent begins with standing context about the project instead of a blank slate. There is nothing special about the file type. It is the filename and location that give it meaning.
A parallel standard called AGENTS.md covers the same ground across tools. Reporting from April 2026 describes it as an open Markdown format that emerged in 2025 out of collaboration between Sourcegraph, OpenAI, Google, Cursor, and Factory, now maintained under the Linux Foundation. Treat the exact governance details as secondary reporting rather than confirmed specification, and check the project repository if it matters to your setup.
| File | Tool it serves | Typical location |
|---|---|---|
| CLAUDE.md | Claude Code | Project root |
| AGENTS.md | Multiple coding agents | Repository root |
| copilot-instructions.md | GitHub Copilot | .github folder |
| README.md | Humans, and most agents by default | Project root |
Keep these files short
Every line in an agent instruction file loads into the model’s context before you type anything. A bloated file eats the space you actually need for work. Practitioners writing about this consistently recommend keeping such files brief and specific. That is shared experience rather than measured research, so treat it as sensible practice, not a proven rule.
What is an MD file in GitHub and VS Code?
On GitHub, a Markdown file is rendered automatically. Upload a README.md and the site displays formatted headings, lists, and tables rather than raw symbols. In VS Code, an MD file opens as text by default, and a built-in preview shows the rendered version side by side. Neither tool changes the file. Both just draw it.
GitHub Flavored Markdown versus CommonMark
The GitHub Flavored Markdown specification describes GFM as a strict superset of CommonMark. Everything valid in CommonMark is valid in GFM, and GFM adds extensions on top. The spec also notes that GitHub performs extra post-processing and sanitization after converting to HTML, for security and consistency.
One thing to keep straight: the formal GFM spec and GitHub’s live renderer are not the same thing. The site supports features that the published spec does not document. So “it works on GitHub” is not proof that it will work anywhere else.
Previewing in VS Code
VS Code ships with Markdown preview built in. Open the .md file, then use the preview command from the command palette or the preview icon in the editor tab bar. Split view puts raw text on one side and rendered output on the other, which is the fastest way to learn the syntax by watching it take effect.
How to open an MD file
Any text editor opens an MD file. Nothing needs installing. The real question is whether you want to read the raw text or see it rendered. For reading raw, use whatever editor is already on your machine. For reading it formatted, use an editor with preview, a browser extension, or a dedicated Markdown app.
On Windows
Right-click the file, choose Open with, and pick Notepad for a quick look. For anything more, Notepad++, VS Code, or Sublime Text give you syntax highlighting and, in VS Code’s case, live preview. If Windows keeps prompting you for an app every time, set a default: right-click, Open with, Choose another app, tick the box to always use it, then confirm.
On Mac
TextEdit is already installed and opens MD files fine, but switch it to plain text mode first. Rich text mode can quietly add formatting you do not want. MacDown, Typora, and iA Writer are purpose-built alternatives with live preview.
| Tool | Platform | Live preview | Cost |
|---|---|---|---|
| Notepad | Windows | No | Free |
| TextEdit | Mac | No | Free |
| VS Code | Windows, Mac, Linux | Yes | Free |
| MacDown | Mac | Yes | Free |
| Typora | Windows, Mac, Linux | Yes | Paid |
How do I open an MD file in Word?
Desktop Word will open a Markdown file, but it shows you the raw symbols. There is no setting that turns Word into a Markdown parser, and pasting Markdown into a document keeps the punctuation rather than converting it. Reporting from July 2026 makes the same point, and warns against assuming that Markdown shortcuts in Teams or Loop mean Word can import Markdown properly. It cannot.
The browser side changed recently. Microsoft turned on native Markdown editing for .md files in OneDrive and SharePoint, with view, edit, and split modes. Independent coverage puts general availability at April 21, 2026, with rollout expected to finish by late May 2026. Those dates come from Microsoft-watching press rather than a primary Microsoft page we could open directly, so confirm against your own tenant before relying on them. For a formatted document you can hand to someone, converting Markdown to DOCX with a dedicated converter remains the cleaner route.
How to create your own MD file
Creating a Markdown file takes three steps and no special software. Open a text editor, write your content using Markdown symbols, and save it with a .md extension. That is the whole process. The file is valid the moment you save it, whether or not you used any formatting symbols at all.
- Open Notepad, TextEdit in plain text mode, or VS Code.
- Type your content. Start a line with # for a heading and – for a bullet.
- Save as, name the file notes.md, and set the file type to All Files so the editor does not add its own extension.
The mistake that saves your file as .md.txt
Notepad defaults to saving text documents, so it appends .txt to whatever you typed. You end up with notes.md.txt and nothing recognizes it. Fix it by choosing All Files in the save dialog before you save. On Windows, turn on file extension display in File Explorer’s View menu so you can actually see what you ended up with.
Are MD files safe?
A Markdown file cannot execute anything on its own. It is text, it has no macros, and opening one in a text editor carries essentially no risk. That is the answer every guide gives, and for the ordinary case it is correct. The answer stops being complete the moment an AI tool reads the file on your behalf, which in 2026 happens constantly.
The risk nobody mentions
Markdown supports image and link syntax. When an assistant renders its output, a Markdown image tag causes the viewer to fetch that image URL automatically. If attacker-controlled text inside a document can influence what the model writes, it can steer the model into emitting an image whose URL carries your data as a parameter. The fetch happens without a click.
This is documented, not theoretical. The OWASP prompt injection prevention cheat sheet lists rendered Markdown and hidden image tags as a recognized data exfiltration pattern. Microsoft’s security response team has published its own account of blocking exactly this technique after an external researcher reported it. A May 2026 writeup found the same zero-click path in an AI coding extension for VS Code, since patched by its maintainers.
| Claim about MD file safety | Evidence level | What it means for you |
|---|---|---|
| The file itself cannot run code | Confirmed by format documentation | Opening in a text editor is safe |
| Markdown rendering can leak data via image tags | Documented by OWASP and vendor security teams | Matters when an AI reads untrusted files |
| Markdown can contain hidden HTML | Confirmed, since many parsers allow inline HTML | Read raw before trusting a file from a stranger |
| Any .md file from anywhere is harmless | Unsupported, contradicted by the above | Apply the same caution you would to any download |
Three habits that keep you safe
- Open unfamiliar Markdown files as raw text first, before letting anything render them.
- Be deliberate about feeding downloaded .md files to an assistant that also has access to your private data.
- Keep your editors and AI extensions updated, since most of these issues get patched once reported.
Is a Markdown file better than a PDF?
Neither format is better in general, because they solve opposite problems. Markdown is a writing format built for editing and reuse. PDF is a publishing format built to freeze a layout so it looks identical everywhere. Asking which is better is like asking whether a draft is better than a printed page.
| Situation | Better choice | Why |
|---|---|---|
| Docs that change weekly | Markdown | Edits are easy and changes are trackable |
| Signed contract or invoice | Layout is fixed and it is hard to alter casually | |
| Feeding a document to an AI tool | Markdown | No extraction step, structure survives intact |
| Print-ready design work | Markdown has no layout control at all | |
| Notes you want to still open in 2040 | Markdown | Plain text has no reader dependency |
A simple rule covers most cases. Write in Markdown, deliver in PDF. Keep the editable source, export the frozen copy when someone needs to receive it.
When a .md file is not a Markdown file at all
The .md extension is not exclusive to Markdown. File format databases list several unrelated types sharing those two letters. If a .md file refuses to make sense as text, it may not be Markdown, and no Markdown editor will help you.
- SEGA Mega Drive game ROM images
- Machine description files referenced by the GNU Compiler Collection
- MDCD compressed archives from MS-DOS era tools
- MuseData musical scores, a plain text notation format from 1983
- Moneydance personal finance data files
Telling them apart takes ten seconds. Open the file in a text editor. If you see readable sentences with pound signs and asterisks, it is Markdown. If you see garbled characters and symbols that look like noise, you have a binary file wearing a familiar extension.
Frequently asked questions about MD files
Is a Markdown file just a text file?
Yes. A Markdown file is a plain text file, and you could rename it to .txt without changing a single byte inside. The difference is the label. The .md extension signals to software that the symbols inside follow Markdown rules and should be rendered as formatting. A .txt file makes no such promise, so nothing tries to render it.
What is the difference between Markdown and DOCX?
A Markdown file is readable text with a few formatting symbols. A DOCX file is a zipped bundle of XML and embedded assets that only word processors read properly. Markdown handles structure such as headings and lists. DOCX handles full page layout, fonts, images inside the file, tracked changes, and comments. Choose Markdown for writing, DOCX for documents other people will format or review.
What is the difference between .md and .markdown?
Nothing, functionally. Both extensions mean the same format, and tools treat them the same way. The .markdown spelling is the longer original form and shows up mostly in older projects and some blogging systems. The .md form is far more common now, largely because it is shorter to type. Pick either one, then stay consistent inside a project.
Can I put images in a Markdown file?
You can reference images, but you cannot store them inside the file. Markdown image syntax points at a file path or a web address, and the renderer fetches the picture at display time. That keeps files small, and it means moving a Markdown file without its image folder breaks every picture. Keep images in a folder beside the file and use relative paths.
How do I add a line break in a Markdown file?
Pressing Enter once often does nothing visible, because most parsers treat a single newline as the same paragraph. Leave a blank line between paragraphs to force a real break. For a line break inside a paragraph, end the line with two spaces before pressing Enter. Some editors strip trailing spaces automatically, which is why this trick sometimes appears not to work.
Is Markdown a programming language?
No. Markdown is a markup language, which describes how text should be structured rather than telling a computer what to do. There are no variables, no logic, and no execution. That is exactly why a Markdown file cannot carry a virus in the way a macro-enabled document can. Learning it takes minutes, and most people are productive after seeing one example.
How do I download an MD file from a repository?
Open the file in the repository, switch to the raw view, then save the page. Saving the rendered view instead gives you an HTML page full of site markup rather than the Markdown source. If you need many files, cloning or downloading the whole repository as a zip archive is faster than saving each one by hand.
How do I convert a Markdown file to HTML?
Converting to HTML is what Markdown was built to do. Pandoc is the standard command-line tool and handles most formats. Many editors include an export option that produces HTML directly. Online converters work for one-off jobs. Expect small differences in output depending on which flavor the converter implements, particularly for tables, footnotes, and task lists.
Can Google Docs open a Markdown file?
Google Docs does not treat .md as a native document format, so uploading one usually gives you the raw symbols rather than formatted text. Converting to DOCX or HTML first and importing that produces a much better result. Check the current import options in your account before assuming, since these features change without much announcement.
How do I find Markdown files on a website?
Search operators are the quickest route. Combining a site restriction with a filetype restriction surfaces documentation files that normal browsing hides. Our guide to Google search operators and index auditing walks through the commands and how to combine them. Results vary, since many Markdown files are rendered as HTML pages and never indexed under their original extension.
The short version on MD files
That README.md sitting in your download folder is a plain text file. Open it in Notepad and you see the writing plus a few symbols. Open it in VS Code with preview on, or drop it into a repository, and the same file turns into clean headings and lists. Nothing about the file changed. You just found something that renders it.
What makes the format worth learning is not the syntax, which takes an afternoon. It is that a Markdown file stays readable with no software at all, converts out to almost anything, and has quietly become the language AI tools speak by default. The limits are real too. No layout control, no embedded images, and enough variation between flavors that your file may look different somewhere else. And the safety answer has grown more complicated now that assistants read these files on our behalf.
Once you know how to open, write, and check one, the next question is a bigger one. If plain text has outlasted every format that promised to replace it, what does that say about the documents you are creating today?
