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.
This commit is contained in:
Duc-Tam Nguyen
2026-06-14 22:25:31 +07:00
parent 5b7f7d9f31
commit 3af26ae0e5
11 changed files with 209 additions and 95 deletions
+1 -1
View File
@@ -24,7 +24,7 @@ A clone of `example.com` lands under `$HOME/data/kage/example.com/` (override th
root with `-o/--out`):
```
kage-out/example.com/
$HOME/data/kage/example.com/
├── index.html # the home page (/), scripts stripped
├── about/index.html # /about
├── blog/
+19
View File
@@ -9,6 +9,25 @@ The authoritative, commit-level history lives in
[releases page](https://github.com/tamnd/kage/releases). This page summarises
each version.
## Unreleased
Packing, so a clone can travel as one file instead of a folder.
- **`kage pack <mirror-dir>`** collapses a mirror into a single distributable
file. `--format zim` (the default) writes an open ZIM archive, the same format
Kiwix uses; `--format binary` appends that archive to a copy of kage to make a
self-contained executable that serves the site offline when run. Packing is
deterministic, so the same mirror produces a byte-identical file.
- **`kage open <file.zim>`** serves a packed ZIM back over a local HTTP server,
the read side of `kage pack --format zim`.
- **An optional native-window viewer.** Built with `-tags webview`, `kage open`
and a packed binary show the site in a real window backed by the operating
system's WebView instead of a browser tab. The default build stays pure Go and
opens the browser, so the release pipeline is unchanged.
- **A pure-Go `zim` package** that reads and writes the ZIM format: a fixed
header, MIME and pointer lists, zstd or stored clusters, redirects, and a
trailing MD5.
## v0.1.0
The first release. kage clones a live website into a self-contained folder you