All 22 apps

CandyMdview

Markdown CLI viewer + pager

inspired by charmbracelet/glow markdown viewer pager

CandyMdview code coverage

Composes SugarMarkdown (rendering) and the SugarForms Viewport (scrolling). Render to stdout or open in a fullscreen pager. Twelve built-in themes (ansi, ascii, plain, notty, dark, light, dracula, tokyo-night, pink, solarized, monokai, github) plus custom JSON.

Install

composer require sugarcraft/candy-mdview   # binary lands in vendor/bin/candy-mdview
wget https://github.com/detain/sugarcraft/releases/download/candy-mdview/latest/candy-mdview.phar   # standalone latest phar

Quickstart

vendor/bin/candy-mdview README.md                   # render to stdout (default)
vendor/bin/candy-mdview -p README.md                # open in a fullscreen pager
git log -1 --pretty=%B | vendor/bin/candy-mdview -p # pipe stdin
php candy-mdview.phar README.md                     # the phar takes the same flags
# with vendor/bin (or the phar) on PATH, drop the prefix:
candy-mdview --theme dracula README.md
candy-mdview --width 80 --no-hyperlinks README.md
candy-mdview --theme-config ./my-theme.json README.md

What's in the box

Stdout modecandy-mdview README.md — pipe-friendly, exits cleanly.
Pager mode-p / --pager — fullscreen scrollable Viewport that reflows live on terminal resize. A header row shows the file, scroll position, and an auto-reload marker. Esc, q, or Ctrl+C to exit.
Theme picker--theme {ansi|ascii|plain|notty|dark|light|dracula|tokyo-night|pink|solarized|monokai|github} (aliases: no, auto-no, tokyonight), --theme-config ./my.json, -s alias for --theme. Three themes (solarized/monokai/github) load from JSON in themes/. With no --theme: ansi on a color-capable terminal, ascii when color is off, plain when the output is undecorated (--no-ansi or a non-terminal without forced decoration).
Word-wrap-w 80 — column width control (1-9999). 0 disables wrapping.
OSC 8 toggleHyperlinks are emitted on terminal output — and into redirected output only when decoration is forced. Labeled links always show the visible text (url) tail; autolinks render the URL itself. --no-hyperlinks strips the OSC 8 envelope.
Stdin supportgit log -1 --pretty=%B | candy-mdview -p — the pager keyboard opens /dev/tty, so piped input stays scrollable.

Source & demos

See also

Try the quickstart →

API

ClassMethodDescription
MdViewModelfromContent(content, width, height)Build the pager Model from already-rendered text
MdViewModelwithDocument(name)Enter document mode: prepend a status header (file name, scroll percent, reload marker)
MdViewModelwithWatch(path, reRender)Auto-reload from disk when the (mtime, size) tuple changes
MdViewModelisWatching()Whether a file watch is armed on this model
FileWatchersnapshot(path)Current (mtime, size) tuple for a file, or null when unreadable
FileWatcherpollTuple(path, lastMtime, lastSize)Sweep one file against the last-seen tuple
FileWatcherhasChangedSince(lastMtime)Instance check against a remembered mtime
FileWatcheridlePollDelayMicroseconds(idle, cap)Bounded exponential backoff for idle poll sweeps
FileWatcherwatch(path)Generator yielding on tuple changes (consumed by tests today)
GlamourThemeisGlamourSchema(decoded)Detect a Glamour-style theme document from decoded JSON
GlamourThemefromJsonString(json)Parse a Glamour theme JSON string
GlamourThemefromFile(path)Load a size-capped Glamour theme JSON file
GlamourThemefromDecoded(array)Build from already-decoded JSON — the entry the CLI --theme-config path takes
GlamourThemeelement(name) / chroma(kind) / indentToken(token)Verbatim access to unmapped style fields — no silent loss
GlamourThemetoMarkdownTheme()Convert to a SugarMarkdown Theme

Visual width measuring is delegated to SugarCraft\Core\Util\Width in sugar-core; this package ships no local width helpers.

Exit codes & trust

Exit codes: 0 rendered successfully (an empty file renders blank), 1 runtime failure, 2 usage error — bad theme, unreadable or oversized theme config, missing or unreadable file, a directory argument, non-text (binary) input, a document over 64 MiB, invalid --width, or no input.

Hostile documents render as data. sugar-markdown strips escape, control, and OSC bytes on output, per element (sanitization is default-on and this tool never opts out), so a document cannot move the cursor or restyle the stream. OSC 8 URLs face a refused-scheme denylist: javascript:, data:, and vbscript: never reach a clickable envelope; other schemes pass to the terminal's opener unfiltered. Usage errors go to stderr with argv paths and option values sanitized before display, and the rendered document is written raw — the output formatter never interprets <tags> inside your Markdown.

Demos.

VHS-recorded demo GIFs, regenerated on pushes that touch the tapes or the source.

Render

Render

The monorepo root README rendered with --theme dark.
Pager

Fullscreen pager

-p flag opens a Viewport-powered scrollable pager. Arrows, wheel, or j/k to scroll; q or Ctrl+C quits.