Website & Publishing
One Astro app (website/) serves both public surfaces
(ADR-0014):
- Landing page (
fjarr.io/) — plain Astro pages that sell the idea and link into the docs. - Developer docs (
fjarr.io/docs/…) — Starlight rendering the engineeringdocs/tree directly (a symlinked content collection), so published docs and repo docs can never fork. Writing for the repo is writing for the public.
Authoring rules
Section titled “Authoring rules”- Every doc carries frontmatter (
title,description) — required by Starlight, harmless on GitHub. - Relative links between docs (
[x](08-protocol.md#anchor)) — they work in GitHub, editors, and Starlight alike. - Mermaid diagrams in fenced blocks (rendered client-side on the site).
- ADRs publish too — they are the “why” documentation integrators love.
- Feature-status honesty: the landing page labels capabilities with
their real roadmap state (
in development,planned) pulled from docs/17. Never market what doesn’t run.
Local workflow
Section titled “Local workflow”make website-dev # astro dev on http://localhost:4321make website-build # production build (CI gate from M0.5)make docs-lint / make docs-links gate the content itself
(docs/13).
Deployment
Section titled “Deployment”Cloudflare Workers Builds via Git integration — no deploy workflow, no
secrets in CI; Cloudflare builds and deploys on every push to main.
Domains fjarr.io + fjarr.dev are registered on Cloudflare (2026-09-15);
repo: github.com/fjarrio/fjarr. The repo carries a root wrangler.jsonc
declaring the site as a static-assets Worker (website/dist).
One-time setup (Cloudflare dashboard → Workers & Pages → Create →
Connect to Git → fjarrio/fjarr):
| Setting | Value |
|---|---|
| Project name | fjarr |
| Build command | pnpm --filter fjarr-website build (Cloudflare auto-runs pnpm install --frozen-lockfile first) |
| Deploy command | npx wrangler deploy |
| Path (advanced) | leave empty (repo root — the pnpm workspace must resolve) |
| API token | “Create new token” (the auto-generated one is fine) |
| Environment variable | NODE_VERSION = 22 |
| Non-production branch builds | on (preview deployments for PRs) |
pnpm’s exact version comes from the root package.json packageManager
field. After the first deploy, attach domains under the Worker’s
Settings → Domains & Routes: add fjarr.io (primary) and
fjarr.dev (or a redirect rule fjarr.dev → fjarr.io). CI
(.github/workflows/ci.yml) independently gates lint/links/build on PRs so
broken docs never reach main.
Versioning published docs
Section titled “Versioning published docs”Until v1: single “latest” tracking main, with the status column in
docs/README as the maturity signal. From the first versioned
release: evaluate Starlight’s versioning plugin
(open question #14); ADRs and the business plan stay
unversioned (they are history, not reference).
Landing page content model
Section titled “Landing page content model”Sections, each owned by a doc so marketing never drifts from engineering: hero (from 00-vision one-liner) → “the problem” (prior-art story) → three-tier integration diagram (from 02) → capability grid with status badges (from 06 + 17) → open-core/pricing summary (from 03) → docs CTA.