Read an MD file in the terminal: cat, less and pandoc

An agent just told you it wrote notes.md, and you're already in a shell. You can read the file right there. Markdown is just text, so small tools that come with many systems can show it.

This guide moves from raw to formatted: cat for short files, less for long ones, and pandoc when you'd rather not read around the syntax marks. Every command ran on the same sample file, and each output shown is what came back.

The sample file

All examples use one short file named notes.md:

# Release notes

Jane Doe asked for a **short** summary of the *open* items.  

## Open items

- Fix the [setup guide](/blog/setup)
- Rename `config.yaml`

```sh
make test
```

Line 3 ends in two spaces. You can't see them yet. cat -e makes them visible.

Print it with cat

cat reads a file and writes it to standard output. For a file that fits on one screen, that's all you need:

cat notes.md

You get the text exactly as stored: the # before each heading, the ** around "short", the brackets and parentheses of the link, and the backtick lines of the code fence. The CommonMark spec calls Markdown "a plain text format," and the design goal it quotes is a source that can be read as-is. For short notes, the raw text often reads fine.

Two flags help when you're checking a file rather than skimming it:

1. Number the lines. cat -n notes.md puts a number in front of every line. Handy when an agent's message points you to "line 7".
2. Show line ends. cat -e notes.md prints a $ after every line. Line 3 of the sample comes out as ...the *open* items. $, so the two trailing spaces show up as a gap before the $. The post on raw and rendered views shows why stray spaces like these can matter.

The catch: cat dumps everything at once. A 900-line report scrolls straight past you.

Page through it with less

less displays a file in a terminal one screen at a time. It can start before it has read all of its input, so large files start showing quickly.

less notes.md

These keys cover most reading, all taken from the less manual:

1. Move forward a screen with Space. Press g to jump to line 1 and G to jump to the last line.
2. Search by typing /, a word, then Enter. For example, /Open jumps forward to the next line containing "Open". The pattern is a regular expression, and searches are case-sensitive by default.
3. Next match with n. N repeats the search in the other direction.
4. Quit with q.

Two flags help here. less -N notes.md numbers every line on screen. less -i notes.md makes searches ignore case, but a pattern with any capital letter in it still matches case exactly.

A handy search for long reports is /^#, which finds lines that start with #. In CommonMark, an ATX heading opens with one to six # characters. Spaces or tabs must follow them, unless nothing else is on that line, and the # may sit after up to three spaces of indent. So /^# lands on most headings. It can also stop on a shell comment inside a code fence, because fence content is literal text, not Markdown.

If a heavy file still crawls, the guide to large Markdown files walks through finding what's weighing it down.

Read it formatted with pandoc

Raw syntax gets tiring over a long file. pandoc converts Markdown into other formats, and when you don't name an output file it writes to standard output. So you can format a file and pipe it into less in one line.

Plain text

pandoc -t plain notes.md | less

-t picks the output format, and plain means plain text. The sample came out like this:

Release notes

Jane Doe asked for a short summary of the open items.

Open items

- Fix the setup guide
- Rename config.yaml

    make test

The # marks, asterisks and backticks are gone. The link kept its text, "setup guide", but the target setup.md didn't appear in this run. The code fence became an indented block. When link targets matter, read the raw file as well.

pandoc also rewraps paragraphs. By default it wraps lines to the column width, which is 72. Add --columns=60 for narrower lines, or --wrap=none to leave lines unwrapped.

Colored text

pandoc's ansi format is text with ANSI escape codes, meant for viewing in a terminal.

pandoc -t ansi notes.md | less -R

The -R matters. Out of the box, less displays control characters in caret notation, so the codes would print as text. With -R, less passes ANSI color sequences and OSC 8 hyperlink sequences to the terminal unchanged. To see what those codes look like, pipe through cat -v, which makes control characters visible:

pandoc -t ansi notes.md | cat -v

The first line it printed, for the heading:

^[[1m^[[23m^[[39m^[[49m^[[24m^[[29mRELEASE NOTES^[[0m

In the sample run, the level-one heading came out in capitals, list items got a • bullet, and the link text sat inside an OSC 8 hyperlink sequence. Many terminals show these codes as bold, italic, color and underline, and some may let you click the link. Others may show only part of that styling. If you see ^[[ strings on screen, check that -R is there.

For color on the raw syntax instead, the dark mode guide pairs a search pattern with less -R.

Which Markdown pandoc reads

When you don't name an input format, pandoc tries to guess it from the file's extension. Its own reader, called Pandoc's Markdown, is one of several Markdown readers it lists. To use its CommonMark reader instead, add -f commonmark:

pandoc -f commonmark -t plain notes.md

For this sample, the output matched the default run. A file that leans on extras such as footnotes may come out differently, since the CommonMark spec treats footnotes as an add-on some parsers offer.

Pick the right one

• Quick look at a short file: cat notes.md.
• Checking line numbers or stray spaces: cat -n or cat -e.
• Long file, raw text, searching: less notes.md.
• Long file, reading for meaning: pandoc -t plain notes.md | less.
• Same, with headings and emphasis styled: pandoc -t ansi notes.md | less -R.

Raw and formatted reads catch different things. A formatted read may hide link targets and the exact marks an agent typed. A raw read makes a long report harder to take in. New to the format? This .md file explainer covers the basics. When an agent run leaves you many files, this triage routine helps you pick which one to open first.

Where Sashmark fits

A terminal suits a fast check. Long reads are a different job, and some people would rather have a calm rendered page with no syntax marks or escape codes in the way. That page is the goal for Sashmark, a desktop Markdown reader and editor being built for the files your AI agents keep producing. It is in development and has not been released. The app itself has no AI features. Live rendering is planned for v1, covering block quotes, tables, code blocks, headings, check-box lists, plain lists, links and local images, with light and dark modes that track your system setting. For detail and status, check the planned features, the help pages and the roadmap.

Follow the project at sashmark.com.