Open and read a Markdown file on Mac, Windows and Linux

Your AI agent finished a task and left a file called something like notes.md. Or a colleague sent one over. You double-click it, and either nothing useful happens or your computer asks which app to use. You just want to read it.

A .md file is plain text with a few marks for headings, lists and links, and any text editor can open it. If you want the background, here's what a .md file is. This page skips that and gets you reading.

Below, each system gets the same four moves: open the file once as plain text, set a default app for .md files, read it in a terminal, and see it formatted. The plain text ways come first, then a free editor that shows it formatted. At the end there's a short list of what a good Markdown reader should add on top.

On a Mac

Open it once as plain text

TextEdit opens plain text documents. To open your file in it just this once:

1. Control-click the file in the Finder.
2. Choose Open With.
3. Choose TextEdit.

You can also select the file in the Finder and choose File > Open With, then pick the app. Or drag the file onto the app's icon in the Finder or the Dock.

TextEdit shows the file as plain text. You'll see the raw marks: # in front of headings, two asterisks around bold words, brackets around link text. That's normal: you're seeing the file exactly as it was written.

Make one app the default for .md files

If you'll get a lot of these files, set a default so a double-click opens them in the app you want:

1. Select a .md file in the Finder.
2. Choose File > Get Info. You can also Control-click the file and choose Get Info.
3. Click the arrow next to "Open with."
4. Click the pop-up menu and choose an app.
5. Click Change All.

From then on, every file of that type opens in the app you picked.

Read it in a terminal

If you already have a terminal window open in the folder, two commands cover most needs:

less notes.md

less shows the file one page at a time. Press / to search and q to quit.

cat notes.md

cat prints the whole file to the screen in one go. It's handy for short files. For anything long, less is easier on the eyes.

See it formatted

To see real headings and bullets, use a free code editor that has a Markdown preview. It's a separate install, not part of macOS.

Once it's installed:

1. Open your .md file in the editor.
2. Open its Markdown preview.

Some editors can also show the raw text and the preview side by side.

On Windows

Open it once as plain text

Notepad opens .md files as plain text:

1. Right-click the file.
2. Choose Open with.
3. Pick Notepad.

Like TextEdit on a Mac, Notepad shows the raw text with the Markdown marks in place.

Make one app the default for .md files

1. Open Settings.
2. Select Apps, then Default apps.
3. In the search bar, type the file extension: .md
4. Select the result that matches.
5. Choose an app.

After that, double-clicking any .md file opens it in that app.

Read it in a terminal

PowerShell 7 has a command called Show-Markdown. It shows a Markdown file in the terminal in a readable format, or in the browser as HTML.

Show-Markdown was introduced in PowerShell 6.1, and PowerShell 7 has it. PowerShell 7 is a separate install. It doesn't replace Windows PowerShell 5.1. It installs to a new folder and runs side by side with it.

See it formatted

A free code editor with a Markdown preview works on Windows too, as a separate install. Open your .md file in it, then open its preview.

Show-Markdown, covered above, is the other route on Windows. It shows the file in a readable form without opening an editor.

On Linux

The steps below use the xdg-open and xdg-mime commands in a terminal.

Open it once

In a terminal, in the folder with the file:

xdg-open notes.md

xdg-open opens a file in your preferred application. What that is depends on your setup. If it opens in a text editor, you'll see plain text with the Markdown marks showing.

Make one app the default for .md files

You need two things: the file type your system has given .md files, and the name of the app's .desktop file. Ask your system for the type instead of guessing:

xdg-mime query filetype notes.md

That prints the file type. Use exactly what it prints in the next command, along with your app's .desktop file name. Here, your-app.desktop and the-type-it-printed are placeholders:

xdg-mime default your-app.desktop the-type-it-printed

This asks your desktop to make that app the default for the type. To check what the default is now:

xdg-mime query default the-type-it-printed

Read it in a terminal

The same two commands as on a Mac:

less notes.md
cat notes.md

less pages through the file. Press / to search and q to quit. cat prints it all at once. If the file is an agent's plan, the guide to reading a Claude Code plan file without an IDE has more on reading it from the terminal.

See it formatted

A free code editor with a Markdown preview works on Linux too, as a separate install. Open the file in it, then open its preview.

Plain text or formatted: which to use

Both are fine. Plain text shows you every character, which helps when you need to copy a command out of the file or check exactly what the agent wrote. Formatted is faster to skim, because headings stand out and lists line up.

A quick rule:

• Skimming a plan or a summary? Use a formatted preview.
• Copying commands, checking front matter, or editing? Use plain text.
• On a server, or in a hurry in a terminal? Use less.

What a good Markdown reader should add

The tools above get you reading today. Agents keep rewriting their Markdown files, and here's what a reader made for that should do.

Open formatted. A reader built for this should open the file formatted from the start.

Notice when the file changes. Agents rewrite files while you read. A good reader should pick up the new version on its own and keep you on the same heading instead of jumping to the top. Sashmark is being built for this; the roadmap shows where it stands.

Show what changed since you last read it. When the same file comes back with edits, you want the new parts, not a full re-read.

Open the file from wherever it lives. Agent output lands in project folders, temp folders and handoff folders. A good reader should open any .md file with a double-click. That's also part of what Sashmark is being built for.

Stay out of the way. No sign-in to read a local file, and no project setup before you see the first line.

Where Sashmark fits

Sashmark is a Markdown reader and editor for people whose AI agents write Markdown, being built for Mac, Windows and Linux. It is in development and has not been released, and the app itself has no AI features. When Sashmark is released, installers will come only from the Sashmark website. See the planned features, the help pages and the roadmap for where each part stands.

Sashmark is in development. See what it is at sashmark.com.