CARREL(1)

NAME
carrel - a quiet place to read your markdown

SYNOPSIS
carrel [DIR]
carrel FILE [PATTERN]
cmd | carrel [- [PATTERN]]
carrel --plain FILE [WIDTH]
carrel --plain - [WIDTH]
carrel --render {FILE|-} [WIDTH]
carrel --tasks FILE
carrel [--diff|--no-diff] FILE
carrel --help
carrel --version

DESCRIPTION
carrel is a markdown reader — not an editor, not a workbench, a reading desk.

Run with no arguments it lists the markdown files around you, newest first, with type-to-filter and a directory picker. Given a FILE it opens a reader with vim motions, incremental search that survives reflow and terminal resize, syntax highlighting, tables, images, and mermaid diagrams. Prose is set to a comfortable measure and centred rather than stretched across a wide terminal; tables, code and diagrams still use the full width.

Given a FILE and a PATTERN, it prints matching lines and exits.

Piped input opens the reader too: git show HEAD:README.md | carrel streams the document in as it arrives, so a slow producer paints immediately and your position and search matches hold while content lands. carrel - forces stdin mode; with stdout also piped the document renders as plain text instead, so pipelines pass through.

OPTIONS

--plain
    Render the document as linear plain text on stdout, for screen readers and for pipes. A bare pipe selects this automatically, so carrel doc.md | less does the right thing. Output is ASCII-safe and contains no escape bytes.

--diff
    Read the input as a unified diff even if its name does not say so: a heading per commit and per file, hunks as code. A pipe and a .diff or .patch file are read this way already; a .md file never is.

--no-diff
    Never adapt a diff, even on a pipe.

--render
    Styled linear text for embedding in another tool's output: weight, slant, strike and OSC 8 hyperlinks, but never an SGR colour. With NO_COLOR set it is exactly --plain.

--tasks
    Print every GFM task in the file as checkbox lines and exit. The file is never modified.

--version ,  -V
    Print the version and exit.

--help ,  -h
    Print usage and exit.

KEYS

  Reader

j, k, ↑, ↓
    Scroll by a line.

Ctrl-E, Ctrl-Y
    Scroll by a line without moving the reading position.

Space, b, PgDn, PgUp, Ctrl-F, Ctrl-B
    Page forward and back.

Ctrl-D, Ctrl-U
    Half a page forward and back.

gg, G
    Jump to the start or the end.

42G Jump to a row by number.

{ } Move to the previous or next block.

zz zt zb
    Put the current match in the middle, at the top, or at the bottom.

/   Search. Matches survive reflow and resize by construction.

n, N
    Next and previous match.

o   Outline picker.

t   Toggle wide tables between card view and wrapping in place.

r   Toggle rendered blocks — diagrams and math — between art and source.

] [ Move to the next or previous code block. The one in focus is marked in the margin.

X   Jump to the next task-list item, wrapping. A count jumps that many.

y   Copy the focused code block, without its fence. With nothing focused, the nearest code block at or after the top of the screen.

F   Follow a document that is still arriving on a pipe: the view stays at the end as content appears. Any deliberate move away detaches it.

A   Auto-read: the view drifts down a row at a time until any motion stops it.

L   What links here — the documents that link to this one, by [[wikilink]] or by ordinary markdown link. Enter opens one.

l   What this points at — every destination in the document, the mirror of L. Enter opens a local one; an external URL is named, never fetched.

m   Set or clear a bookmark at the current position. Bookmarks are remembered between sessions and survive a resize; they do not survive an edit to the file.

'   Go to the next bookmark, wrapping at the end.

    List every bookmark with its line; enter jumps to one.

Tab, Shift-Tab
    Select the next or previous link.

Enter
    Follow the selected link.

Ctrl-O
    Go back where you came from.

T   Cycle themes.

h, F1
    Help.

H   Fold the hint footer.

B   Hide or show the breadcrumb band (the enclosing sections, pinned atop the page while you scroll).

I   Show or hide the document card: words, reading time, structure, links, when the file last changed.

S   Spotlight: dim every paragraph except the one nearest the centre of the view.

za, zM, zR
    Fold the current section behind its heading; fold every section; open all. A <details> block folds the same way behind its summary. Clicking a heading or a summary toggles its fold. Search and links unfold their targets.

%   Jump to the footnote definition of the reference nearest above the view; inside a definition, back to its first reference. Ctrl-O returns.

Esc Clear the selection, the selected link, and any search highlights.

q   Close the file, returning to the home screen if it was opened from there; otherwise quit.

Q, Ctrl-C
    Quit outright, whatever is open.

  Home screen

i   Filter by name; type to narrow, escape to leave. The match is fuzzy — an in-order subsequence, ranked best-first — as it is in the outline picker.

/   Search inside every file; enter opens at the match.

d   Choose a directory. Remembered places are offered first; type a path to complete it against the filesystem; arrows, Ctrl-J/Ctrl-K or Ctrl-N/Ctrl-P move, enter chooses. Typing owns the letters here, so j and k are part of the path.

Mouse
    Click a file to select it, double-click to open it. The same works in the directory picker, and on the results of a file search.

ENVIRONMENT

NO_COLOR
    Honoured: colours off, weight and emphasis kept.

FILES

$XDG_CONFIG_HOME/carrel
    Theme, chosen root directory, footer preference, favourite places (repeated place lines, newest first), and max_width, the reading measure in columns (default 90; 0 turns it off).

$XDG_STATE_HOME/carrel
    Reading positions, so a document reopens where you left it.

$XDG_CACHE_HOME/carrel
    The file index: paths and modification times, nothing else.

PRIVACY
carrel reads only the directory you point it at and sends nothing anywhere. Remote images in documents are never fetched; they render as their alt text.

SEE ALSO
Project home: https://github.com/VaHughes/carrel

LICENSE
MIT OR Apache-2.0, at your option.