From 3af26ae0e5829e03b7cd3645caa8d65f7b5ebbad Mon Sep 17 00:00:00 2001 From: Duc-Tam Nguyen Date: Sun, 14 Jun 2026 22:25:31 +0700 Subject: [PATCH] Rewrite the README and add a recorded demo Rework the README into the house style: badges, a one-line pitch, an anchor nav, a commands table, and dedicated sections for clone, pack, and the native viewer. Every flag and default is checked against the current binary so the docs match what kage actually does. Add a demo recorded with ascii-gif. The tape clones example.com, packs it to a ZIM and to a self-contained binary, and serves it back offline, so the whole loop reads in one frame. It sits at the top of the README and on the docs home. While reviewing the docs, fix the output path everywhere: the default is $HOME/data/kage, not the kage-out the pages claimed, including a few fabricated 'done kage-out/...' lines. Document pack, open, and the native viewer in the release notes. --- README.md | 209 ++++++++++++------- docs/content/_index.md | 8 +- docs/content/getting-started/introduction.md | 2 +- docs/content/getting-started/quick-start.md | 8 +- docs/content/guides/packing-a-mirror.md | 10 +- docs/content/guides/resuming-a-run.md | 2 +- docs/content/guides/serving-a-mirror.md | 10 +- docs/content/reference/configuration.md | 2 +- docs/content/reference/release-notes.md | 19 ++ docs/demo/kage.tape | 34 +++ docs/static/demo.gif | Bin 0 -> 173040 bytes 11 files changed, 209 insertions(+), 95 deletions(-) create mode 100644 docs/demo/kage.tape create mode 100644 docs/static/demo.gif diff --git a/README.md b/README.md index a5c4ba5..373986e 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,64 @@ # kage +[![ci](https://github.com/tamnd/kage/actions/workflows/ci.yml/badge.svg)](https://github.com/tamnd/kage/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/tamnd/kage)](https://github.com/tamnd/kage/releases/latest) +[![Go Reference](https://pkg.go.dev/badge/github.com/tamnd/kage.svg)](https://pkg.go.dev/github.com/tamnd/kage) +[![Go Report Card](https://goreportcard.com/badge/github.com/tamnd/kage)](https://goreportcard.com/report/github.com/tamnd/kage) +[![License](https://img.shields.io/github/license/tamnd/kage)](./LICENSE) + **kage** (影, "shadow") clones a website into a self-contained folder you can browse offline, with all the JavaScript stripped out. It renders every page in headless Chrome, snapshots the final rendered DOM, removes every script and -event handler, and downloads the CSS, images, and fonts and rewrites them to -local paths. The result looks like the live site but runs no code: a plain -folder of `.html` files you can open straight from disk. +event handler, then downloads the CSS, images, and fonts and rewrites them to +local paths. The result looks like the live site but runs no code. -```bash -kage clone example.com -kage serve kage-out/example.com -``` +[Install](#install) • [Commands](#commands) • [Clone](#clone) • [Pack](#pack-it-into-one-file) • [Native viewer](#a-native-window-not-a-browser-tab) • [How it works](#how-it-works) -## Why +![kage cloning a site, packing it into one file, and serving it back offline](docs/static/demo.gif) Saving a page with "Save As" gives you a copy that still phones home, still runs analytics, and often renders blank because the markup is built by JavaScript at -runtime. kage takes the opposite approach: +runtime. kage takes the opposite approach: it drives a real browser, waits for +the page to settle, captures the DOM a human would have seen, and then strips +every script out of it. What lands on disk is inert. No tracking, no network +calls, no surprises, just a folder of `.html` files you can open straight from +disk or pack into a single file to hand to someone. -- **Render first, save second.** Each page goes through real headless Chrome, so - a page whose content is assembled by JavaScript is captured the way a human - would have seen it, not as an empty shell. -- **Strip every script.** Once the DOM is captured, kage removes all `