SnapshotJuly 2026a point-in-time write-up, left as written

A markdown viewer

You’ll read a lot of .md files: specs, AGENTS.md, research notes, Claude’s output, this course. You want a dedicated tool for reading them, separate from whatever you use to write code.

Install Obsidian

I recommend Obsidian, a markdown-native reader and editor that treats a folder of .md files as a browsable knowledge base. Install via Homebrew:

brew install --cask obsidian

Or download from obsidian.md.

Point Obsidian at any folder that contains .md files (your repo’s docs/, your research directory, a scratch notes folder) and it gives you an outline, full-text search, wikilinks ([[filename]]), and a graph view of how the files cross-reference. You don’t have to use any of the heavier features to benefit from it as a viewer.

Obsidian is free for personal use. A lighter alternative if you want “just a viewer” is VS Code’s built-in markdown preview (Cmd-Shift-V on any .md file), which works fine and is already installed if you’ve got VS Code.

A note on installing random tools

Since you’ll end up doing this more as you go: before trusting any app or GitHub repo, look at the developer, the star count, recent activity, and whether the project actually gets updates. Obsidian is mature, actively developed, and used widely. Plenty of things you’ll stumble across aren’t. The same heuristic applies every time you grab a community tool.

Why a dedicated viewer

VS Code works, but it’s designed for writing code, heavier than reading warrants. A purpose-built markdown tool gives you a cleaner surface for reviewing specs, diffs, and Claude’s generated docs.

More fundamentally, why markdown at all instead of Word or Google Docs? A .md file is just a .txt file with a few conventions (# for headings, * for bold, - for bullets). That means:

See Markdown as the medium for why this matters for everything you build.

Resources