Markdown cheatsheet · Open a README.md
How to open a README.md file
It's a plain text file with formatting written in punctuation. Nothing is corrupted; you're just seeing the source instead of the rendered page.
What you're looking at
You downloaded something, or cloned a repository, and there's a file called README.md sitting in the folder. You opened it and got a wall of text with hashes, asterisks and brackets in it.
Nothing is broken. That file is written in markdown, a way of adding formatting to plain text using punctuation. The # marks are headings. The **stars** make bold. It looks like this because you're seeing the raw source instead of the rendered result, the same way HTML looks like tag soup until a browser draws it.
On GitHub, that same file is what's displayed, formatted, on the project's front page. Your text editor just doesn't do that part.
How to read it properly
The easiest way: read it on GitHub
If the file came from a GitHub project, the README is already rendered on the project page. Nothing to install, and it's the same file. This is the right answer surprisingly often.
If the file is only on your disk
Open it in something that renders markdown. A dedicated editor shows the file formatted, the way its author meant it: maxdown is free and runs on macOS, Windows and Linux. VS Code works too if you already have it (Ctrl+Shift+V for the preview).
If you just need to skim it once
Notepad or TextEdit will show it. Raw markdown is designed to stay readable, which was the whole point of the format: the hashes and stars are noise, but the text underneath is plain English.
Platform-specific steps: on Windows, on Mac.
What the symbols mean
Enough to read almost any README without looking anything else up:
| You see | It means |
|---|---|
# Title | A big heading. More hashes, smaller heading. |
**text** | Bold |
*text* | Italic |
`code` | A command or filename |
``` | Start or end of a block of code you're meant to copy |
- item | A bullet point |
[text](url) | A link. The text is what you'd click. |
 | An image. The ! is the difference. |
> text | A quote or a callout |
The full cheatsheet covers the rest, but that table is 90% of what a README uses.
Why is it called README?
Convention, and an old one: a file named README sorts near the top of a directory listing and is the obvious thing to open first. It predates markdown by decades; plain README files with no extension go back to the 1970s. The .md on the end is just the modern part, added once GitHub started rendering them.
Common questions
Can I delete the README?
You can, it's only documentation and nothing runs it. But it's usually the only instructions you have for whatever you just downloaded, so read it first.
Do I need to install anything to read a README?
No. Any text editor opens it. You'd install something only if you want it rendered, or if you're going to be reading .md files regularly.
Why is README.md not opening at all?
If double-clicking does nothing, your system has no app registered for .md. Right-click and use "Open with" to pick one; see the Windows and Mac guides for making that stick.
Is README.md the same as readme.txt?
Same purpose, different format. A .txt readme is plain text with no formatting. A .md one is plain text with formatting encoded in punctuation, which renders on GitHub.