- Category
- Developer Tools
- Rank
- No. 1954Tools index
Previous survey · No. 1846 ·
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Productivity & Collaboration · Software Testing & Quality
- Interfaces
- CLI
- GitHub
- 2 stars
- Latest release
- v0.1.2
- Date
About
A terminal-based Markdown previewer and docs linter that renders READMEs, changelogs, and release notes as a styled TUI with themes, search, and inline image/Mermaid support. It also includes a --check mode that flags common docs issues like broken links, missing alt text, and malformed heading structure before publishing.
What it does
A single Go binary that reads a file or piped input, parses it with GitHub-flavoured syntax, and paints the result in the terminal. By default it opens a scrollable full-screen viewer with a heading outline, a find box and a theme picker, and it can reload when the file changes. Flags switch it to one-shot output instead: styled text, plain text, a heading list, or a quality pass that prints warnings and exits with status 2 when it finds any.
Why it's ranked here
A small, well-scoped tool built on mature parts: the goldmark parser, the Charm terminal UI libraries and Chroma for code colouring. MIT licensed, installable through Go or npm, with continuous integration that runs formatting, tests, vet, a build and the npm wrapper tests on every push. The standout is the nonzero exit on warnings, which turns a previewer into something a pipeline can gate on. It is still an early release from a single author, and the checker is shallower than a dedicated linter.
What's good
The quality pass is specific and cheap: it flags skipped heading levels, repeated or empty headings, more than one top-level title, images without alt text, link text that is just the raw address, and local files that do not exist, resolved relative to the document. Tables get flagged when a row has the wrong cell count, a header passes 40 characters or a cell passes 80. Mermaid diagrams render through the external Mermaid CLI with a 10 second timeout and a cache keyed by a hash of the diagram source. The npm installer verifies a SHA-256 checksum of the downloaded release archive.
Tradeoffs
Link checking is local only: anything with a scheme, mail links and in-page anchors are skipped, so dead web links and wrong anchors pass. Release builds cover macOS and Linux on x86-64 and ARM64 only; there is no Windows binary, and the npm package declares the same limit. Inline images need a terminal speaking the Kitty graphics protocol, which the project names as Kitty and Ghostty; elsewhere you get a placeholder. The npm install downloads a binary from GitHub at install time, and an environment variable can switch off the checksum step.
How to use it well
Best for people who live in the terminal and write READMEs or changelogs: keep the viewer open in watch mode beside the editor, then add the quality pass to CI so a skipped heading or missing image fails the build. Set a fixed width for one-shot output when the result is logged. Pair it with a separate external link checker, since this one ignores web URLs. Install the Mermaid CLI only if you use diagrams and a Kitty-compatible terminal.
Technical notes+
cmd/shine/main.go hands off to a cobra root command in internal/cli/cli.go, where --print, --plain, --outline and --check bypass the Bubble Tea UI and --check returns exitError{code: 2} on any warning. internal/parser/parser.go uses goldmark with extension.GFM and maps nodes to an internal block model, detecting GitHub-style callouts from blockquotes starting with [!. The rules live in internal/inspect/inspect.go (Check, headingWarnings, tableWarnings, linkWarnings); isExternalTarget skips targets containing ://, mailto: or tel:. internal/render/render.go caps table columns at 28 cells wide, clamps width to at least 32, shells out to mmdc (overridable via SHINE_MERMAID_CMD) under context.WithTimeout of 10 seconds, and skips Chroma highlighting for the github and claude themes. internal/tui/tui.go filters all non-wheel mouse events and caches the viewport body. npm/install.js honours SHINE_SKIP_CHECKSUM and SHINE_BINARY_PATH. .goreleaser.yaml builds with CGO_ENABLED=0 for darwin and linux.
Observed
- License
- MIT (LICENSE)
- Language
- Go, with a Node.js install wrapper (go.mod, package.json)
- Install surface
- go install, npm global package that downloads a release binary, or build from source
- Interfaces
- CLI with interactive terminal viewer and non-interactive print, plain, outline and check modes
- Platforms
- macOS and Linux, amd64 and arm64 release builds; no Windows target (.goreleaser.yaml)
- CI exit code
- Check mode exits with status 2 when any warning is found (internal/cli/cli.go)
- Link checking scope
- Local file targets only; URLs with a scheme, mailto, tel and anchors are skipped (internal/inspect/inspect.go)
- Continuous integration
- gofmt, go test, go vet, build and npm wrapper tests on push and pull request (.github/workflows/ci.yml)
- Install integrity
- SHA-256 checksum verification of the release archive, skippable by environment variable (npm/install.js)
Read from README.md, go.mod, package.json, LICENSE, cmd/shine/main.go, internal/cli/cli.go, internal/parser/parser.go, internal/render/render.go, internal/source/load.go, internal/inspect/inspect.go, internal/tui/tui.go, npm/install.js, .goreleaser.yaml, .github/workflows/ci.yml.
What it can do
Render Markdown files (READMEs, changelogs, release notes) as a styled terminal UI
Markdown file → Styled TUI preview
Search within rendered documentation
Search query → Matched text locations
Display inline images and Mermaid diagrams within Markdown preview
Markdown file with images/Mermaid code → Rendered images/diagrams in TUI
Check documentation for issues like broken links, missing alt text, and malformed heading structure
Markdown file → List of docs issues
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.