What Is an MD File? Markdown, README.md and CLAUDE.md (2026)

An MD file is a plain-text document written in Markdown: the .md extension means the text inside uses formatting characters like # for headings, ** for bold, and - for lists. Any text editor opens it as raw text, and any Markdown-aware tool renders it as formatted HTML.

In one line: An MD file is a plain-text document with the .md extension containing Markdown syntax. In 2026 you meet it in two shapes — files an AI writes for you to read (a plan, a summary, a README.md) and files an AI reads from you (CLAUDE.md, AGENTS.md, copilot-instructions.md). Same format, opposite direction.

Most people meet the extension through a tool rather than a tutorial: a coding agent leaves a plan in your project, or a repository hands you a README.md. Opening one takes seconds — the useful question is which of those two kinds you are holding. For the origin of the format itself, created by John Gruber and Aaron Swartz in 2004, see what Markdown is.

GitHub alone hosts over 630 million repositories (GitHub Octoverse, 2025), and README.md is the file GitHub renders on a project's front page by convention — which is where most people meet the extension for the first time. Beyond GitHub, MD files power documentation sites, note-taking apps like Obsidian and Bear, static site generators like Hugo and Jekyll, and — increasingly — AI agent configuration files like AGENTS.md and llms.txt.

GitHub hosts 630 million repositories (GitHub Octoverse, 2025), and Markdown is the format it renders for documentation, READMEs, and changelogs. The format's dominance stems from one design choice: MD files are readable as plain text, even before rendering.

What Does the .md File Extension Actually Mean?#

The .md extension stands for "Markdown." Some tools also recognize .markdown, .mdown, or .mkd, but .md is the standard used by GitHub, GitLab, VS Code, and every major documentation platform. The extension signals to editors and renderers that the file contains Markdown syntax and should be parsed accordingly.

Unlike .docx (Microsoft Word) or .pages (Apple Pages), an MD file is not a binary format. Open any .md file in a basic text editor — TextEdit on macOS, Notepad on Windows, or nano in a terminal — and you see the actual content, not garbled characters. This portability is the core reason Markdown won the documentation format wars.

Here is the smallest useful MD file, in raw form:

# Project Name
 
A short description.
 
## Usage
 
- Import the module
- Check the **output**

Rendered, that becomes a heading hierarchy, a paragraph, a bulleted list, and bold text. The syntax follows the CommonMark specification (version 0.31.2, released January 2024), which defines over 600 test cases so that every compliant parser handles Markdown identically. A complete file appears further down.

The .md file extension stands for Markdown, the plain-text formatting language created by John Gruber in 2004. Unlike binary formats like .docx, an MD file is readable in any text editor. The CommonMark specification (version 0.31.2, 2024) standardizes the syntax across 600+ test cases, ensuring consistent rendering on every compliant parser.

Why Did an AI Give Me a .md File?#

If a tool just dropped a .md file on you, it is one of two things, and the difference decides what you do with it.

Markdown an AI wrote for you to read. Coding agents — Claude Code, Codex, Cursor — write plans, summaries, code reviews, and documentation into your project as .md because the format keeps headings, lists, tables, and code in portable plain text. (Web ChatGPT and Claude usually render Markdown inline; it is the CLI and agent tools that leave an actual file on disk.) That file is finished content meant to be read formatted, not configuration. On a Mac, the habit that makes it readable is two steps: save the AI output as Markdown, then view it rendered.

Markdown an AI reads from you. The other kind is instructions you write for the agent: CLAUDE.md for Claude Code, .github/copilot-instructions.md for GitHub Copilot, AGENTS.md for a growing list of tools. Those are config files you edit as plain text — rendering them is beside the point.

AGENTS.md is the most standardized of the second group. OpenAI contributed it to the Agentic AI Foundation, formed by the Linux Foundation on December 9, 2025 alongside Anthropic's Model Context Protocol and Block's goose; more than 60,000 open source projects had adopted the convention by that announcement (Linux Foundation, December 9, 2025, verified July 29, 2026).

How Do You Open an MD File?#

Any text editor opens an MD file, because it is plain text — TextEdit on macOS, Notepad on Windows, nano or vim on Linux. That gives you the raw syntax. To see the formatted document instead, with headings styled and links clickable, you need something that renders Markdown: the preview pane in VS Code (Cmd+Shift+V or Ctrl+Shift+V), a free Markdown preview tool in the browser, or a native app. On macOS, MacMD Viewer renders .md files with syntax highlighting, a table of contents, and Mermaid diagrams, and adds QuickLook support so pressing Space on a file in Finder shows it formatted — $19.99 once, no subscription.

