Documentation

The docs are Markdown files in apps/docs, built into a site with VitePress: how the app is built under technical/, how each game works under games/.

Adding a doc

Link each new doc from index.md, and add it to the sidebar in .vitepress/config.ts.

Running the docs

To run the site locally from the repo root:

pnpm --filter @repo/docs dev:docs

Both build the diagrams first. pnpm --filter @repo/docs build:docs builds the site into .vitepress/dist.

Publishing

The site is served at docs.playcards.games by a Cloudflare Worker with static assets, set up in wrangler.jsonc. The Deploy Docs workflow builds and deploys it on each push to main that changes apps/docs, and can be run by hand from the Actions tab. There are no preview deploys for pull requests.

The workflow reads CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID from the docs GitHub environment, which only main can deploy to.

Diagrams

Diagrams are written in D2 under diagrams/. Each builds to a .light.svg and a .dark.svg, which aren't committed. Link to the light one from a doc; the site swaps in the dark one when its light/dark toggle is set to dark.

To check a diagram compiles without starting the site, from the repo root:

pnpm --filter @repo/docs build:diagrams