The source for docs.stable.xyz — Stable's stablecoin
payments, liquidity, and infrastructure documentation. Built with
Vocs and deployed to Cloudflare (see wrangler.jsonc).
If you are an agent or contributor working in this repo, read this first.
Significant technical decisions are documented as ADRs in ADRs/.
Each record captures the context, decision, and consequences of a
choice so the rationale survives beyond the conversation that produced it.
- Before changing architecture, search
ADRs/for an existing decision. Do not silently revisit a settled decision — extend or supersede it with a new ADR. - After making a significant decision, write an ADR. Naming convention:
DR###_DESCRIPTIVE_NAME.md(zero-padded, incrementing — e.g.DR009_Search_Provider.md). - See
ADRs/README.mdfor the full convention and the index of current records.
English is the source of truth — write content in docs/pages/en/ only;
cn/ko are generated by the translation pipeline. See
CONTRIBUTING.md for the editor workflow and
DR002 for the rationale.
Requires Node >=22 (see .nvmrc).
nvm use
npm install
npm run docs:dev # local dev server
npm run docs:build # static build (outputs to docs/dist)
npm run docs:preview # preview the production build
npm run check # full local verification gate- Run
nvm useso Node 22 is active. - Edit source content in
docs/pages/en/only. - If pages are added, moved, renamed, or deleted, update only the
/ensection ofdocs/sidebar.json. - Run
npm run checkbefore opening or handing off a PR.
| Path | Purpose |
|---|---|
docs/pages/ |
Content pages (en, cn, ko locales; en is the source of truth, Diátaxis structure) |
docs/sidebar.json |
Navigation (/en hand-maintained; /cn+/ko generated from it — localized links + labels) |
docs/lib/structured-data.ts |
Per-page JSON-LD / SEO <head> injection (see DR001) |
docs/lib/verify-i18n.mjs, docs/lib/i18n-translate.mjs, docs/lib/i18n-sidebar.mjs |
i18n parity checker + page translation engine + sidebar generator (see DR002) |
docs/components/, docs/layout.tsx, docs/styles.css |
Theme and layout |
vocs.config.ts |
Site config, theme, nav, socials |
ADRs/ |
Architectural Design Records |
- Content:
docs/pages/en/ - Generated translations:
docs/pages/cn/,docs/pages/ko/ - Navigation:
docs/sidebar.json - Runtime customization:
vocs.config.ts,docs/layout.tsx,docs/styles.css - SEO and analytics:
docs/lib/structured-data.ts,docs/lib/analytics.ts - Automation:
docs/lib/*.mjs,.github/workflows/*