Duc-Tam Nguyen
3af26ae0e5
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.
54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
---
|
|
title: "Introduction"
|
|
description: "Why kage renders before it saves, and what it means to strip the JavaScript out of a clone."
|
|
weight: 10
|
|
---
|
|
|
|
A normal website is not a document; it is a program. The HTML the server sends
|
|
is often a near-empty shell, and the page you actually see is assembled in your
|
|
browser by JavaScript: fetching data, building the DOM, wiring up handlers. That
|
|
is why "Save As" so often fails. You get the shell, not the page, and whatever
|
|
you do get still runs trackers and phones home when you open it.
|
|
|
|
kage treats a clone as three steps in order.
|
|
|
|
## 1. Render
|
|
|
|
Every page is loaded in a real headless Chrome through the DevTools protocol.
|
|
kage navigates to the URL, waits for the network to go quiet, optionally scrolls
|
|
to trigger lazy-loaded images, and then serialises the **final** DOM, the markup
|
|
that exists after the page's JavaScript has finished building it. This is the
|
|
same thing you would see if you opened the page and chose "Inspect".
|
|
|
|
## 2. Strip
|
|
|
|
From that captured DOM, kage removes everything executable:
|
|
|
|
- every `<script>` tag, inline or external;
|
|
- every `on*` event handler attribute (`onclick`, `onload`, and the rest);
|
|
- every `javascript:` URL;
|
|
- `<meta http-equiv="refresh">` redirects and dead resource hints like
|
|
`<link rel="preload" as="script">`.
|
|
|
|
What remains is inert. The saved page makes no network calls, runs no code, and
|
|
tracks nothing.
|
|
|
|
## 3. Localise
|
|
|
|
A page with no working CSS or images is not much of a clone, so kage keeps the
|
|
parts that define how it looks. It downloads every stylesheet, image, font, and
|
|
media file, rewrites the references in the HTML and inside the CSS (`url()` and
|
|
`@import`) to relative local paths, and rewrites in-scope page links to point at
|
|
the other saved pages. The mirror is fully self-contained: you can move the
|
|
folder anywhere, open it with no network, and click around.
|
|
|
|
## The shape of a clone
|
|
|
|
kage crawls breadth-first from a seed URL, staying within the seed's host (and
|
|
optionally its subdomains). It is polite by default: it honours `robots.txt` and
|
|
seeds itself from `sitemap.xml`. Output lands in `$HOME/data/kage/<host>/`, with pages
|
|
as `<path>/index.html` and assets under a reserved `_kage/` directory alongside
|
|
the crawl state that powers `--resume`.
|
|
|
|
Next: [install kage](/getting-started/installation/).
|