Timeline DSL Landing & Docs
日本語 README →
LP / documentation site for the public Timeline DSL project. Timeline DSL is a Rust-based DSL compiler for defining timelines as text, importing Wikidata-backed data, and rendering the result as HTML / SVG / PNG / PDF.
Tech stack
| Area | Stack | Notes |
|---|
| Site framework | Astro 7 + Starlight 0.41 | Static LP, docs, changelog, gallery, showcase, and playground routes. |
| Language/runtime | TypeScript 6, Node.js 26, pnpm 12 | All commands run under site/. |
| Styling | Astro components + CSS tokens | Global design tokens live in site/src/styles/tokens.css; avoid ad-hoc colors. |
| Playground | Vendored @keroway/tdsl-wasm 2.1.0 | Browser validation and SVG rendering go through site/src/lib/tdsl-wasm.ts. |
| Search | Pagefind generated at build time | Used by the site-wide search dialog. |
| Quality | astro check, Vitest, Biome, Prettier, axe-core, Playwright, Lighthouse CI | pnpm build is the minimum CI gate; extra smoke scripts cover SEO/i18n/a11y/playground. |
| Hosting | Cloudflare Pages | GitHub integration builds from site/ and publishes dist/. |
Local development
cd site
pnpm install --frozen-lockfile
pnpm dev
Common commands:
pnpm fetch:releases # Fetch keroway/timeline-dsl GitHub Releases into site/src/data/
pnpm smoke:wasm # Smoke-test the vendored WASM bridge
pnpm smoke:playground # HTTP smoke test for Playground
pnpm smoke:a11y # axe-core audit for key pages (requires Chromium)
pnpm lint
pnpm format:check
pnpm build # smoke:wasm → astro check → astro build
pnpm check # lint → format:check → test:unit → build → bundle-size (local CI mirror, non-browser)
pnpm check:full # pnpm check + preview server + all browser/a11y/visual/Lighthouse gates
pnpm preview
Deploy
Deployment is handled by Cloudflare Pages via GitHub integration. GitHub Actions runs the Site build workflow's full required-status-check gate (lint, format:check, test:unit, build, bundle-size, smoke:seo, smoke:i18n, smoke:i18n:browser, smoke:playground, smoke:playground:browser, smoke:a11y, test:visual, lhci) as CI only; publishing and Preview URL creation are delegated to Cloudflare Pages. pnpm check mirrors the non-browser steps locally, and pnpm check:full additionally covers the browser-dependent gates.
Cloudflare Pages project:
- Project name:
timeline-dsl
- Production branch:
main
- Build command:
pnpm build
- Build output directory:
dist
- Root directory:
site
- Deploy command: (no setting shown)
Workflows:
Site build: Runs the full CI gate (lint / format:check / test:unit / build / bundle-size / smoke:seo / smoke:i18n / smoke:i18n:browser / smoke:playground / smoke:playground:browser / smoke:a11y / test:visual / lhci) on PR, main push, and manual dispatch.Remove in-progress label on close: When a PR is merged, removes the in-progress label from issues referenced by Closes #N / Fixes #N / Resolves #N in the PR body. Also removes the label when an issue is directly closed. On manual dispatch, specify issue_number to remove the label from any issue.
Event policy:
pull_request: Runs GitHub Actions Site build and Cloudflare Pages Preview deployment. During review, verify / and /docs/ on the Cloudflare Pages Preview URL.push to main: Cloudflare Pages deploys to https://timeline-dsl-lp.pages.dev as the production branch.release.published: Not used as a direct deploy trigger via the Cloudflare Pages GitHub integration. Releases are published after a main merge once the production deployment succeeds.workflow_dispatch: Limited to manually re-running GitHub Actions CI. To re-run a deployment, use the Retry deployment button in the Cloudflare Pages dashboard.
If the Cloudflare settings UI requires a Deploy command or shows a deploy command for non-production branches, you are looking at Workers Builds, not Pages. This site is a Pages project — import the GitHub repository from Pages in the Cloudflare dashboard, not Workers.
Quality gates (Lighthouse CI)
The Site build workflow runs Lighthouse CI (@lhci/cli) against the running preview server after the smoke tests, guarding against silent regressions in performance, accessibility, SEO, and best-practices scores. Run it locally with the preview server up:
cd site
pnpm preview & # or pnpm dev
pnpm lhci # set LHCI_BASE_URL to target a non-default origin
Audited pages (one per archetype, across both locales): /, /en/, /docs/, /playground/, /gallery/, /showcase/, /changelog/. Each is measured 3 times and the median is asserted. Config: site/lighthouserc.cjs.
Baseline thresholds and their rationale:
| Category | Level | Min score | Rationale |
|---|
| Performance | error | 0.80 | LCP/TBT vary with shared CI runner load, which is why it originally started as a non-blocking warning; promoted to error after 3+ months and 15+ runs showed zero threshold breaches (#663). |
| Accessibility | error | 0.90 | A static, token-driven site clears this reliably; complements the axe-core smoke:a11y audit. |
| Best practices | error | 0.90 | Catches console errors, insecure resources, and deprecated APIs introduced by future changes. |
| SEO | error | 0.90 | The site lives or dies by discoverability; metadata/hreflang/JSON-LD regressions must fail CI. |
Desktop preset is used (the docs site is primarily read on desktop, and it keeps the performance score stable). To raise a threshold or promote performance to error, edit the assert.assertions block in site/lighthouserc.cjs.
WASM bundle
All calls to the Timeline DSL WASM from the Playground and runnable docs go through site/src/lib/tdsl-wasm.ts only. The generated @keroway/tdsl-wasm browser package is vendored in site/public/wasm/ so the LP can build independently of the main repository release pipeline.
To update: build crates/tdsl-wasm in the main repo with wasm-pack build --target web, then sync tdsl_wasm.{js,d.ts}, tdsl_wasm_bg.wasm, and package.json into site/public/wasm/. pnpm build runs check_source and render_svg_from_source smoke tests before the main build.
