How to open a .md file

What a .md file is

MD stands for Markdown, a way of writing formatted text using ordinary punctuation. A # at the start of a line means "this is a heading". Two asterisks around a word mean "bold". That is the whole idea.

The consequence is the useful part: the file is plain text, so it opens in anything, weighs a few kilobytes, works in every version of every operating system, and will still be readable in thirty years. It is why almost every software project ships its instructions as README.md, and why notes apps, static websites and documentation are written in it.

A .md file is not a Word document, not compressed and not proprietary. There is nothing to convert and no program you are obliged to buy. You can even read it in Notepad — you will simply see the # and * marks instead of headings and bold text, which is what most people are hitting when they search for this.

You will also meet .markdown, .mdown, .mkd and .mdx. The first three are the same thing under a longer name. .mdx is Markdown with embedded components for JavaScript sites, and most readers will show its text and ignore the components.

Open one right now, in a browser

This is the fastest answer on every device and needs nothing installed. It works the same on Windows, Mac, Linux, Android and iPhone.

1. Open the web app. markdowneye.com/app — no account, no sign-in, no upload.
2. Press the Open button in the toolbar, or the Open a file button in the middle of an empty window. On a keyboard, Ctrl + O.
3. Pick your .md file. Or skip the dialog and drag the file onto the window.

It renders with a contents list down the side that follows where you are, highlighted code, real mathematics and diagrams drawn from text. There is a Split mode if you want to edit while you read, and eight themes if the default is not to your taste.

Windows

Windows has no built-in Markdown renderer, which is the whole problem: double-clicking a .md file on a clean install either asks what to open it with or hands it to Notepad, and Notepad shows the marks. These are the real options.

Make it open on double-click

Once a program is installed, tell Windows to use it. Two routes, both permanent.

From the file

1. Right-click the .md file. On Windows 11 the short menu appears first; choose Open with, then Choose another app.
2. Pick the program from the list, or scroll to More apps if it is not shown.
3. Press Always, not Just once. On Windows 10 the same thing is a checkbox reading Always use this app to open .md files.

From Settings

1. Open Settings with Windows + I, then Apps › Default apps.
2. Type .md into the box labelled Set a default for a file type or link type.
3. Click the result and choose the program. Repeat for .markdown if you have files with the longer extension.

The installer for Markdown Eye registers itself as a handler for .md, .markdown and .pdf, so in most cases it will already be in that list — Windows still asks you to confirm the choice, which is by design and not something an installer is allowed to skip.

Mac

TextEdit opens .md files and shows the marks, the same as Notepad. To read one properly, either use the web app in Safari or Chrome, or install a Markdown editor — VS Code, Obsidian and Typora are all on macOS. Quick Look (select the file, press Space) shows the raw text as well.

To change what double-click does:

1. Select the file and press Command + I for Get Info.
2. Open the Open with section and pick the program.
3. Press Change All… to apply it to every .md file rather than this one.

There is no Windows-style installer for Markdown Eye on macOS — the desktop build is Windows only. The browser version has the same features and runs on any Mac.

Linux

Everything is already there. cat README.md or less README.md shows the text; xdg-open README.md hands it to whatever the desktop has registered. For a rendered view without installing anything, open the web app; for a terminal one, glow and bat are both packaged in most distributions. To change the default, right-click the file, choose Open With Other Application, and use the set as default option in that dialog — the exact wording depends on your desktop rather than the distribution.

Android and iPhone

Phones have no Markdown support of their own, and the file managers that will open a .md file mostly show it as plain text. The browser is the practical answer on both:

1. Open markdowneye.com/app in Chrome, Safari or whatever you use.
2. Tap Open a file and pick the document. On iPhone the picker reaches into Files, iCloud Drive, Dropbox and Google Drive; on Android, Downloads and Drive.

If you do this often, add it to your home screen — Share › Add to Home Screen in Safari, or the browser menu on Android — and it opens without browser furniture around it.

An emailed .md attachment is the one awkward case: both mail apps will offer to preview it as text. Save it to Files or Drive first, then open it from the app above.

Turn it into a PDF or a Word file

PDF is built in and needs no other tool. Open the document, press Ctrl + P (Command + P on a Mac), and choose Save as PDF as the destination — or Microsoft Print to PDF on Windows. What you get is the rendered document, with the headings, code and diagrams intact, not the raw marks.

Word has no direct route. The reliable way is pandoc, a free converter:

pandoc README.md -o README.docx

For a one-off, selecting the rendered document, copying it and pasting into Word keeps the headings, bold, lists and tables, which is usually what was wanted.

Why is the text full of # and * symbols?

Because you are looking at the source rather than the document. Those marks are the formatting: # at the start of a line means a heading, **bold** means bold, - starts a bullet. Notepad has no idea what they mean, so it shows them literally. A reader interprets them and shows you the heading instead.

Same file, two ways of looking at it:

Nothing is wrong with the file and nothing needs repairing. If you want to know what the rest of the marks mean, the Markdown cheat sheet has every one of them with its result beside it.

When it does not work

The file is called notes.md.txt. Notepad appends .txt unless you set Save as type to All Files. Rename it and drop the .txt. If you cannot see the extension at all, turn on View › Show › File name extensions in File Explorer first.

“Windows can’t open this file”. Nothing is assigned to .md yet. Pick a program with Open with, or set a default using the steps in making it the default.

The browser downloads it instead of showing it. That is the server sending the file as something to save rather than something to display, and it is not a fault on your end. Use Open a file in the web app on the copy you just downloaded.

It opens empty, or the size is 0 KB. On OneDrive and iCloud Drive the file may only be a placeholder that has not downloaded yet. Right-click it and choose Always keep on this device, wait for the tick, then open it again.

Accented or non-English characters look like gibberish. The file was saved in an older encoding. Re-save it as UTF-8 — in Notepad that is Save as and the Encoding dropdown at the bottom.

Questions people actually ask

Next

• Markdown cheat sheet — every mark you will meet in a .md file, with what it renders as.
• Open the web app — read or edit a file right now, free, with no sign-in.
• Download for Windows — installer or portable, so double-clicking a .md file just works.