For Contributors

This section is for those who fork and develop Timeline DSL itself or this documentation site, create pull requests, and maintain publish settings.

If you only need to create, validate, and render .tdsl files, start with Installation and Quick Start.

Local setup

This site is built with Astro + Starlight, and all commands run under site/. It uses pnpm as the package manager and Node.js 26.

cd site
pnpm install --frozen-lockfile  # install dependencies
pnpm dev                        # dev server (http://localhost:4321)

Local quality gates

Two aggregate commands reproduce the same gates CI runs (.github/workflows/site-build.yml). Run at least pnpm check before pushing.

Command	What it does
pnpm check	Fast, non-browser gate. lint → format:check → test:unit → build (smoke:wasm → astro check → astro build) → bundle-size
pnpm check:full	Everything above, plus a preview server and smoke:seo / smoke:i18n(:browser) / smoke:playground(:browser) / smoke:a11y / test:visual / Lighthouse CI. Always stops the preview server, on success, failure, or interruption. Needs Chromium (pnpm exec playwright install chromium).

pnpm check:full includes smoke:i18n:browser and smoke:playground:browser, and these do run in CI (browser gates are never skipped there). Individual commands (pnpm smoke:wasm / smoke:playground / smoke:i18n / smoke:seo, etc.) remain runnable on their own.

If you change the LP’s layout, colors, or typography, run pnpm test:visual on its own, confirm the diff is an intended change, then update the baselines with pnpm test:visual:update. Baseline image changes need visual review and should be included in the PR (pnpm test:visual itself also runs in CI under the RUN_FULL condition).

Pull request conventions

• Write commits in Conventional Commits form (feat: / fix: / docs:, etc.).
• Always link the issue with Closes #N in the PR body, and keep the PR title within 70 characters.
• Split the PR when a change spans multiple concerns (1 PR = 1 logical change).
• Force-pushing to main is forbidden (it breaks the CI history and the Cloudflare Pages deployment history).
• Confirm the Cloudflare Pages preview deployment is green before merging.

i18n pairs and design tokens

• When you edit a ja document, update the matching en page in the same PR. Do not leave English titles on Japanese pages.
• Do not hard-code new colors; use the --color-* tokens in site/src/styles/global.css. When a new color is genuinely needed, add the light / dark / high-contrast set together.

Related pages

• Site Deployment