Contributing to the Docs

This site is a VitePress docsite, themed from design-system/DESIGN.md, gated behind Cloudflare Access. Drop a markdown file into a category folder and it appears in the sidebar. Need richer than markdown? Inline Vue lives in the same file. Need a fully standalone artifact? Drop it in public/.

InternalAudience: OnRamp engineersStack: VitePress + Vue + DESIGN.md tokens

Using Claude Code? Reach for the docs skill first. It encodes everything on this page — category structure, the three fidelity tiers, the stale mechanism, mermaid + design-token rules, maintaining section overviews, and a ready-to-fork HTML mock template — so an agent adds docs the right way without you re-explaining any of it. Just ask it to "add an architecture doc", "mark this doc stale", or "add an HTML mock to docs" and the skill loads automatically.

6

Categories

3

Tiers of fidelity

~30s

To add a markdown doc

0

Config edits required

Quick start

# from the repo root
bun install
bun run docs                 # vitepress dev docs --port 5199
# → http://localhost:5199

VitePress is pinned as a devDependency (vitepress@1.6.4), so bun run docs uses the local binary — no bunx fetch, reproducible across machines. There's also a Docs entry in .claude/launch.json (runs bun run docs) for the Claude Code preview tooling.

Drop-in workflow. Create docs/<category>/my-doc.md, add a title: and order: to its frontmatter, restart the dev server, and it's in the nav + sidebar. No config.mts edits.

Pick a tier of fidelity

Pick the lowest tier that fits — higher tiers add maintenance cost.

Tier 1 — Markdown

Plain markdown, fenced code, mermaid, frontmatter. The default for most docs.

---
title: My Doc
order: 3
---

# My Doc

Short intro paragraph.

## A section

- Lists
- `inline code`
- Tables, fenced code, mermaid all work natively

​```python
def hello(): return "world"
​```

​```mermaid
flowchart LR
    A[Start] --> B[Done]
​```

Use it for: runbooks, RFCs, architecture notes, dev-setup guides — anything that reads top-to-bottom.

Tier 2 — Inline Vue

The .md file is compiled as a Vue template. You can write <script setup> at the top, declare reactive refs, and put v-show / v-if / @click on inline HTML. The page still lives in the docsite shell — sidebar, search, dark mode, theme all keep working.

---
title: My Interactive Doc
order: 3
---

<script setup>
import { ref } from 'vue'
const tab = ref(1)
</script>

<div class="my-doc">

# My Interactive Doc

<button @click="tab = 1" :class="{ active: tab === 1 }">Tab A</button>
<button @click="tab = 2" :class="{ active: tab === 2 }">Tab B</button>

<div v-show="tab === 1">

## Tab A

Normal markdown — lists, `code`, fenced ```mermaid``` blocks all render.

</div>

<div v-show="tab === 2">

## Tab B

More markdown content here.

</div>

</div>

