What Is an .md File? The Complete Guide to Markdown Files

An .md file is a plain-text file written in Markdown — a lightweight formatting language that turns simple symbols like #, ** and - into headings, bold text and lists when the file is rendered. You'll most often meet .md files as READMEs on GitHub, documentation, notes, and configuration files for AI tools.

Markdown hits a sweet spot that few formats manage: it's readable as raw text in any editor, but renders into a fully formatted document when you need it to. That duality is why it has become the default writing format for developers, documentation teams, and increasingly AI agents.

The .md File Extension — What Does It Stand For?

.md is short for Markdown. The extension was chosen by John Gruber when he created the Markdown language in 2004. Before .md, there was no standard file extension for lightweight markup — documents were either plain .txt (no formatting) or heavyweight formats like .html and .doc.

Today, .md is one of the most recognisable file extensions in software development.

Common Markdown File Extensions

If you see any of these, the file is fundamentally Markdown — just with extra capabilities layered on top.

What's Actually Inside an .md File?

Pure text, with a few special characters that tell renderers how to format the content. Here's the entire "language" of a basic file:

# This is a heading

This paragraph has **bold** text, *italic* text, and a [link](https://example.com).

- A bullet list
- With two items

1. A numbered list
2. With two items

> A blockquote for emphasis

`inline code` and code blocks

| Name | Role |
|------|------|
| Ada  | Dev  |

Rendered, that becomes a formatted page with a heading, styled text, lists, a quote, and a table. But the file itself, open in any text editor, is still 100% readable as-is — no hidden XML, no binary headers, no proprietary markup. That's the defining feature of the format.

Why .md Files Exist

Markdown was created in 2004 by John Gruber to let people write for the web without learning HTML. The format caught on because it solved a real problem: writers wanted formatting, but HTML was too verbose for quick notes and drafts.

The format hits a sweet spot no other format matches:

• Plain text — no proprietary binary format, opens in literally any editor
• Version-control friendly — diffable, mergeable, reviewable like code
• Renders everywhere — GitHub, documentation sites, notes apps, chat tools
• It's the web's default — practically every developer platform speaks it

.md vs Other File Formats

The .md format is the only one that's both human-readable in raw form and renderable into a styled document:

The .txt file is readable but unformatted; the .docx is formatted but proprietary. Markdown splits the difference: readable as text, renders as a document, and treats formatting as something you can review line by line.

Markdown Flavours

Markdown has several "flavours" — the core syntax is the same, but different platforms add extras:

Where You'll Find .md Files

• GitHub / GitLab — README.md greets you in every repository; the most recognisable .md file on the web
• Documentation sites — Docusaurus, Next.js docs, and most static sites are built from .md files
• Note-taking apps — Obsidian, Logseq, and Bear store notes as plain .md files
• AI agent configs — CLAUDE.md and AGENTS.md are .md files that coding agents read at session start
• Blogging — static site generators like Hugo, Jekyll, and Astro use .md for posts
• Technical writing — API docs, guides, and wikis

How to Open an .md File

Since .md files are plain text, every route works — the question is what you want out of it.

Option 1 — Open It in Your Browser (Recommended)

The quickest route, and it needs no software at all:

1. Open a markdown file viewer.
2. Drag the .md file into the box, or paste its contents.
3. Read the formatted document — headings, tables and code blocks all render.

Why this is usually the best option: you see the file as intended, not as a wall of ## symbols. It works on any operating system, including Chromebooks and tablets, and there's nothing to install or update.

Option 2 — Open It on Windows

• Notepad — right-click the file → Open with → Notepad. You'll see the raw text; formatting shows as #, **, -.
• VS Code — open the file, then Ctrl+Shift+V for a rendered preview side by side with the source. Best choice if you'll edit it.
• Word / WordPad — not recommended. They don't understand Markdown; you'll get an unformatted wall of text with the syntax marks intact.

Option 3 — Open It on macOS

• TextEdit — opens .md as plain text. Use Format → Make Plain Text first so it doesn't try to add rich-text formatting.
• VS Code — same Cmd+Shift+V preview as Windows.
• Xcode — opens .md files with a basic rendered view; handy if you're already in it.

Option 4 — Open It on Linux

• Any text editor — Gedit, Kate, Mousepad — shows the source.
• VS Code or another editor with a Markdown preview gives you the rendered view.
• Terminal users: less file.md reads it raw; glow file.md renders it nicely in the terminal if you have it.

Option 5 — Open It on Your Phone

• iPhone — the Files app previews some .md files; for reliable rendering, paste the content into a browser-based viewer.
• Android — open with any text editor, or paste into the viewer.
• Dedicated Markdown apps work too, but for a one-off read a browser tab is faster.

How to Create an .md File

Open any text editor, write text, save with a .md extension. That's genuinely all there is:

# My first document

Hello, world. **Bold words** cost nothing here.

GitHub will render it, your notes app will render it, your docs site will render it. No special software, no export step, no format conversion.

Markdown Live Preview — See Your Formatting as You Type

Markdown live preview is the ability to see the formatted result of your .md file while you're writing it — no save, no compile, no separate render step. Type # Heading, and the editor instantly shows a large bold heading. Add **bold**, and the text darkens on the spot.

Live preview matters because Markdown's biggest weakness is imagination: raw ## and ** symbols don't tell you how the final document will look. A live preview closes that gap in real time.

How It Works Under the Hood

A live-preview editor is a small render loop:

textarea.addEventListener('input', () => {
  const html = marked.parse(textarea.value);   // parse markdown → HTML
  preview.innerHTML = DOMPurify.sanitize(html); // sanitize, then render
});

Three things make it feel instant:

1. Incremental parsing — only re-render the section that changed, not the whole file.
2. Debouncing — batch rapid keystrokes into a single render (usually 50–200 ms).
3. Sanitisation — raw HTML/scripts in markdown are cleaned before rendering, so a malicious pasted file can't execute in the preview.

Why Live Preview Transforms Your Writing

The result isn't just nicer — it's measurably faster. Writers stop second-guessing syntax, catch broken links and table misalignments immediately, and spend their attention on content.

Where You'll Find Markdown Live Preview

Live preview is now the default expectation across the ecosystem:

• VS Code — Ctrl+Shift+V (preview tab) or Ctrl+K V (side-by-side split); updates continuously as you type and follows your cursor.
• Obsidian — "Live Preview" is the default editing mode: formatting renders inline in the source pane.
• Typora / MarkText — fully WYSIWYG: the document itself is the preview.
• Notion — slash-commands and block editing hide Markdown entirely; you never see source, only preview.
• Online tools — StackEdit, HackMD, Dillinger, and browser-based editors like MD Vessel ship split-pane live preview out of the box.
• Blogging platforms — Ghost, Bear, and most static-site admin panels preview posts while you draft.

Why Does My .md File Look Like Plain Text With # and *?

You're seeing the source, which is the point of Markdown — the file is readable without any special software. Those characters are the formatting instructions:

Any viewer, editor preview, or site like GitHub renders it into a formatted document.

What About CLAUDE.md and AGENTS.md?

You'll see these two specific .md files increasingly often: they're how AI coding agents get project context. CLAUDE.md is read by Claude Code at session start; AGENTS.md is the emerging cross-agent convention. Both are normal Markdown — the magic is in who reads them.

Frequently Asked Questions

Is .md the same as Markdown? Yes. .md is the file extension for Markdown files. Markdown is the format itself.

What's the difference between .md and .markdown? Only the extension — the content is identical. .md is simply the more common of the two.

Can I change .md to .txt? You can rename it, but the content stays the same — it's already plain text. You'll lose syntax highlighting and rendering in tools that recognise .md files.

Can Word open .md files? Word opens .md as plain text but won't render the formatting. Convert to .docx or use a Markdown viewer instead.

Is a .md file safe to open? Yes. An .md file is plain text; it can't run code or install anything. Opening an .md file is no riskier than opening a .txt file.

What program creates .md files? Any text editor. Write text, save with a .md extension — no special software required.

How do I convert an .md file to PDF? Use a converter, or print the rendered preview to PDF from your browser.

Why do developers prefer .md files? They're version-control friendly (clean diffs), universally readable, and render nicely on GitHub, docs sites, and note apps without any conversion step.

What does "live preview" mean in markdown editors? It means the rendered document updates in real time as you type — no manual refresh, save, or build step between writing and seeing the formatted result.

Is live preview the same as a markdown viewer? Not quite. A viewer renders a finished file for reading. Live preview renders while you edit, inside the editor. Many editors are both: the preview pane is a viewer running live.

Does live preview slow down large documents? Modern editors use incremental parsing and debouncing, so previews stay smooth even on long files. If an editor chokes on big docs, it's doing full re-parses — a sign of a weak implementation.

Can I trust what I see in live preview to match GitHub? Usually yes — if the editor uses a CommonMark/GFM-compliant parser (VS Code, Obsidian, and most online editors do). Differences appear only with exotic extensions, not core syntax.

Related

• Markdown Cheat Sheet — Every Syntax Element in One Table
• What Is an .md File?
• How to Open an .md File
• How Claude Code Uses CLAUDE.md
• What Is an AGENTS.md File?