Working on these docs

This site lives in docs/ and is built with Astro Starlight. It’s a static site, served at https://docs.zimmet.dev.

Run and build

cd docs
npm install
npm run dev       # http://localhost:4321
npm run build     # static output in docs/dist
npm run preview   # serve the build

Writing pages

Pages are Markdown or MDX files in docs/src/content/docs/. The file path is the URL: guides/custody.md is served at /guides/custody/.

Each sidebar group is generated from a folder (getting-started, concepts, guides, reference, development). Set the order inside a group with frontmatter:

---
title: Custody handovers
description: One sentence, used for search results and link previews.
sidebar:
  order: 1
---

Use asides for notes and warnings:

:::caution[Demo limitation]
Nothing is sent.
:::

Status chips match the app’s colors: <span class="status bad">faulty</span> (classes ok, warn, idle, bad, off).

Languages

English pages live at the root. Turkish pages mirror the same paths under tr/: the Turkish version of guides/custody.md is tr/guides/custody.md, served at /tr/guides/custody/. Internal links in Turkish pages must start with /tr/.

When a page has no Turkish version, Starlight shows the English one with a note that it isn’t translated yet. Sidebar group labels are translated in astro.config.mjs (translations).

When you change an English page, update its Turkish counterpart in the same change.

Deploying

The site is deployed like the landing page, as a static-assets Cloudflare Worker through Workers Builds:

Setting	Value
Root directory	`/docs`
Build command	`npm ci && npm run build`
Deploy command	`npx wrangler deploy`
Custom domain	`docs.zimmet.dev`

docs/wrangler.jsonc serves dist/ as static files, with 404.html for unknown paths. Its name must match the Worker’s name in Cloudflare. Without this file, wrangler detects Astro and auto-installs the @astrojs/cloudflare SSR adapter, and the build fails.

To deploy from your machine:

cd docs
npm run build
npx wrangler deploy

site in astro.config.mjs is set to https://docs.zimmet.dev, which canonical URLs and the sitemap use. Change it there if the domain changes. public/_headers caches hashed assets for a year, and public/robots.txt points crawlers to the sitemap.