Substratum.cloud

Appearance

ADR 06: Documentation Hosting (Tangled Sites) ​

Status: Accepted Date: 2026-04-09

Substratum's documentation is built using VitePress and hosted on Tangled Sites (tngl.sh).

Why Tangled? ​

Tangled is a federated Git collaboration platform built on the AT Protocol—the exact same identity and authentication protocol that Substratum uses. Hosting our documentation on tngl.sh aligns perfectly with our architectural philosophy of leveraging the AT Protocol ecosystem.

Deployment Architecture ​

Tangled Sites serves static files directly from a Git branch. We commit the built site under site/ at the repo root.

Local build (every docs edit) ​

  1. Trigger: A developer runs git commit with staged changes under docs/ (source only; not site/ alone).
  2. Check: The Husky pre-commit hook detects staged docs/ paths.
  3. Build: Runs pnpm run docs:build (output → site/).
  4. Stamp: Writes site/.deploy-stamp (ISO time + git revision).
  5. Stage: git add -f site so compiled assets are included in the same commit.

Publish to tngl.sh ​

From the repo root:

bash
pnpm run docs:deploy
git push origin main

docs:deploy rebuilds VitePress, updates .deploy-stamp, stages site/, and commits. Push to main so Tangled redeploys.

Tangled Sites settings ​

In Settings → Sites for this repository:

SettingValue
Branchmain
Deploy directory/site
Site typeSub-path site (straiforos.tngl.sh/substratum.cloud)

VitePress base remains /substratum.cloud/ in docs/.vitepress/config.mts for sub-path URLs.

If the live site is stale after a push, save site settings again or disable and re-enable the site for a full republish.

Configuration Steps (Manual) ​

To enable this on a new repository on Tangled:

  1. Go to Settings → Sites in the Tangled repository.
  2. Choose Index site or Sub-path site (e.g. yourname.tngl.sh/substratum.cloud).
  3. Set the Branch to main.
  4. Set the Deploy directory to /site.
  5. Click Save. The site updates when you push commits that include changes under site/.
  • Root package.json scripts: docs:dev, docs:build, docs:deploy
  • scripts/docs-deploy.mjs — deploy stamp and staging
  • docs/.vitepress/config.mts — sidebar; update when adding pages