From 00bbd8168be895c699c7f83f3604529c3cfadc3b Mon Sep 17 00:00:00 2001 From: ryno Date: Sat, 25 Apr 2026 21:08:07 +0200 Subject: [PATCH] Update readme --- .github/workflows/{pr.yml => ci.yml} | 2 +- CHANGELOG.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 66 +++++++++------------------- docs/releasing.md | 6 +-- 5 files changed, 26 insertions(+), 52 deletions(-) rename .github/workflows/{pr.yml => ci.yml} (98%) diff --git a/.github/workflows/pr.yml b/.github/workflows/ci.yml similarity index 98% rename from .github/workflows/pr.yml rename to .github/workflows/ci.yml index 61dacb1..6d6890d 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,4 @@ -name: pr +name: ci on: pull_request: diff --git a/CHANGELOG.md b/CHANGELOG.md index 26cadb3..04d36da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -121,7 +121,7 @@ description of what scroll ships today. crypto/tls, net/url, os). - Makefile targets: `build`, `test`, `release`, `clean`. `make release` cross-compiles linux + darwin (amd64 + arm64). -- GitHub Actions workflow `pr.yml`: `go vet`, `staticcheck`, +- GitHub Actions workflow `ci.yml`: `go vet`, `staticcheck`, `govulncheck`, `go test -race`, `go build` on every PR and push to `main`. - GitHub Actions workflow `release.yml`: tag-triggered diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef42093..57f2ebb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -116,7 +116,7 @@ Body (only when the change isn't self-evident): linear). - One concern per PR. If your change naturally splits into "refactor" + "feature", land them as two PRs. -- Wait for the `pr.yml` workflow to go green before requesting +- Wait for the `ci.yml` workflow to go green before requesting review. If it's red, fix it locally — don't push fixes one at a time hoping CI eventually agrees. - Update [`docs/`](docs/) and the [`CHANGELOG.md`](CHANGELOG.md) diff --git a/README.md b/README.md index ca183a7..4a8a93e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # scroll -[![PR](https://github.com/rynobey/scroll/actions/workflows/pr.yml/badge.svg?branch=main)](https://github.com/rynobey/scroll/actions/workflows/pr.yml) +[![ci (main)](https://github.com/rynobey/scroll/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/rynobey/scroll/actions/workflows/ci.yml?query=branch%3Amain) [![Go Reference](https://pkg.go.dev/badge/github.com/rynobey/scroll.svg)](https://pkg.go.dev/github.com/rynobey/scroll) [![Latest release](https://img.shields.io/github/v/release/rynobey/scroll?sort=semver)](https://github.com/rynobey/scroll/releases/latest) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) @@ -18,51 +18,25 @@ docs/screenshots/README.md for capture suggestions. --> ## Why scroll? -Most terminal markdown tools are good at one thing: `glow` is a -nice viewer but light on tables and navigation; `mdcat` does -excellent inline images but is static-only; `bat` is really a -code viewer that happens to recognise markdown. scroll's bet is -that **reading long-form docs in a terminal is its own -workflow** — and the things that matter for that workflow are -real navigation, decent tables, working images, and a layout -that doesn't waste horizontal space on wide screens. - -What that looks like in practice: - -- **Multi-column "newspaper" layout** when the terminal is wide - enough — set `columns = 2` (or 3) and the doc paginates into - column-aligned pages, like reading a paper. -- **Real link navigation.** `Tab` cycles between links, - `Enter` follows them: relative paths load in-place, - `#anchor` jumps scroll to the heading, URLs dispatch to - `xdg-open`. `Ctrl+O` / `Ctrl+I` walk the back/forward stack. -- **Inline image *impressions***. Images render as a grid of - coloured Unicode block glyphs — enough to recognise the - subject (a chart's shape, a photo's composition, a logo's - silhouette) but visibly low-resolution. Two paths: the - default uses the standard Unicode block + sextant glyphs and - works on every truecolor terminal; the optional patched - "fine-blocks" font ups the sub-pixel grid to 15 per cell. - Neither is pixel-accurate; for that you need a real graphics - protocol (Kitty / Sixel / iTerm) — Kitty is supported but - experimental. See [fine-blocks.md](docs/fine-blocks.md). -- **Mermaid diagrams as Unicode box-drawing**, via the - [termaid](https://github.com/fasouto/termaid) CLI. No - Chromium dependency, no PNG round-trip, text labels stay as - real text. -- **Within-doc search** (`/pattern`, RE2 regex with literal - fallback), **heading-tree folding** (`za`/`zM`/`zR`), - **jump-to-heading picker** (`Space`), **heading-level - navigation** (`]]`/`[[`/`]m`/`[M`), and a **help overlay** (`?`) - that lists every keybinding in scope. -- **Live reload.** Edit the file in another window, scroll - re-renders within ~500ms — without losing your scroll position. -- **Per-file scroll position persistence.** Re-opening a file - resumes where you left off. -- **TOML themes.** Structured fields cover layout/colours/spacing - for every block type; an optional template DSL lets individual - elements decorate their content - (e.g. `h1 = "{215}{bold}{text}\n{8}{rule}"`). +Built for **reading long-form docs in a terminal**, with the +things that workflow needs: + +- **Multi-column "newspaper" layout** on wide terminals. +- **Real link navigation** — `Tab` to cycle, `Enter` to follow, + `Ctrl+O` / `Ctrl+I` for back/forward. +- **HJKL heading-tree navigation**, jump-to-heading picker, + fuzzy file picker, RE2-regex search, heading-tree folding. +- **Inline image *impressions*** — coloured Unicode block + glyphs that read as a recognisable thumbnail without needing + a graphics protocol. Pixel-accurate Kitty rendering is + available as an experimental opt-in. +- **Mermaid diagrams as Unicode box-drawing** via + [termaid](https://github.com/fasouto/termaid). +- **Live reload, per-file scroll-position memory, TOML themes** + with a template DSL for custom decoration. + +See the [comparison table](#how-does-it-compare) below for how +this lines up against `glow` and `mdcat`. diff --git a/docs/releasing.md b/docs/releasing.md index 71c6134..c480774 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -34,8 +34,8 @@ broken state. - [ ] Working tree clean. `git status` is empty. - [ ] Up-to-date with the remote. `git fetch && git status -uno` reports "Your branch is up to date with 'origin/main'". -- [ ] The latest `pr.yml` run on `main` is green - ([Actions tab](https://github.com/rynobey/scroll/actions/workflows/pr.yml)). +- [ ] The latest `ci.yml` run on `main` is green + ([Actions tab](https://github.com/rynobey/scroll/actions/workflows/ci.yml)). ### Local quality gates @@ -85,7 +85,7 @@ The convention is documented in - [ ] `git add CHANGELOG.md && git commit -m "release: vX.Y.Z"`. - [ ] `git push origin main`. -- [ ] Wait for `pr.yml` to go green on the push commit. +- [ ] Wait for `ci.yml` to go green on the push commit. **Don't tag if the workflow's still running or red** — a tagged release built from a broken commit is much worse than a delayed release.