tavrn website

The source of https://tavrn.org: the landing page, downloads, the documentation (wiki), the status page of the official node, the roadmap and the legal pages of the tavrn project. It is a fully static site built with Astro and Starlight, served by Caddy from a small container.

Status: private review. The site is being built before the project's first public release.

What is where

Path	What
src/pages/	The custom pages: landing (index.astro), download, status, issues (known issues), report (report a problem), roadmap, legal/, 404
src/components/	Header, footer, Brand (the name with translate="no"), Shot (screenshot frames), the landing's interactive parts (Federation, E2eeToggle, Showcase); download/ the download page's parts (Releases, which renders the releases at runtime, the OS cards and the checksum verifier), status/ the status page's Preact island (NodeStatus, UptimeHistory, written against the React API through preact/compat) and the live dot of the "Status" link (StatusDot, vanilla JavaScript); issues/ the known-issues page's Preact island (KnownIssues)
src/content/docs/	The wiki (Starlight), served under /docs/; its sidebar is src/docs-sidebar.ts. users/ holds the hand-written user guides, synced/ the pages generated from sources/ (gitignored, see "The wiki and its sources")
src/content/pages/	Markdown pages outside the wiki (the roadmap, generated from sources/tavrn)
sources/	Git submodules of the repositories the wiki copies its operator and developer pages from
src/i18n/	UI strings of the custom pages (en.json), the t() / rich() helpers, the list of languages
src/styles/	tokens.css (the web client's design tokens), global.css (pages), starlight.css (docs)
src/assets/screenshots/	The screenshots and manifest.ts (scene key → image, alt text, caption)
public/	Favicons, app icons, og.png (rendered by just og-image from scripts/og/template.html and src/assets/brand/og-background.png), site.webmanifest, robots.txt
src/assets/brand/	Logo and wordmark, the Open Graph background and the hero background (two generated abstract images, CC-BY-4.0 like the texts)
deploy/	Dockerfile, Caddyfile, entrypoint.sh, docker-compose.yml, .env.example, deployment notes
e2e/	Playwright: every route, axe scans, keyboard, CSP, privacy
tests/	Vitest checks of the built site (JavaScript budget, CSP hashes, no foreign URLs)
scripts/	CSP hashes, SPDX and license checks, the publication check, the docs sync (sync-docs.mjs, docs-sources.mjs, gen-env-reference.mjs, lib/)

Running it

Requirements: Node.js 24, pnpm (the version in package.json, corepack enable provides it), just, Docker for the image and the Caddyfile check.

git submodule update --init   # the docs sources under sources/ (a fresh clone has empty directories)
pnpm install
just dev          # http://localhost:4321, hot reload
just build        # dist/ and csp-script-hashes.txt
just preview      # serves dist/ on http://127.0.0.1:4400
just check        # everything below, must be green before a commit

just check runs the strict docs sync, astro check, the build, Vitest (unit tests, the checks of dist/ and its link checker), the SPDX and license checks, scripts/publish-check.sh, caddy validate on deploy/Caddyfile and the Playwright suite. The two Docker tests of the Caddyfile (just caddy-test: the GitHub proxies under /gh/, the desktop update feeds and the legal pages' runtime values) run separately. Playwright runs only Chromium and the Android phone emulation with two workers:

just e2e          # = playwright test -c e2e/playwright.config.ts --project chromium --project mobile-android --workers=2

The suite serves dist/ with astro preview on port 4400 (E2E_PORT changes it), so build first. It needs the Chromium of Playwright 1.63 (pnpm exec playwright install chromium if it is not cached).

The wiki and its sources

The wiki has three groups: Users (written here, in src/content/docs/users/), Node admins and Developers. The pages of the last two are not kept in this repository: they are copied at build time from the repositories where they are versioned with the code, so they always match it.

Submodule	What the wiki takes from it
sources/tavrn	docs/self-hosting.md (admin overview), docs/architecture.md, docs/roadmap.md (also /roadmap)
sources/tavrn-node	docs/HANDBOOK.md, split into one page per section, and deploy/.env.example (the configuration reference)
sources/tavrn-protocol	The specification: README.md, PROTOCOL.md, FEDERATION.md, ENCRYPTION.md and the other documents
sources/tavrn-js	The READMEs of sdk/, e2ee/ and bot/
sources/tavrn-web	docs/CLIENT.md, docs/DESKTOP.md, docs/ACCESSIBILITY.md

scripts/sync-docs.mjs does the copying (the list is scripts/docs-sources.mjs). It runs before every pnpm dev, pnpm build and pnpm typecheck, and alone as just sync-docs. It writes src/content/docs/synced/ and src/content/pages/roadmap.md (both gitignored) and

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