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 rendered. 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.

Either way you land in Read mode: the rendered document, no syntax showing. The outline sidebar lists every heading, so you can jump to "Installation" or "Usage" without scrolling. Code blocks have a copy button, which matters for a README, since most of what you want from one is the command to paste into your terminal.

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

```
brew install tidemark
```

## Usage

Run it against a folder:

```
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 copyable 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

Everything in that example renders the way the author wrote it: the headings, both command blocks, the two-column options table. 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, or Split mode to keep source and rendered view side by side.

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 has no network access, so they show as their alt text instead of pictures. Images stored next to the file render normally.