What is a .md file, and how do you open one?

You found a file that ends in .md and want to know what it is. Short version: it is a text file. You can open it with tools you already have.

This page covers what is inside a .md file, where they come from, and how to open, read and create one.

What is inside a .md file

A .md file holds plain text written in Markdown. Markdown uses a few symbols to mark formatting. Here is a short example:

# Release checklist

Owner: Jane Doe

- [x] Update the version number
- [ ] Run the tests
- [ ] Write the release notes

See the [setup notes](docs/setup.md) first.

Read raw, it is already clear. The # line is a title. The lines with - are a list. The [ ] and [x] are open and done tasks. The square and round brackets make a link.

A Markdown viewer shows the same file formatted. The title is large, the list has bullets, the tasks are check boxes, and the link is clickable. The Markdown syntax guide shows every common element both ways.

.md, .markdown and .mdx

• .md is the usual extension for Markdown.
• .markdown is the long form. The content is the same. Most tools open both.
• .mdx is a different format. It mixes Markdown with code for website components. A plain Markdown viewer may not show it the way its author meant.

You may also see .mdown or .mkd in older projects. Those are Markdown too.

Where you see .md files

• README.md. The front page of most code projects. It explains what the project is and how to use it.
• Documentation. Many docs sites are written as folders of .md files.
• Notes. Some note apps save each note as a .md file.
• AI agent files. Coding agents read instruction files written in Markdown. Claude Code reads CLAUDE.md, and Codex reads AGENTS.md. Agents also write plans, handoffs and reports as .md files. See what an agent handoff file is.

Markdown is popular for all of these for the same reason. The file is readable as plain text, works with version control, and does not lock you into one app.

How to open a .md file

You have three kinds of options. Pick by what you need to do.

Read it as plain text

Any text editor works. On Windows, right-click the file, choose Open with, and pick Notepad. On a Mac, TextEdit opens it. On Linux, use the text editor that came with your desktop.

From a terminal, cat README.md prints the file, and less README.md lets you scroll it.

This is fine for short files. Long files with tables are harder to read this way.

Read it formatted

A Markdown viewer or reader shows the file the way it was meant to look. Many code editors include a Markdown preview. There are also standalone Markdown apps for every desktop system.

Read formatted when the file is long, has tables or task lists, or when you only need to read it, not change it.

Edit it

Any text editor can edit a .md file, since it is plain text. A Markdown editor adds a preview or lets you edit the formatted page directly.

One thing to watch: some editors rewrite the whole file when they save. They change list markers or wrap lines. The text means the same, but every changed line shows up in a diff. This matters when other people or agents work on the same file.

How to create a .md file

1. Open a plain text editor.
2. Write your text, using Markdown symbols where you want formatting.
3. Save it with a name that ends in .md, such as notes.md.

Two common traps:

• Windows may add .txt. Notepad can save notes.md as notes.md.txt. In the save dialog, set the file type to All files. Turn on file name extensions in File Explorer so you can see the real name.
• TextEdit may save rich text. On a Mac, TextEdit starts new documents as rich text by default. Choose Format > Make Plain Text before you save.

Where Skimmark fits

Skimmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released. The app itself has no AI features.

Planned for v1: open a .md file and see it rendered as one clean page, with check-box lists, tables and code blocks. Live Reload keeps your Reading Position when an agent rewrites the file. Edits on the rendered page save without touching the lines you did not change. When it cannot promise that, Document Lock turns editing off for that file.

You can see what Skimmark is and follow along at skimmark.com.