Documentation Site

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

# Documentation Site Template (Vanilla)

A premium, minimal, **light-mode-first** developer documentation template built
for DevSnips with plain HTML, CSS (Pico CSS foundation), and vanilla JavaScript.
The template is split into modular files — `code.html` (HTML structure) +
`style.css` (the design system) + `script.js` (router, content, interactions) —
with `preview.html` as a self-contained single-file preview of the UI so you can
open it directly and see exactly how the template looks.

**Technology:** vanilla
**Category:** templates
**Subcategory:** documentation-site
**Type:** single-page (15 documentation sections, hash-routed)

## Files

```
Documentation Site/
├── code.html               # HTML structure (links style.css + script.js) — the modular source
├── style.css               # the design system (Pico CSS foundation + DevSnips --ds-* tokens)
├── script.js               # router + content (15 sections) + interactions (vanilla JS, no deps)
├── preview.html            # single-file preview of the UI (inlines style.css + script.js) — open this to see it
├── metadata.json           # DevSnips registration metadata
├── README.md               # This file
└── assets/
    ├── logo.svg            # DevSnips [D] mark
    └── favicon.svg         # DevSnips favicon
```

## Preview

Open `preview.html` directly in a browser to see the template — it is a
self-contained single-file preview that inlines the CSS and JS:

```bash
cd "Vanilla/Templates/documentation-site"
python3 -m http.server 8080
# visit http://localhost:8080/preview.html
```

For development and customization, work with the split files — open `code.html`
(which references `style.css` and `script.js` relatively) in the same served
folder. The whole template runs without a build step. The only external requests
are Google Fonts (Inter + JetBrains Mono) and Pico CSS, both from CDNs.

Per the shared `design-tokens.md` convention, the template folder contains
exactly **one** `preview.html`. It is the canonical preview shown by the DevSnips
website. It is fully responsive, uses the template's real CSS/JS, uses relative
paths, and loads correctly when opened directly.

### Architecture

The template is split into three modular files plus a single-file preview:

- **`code.html`** — the HTML shell (header, sidebar, main, TOC, search modal,
  drawer) that links `style.css` and `script.js`. This is the modular source you
  customize.
- **`style.css`** — the entire design system: Pico CSS overrides, the `--ds-*`
  token layers, and every component style.
- **`script.js`** — the runtime + content: a `NAV` config drives the nested
  sidebar, a `PAGES` object maps each section ID to a content-builder function,
  and the runtime handles routing, scrollspy, search, code tools, theming, and
  the mobile drawer. All content for all 15 sections lives here — there are no
  separate `pages/`.
- **`preview.html`** — a self-contained single-file preview that inlines
  `style.css` and `script.js` into the `code.html` structure, so it can be opened
  directly with no build step and renders identically to the modular version.

### Sections (15)

| Group | Sections |
|---|---|
| **Start** | Documentation Home, Introduction, Getting Started, Installation, Quick Start |
| **Library** | Vanilla, Components, Templates, Design Tokens |
| **Reference** | Guides, API Reference, Examples, FAQ |
| **Project** | Changelog, Roadmap, Contributing |

### Design system

The template extends the shared DevSnips `--ds-*` token system (defined in
`Vanilla/Templates/design-tokens.md`) with a handful of `--template-*` variables
that adapt — never override — the global language. It is **neutral-first** with
one controlled **blue-600** accent (never violet/neon), hairline 1px borders,
restrained shadows, an Inter + JetBrains Mono type scale, a base-4 spacing
scale, and small radii by default. Light and dark mode are supported via a
`data-theme` attribute on `<html>` with a no-flash system-preference fallback.

## Features

- **Single SPA** covering all 15 documentation sections via hash routing
- **Nested sidebar navigation** with four groups, expandable parents, active
  page state (`aria-current`), and a live filter input
- **Breadcrumbs**, **last-updated metadata**, **reading-time estimate**, and an
  **edit-on-GitHub** action on every content page
- **Sticky scrollspy table of contents** generated per page from `h2`/`h3`
  headings via `IntersectionObserver`; collapses to a tappable panel below 1180px
- **Previous/next navigation** at the foot of every content page
- **Cmd+K (and `/`) search command palette** — arrow-key navigation, Enter to
  open, Esc to close, grouped results with matched-term highlighting
- **Code blocks** with a lightweight vanilla-JS syntax highlighter
  (HTML, CSS, JS, JSON, Bash), a language label, and a **clipboard copy button**
