Installation

There is no environment to install

This is the headline feature: zero dependencies. The dev server and the wrap script are written entirely against the Python standard library, so there is no pip install, no conda environment, no npm, and no build step. Nothing to pin, nothing to keep in sync, nothing to rot — if a machine has python3, it can serve this site, today and in three years.

Concretely, getting from clone to a running site is two commands:

git clone https://github.com/jianzhou0420/htmlkb.git my-docs
cd my-docs && ./run_dev.sh

For contrast, the generator-based predecessor of this scaffold required a conda create plus pip install -r requirements.txt (MkDocs, the theme, and several nav/redirect plugins) — and broke when a transitive dependency drifted. That entire class of setup and upkeep is gone.

Prerequisites

Python 3.8+ on your PATH — the only requirement. The dev server and wrap script are pure standard library, so there is nothing to pip install. If your interpreter isn't named python3, point at it with PYTHON=/path/to/python ./run_dev.sh.
Git — for cloning, and recommended for version-controlling your own content.

Clone

git clone https://github.com/jianzhou0420/htmlkb.git my-docs
cd my-docs

Or use the "Use this template" button on GitHub to create your own repo from this one. There are no submodules to recurse and no environment to create.

Serve locally

./run_dev.sh

This launches the stdlib live-reload server (docs/_lib/_serve.py) on http://0.0.0.0:8002. It serves docs/ directly — there is no compiled output. Edit any file and the browser reloads within about half a second.

Override host, port, or poll interval:

./run_dev.sh 9000                  # custom port
HOST=127.0.0.1 ./run_dev.sh        # bind localhost only
INTERVAL=1.0 ./run_dev.sh          # slower file-watch poll (default 0.5s)

Deploy

Because the site is the static output, deploying is just copying docs/ to any static host (GitHub Pages, Netlify, S3, nginx). The _lib/ Python is only used at authoring time; you can exclude it from the upload, or leave it — browsers ignore .py files.

Uninstall

Delete the clone. No system-wide state is created.

Troubleshooting

"python3: command not found" — install Python 3, or edit run_dev.sh to point at your interpreter.
Port already in use — pass a different port: ./run_dev.sh 9000.
A page shows no sidebar or wrong title — re-run the wrap script: python3 docs/_lib/_wrap_handwritten.py. See Conventions § Bake the chrome.
Edits don't reload — the watcher ignores dotfiles and __pycache__; make sure you're editing a tracked .html/.css/.js file under docs/.