Markdown viewer

ws view shows a Markdown file rendered for the terminal, and re-renders it whenever the file changes. Use it to read an agent’s plan, a project’s log or a README while it’s being written, in a pane next to the agent writing it.

The prefix key is Ctrl-Space: prefix V means press Ctrl-Space, let go, then press V. Every key is in Keys and mouse.

Opening a file

ws view README.md                  # in this pane; q closes it
ws view --split plan.md            # inside wrkstrms: in a new pane on the right
ws view --split --below log.md     # inside wrkstrms: in a new pane below

Flag	Effect
`-s`, `--split`	Open the viewer in a new pane beside this one, on the right, and focus it
`--below`	With `--split`: put the new pane below instead of on the right

The file must exist when you run the command. The path is relative to the directory you run it in.

Without --split, the viewer takes over the pane you run it in until you press q. --split only works in a wrkstrms pane; anywhere else, ws view --split shows the file in the current terminal instead.

From the keyboard: `prefix V`

Inside wrkstrms, prefix V asks for a file, with README.md filled in. Type a path and press Enter. An empty path means README.md.

The path is relative to the focused pane’s current directory: the directory of the program running in it. If ws can’t tell, it uses the workstream’s directory, then wrkstrms’s own. The viewer opens in a new pane on the right of the focused pane, labeled view.

“View Markdown…” in a pane’s or tab’s right-click menu opens the same dialog.

Live reload

The viewer checks the file’s modification time about every 300 milliseconds and re-renders when it changes, keeping your place. Press r to re-read the file by hand.

If the file can’t be read (for example, it was deleted and not yet written again), the viewer shows waiting for <path> and picks the file up again once it’s back.

The text also re-wraps when the pane is resized.

Keys

Key	Action
`j` / `↓`	Scroll down a line
`k` / `↑`	Scroll up a line
`d` / `u`	Down / up half a page
`Space`, `f` or `PageDown`	Down a page
`b` or `PageUp`	Up a page
`g` or `Home`	Top
`G` or `End`	Bottom
`]` / `[`	Next / previous heading
`/`	Search: type a query, Enter to find, Esc to cancel
`n` / `N`	Next / previous match
`r`	Reload the file
`q`, `Esc` or `Ctrl-C`	Close the viewer

The mouse wheel scrolls three lines at a time.

Search ignores case and wraps around the document. The line with the match is highlighted and scrolled into view. If nothing matches, the status line says so.

The status line at the bottom shows VIEW, the file name, and how far through the document you are (all when it fits on screen, otherwise a percentage). On the right it shows the main keys, the search as you type it, or a message.

What renders, and how

The viewer reads CommonMark with the common extensions: tables, task lists, strikethrough and footnotes. Text wraps to the pane’s width.

Markdown	Rendered as
`# Heading`	Bold, colored, with a heavy rule underneath
`## Heading`	Bold, in a second color
`### Heading` and deeper	Bold, with the `###` marks kept
`bold`, `italic`, `~~struck~~`	Bold, italic, struck through
`code`	Highlighted on a shaded background
Fenced or indented code blocks	A shaded block, with the language named on its top line. Long lines are cut, not wrapped.
Bulleted lists	`•`, then `◦` and `▪` for nested lists
Numbered lists	Numbered, starting from the list’s first number
Task lists	`☐` for open, `☑` for done
Tables	Box-drawn, with a bold header row. Columns shrink to fit and long cells are cut.
`> quotes`	Indented behind a `│` bar, in dim italics
Links	Underlined, in the link color. The URL isn’t shown.
Images	`[image: alt text]`
`---`	A horizontal rule
Footnotes	`[^label]` references and definitions
HTML comments	Hidden
Other HTML	Shown as written, dimmed

Limitations

No images. Images show as their alt text.
No syntax highlighting. Code blocks are shown in one color.
No link targets. Links show their text only; you can’t see or follow the URL from the viewer.
Read-only. To edit the file, open it in the tab’s Neovim with ws open <file>; see Workstreams.