CandyMdview
Markdown CLI viewer + pager
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
candy-mdview README.md — pipe-friendly, exits cleanly.-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 {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).-w 80 — column width control (1-9999). 0 disables wrapping.text (url) tail; autolinks render the URL itself. --no-hyperlinks strips the OSC 8 envelope.git log -1 --pretty=%B | candy-mdview -p — the pager keyboard opens /dev/tty, so piped input stays scrollable.Source & demos
- Source on GitHub
- Full README
- Runnable example
- Originally inspired by glow (Go); SugarCraft is developed as a native PHP project.
See also
- SugarMarkdown — markdown renderer that powers CandyMdview
- SugarForms — Viewport component used for scrolling
API
| Class | Method | Description |
|---|---|---|
| MdViewModel | fromContent(content, width, height) | Build the pager Model from already-rendered text |
| MdViewModel | withDocument(name) | Enter document mode: prepend a status header (file name, scroll percent, reload marker) |
| MdViewModel | withWatch(path, reRender) | Auto-reload from disk when the (mtime, size) tuple changes |
| MdViewModel | isWatching() | Whether a file watch is armed on this model |
| FileWatcher | snapshot(path) | Current (mtime, size) tuple for a file, or null when unreadable |
| FileWatcher | pollTuple(path, lastMtime, lastSize) | Sweep one file against the last-seen tuple |
| FileWatcher | hasChangedSince(lastMtime) | Instance check against a remembered mtime |
| FileWatcher | idlePollDelayMicroseconds(idle, cap) | Bounded exponential backoff for idle poll sweeps |
| FileWatcher | watch(path) | Generator yielding on tuple changes (consumed by tests today) |
| GlamourTheme | isGlamourSchema(decoded) | Detect a Glamour-style theme document from decoded JSON |
| GlamourTheme | fromJsonString(json) | Parse a Glamour theme JSON string |
| GlamourTheme | fromFile(path) | Load a size-capped Glamour theme JSON file |
| GlamourTheme | fromDecoded(array) | Build from already-decoded JSON — the entry the CLI --theme-config path takes |
| GlamourTheme | element(name) / chroma(kind) / indentToken(token) | Verbatim access to unmapped style fields — no silent loss |
| GlamourTheme | toMarkdownTheme() | 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
The monorepo root README rendered with--theme dark.