How to read a README file on Mac

A README file is a Markdown file, so to read it the way it's meant to look, open README.md in a Markdown reader like Unmarked. Double-click it in Finder if Unmarked is your default Markdown app, or open Unmarked and press Open. Read mode shows the headings, lists, code, and tables formatted instead of as raw symbols.

What a README actually is

A README is the file a project shows you first. It explains what the project is, how to install it, and how to use it. The file is almost always named README.md, and that .md means Markdown: plain text with a few formatting characters mixed in.

Open one in a text editor and you see the raw version. Headings start with #. Code sits between backticks. Links look like [text](url). It's all readable, but it's not what the author intended you to see. A Markdown reader turns those characters into a real document, so a ## Installation line becomes an actual heading and a fenced block becomes a code box you can copy from.

So "reading a README on Mac" comes down to one choice: read the raw text, or read the rendered document. For anything longer than a few lines, rendered wins.

Open it in Unmarked

If you're in Finder and Unmarked is set as your default Markdown app, double-click README.md and it opens there. To set that once: right-click the file, choose Get Info, pick Unmarked under "Open with," and click "Change All."

If you'd rather start from the app, open Unmarked and press Open (⌘O), then pick the file. Unmarked opens .md, .markdown, .mdown, .mkd, and plain .txt, so a README under any of those extensions works.

If the README comes up in Write mode, press ⌘E for Read: the rendered document, no syntax showing. The outline sidebar lists every heading, so you can jump to "Installation" or "Usage" without scrolling. Code blocks sit in their own boxes, colored by language when the author tagged the fence with one, such as bash. Most of what you want from a README is a command to paste into your terminal. Select it and press ⌘C. For a whole block, Write mode has a copy button on the block your cursor is in.

What a typical README looks like

Here's the shape of a normal project README in raw Markdown:

# Tidemark

A command-line tool for renaming photo files by date.

## Install

```bash
brew install tidemark
```

## Usage

Run it against a folder:

```bash
tidemark ./vacation-photos
```

## Options

| Flag | What it does                       |
|------|------------------------------------|
| `-r` | Recurse into subfolders            |
| `-n` | Dry run; print changes, write none |

## Tasks

- [x] Rename by EXIF date
- [ ] Undo last run
- [ ] Custom date formats

Read that as raw text and your eye trips over every #, pipe, and backtick. Read it rendered and you get a titled document with a heading for each section, two command boxes, a clean two-column table, and a checklist showing what's done. Same file, far less work to follow.

What renders, and what doesn't

The task list at the bottom becomes real checkboxes, and they're clickable. Tick one and it saves back to the file. Want the raw Markdown? Press ⌘E for Write mode.

One thing in a README behaves differently. Status badges at the top, the little "build passing" graphics, are remote images loaded from the web. Unmarked doesn't fetch anything from the web, so they show as their alt text instead of pictures. Images stored next to the file render normally.