<style>
.my-doc button.active { background: var(--color-primary); color: #fff; }
</style>

Two Tier 2 gotchas — read these first

1. Markdown inside HTML needs blank lines. To get markdown processed inside a <div> (e.g. a Vue v-show panel), separate it from the tags with blank lines. Otherwise the content is treated as raw HTML and stays unrendered.

2. <style> blocks in a .md are GLOBAL, not scoped. Wrap the page in a single <div class="my-page">…</div> and prefix every selector with .my-page so the styles don't leak to other pages.

Use it for: phase tabs, filterable tables, comparison toggles, anything that benefits from interactivity. See proposals/golden-seed.md for the worked example.

Tier 3 — Standalone HTML (escape hatch)

A full .html file in docs/public/ is served at the site root, bypassing the VitePress shell. Reach for this only when the content shouldn't live in the shell.

Genuine use cases:

• A customer-facing security document destined for our customers' security teams that intentionally doesn't follow the OnRamp design system.
• A single-file artifact you want to share/print outside the site.
• Content that depends on heavy libs the docsite build shouldn't carry.

Tradeoffs you accept:

• Not indexed by the docsite's local search.
• Not in the sidebar / nav.
• You build your own page chrome (header, footer, navigation).
• Theming is your responsibility — DESIGN.md tokens are still available via /tokens.css, but standalone HTML is also the right place to not track the design system on purpose.

How to add one:

1. Copy .agents/skills/docs/references/html-mock-template.html to docs/public/<name>.html.
2. The template <link>s /tokens.css (the live DESIGN.md token set). For a customer-facing doc that should ignore OnRamp branding, drop the link.
3. Optionally link to it from a category page with the themed .doc-cta-card / .doc-cta-button helpers in theme/custom.css.

If you find yourself wanting Tier 3 for an internal interactive doc (tabs, filters, diagrams) — use Tier 2 instead. You'll get the same interactivity and keep search, sidebar, and dark mode.

Categories

Every category is a top-level folder under docs/. Drop a .md in and it appears.

Folder	Sidebar label	Goes here
architecture/	Architecture	System/design docs.
research/	Research	Deep-dive investigations / external research.
design-system/	Design System	DESIGN.md tokens, style guidance.
proposals/	Proposals & RFCs	Design proposals/RFCs. Copy proposals/_template.md.
runbooks/	Runbooks & Guides	Operational runbooks.
dev-setup/	Dev Setup	New-machine / dev-environment setup.

Add a new category

Add one row to CATEGORIES in config.mts and create the matching folder with at least one .md (otherwise it's skipped):

const CATEGORIES = [
  { dir: 'architecture', label: 'Architecture' },
  // ...
  { dir: 'my-new-cat', label: 'My New Category' },
]

Marking a doc stale

Out-of-date docs stay reachable (so inbound links don't break) but lose top billing. Set stale: true in the frontmatter:

---
title: Old Architecture Note
stale: true
staleNote: Superseded by the Views agent rework — kept for history.   # optional
---

Two things happen automatically off that one flag:

• The doc drops out of its category's main list into a collapsed "Stale" sub-group at the bottom of that category in the sidebar.
• A warning banner renders at the top of the page (injected by theme/Layout.vue).

The file does not move, so its URL is unchanged and inbound links keep working.

Recently updated on the home page

The home page shows a Recently updated grid of the six freshest docs — so a doc you add surfaces there with no extra work. The signal is the last git commit date for the file (falling back to file mtime if git history isn't available at build time); stale-flagged docs and category landing pages are excluded.

Mermaid diagrams

Fenced ```mermaid blocks render client-side. The theme cleans up after failures so a single broken diagram can't pollute other pages.

Semicolons break sequenceDiagram text. ; is a statement separator in mermaid's sequence grammar. Inside any sequenceDiagram message or Note, use —, ,, or <br/> instead.

Note over X: token validated; identity locked    ❌ parse error
Note over X: token validated, identity locked    ✓

Design tokens

The docsite imports the live DESIGN.md token set. Use the CSS variables for every color, font, and radius — never hardcode brand hex.

/* available globally on every page */
color: var(--color-primary);          /* brand primary (Core Purple) */
background: var(--vp-c-bg-soft);      /* dark-mode aware surface */
border-radius: var(--radius-lg);      /* 16px */
font-family: var(--font-body);

Variable family	Source	Use for
--color-primary, --color-brand-*, --color-purple-50..950 (+ pink/green/red/orange/black ramps)	design-system/generated/tokens.css (from DESIGN.md)	Brand, accents, tints.
--vp-c-bg, --vp-c-bg-soft, --vp-c-bg-alt, --vp-c-text-1, --vp-c-text-2, --vp-c-divider, --vp-c-brand-1	VitePress + theme overrides	Surfaces and text — dark-mode aware. Prefer these for chrome.
--radius-xs..xl, --font-body	DESIGN.md	Shape and type.

See /design-system/ in the sidebar for the palette and full token list.

Run locally / build / deploy

bun run docs            # dev w/ HMR        (vitepress dev docs --port 5199)
bun run docs.build      # production build   (catches dead links)
bun run docs.preview    # serve the built site locally

These scripts call the pinned local vitepress@1.6.4 binary. The dev branch auto-deploys to Cloudflare Pages; to preview any other branch before merge, run the Docs Preview GitHub Action (workflow_dispatch in .github/workflows/docs-preview.yml) against your ref for a shareable URL.

Dev-server restart needed for new files/categories. The nav + sidebar are generated by a filesystem scan at config-load time. HMR covers content edits live, but a newly added file or category only shows up after the dev server restarts (or in a fresh build).

See also

• For Claude Code agents: the docs skill — same content, agent-targeted.
• Tokens source of truth: design-system/DESIGN.md. Hand-edit; generated artifacts flow from it.
• VitePress docs: vitepress.dev for the framework itself (Vue in markdown, frontmatter, custom theme).