Platform-by-platform walkthrough, including double-click behavior and file associations: how to open an MD file. For native macOS alternatives side by side, see the roundup of Markdown viewers for Mac.

What Is Inside an MD File? Markdown Syntax Explained#

An MD file contains plain text annotated with Markdown syntax characters. These characters map directly to HTML elements. The full syntax is defined by the CommonMark specification (2024) and extended by GitHub Flavored Markdown (GFM) for tables, task lists, and strikethrough.

Here are the building blocks you will find in any MD file:

Headings#

# Heading 1
## Heading 2
### Heading 3

Hash characters set the heading level: one produces an <h1>, two produce <h2>, through six levels. The space after the hashes is required by the spec.

Emphasis (bold, italic, strikethrough)#

**bold text**
*italic text*
~~strikethrough~~

Double asterisks for bold, single asterisks for italic, double tildes for strikethrough. For a complete reference, see the markdown text formatting guide.

Links and images#

[Link text](https://example.com)
![Alt text](image.png)

Square brackets hold the visible text, parentheses hold the URL; images use the same syntax with a leading !.

Lists#

- Unordered item
- Another item
 
1. Ordered item
2. Another item
 
- [x] Task complete
- [ ] Task pending

Dashes, asterisks, or plus signs create unordered lists; numbers followed by periods create ordered lists; GFM adds task checkboxes with [x] and [ ]. For nesting and edge cases, the markdown lists guide covers every variation.

Code blocks#

Inline code: `const x = 1`
 
Fenced block:
```javascript
function hello() {
  return "world";
}
```

Backticks create inline code spans. Triple backticks create fenced code blocks with optional language identifiers for syntax highlighting.

Tables (GFM extension)#

| Column A | Column B |
|----------|----------|
| Cell 1   | Cell 2   |

Tables are not part of the original Markdown specification. They were added by GitHub Flavored Markdown and are now supported by most parsers. If you work with tabular data frequently, the markdown table generator can save time.

MD File Example: A Complete README.md#

Fragments explain the syntax; a whole file explains the format. Here is a realistic README.md from start to finish — every character of it is plain text you could type in Notepad:

# Sparkline Kit
 
A dependency-free chart library, 4 KB minified.
 
## Install
 
```bash
npm install sparkline-kit
```
 
## Usage
 
```js
import { line } from "sparkline-kit";
line("#chart", [3, 7, 4, 9]);
```
 
## Options
 
| Option  | Type   | Default   |
|---------|--------|-----------|
| `color` | string | `#0a84ff` |
| `width` | number | `120`     |
 
## Roadmap
 
- [x] Line charts
- [ ] Bar charts
- [ ] Dark mode
 
> **Note:** requires Node 20 or later.
 
Licensed under [MIT](LICENSE.md). See `CHANGELOG.md` for release notes.

Rendered, that becomes a page with a heading hierarchy, two syntax-highlighted code blocks, a table, a checklist, and a callout. Unrendered, it is still perfectly readable — which is the whole design goal, and the reason .md outlived richer formats in developer tooling.

What Is the Difference Between an MD File and a TXT File?#

Both .md and .txt files are plain text. The difference is semantic: an MD file contains structured formatting that a Markdown parser can interpret, while a .txt file is unstructured plain text with no rendering expectations.

The practical takeaway: if you rename notes.txt to notes.md, the content does not change. But a Markdown-aware tool will now parse the syntax characters and render formatted output.

Where Are MD Files Used in Practice?#

Five contexts cover almost all of it:

Software repositories. GitHub, GitLab, and Bitbucket render README.md automatically on the project page, and CONTRIBUTING.md, CHANGELOG.md, and LICENSE.md follow the same convention. GitHub merged 43.2 million pull requests per month on average in 2025, most carrying Markdown in descriptions and comments (GitHub Octoverse, 2025).

Documentation sites. Static site generators — Jekyll, Hugo, Docusaurus, MkDocs, VitePress — convert MD files into full websites, which keeps content separate from presentation.

Note-taking. Obsidian, Bear, Logseq, Notion (export), and iA Writer store notes as .md, so the notes are never locked into a proprietary format and move between apps freely.

AI work, in both directions. Agents write .md for you to read and read .md that you write for them — the distinction covered earlier on this page, and the fastest-growing reason people encounter the extension at all.

Team communication. Slack, Discord, Microsoft Teams, and Reddit all support Markdown in messages. The Discord markdown formatting guide and Markdown in Slack guide cover the platform-specific syntax differences.

What an MD file is used for: software repositories (README.md, CHANGELOG.md, CONTRIBUTING.md), documentation sites (Jekyll, Hugo, Docusaurus, MkDocs), note-taking apps (Obsidian, Bear, Logseq), AI agent instructions (CLAUDE.md, AGENTS.md), and messages on Slack, Discord, and Teams. One format across all of them, because plain text moves everywhere without conversion.

How Do You Create an MD File From Scratch?#

Three steps: open any text editor (VS Code, Sublime Text, TextEdit in plain text mode, nano in a terminal), write Markdown syntax, save with the .md extension. No compilation step, no build tool, no account. The file is readable as plain text the moment you save it.

For a syntax reference worth bookmarking, the markdown cheat sheet covers every element from headings to Mermaid diagrams. To start from an existing HTML document instead, the HTML to Markdown converter handles the translation.

How Do You Convert an MD File to Other Formats?#

Because the source is structured plain text, MD files convert to almost anything:

• MD to HTML — every parser does this natively, or use the Markdown to HTML tool
• MD to PDF — Pandoc, or the Markdown to PDF converter
• MD to DOCX — pandoc input.md -o output.docx
• MD to slides — Marp, Slidev, and Reveal.js turn .md into decks

The reverse works too: PDF to Markdown, CSV to Markdown tables, or HTML to Markdown, structure intact.

Frequently Asked Questions About MD Files#

What is an MD file?#

An MD file is a plain-text document written in Markdown syntax — the .md extension signals that the file uses Markdown formatting such as # for headings, ** for bold, and - for lists. It can be opened in any text editor and rendered into HTML by any Markdown-compatible tool.

What does the .md file extension stand for?#

The .md extension stands for Markdown, so an MD file and a Markdown file are the same thing. Some tools also accept .markdown, .mdown, or .mkd, but .md is the standard used by GitHub, GitLab, VS Code, and all major documentation platforms.

Why did ChatGPT or Claude give me a .md file?#

Coding agents like Claude Code, Codex, and Cursor write .md (Markdown) files into your project because the format preserves structure — headings, lists, tables, code — in portable plain text that renders cleanly anywhere. A plan, summary, or README from these tools is Markdown content meant to be read formatted, not a config file. (Web ChatGPT and Claude usually render Markdown inline, so it is the CLI and agent tools that leave you an actual file.) Open it in any text editor for the raw text, or a Markdown viewer for the rendered version.

What is an MD file used for?#

MD files carry documents that need structure without a proprietary format: README.md, CHANGELOG.md, and CONTRIBUTING.md in software repositories; pages for documentation sites built with Jekyll, Hugo, Docusaurus, or MkDocs; notes in Obsidian, Bear, and Logseq; and instructions for AI agents in files like CLAUDE.md and AGENTS.md. The common thread is plain text that stays readable before anything renders it.

How do I make an MD file?#

Open any text editor, type your content using Markdown syntax, and save the file with a .md extension — notes.md, README.md, whatever fits. There is no compilation step, no build tool, and no account. The file is readable as plain text immediately and renders in any Markdown-aware tool.

How do I open an MD file?#

Any text editor opens an MD file as plain text. For a formatted preview, use VS Code (press Ctrl+Shift+V or Cmd+Shift+V), a dedicated viewer like MacMD Viewer ($19.99 for macOS), or an online Markdown preview tool. MacMD Viewer also supports Quick Look in Finder.

Is an MD file the same as a text file?#

An MD file is a plain-text file, so any text editor can open it. The difference is that it contains Markdown syntax designed to be parsed into formatted HTML. A plain .txt file has no syntax conventions, while an .md file follows the CommonMark specification.

What is a README.md file?#

A README.md is a Markdown file placed in the root of a software repository. It serves as the project's front page on GitHub or GitLab, explaining what the project does, how to install it, and how to use it. GitHub renders it automatically beneath the file list.

What is the difference between .md and .mdx?#

MDX extends Markdown by allowing JSX components (React) inside the document, so an .mdx file can render interactive components alongside standard Markdown text. A standard .md file contains only Markdown syntax and cannot execute code. MDX is common in documentation frameworks like Docusaurus and in blogs built with Next.js.