- **Tabbed code blocks** (e.g. npm/pnpm/yarn) with ARIA tablist semantics
- **Five callout variants** — info, note, tip, warning, danger
- **Responsive tables** in `overflow-x:auto` wrappers (never cause page overflow)
- **Status/category badges** — stable, beta, deprecated, accent, neutral, solid
- **API reference blocks** with signature, return type, parameter table, example
- **Light/dark mode** — no-flash system preference + persisted header toggle
- **Responsive by composition** — sidebar → off-canvas drawer below 1024px,
  TOC → collapsible panel below 1180px, header compacts below 640px

## Accessibility

Skip link, semantic landmarks (`header`/`main`/`nav`/`aside`/`article`), ARIA
on the search dialog, tablists, drawer, breadcrumbs, and TOC, `:focus-visible`
rings throughout, keyboard-operable controls (Escape closes overlays, Cmd/Ctrl+K
and `/` open search, arrow keys navigate results), and `prefers-reduced-motion`
guards on every animation.

## QA

Verified with Playwright across six viewport widths (320–1920px):

- **0 console errors** on every page and breakpoint
- **0 horizontal overflow** — `scrollWidth == clientWidth` at 320, 375, 768,
  1024, 1280, and 1920px
- Strict HTML5 valid (html5lib), valid `metadata.json`
- Interactions pass: hash routing + active nav, scrollspy TOC, search open/close,
  theme toggle, code copy buttons, code tabs, mobile drawer open/close

Zero runtime dependencies beyond Pico CSS and Google Fonts (both from CDN).

## Customizing

The whole template is data-driven from the top of the `<script>` block in
`preview.html`:

- `NAV` — sidebar structure (groups, items, nested children, badges)
- `META` — per-page eyebrow, title, last-updated date, edit-on-GitHub path
- `PAGES` — per-section content-builder functions

To add a section: add an entry to `NAV`, a row to `META`, and a `PAGES.<id>`
function. The router, TOC, search index, and prev/next pick it up automatically.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# AGENTS.md — Documentation Site

Guidance for an AI agent adapting this template. Read this before editing.

## What this template is

A light-mode-first developer documentation template: 15 routed sections via hash routing, a nested sidebar, a scrollspy TOC, a Cmd+K search palette, tabbed code blocks with a lightweight syntax highlighter, and five callout variants. Modular files.

## Design system

Built on the shared [`design-tokens.md`](../design-tokens.md) `--ds-*` token system (1062 references, 81 unique tokens—the most token-saturated template). **Light is the default**; dark mode is opt-in (persisted, no-flash pre-paint script). Blue-600 accent—never violet/neon.

## File layout

```
Documentation Site/
├── pages/
│   ├── code.html      # HTML structure (links style.css + script.js)
│   ├── style.css      # the design system (--ds-* tokens)
│   └── script.js      # router + content + scrollspy + search + code tools + theme
├── assets/            # logo.svg, favicon.svg
├── preview.html       # self-contained preview (inlines CSS+JS)
├── metadata.json
└── README.md
```

All content lives in `script.js` (`NAV` config + `PAGES.<id>` content builders)&mdash;there are no per-page files. `preview.html` is `code.html` with `style.css` + `script.js` inlined.

## How to adapt it

1. **Change the docs content**: edit the `PAGES` object in `pages/script.js` (each page id maps to a content-builder function). The router and sidebar regenerate from `NAV`.
2. **Restructure navigation**: edit the `NAV` config in `pages/script.js` (groups + nested entries).
3. **Rebrand**: edit the `--ds-*` tokens in `pages/style.css` `:root`&mdash;keep blue-600 as the accent.
4. **Rebuild the preview**: after editing the modular files, regenerate `preview.html` by inlining `style.css` and `script.js` into `code.html`.

## Do not

- Do not introduce a framework. The router, search, and highlighter are deliberately vanilla.
- Do not move content out of `script.js` into separate page files&mdash;the hash router expects in-memory content builders.
- Do not darken the default theme. Light is the canonical docs experience.

## Quality bar

Reduced-motion guards on all animations, ARIA on the search dialog / tablists / drawer / TOC, `:focus-visible` rings, keyboard-operable (Esc, Cmd/Ctrl+K, `/`, arrows, Enter). Run `python3 scripts/qa/resources/qa_vanilla.py` after changes.

## Gotcha

`script.js` and the inlined `preview.html` script block contain example code strings with literal `<script>` tags&mdash;the closing `</script>` must be escaped as `<\/script>` in JS source or the HTML parser closes the real script block prematurely.