# Move the documentation catalog to another hostname

The catalog is a **static tree** (`site/` in the monorepo). HTML cards and PDF clicks are **path-relative**, so the same files can be served from `https://zapier.georgelambert.org/` today and `https://docs.verae-time.net/` later without rewriting links.

Live service doors (portal, IAM, fleet, …) stay on their own hostnames. Forgejo stays on `git.georgelambert.org`.

**Script:** `scripts/rewrite-docs-host.py` in [master-zapier-plan-draft](https://git.georgelambert.org/marchon/master-zapier-plan-draft)  
**Build:** `scripts/build-docs-site.py` · **Deploy:** `scripts/deploy-docs-site.sh`

## Default (relative) — no hostname pass

1. Build: `python3 scripts/build-docs-site.py`
2. Rsync the `site/` directory to the new host document root (must be the site root, `/`).
3. Point DNS + TLS (Caddy `file_server` with `index index.html index.pdf README.html README.pdf`) at that tree.

PDF annotations look like `README.pdf` and `../../index.html` (relative to the PDF). Browsers resolve them against the PDF’s own URL, so they follow the new host.

Optional label in the HTML banner (not a link target):

```bash
DOCS_PUBLIC_HOST=docs.verae-time.net python3 scripts/build-docs-site.py
```

## Absolute URLs (only if a viewer needs them)

Bake a public origin at build time:

```bash
DOCS_PUBLIC_URL=https://docs.verae-time.net \
DOCS_PUBLIC_HOST=docs.verae-time.net \
  python3 scripts/build-docs-site.py
```

Or retarget an **already built** `site/` without rebuilding PDFs from markdown:

```bash
# Lab origin → future docs host
python3 scripts/rewrite-docs-host.py \
  --site ./site \
  --from https://zapier.georgelambert.org \
  --to https://docs.verae-time.net

# Strip the origin (same as the default build)
python3 scripts/rewrite-docs-host.py --site ./site --relative

python3 scripts/rewrite-docs-host.py --site ./site --from … --to … --dry-run
```

The rewrite walks HTML/SVG/CSS/JS/MD text and PDF `/URI` annotations. It does **not** change `portal.zapier.georgelambert.org`, `iam.…`, or `git.georgelambert.org`.

## Caddy (any host)

```caddy
docs.verae-time.net {
	root * /SSD2/sites/docs.verae-time.net
	encode gzip zstd
	file_server {
		index index.html index.pdf README.html README.pdf
	}
	try_files {path} {path}/index.html {path}/index.pdf {path}/README.html {path}/README.pdf
}
```

Lab copy: `packages/verae-ops/caddy/zapier.georgelambert.org.caddy`.

## Check

```bash
python3 scripts/check-doc-links.py
```

Local files must exist for homepage hrefs and PDF URI targets. Off-site HTTPS (Forgejo, live doors) is left alone.

## Publish lab catalog (today)

```bash
git -C /Users/marchon/apps/zapier push ns1 main
git -C /Users/marchon/apps/zapier push ns1 main:master
bash scripts/deploy-docs-site.sh
# → marchon@70.88.205.138:/SSD2/sites/zapier.georgelambert.org
```