| name | gazeplotter-docs |
| description | Conventions for the user-facing documentation served at /docs. MUST use when modifying anything under docs/ or adding a feature that needs documentation. |
GazePlotter Docs
The top-level docs/ tree is markdown rendered and served at the /docs route (import.meta.glob('/docs/**/*.md') in src/routes/docs/docs.ts). It is the user-facing source of truth.
Structure
Real top-level pillars: setup/, upload-data/, metrics/, visualizations/, export/, advanced/ (plus index.md).
- Plot/visualization pages live in
docs/visualizations/ (e.g. scarf-plot.md). There is no docs/basic/; old basic/* slugs are 308-redirected via the REDIRECTS map in src/routes/docs/[...slug]/+page.ts.
- Data-format pages live in
docs/upload-data/.
DOs
- Mirror exact UI labels case-sensitively and in bold: if the UI says Stimulus, write Stimulus, not "the stimulus button".
- Update docs in the same change as the code: a new plot needs a
docs/visualizations/<plot>.md; a new or changed ingest format needs the matching docs/upload-data/<format>.md.
- Callouts use the
> **Bold Title**: Content blockquote syntax.
- Screenshots use the
/docs/images/... path (assets live in static/docs/images/).
- Internal links use absolute
/docs/... paths.
- Document format constraints precisely against the parser. Format parsers live in
src/lib/data/ingest/formats/ (e.g. csvSegmentedDuration.ts, tobii.ts); if the docs state required headers or segmentation rules, the parser must enforce them. Headers vary by format (e.g. the time-series custom CSV uses Time, Participant, Stimulus, AOI per docs/upload-data/custom-csv.md), so do not state one header set as universal.
DONTs
- No fuzzy UI descriptions and no conversational fluff; use clinical, senior-level technical writing.
- Do NOT use
::: custom blocks or # headers inside callouts.
- Do NOT invent a parameter table from memory. Plot setting defaults come from each plot's
getDefaultSettings (plus the optional size field) in src/lib/plots/<plot>/definition.ts via definePlot. They are NOT in registry.ts, and there is no getDefaultConfig.
Page metadata
A page's title and description in the /docs route come from the SIDEBAR config in src/routes/docs/sidebarConfig.ts (read by getDoc in docs.ts), matched by href, NOT from YAML frontmatter. Frontmatter is inconsistent across the corpus and does not drive rendered metadata; when adding a page, add its SIDEBAR entry.
