` and meta description) that hydrates on load, plus a `404.html` fallback — deep links work with no rewrite rules on any static host (GitHub Pages, Netlify, Vercel, S3). `build` runs `check`'s work first, so everything that command calls an error fails the build: site-structure errors (unknown `@section`, two entities on one route, unresolvable `home`), grammar errors, an unresolved `component={…}`, and a stage that does not compile. Checking first is also what makes the message readable — Vite would report a stage error against the virtual module (`/@sdocs/iframe/<base64>/x.svelte (81:2)`), while this path names the `.sdoc` file and line. A stage error in `dev` still shows Vite's overlay with the virtual id; run `sdocs check` for the mapped location. Pass `--base` when serving under a sub-path (a GitHub *project* Pages site lives at `/<repo>/`): ```bash npx sdocs build --base "/my-repo/" ``` `sdocs check` compiles every stage and validates the site structure without starting a server or writing a build, printing each problem with its file, entity, and stage, and exiting 1 when anything errors — the CI gate for "do all the docs still work?". The MCP `check_docs` tool runs the same check. `check` and `build` both fail on site-structure errors (unknown `@section`, two entities on one route, an unresolvable `home`) and on a `component={…}` reference that resolves to no component file — one map, read the same way, so `check` never passes a site `build` would refuse. The dev server only warns about the latter, so the doc can be fixed while it runs. Because `run`/`build` need no local install, CI can build a docs site from a project that doesn't even depend on sdocs: `npx --yes sdocs build` then publish `dist/`. **Embedding** — instead of the standalone server, mount sdocs as a route in an existing Vite/SvelteKit app via its Vite plugin (`sdocsPlugin()`); options passed there override the config file, and `routing` defaults to `'hash'` when embedded. ## MCP server sdocs ships an MCP server with authoring tools, so an agent can validate and scaffold `.sdoc` files against the real parser instead of guessing — and read the current project's components and docs through the same extraction the Explorer uses: - `validate_sdoc { source }` — parse `.sdoc` text and return diagnostics (message, code, 1-based line/column), the entities found, and each entity's resolved `route`. Check the route before committing to a title: slugs lowercase each segment whole, so `IconButton` serves at `/iconbutton`. - `scaffold_component_doc { componentPath, title? }` — extract a `.svelte` component's props and return a starter `.sdoc` (control defaults derived from the props) plus the suggested file path; it never writes files. - `get_authoring_guide { section? }` — this guide. It runs to about 40k characters, so pass `section` when you only need one part of it: `section: 'prose'` returns the `[PROSE]` chapter alone, matching a case-insensitive substring of the heading. A section that matches nothing comes back as the list of headings. Also exposed as the `sdocs://authoring-guide` resource. - `get_changelog { since? }` — this install's `CHANGELOG.md`. With `since`, the reply leads with every **breaking** change released after that version, then the full entries. **Call it whenever the project's installed sdocs is newer than the version this guide describes.** `list_docs` reports the running version; a `.sdoc` written against an older format may not parse. This is the migration path — there is no separate migration tool, because the breaking sections of the changelog are what a migration would say. - `list_docs {}` — map the project's documentation: every `.sdoc` file the config's `include` globs match, each with its entities (kind, title), the **route** each one serves at (plus a route per example), the components its previews document, and everything the entity carries — its `notes`, its `[TODO]` tree, its `[GLOSSARY]` terms, and each component's `status`. The routes come from the Explorer's own router, so they're exactly what the site serves — drive a browser over them to smoke test every page. - `search_docs { query?, type?, limit? }` — find documentation by any name it goes under: the entity title, a component it previews, that component's `synonyms`, an example title, an example's `tags`, a `[GLOSSARY]` term or its definition, a `[TODO]` line, or the text of any `notes` on either. Matching is a case-insensitive **substring**, so `butt` finds `Button` and `menu` finds every example tagged "user menu". `type` sweeps by note status instead — `type: 'bug'` lists everything marked bug with no query at all, and `'none'` finds notes written without one; give both and a result has to satisfy both. Each hit says which names matched, the notes it carries, and the route it serves at — pass that route to `resolve_visual_target` to screenshot it. Reach for it before reading files. - `set_notes { file, entity, example?, notes }` — replace a `[NOTES]` block's contents. Pass the whole list you want; an empty one removes the block. Each note is `{ note, type? }` with type `bug`/`a11y`/`warning`/`perf`/`tip`/`info`. - `set_status { file, entity, component, status }` — set a `[COMPONENT]`'s status, or `null` to remove it. Name the component by its `component={…}` identifier, or by its `title="…"` when one entity previews the same component twice. - `set_todos { file, entity, example?, todos }` — replace a `[TODO]` checklist. Items are `{ text, done?, children? }`, nesting to any depth. - `toggle_todo { file, entity, example?, path, done }` — tick one item by its position at each level (`[1, 0]` is the first child of the second root item, as `list_docs` reports the tree). Rewrites one character; prefer it to `set_todos` when you are only ticking something off. **The four writes above edit the project's `.sdoc` files.** Each rewrites the smallest span that will do — a block's own span, or a single attribute — so formatting, comments and every other byte survive. Reach for them rather than editing `.sdoc` text yourself: they cannot produce a file that does not parse. Each refuses any path the project's `include` globs do not already match. - `check_docs { file? }` — **compile** every stage (previews, examples, page and layout bodies) the way the dev server does and report what breaks: Svelte compile errors, relative imports that resolve to no file, and grammar diagnostics — with the file, entity, stage, and a `.sdoc` line where it maps cleanly — plus site-structure errors when checking the whole project. `validate_sdoc` only checks the grammar; this catches what otherwise appears only when the route is opened. Omit `file` to check the whole project. It does not type-check and cannot see runtime-only failures: a stage whose `<script>` throws compiles cleanly, and the throw surfaces in the preview frame instead. - `check_coverage {}` — documentation coverage: which components under the `components` globs have a `[COMPONENT]` preview and which don't, plus components documented from more than one file, references that resolve to no source, and documented components outside the globs. A compound family is measured per sub-component. - `resolve_visual_target { target, file? }` — resolve a stage ("Button / Sizes", a route from `list_docs` — an entity route resolves to that entity's own stage, a stage route to that stage — or a stage id) to a preview-only route, the selectors to wait on, the `.svelte` file and `.sdoc` line behind it, its declared `args`, and its resolved stage layout. Ambiguity is reported, never guessed. - `get_component_api { componentPath }` — a component's full extracted API: props (types, defaults, descriptions), events, snippets, methods, states, CSS custom properties, and class/rest forwarding. The server also serves `sdocs://visual-testing-guide`: how to inspect a component through a browser without photographing the whole Explorer. ### Looking at a component with a browser Every stage is its own page. `/@sdocs/preview/<token>/<slug>` renders one `[COMPONENT]`, `[EXAMPLE]`, or `[LAYOUT]` — project css, declared args, no Explorer chrome — and works as a direct top-level navigation. Photographing that instead of the Explorer is the difference between ~2 image tokens and ~2000 for the same button. The page carries what automation needs: - `<html data-sdocs-stage-ready>` — set after mount, webfonts, and image decode. A stage that *fails* is marked ready too (with `data-sdocs-stage-error="render|script|timeout"`), so a client never hangs. - `window.__sdocs.stage` — `{ id, kind, name, component }`. - `window.__sdocs.captureRect(selector?, { padding })` — a clip rect grown to include what the element actually paints. A tight crop to `boundingBox()` **clips shadows, glows, and focus rings**; this reads the computed styles instead. Reports `bleeds` (paints outside its box) and `clipped` (the halo runs past the viewport). - `window.__sdocs.inkBleed(selector?)` — the per-side overflow on its own. - `?axis-<id>=<value>` sets `data-<id>` on the document — one per configured axis, combinable (`?axis-scheme=dark&axis-density=compact`) to open a stage in one exact variant. `list_docs` reports the project's axes and their values. - `?scale=<number>` sets the scale custom property (add `?scale-var=--ui-scale` when the project renamed it), so a stage can be photographed at a given size. - `?theme=<name>` sets `data-sdocs-theme` on the document; `?css=<name>` picks a configured stylesheet. Media-query themes are the browser's to emulate. Prefer reading the DOM over any screenshot: `getComputedStyle` answers spacing and color questions exactly, where an image can only be estimated from. In dev, each stage shows a copyable id on hover — the handle for `resolve_visual_target`. sdocs takes no screenshots and depends on no browser. Two ways to connect: - **stdio** — `npx sdocs mcp` (e.g. `claude mcp add sdocs -- npx -y sdocs mcp`, or the equivalent stdio entry in any MCP client config). The VS Code sdocs extension registers this server automatically. - **HTTP** — while `sdocs dev` runs, the same server is served at `http://localhost:3000/mcp` (stateless streamable HTTP, POST), and the Explorer top bar shows an **MCP** button with the connection info. Dev only: built sites are static and carry no MCP endpoint. Disable both with `mcp: false` in `sdocs.config.js` (the explicit `sdocs mcp` command still works). ## Built-in routes Two routes exist in every site, alongside the ones your entities create: - `/about` — the mascot, what the project contains, and the sdocs version that built the site. Also the landing page when the config sets no `home`. - `/changelog` — the changelog of the sdocs that built the site, rendered at build time and shipped with it. Not fetched from GitHub: a docs site is often read offline or behind a firewall, and the log that matches the version in your hands is the useful one. Reached from the About page and from the top bar's menu, and code-split, so a reader who never opens it never downloads it. ## Configuration sdocs reads `sdocs.config.js` (or `.ts`/`.mjs`) from the project root — checked in the order `.ts` → `.mjs` → `.js`, first found wins (prefer `.js`/`.mjs` unless your Node strips TS types). Missing config is fine; defaults apply. ```ts interface SdocsConfig { include?: string | string[]; // globs for .sdoc files. Default ['./src/**/*.sdoc'] port?: number; // dev port. Default 3000 (standalone CLI only) open?: boolean; // open the browser on dev/preview. Default false css?: string | Record<string, string>; // stylesheet(s) loaded into STAGES only. Default null title?: string; // top-bar title. Default 'sdocs' logo?: string | false; // 'sdocs' mascot | image URL | false. Default 'sdocs' favicon?: string; // tab icon path/URL sections?: ({ slug: string; title?: string; order?: string[] } | { type: 'divider' })[]; home?: string; // route path of the landing page routing?: 'history' | 'hash'; // Default 'history' (CLI), 'hash' (embedded) base?: string; // public base path for build. Default '/' mcp?: boolean; // serve /mcp + the top-bar MCP button in dev. Default true components?: string | string[]; // component globs for coverage. Default: include with .sdoc → .svelte axes?: { id: string; label?: string; values: string[] }[]; // design-system dimensions the reader can switch. Default [] scale?: { min?: number; max?: number; default?: number; step?: number; var?: string; label?: string; presets?: { label: string; value: number }[] }; // a top-bar slider setting a CSS custom property on every stage static?: string; outDir?: string; // where `sdocs build` writes. Default 'dist'. The build // empties it, and refuses one it did not create.// static assets folder, served at site root content?: { // per-entity-kind sizing/stage defaults (see below) doc?: { maxWidth?: string; padding?: string; toc?: boolean; contentX?: string }; page?: { maxWidth?: string; padding?: string; contentX?: string }; showcase?: { maxWidth?: string; padding?: string; direction?: string; gap?: string; contentX?: string; contentY?: string; background?: string; minHeight?: string }; layout?: { maxWidth?: string; padding?: string; background?: string; minHeight?: string }; }; } ``` Key options: - **`include`** — glob(s) matching `.sdoc` files. Relative to project root. - **`css`** — stylesheet(s) loaded into **stages only** (preview/example iframes and `[LAYOUT]` pages), never page prose or the docs chrome — this is what keeps "your product" and "the documentation" visually separate. A single path, or a `{ name: path }` map the reader switches between via a dropdown (e.g. light / dark). Keep build stylesheets self-contained (inline `@import`/`url()`; fonts can be data URIs). Stage css is processed by Vite, so an `@import` resolves against the **importing file**, not the site root: pulling in a stylesheet that lives in the `static` folder must be root-absolute (`@import url('/fonts/faces.css')`), because postcss leaves absolute URLs to the browser and would otherwise fail with ENOENT. This is the one place the base-relative rule used for stage *assets* does not apply. - **`static`** — a folder served at the site root in dev and copied into `dist/`. In **prose** reference assets root-absolute (`![hero](/hero.png)`); inside **stages** reference them **base-relative, no leading slash** (`src="hero.png"`, `path="icons/x.svg"`), because the stage carries a `<base href>` for correct resolution under a sub-path deploy. - **`sections`** — the top-bar sections in order, each `{ slug, title?, order? }`. `slug` is the first route segment and what titles reference via `@slug/…`; `order` is an array of route paths that sort first. Default: a single implicit `docs` section. Referencing an undeclared section is a build error. A `{ type: 'divider' }` entry draws a rule between the tabs on either side of it — it has no slug, no routes and no sidebar, and one with no section before it (or none after) draws nothing. - **`axes`** — dimensions of the design system the reader can switch between, each `{ id, label?, values }`. Every axis gets a top-bar control (segmented while there's room, a dropdown once there isn't), and the reader's pick lands on every stage's `<html>` as `data-<id>="<value>"`. **sdocs never interprets an axis** — the project's own css supplies the meaning (`[data-density="compact"] { --space-md: 8px }`), which is why a project can declare any dimensions it likes. The first value is the default; `label` defaults to the capitalized `id`; ids are lowercase letters/digits/dashes and `sdocs-` is reserved. Prefer this over named `css` stylesheets when variants multiply: three palettes × two densities is six files but two axes. A dark theme must be reachable by attribute — a `prefers-color-scheme`-only theme can't be switched — and should set `color-scheme` so native controls follow. - **`scale`** — a continuous knob, rendered as a slider in the top bar beside the axis controls. Its value lands on every stage's `<html>` as a CSS custom property — `--scale` unless `var` names another — so the project's css can multiply by it (`padding: calc(8px * var(--scale, 1))`). Defaults: `min` 0.75, `max` 1.5, `default` 1, `step` 0.05, `label` 'Scale'. Clicking the control's label or its value — anything but the slider itself — returns it to the default, as does double-clicking the slider. The label drops away when the bar runs short of room, at the width the axis switches turn into dropdowns. Unlike an axis it carries a *property* rather than an attribute, because a range has no set of names to key off: one rule reading a number beats a rule per step. The pick persists, and a stage page takes it as `?scale=1.25` (with `?scale-var=--ui-scale` when the project renamed it). `presets` adds named stops — `[{ label: 'S', value: 0.875 }, { label: 'M', value: 1 }]` — rendered inside the slider's own control, to the right of its value; the slider still reaches everything between, and a preset outside `min`–`max` is refused rather than clamped, since a button that lands somewhere other than its label says is worse than one that isn't there. - **`home`** — route path of the landing page (root URL + logo target). Default: the built-in About page. Must resolve to an entity. - **`base`** — set to `/<repo>/` for a GitHub project Pages deploy (or pass `--base` on the CLI). Applies to `build` only. `content` defaults, overridable per entity/block with the same attributes (**block beats entity beats config**): | kind | maxWidth | padding | other | |---|---|---|---| | `doc` | `1200px` | `32px` | `toc: true`, `contentX: left` | | `page` | `1200px` | `32px` | `contentX: left` | | `showcase` (stages) | `1200px` | `16px` | `direction: row`, `gap: 16px`, `contentX: left`, `contentY: top`, `background`/`minHeight`: none | | `layout` | `100%` | `0px` | `background`/`minHeight`: none | `minHeight` reserves room for content that overflows the stage (an open dropdown or popover) that the auto-sized preview would otherwise clip. --- # The `.sdoc` format ## File anatomy Three parts, in this order (only the entities are required): 1. `<script>` — top, optional. Imports and shared values (JS/TS), visible to every entity in the file. 2. Entities — the middle. Any mix of `[SHOWCASE]`, `[PATTERNS]`, `[DOC]`, `[PAGE]`, `[LAYOUT]`. Each is its own route and (usually) its own sidebar entry. 3. `<style>` — bottom, optional. CSS available to the file's previews/examples. Name the file after its main entity (`Button.sdoc`) and put that entity first. The file `<script>` is shared *source*, not shared *state*: every preview and example renders isolated, so each gets its own copy of anything mutable. ## Syntax rules - Tags are line-anchored square brackets, each on its own line: `[SHOWCASE …]` opens, `[/SHOWCASE]` closes. - Entity tags are UPPERCASE (`[SHOWCASE]`, `[PATTERNS]`, `[DOC]`, `[PAGE]`, `[LAYOUT]`); inner blocks inside them are UPPERCASE too (`[COMPONENT]`, `[COMPONENTS]`, `[EXAMPLE]`, `[NOTES]`, `[TODO]`, `[PROSE]`). `[COMPONENT]` and `[EXAMPLE]` are also accepted lowercase, indefinitely — files written before 0.0.139 keep working, and the formatter capitalizes them when a document is next formatted. The text blocks are uppercase-only, so a line opening with a markdown link (`[notes](…)`) stays prose. - Attributes use Svelte syntax: `title="text"` (string), `component={Button}` (expression), `args={{ … }}` (expression). Openers may span multiple lines. - Svelte code is valid only *inside* blocks; body text outside any block is an error. ## The four entities | Entity | Documents | Context | |---|---|---| | `[SHOWCASE]` | components — live previews with controls, examples, extracted API | stages: project | | `[DOC]` | freeform markdown content, auto table of contents | prose: docs | | `[PAGE]` | a Svelte-built page (landing pages, custom routes) | docs | | `[PATTERNS]` | one composition of several components — a user menu, a notifications system | stage: project | | `[LAYOUT]` | a full-page composition of your product, isolated frame | project | `[PATTERNS]` is a `[SHOWCASE]` with the prop half switched off. It documents a composition — several components assembled into one thing — which has no single component whose API it could extract, so there is no `[COMPONENT]`, no props panel and no controls. Everything else is the same: `[EXAMPLE]` states, `[PROSE]` between them, `[NOTES]`, `[TODO]`, `[GLOSSARY]`, the same stages. ```sdoc [PATTERNS title="Patterns / User Menu" description="Avatar, menu and badge."] [EXAMPLE title="Signed out"] <Menu>Sign in</Menu> [/EXAMPLE] [EXAMPLE title="Signed in"] <Avatar name="Ada" /> <Menu>Profile · Sign out</Menu> [/EXAMPLE] [/PATTERNS] ``` Attributes are the `[SHOWCASE]` set: `title` (required), `description`, `slug`, `hide`, and the stage attributes. Each `[EXAMPLE]` is a state, gets its own sidebar entry under the pattern and its own route. A `[COMPONENT]` in one is an error pointing at `[SHOWCASE]`; loose markup is an error, as in a `[SHOWCASE]`. **Project context vs docs context** (the concept that ties the format together): `[EXAMPLE]`/`[COMPONENT]` **stages** and `[PATTERNS]`/`[LAYOUT]` bodies load your project's `css` — they look like your product. `[DOC]` prose and `[PAGE]` bodies render in the **docs** context (the docs app's own styling, its CSS variables) — the project `css` never touches them. Rule of thumb: *prose is docs-styled, stages are project-styled.* ## Titles place entities: sections, groups, folders The `title` is a `/`-separated path that builds a three-level navigation hierarchy: - **Section** (`@slug/` prefix) — the top-level separation: a **tab in the top bar**, declared in `sdocs.config.js` (`sections: [{ slug, title?, order? }]`). Each section has its own sidebar tree, and the slug is the first route segment. `title="@components/…"`. An undeclared slug is a full-page error; a title with no `@` goes to the `docs` section (implicit when no sections are declared). Use sections for the site's major areas: Guides vs Components. Route segments are slugified from the title: lowercased, spaces to hyphens, and accented letters folded to their base (`Verificări` → `verificari`, `Zażółć` → `zazolc`). Scripts with no ASCII base (Greek, Cyrillic, CJK) have nothing to fold to and need an explicit `slug="…"` on the entity — which is also how you pin a route that must not move when the title is reworded. - **Group** (`:` prefix on the first segment after the section) — a **bold uppercase header** carving the sidebar into areas of similar things (`:Layout`, `:Form`, `:Display`). Expanded by default; only the first segment can be a group. `title="@components/:Form / Button"`. - **Folder** (any plain segment) — a **collapsible tree node** that stacks entities under it: `title="Foundations / Page 1"`, `"Foundations / Page 2"` puts both pages under a Foundations folder. Folders nest (`"Forms / Inputs / Text"`), are purely structural (not pages themselves), and start collapsed. Combine all three: `title="@components/:Layout / sdocs / Button"` → the `components` tab, the **LAYOUT** group, an `sdocs` folder, a Button page. **How a segment becomes a route slug**: lowercase → strip anything that isn't a word character, whitespace, or `-` → replace runs of whitespace and `_` with a single `-`. **CamelCase is not split**, so `IconButton` becomes `iconbutton`, not `icon-button`. Write the title with a space (`'Icon Button'`) or override the segment on the opener — `slug="icon-button"` (lowercase letters, digits, and hyphens only). `list_docs` returns the resolved route for every entity, so an agent never has to reimplement this. Two more structural facts: - A component page with examples becomes its own expandable node with one sub-page per example — selecting the component itself shows its docs. A doc with several `[COMPONENT]` previews gets a distinct compound icon. - `:` groups are always expanded; folders start collapsed. - **Ordering**: siblings at every level sort alphabetically; pin items first by listing their route paths in the section's `order` array (`order: ['introduction', 'form/button']`). The page heading and browser tab show only the title's **last segment** — the levels above it structure the nav, not the page. ## `[SHOWCASE]` — documenting a component Holds any number of `[COMPONENT]` previews (live, control-driven) and `[EXAMPLE]` blocks (frozen, verbatim). Zero previews is valid (examples-only page). Several previews grow a **tab bar** — made for compound families like `Tabs`/`Tab` (wrap the child in its parent inside each preview body). Attributes: `title` (required), `description` (inline markdown), `slug`, `hide` (routable but unlisted), plus stage defaults its blocks inherit: `maxWidth`, `padding`, `direction`, `gap`, `contentX`, `contentY`, `background`. These attributes are how a stage is laid out. The stage element is itself the flex container, so content goes straight into the block — see "the stage is already the container" below before reaching for a wrapper `<div>`. ### `[COMPONENT]` — a live, interactive preview ```sdoc [COMPONENT component={Button} args={{ variant: 'primary', disabled: false }}] <Button {...args} /> [/COMPONENT] ``` - `component={X}` (required) — an identifier imported in a `<script>`. Drives prop extraction and the interactive controls. Compound members resolve too — `component={NavTree.Item}` from a single `import NavTree from './index.js'`. The index module is read as TypeScript, so the root resolves through `export default`, `export { X as default }`, `Object.assign(Root, …)`, and annotated forms (`const Nav: typeof Root & { Item: typeof Item } = …`). A reference that resolves to nothing is an error in `check` and in a build. - `args={{ … }}` (optional) — this preview's control defaults. In scope in the body: spread it (`<X {...args} />`), pick from it, or ignore it. - `synonyms="pill, chip"` (optional) — the other names this component answers to. A comma-separated list; spacing, a trailing comma and a repeat all wash out. Rendered as quiet chips above the preview, and searched by `search_docs`, so a reader (or an agent) looking for "chip" lands on the Badge that is one. - `title` (tab label — defaults to the component name; set it to distinguish two previews of the same component), `description`, and the same stage attributes. Declared `args` seed the stage's initial state, so a component that reads a required prop on first render has it before the controls' first update; a stage that throws anyway shows the error in place instead of going blank. **`args` values are plain literals only: strings, numbers, booleans, and `null`.** They are sent into the isolated preview at runtime, so no expressions, arrays, objects, or imported values — put anything richer directly in the body markup, where full Svelte is available. One invalid value rejects the whole `args` object, so keep every value literal. ### `[EXAMPLE]` — a frozen showcase Renders **exactly what you wrote**; controls never touch it. Requires a `title` (unique within the block). Same stage attributes as `[COMPONENT]` plus `description`. Examples render below the previews and stay visible on every tab; the same block also works inside a `[DOC]`, mid-prose. `code="false"` (optional) hides the example's code panel — for a `[DOC]` that wants the rendered thing and not its source. Shown by default; anything but `"true"` or `"false"` is an error rather than a silent no. `tags="user menu, badge"` (optional) marks what an example shows — the parts it puts on screen, or the context it belongs to. Same comma-separated list as `synonyms`, rendered as quiet chips under the description, and searched by `search_docs`: tag every example that composes a user menu and one query collects them from across the project. ## `[NOTES]` — standing remarks One note per line, once per entity and once per `[EXAMPLE]`: ```sdoc [SHOWCASE title="Forms / Button"] [NOTES] - bug: Focus ring lands 1px off in Safari. - a11y: The icon-only variant has no accessible name. - warning: Being replaced by ActionButton in v4. - tip: Pair it with Field when it labels an input. - Ships in the next release. [/NOTES] [COMPONENT component={Button} status="review"] <Button {...args} /> [/COMPONENT] [/SHOWCASE] ``` - Each line is `- text`, or `- type: text`. A note's text is one line: the block's grammar is one note per line, so a wrapped note is two notes. - The type is one of `bug`, `a11y`, `warning`, `perf`, `tip`, `info`. Leave it off and the note is a plain remark, shown in grey. A type outside that set is an error, not a silent fallback: grey is a real choice, and a typo would read as one. - A note is an **observation** — what should someone know about this. Where a component sits in its life is `status` on the `[COMPONENT]`, which is a property of the thing rather than a remark about it; the two vocabularies were one until 0.0.140. - Each renders as an alert directly under the entity's title, in the order written. - **Only `[SHOWCASE]`, `[DOC]` and `[EXAMPLE]` bodies hold them.** A `[PAGE]` or `[LAYOUT]` body is captured whole as Svelte markup, so a block written there is never read back — it renders as literal text on the page. sdocs reports it (`block-in-body`) rather than letting it through. Under `sdocs dev` the Explorer can write them: a note button at the end of every entity and example title opens an editor, and Save rewrites the `[NOTES]` block in the `.sdoc` itself. It is offered only where a block can actually live — `[SHOWCASE]`, `[DOC]` and their examples. Dev only — the endpoint behind it exists on no built site, and it refuses any file the project does not document. In the sidebar the notes become one dot on the row: **filled** when the worst of them is on that page, **hollow** when it is on something inside it. A row shows the worst note at or under it, ranked by how much it costs the reader to not know: `bug` > `a11y` > `warning` > `perf` > *no type* > `tip` > `info` `a11y` sits under `bug` because it is a defect with a narrower blast radius, and above `warning` because it is still a defect rather than a caveat; `perf` sits under `warning` for the same reason in the other direction. A note with no type outranks `tip` and `info` deliberately — an author who did not reach for a word was not being reassuring. A `hide` entity's notes stay out of the roll-up. ## `status` — where a component is in its life An optional attribute on `[COMPONENT]`, shown as a glyph after the name on its tab (which is why the tab strip renders even for a single component): ```sdoc [COMPONENT component={Button} status="experimental"] <Button {...args} /> [/COMPONENT] ``` One linear path, plus the end of it: | Value | Means | |---|---| | `draft` | sketched, not real yet | | `wip` | being built | | `review` | built, waiting on sign-off | | `experimental` | usable, but the API may still change | | `ready` | done — use it | | `deprecated` | on the way out | `review` and `experimental` are both "not final", and the difference is who they wait on: a review waits on a person, an experiment waits on real use. Leave it off and the component has no status, which reads as *nobody said* — a different thing from `draft`. A value outside the set is an error rather than a silent no-status, for the same reason an unknown note type is. This is a property of the component. A remark *about* it — including "this is being replaced by X" — is a `[NOTES]` line, which can carry the text that says what to use instead. ## `[TODO]` — a checklist Once per entity and once per `[EXAMPLE]`, nested to any depth by indentation: ```sdoc [TODO] - [x] Ship the component - [ ] Document the dark theme - [ ] Decide the token names - [x] Pick the ramp [/TODO] ``` Every line is `- [ ] text` or `- [x] text`; the text is inline markdown. It always renders when present — this is not a dev-only affordance — and under `sdocs dev` the boxes are live: ticking one writes straight back into the `.sdoc`, rewriting the single character between the brackets and nothing else. A built site shows the same list read-only, since there is no source there to write to. Indentation is meaning here, not layout: it is what nests one item under another. The formatter leaves a `[TODO]` body exactly as written for that reason. ## `[GLOSSARY]` — a titled list of terms One `- Term: what it means` per line, rendered where it is written. As many per entity as you like — a page can carry both "Terms" and "Abbreviations". ```sdoc [GLOSSARY title="Terms" subtitle="Words this page uses" search] - Stage: the isolated frame a preview renders in, with the project's css. - Measure: the width of a line of text, in characters. [/GLOSSARY] ``` - `title` — heading above the list. Without one, no heading renders. - `subtitle` — a line under the title; inline markdown renders. - `search` — a bare flag showing a filter box over the terms. **Off by default**: a filter over four terms is furniture, and only the author knows whether the list is four terms or forty. - The definition is inline markdown. The first colon splits the line, so a term may not contain one. A line that is not a definition is an error rather than a dropped entry, and so is the same term twice. In a `[SHOWCASE]` it flows with everything else, in source order. In a `[DOC]` it sits **mid-prose**, exactly where written — the same splice an `[EXAMPLE]` in a doc body already uses. Its tag is matched **uppercase only**, unlike `[COMPONENT]` and `[EXAMPLE]`: a tag carrying attributes cannot use the "nothing else on the line" rule that keeps `[glossary](/some/link)` a markdown link, so the casing does that job. ## `[PROSE]` — markdown between the blocks A `[SHOWCASE]` is not only a component and its examples — it can explain itself. `[PROSE]` gives it the capabilities of a `[DOC]` body (markdown, code fences, tables, Svelte islands) anywhere in the entity, as many times as it likes: ```sdoc [SHOWCASE title="Forms / Button"] [PROSE] A button triggers an action. For navigation, use a link. [/PROSE] [COMPONENTS] [COMPONENT component={Button}] <Button {...args} /> [/COMPONENT] [COMPONENT component={ButtonGroup}] <ButtonGroup {...args} /> [/COMPONENT] [/COMPONENTS] [PROSE] ### Choosing a variant Ghost buttons are for the third action in a row, never the first. [/PROSE] [EXAMPLE title="Ghost"] <Button variant="ghost">Cancel</Button> [/EXAMPLE] [/SHOWCASE] ``` Blocks render **in the order they were written**, with one exception: several `[COMPONENT]` blocks are tabs over a shared stage, so the whole tab strip is a single item wherever the first of them appears. Inside an `[EXAMPLE]`, `[PROSE]` is markdown only — no islands to compile — and it follows the example to its own route, where a sibling block would not. A `[DOC]` takes no `[PROSE]`: its body is already prose, and a block nested in it would have no answer to where it goes relative to the body around it. ## `[COMPONENTS]` — one tab strip `[COMPONENT]` blocks are not flow, they are tabs: several of them share one stage, one code panel and one API table. `[COMPONENTS]` makes that explicit, so the strip is a single item and prose around it means something. - A lone `[COMPONENT]` needs no container. - Two or more **must** sit inside one `[COMPONENTS]`. With two bare components and prose between them there is no correct place for the tab strip they share, so this is an error rather than a guess. - One container per `[SHOWCASE]`, holding `[COMPONENT]` blocks only. ## Scoped `<script>` / `<style>` — the ladder Any container can open with a `<script>` and close with a `<style>`; scopes nest lexically: **file → entity → block**. File script visible everywhere; entity script (right after the opener) visible to that entity's blocks/body; block script (the **first** content of the body, `<style>` the **last**) local to that block. Don't re-import or re-declare a name the file script provides (scopes nest, they don't shadow); `args` is in scope in preview scripts; reserved names (`args`, `__sdocsRef`, `__sdocsExample`) are diagnosed where they'd collide. ## `[DOC]` — freeform markdown Body is markdown, rendered with an auto table of contents (from `##`–`####` headings; hide with `toc="false"`). Attributes: `title`, `maxWidth`, `padding`, `contentX`, `toc`, `slug`, `hide`. A leading `#` heading becomes the displayed page title (the `title` attribute then only names the sidebar entry). The markdown dialect is GitHub-flavored, plus two Svelte conveniences and inert fences: - **`{expression}` interpolation** — values from the file `<script>` drop into prose: `currently {version}`. A balanced `{…}` is passed to Svelte verbatim. - **Svelte islands** — a line starting with a component/HTML tag (`<Button`, `<div`) or a Svelte block (`{#snippet`, `{@render`), after a blank line, begins an island that runs until its tags/blocks balance. Islands run in the **docs** context (structure the page itself; for product-styled output use `[EXAMPLE]`). - **Snippets** — declare `{#snippet name(...)}…{/snippet}` as an island, render with `{@render name(...)}` anywhere in the body. - **GFM** — headings, links (external open in a new tab), images, tables with `:---:` alignment, task lists (`- [x]`), `~~strikethrough~~`, blockquotes, rules, and **alerts**: a blockquote whose first line is `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!CAUTION]` renders as a tinted callout. - **Inert fences** — code inside ``` fences ``` (and `` `inline code` ``) is displayed/highlighted, never executed, even if it looks like a component or an `[EXAMPLE]` opener. Fence languages: anything shiki knows, plus `sdoc`. Escape a literal brace in prose as `\{`. Drop an `[EXAMPLE]` block anywhere in the flow to showcase real, project-styled components mid-prose. A page has no controls or prop extraction — for stateful component demos reach for a `[SHOWCASE]` or `[LAYOUT]`. ## `[PAGE]` — a Svelte-built page Body is plain Svelte (components, HTML, snippets, expressions) rendered as a real page in the **docs** context — no markdown, no toc, no stage tooling. This is how you build a landing page. Attributes: `title`, `maxWidth`, `padding`, `contentX`, `slug`, `hide`. There's no automatic heading — `title` names the route/sidebar entry; the markup is entirely yours. Sectioning is special for pages: a `@section/`-prefixed title behaves like any entity, but a **sectionless** title routes at the **site root** — `title="Welcome"` serves at `/welcome`, listed in no sidebar, reached by links or as the `home` page. Only `[PAGE]` may be sectionless. Markdown fences don't exist in a PAGE, so show code with the built-in component: ```svelte <script lang="ts"> import { CodeBlock } from 'sdocs/ui'; </script> <CodeBlock code={source} lang="sdoc" /> ``` `sdocs/ui` resolves even in standalone projects (the CLI provides its own copy). ## `[LAYOUT]` — a full-page composition Body is full Svelte, rendered full-width in an **isolated frame**: the host app's styles don't leak in — only `config.css` plus the file's own `<style>` apply. No controls, no prop extraction — just the composition. Attributes: `title`, `slug`, `hide`, `maxWidth` (default `100%`), `padding` (default `0px`), `background`, `minHeight`. Not the flex stage attributes — a layout body is flow-root. The frame fills the viewport height and scrolls when the sketch is taller, so a full-page composition previews like a real browser window; use a viewport unit (`height: 100vh` or `minHeight="100vh"`) for full height — `height: 100%` collapses against the content-height canvas. (Despite the name, unrelated to a SvelteKit `+layout.svelte` — it *is* a page.) Layouts can link to each other (and to any sdocs page) with plain anchors — see "Linking between pages" below — so a multi-screen sketch wires its flows together: a cart layout's checkout button opens the payment layout. ## Describing a component Two descriptions can sit under a component's tab, and they answer different questions: ```svelte  <script lang="ts"> let { label }: { label: string } = $props(); </script> ``` ```sdoc [COMPONENT component={Button} description="This preview starts disabled — flip the control."] <Button {...args} /> [/COMPONENT] ``` - The `.svelte` file's **``** comment describes the *component*, wherever it appears. It is Svelte's own convention — editors already show it on hover — so write it once, beside the code, rather than repeating it in every `.sdoc` that previews the component. **Markdown and code fences work inside it**, and sdocs renders them. - The block's **`description="…"`** describes *this preview*: what it is set up to show, what to try. Inline markdown only. Both render when both are present — the block's line first, the component's own underneath, then the stage. `get_component_api` returns the `@component` text too, so an agent reading a component's API sees what it is for. ## Writing components so sdocs documents them well For every previewed component, sdocs parses the source and extracts its full public API. What's extracted, and from where: | Category | Source | |---|---| | Props | a props interface + `let { … } = $props()`. The interface may carry any name — sdocs reads whichever type the `$props()` declaration is annotated with. **Defaults come from the destructuring**: binding `$props()` to a name (`let props: P = $props()`) still yields types, descriptions and optionality from the interface, but no defaults, and `get_component_api`/`scaffold_component_doc` return a `warnings` array saying so | | Events | props named `on*` whose type contains `=>` (a non-callback `on*` prop stays a prop) | | Snippets | props typed `Snippet` or `Snippet<[…]>` (the parameter tuple is preserved) | | Methods | `export function foo() { … }` | | States | `export const x = $state(…)` / `$derived(…)` | | CSS custom properties | `@cssvar` annotations (defaults filled in from `var()` fallbacks) | Rules that make the tables (and interactive controls) come out right: - **JSDoc descriptions**: a `/** … */` comment on an interface member, exported function, or state becomes its description — hard-wrapped lines are rejoined (list items keep their breaks) and inline markdown (`` `code` ``, `**bold**`, `*italics*`) renders styled. - **Select controls** need an **inline union** (`variant?: 'primary' | 'secondary'`); a type *alias* (`variant?: Variant`) can't be expanded into a control. - **Snippets**: for `children` / named snippets to be categorized as snippets (not props), declare a **named `interface Props`** — an inline `{ children: Snippet }` type is read as a prop. - **`class` / `...rest` forwarding** (a merged `class` + rest spread on the root element) is recognized from the `$props()` destructuring and rendered as chips under the props — never as fake required prop rows. When the interface `extends` a type (e.g. `HTMLAttributes<HTMLDivElement>`), the chip names it. - **Plain-JS components** get the same extraction through JSDoc: an inline `/** @type {{ label?: string }} */` on the `$props()` declaration, or `@typedef {Object} Props` + `@property {string} [label] - Description` (the bracketed name marks it optional; this form carries descriptions too). - **CSS custom properties**: a var is documented when it carries a `@cssvar` annotation in a JSDoc block inside the `<script>` — nothing is extracted from the `<style>` on its own, because a component references far more vars than a consumer is meant to override. The default is filled in from the style: the root `--x: value` declaration if the component sets one, else the `var(--x, fallback)` fallback when every use agrees — uses that disagree show **Mixed** (hover for the per-property breakdown). The annotation gives the var its type and description: `@cssvar {color} --bg - Surface background (default: var(--base-0))`. Types `color` (colour picker) and `dimension` (number + px) get specialised controls; other tokens (`shorthand`, `length`, `string`) fall back to a text field. Use a single token in the braces — a union there fails to parse and drops the var from the docs. A trailing `(default: …)` in the description sets the documented default. - **Limitations**: untyped `$props()` with no JSDoc extracts names and defaults only; non-`on*` callbacks are classified as props; complex or imported types show by name only (sdocs doesn't follow imports). ## Linking between pages from a stage An `<a>` inside any stage (a preview, an example, or a layout body) that points at another sdocs route navigates the **app**, not the iframe — the Explorer never re-renders inside the stage. Write the href as the target page's route, **base-relative** (no leading slash), exactly like stage assets: ```svelte <a href="guides/flows/payment">Payment</a>  <a href="components/layouts/auth/sign-up" style="display: block; text-decoration: none;"> <Button text="Sign up" width="fill" /> </a> ``` The route is the section slug plus the slugified title path — what the URL bar shows for that page. The stage page carries a `<base href>`, so base-relative links resolve in dev and under a sub-path deploy alike; a root-absolute `/guides/…` breaks under a sub-path. External `http(s)` links, `target="_blank"`, `download`, and same-page `#anchors` keep their native behaviour. ## Two authoring conventions worth internalising - **Pass CSS custom properties with Svelte's `--prop="value"` attribute syntax**, not a `style` string: `<Placeholder text="hi" --bg="var(--info-100)" --fg="var(--info-600)" />`. - **The stage is already the container — do not wrap its content.** A preview/example stage renders as `display: flex; flex-wrap: wrap` with `flex-direction`, `gap`, `justify-content` and `align-items` driven by its attributes, so a wrapper `<div>` only fights it. Lay content out with `direction`, `gap`, `contentX`, `contentY` and `padding` on the block instead. A wrapper for **height or scrolling** is redundant for a second reason: the frame measures its content and grows to fit, scrolling on its own past 800px. Nothing needs a fixed height to become scrollable. ```sdoc  [EXAMPLE title="Sizes"] <div style="display: flex; gap: 8px; height: 500px; overflow-y: auto;"> <Badge text="sm" /> <Badge text="md" /> </div> [/EXAMPLE]  [EXAMPLE title="Sizes" direction="row" gap="8px"] <Badge text="sm" /> <Badge text="md" /> [/EXAMPLE] ``` The one height knob worth reaching for is `minHeight`, and it does the opposite of a scroll box: it **reserves** room so content that overflows the stage — an open dropdown, a popover — is visible instead of clipped. ## Full example — a component doc ```sdoc <script lang="ts"> import Badge from './Badge.svelte'; </script> [SHOWCASE title="@components/:Display / Badge" description="A small status **badge** — dot, count, or label."] [COMPONENT component={Badge} args={{ text: 'New', size: 'sm' }}] <Badge {...args} /> [/COMPONENT] [EXAMPLE title="Sizes" direction="row" gap="8px" contentY="middle"] <Badge text="xs" size="xs" /> <Badge text="sm" size="sm" /> <Badge text="md" size="md" /> [/EXAMPLE] [EXAMPLE title="Coloured" description="Theme with `--bg` / `--fg`."] <Badge text="info" --bg="var(--info-100)" --fg="var(--info-600)" /> [/EXAMPLE] [/SHOWCASE] ``` ## Full example — a config ```js /** @type {import('sdocs').SdocsConfig} */ export default { include: ['./src/lib/**/*.sdoc'], title: 'Acme Design System', sections: [ { slug: 'guides', title: 'Guides', order: ['getting-started'] }, { slug: 'components', order: ['button', 'input', 'select'] }, ], home: 'guides/getting-started', css: './src/styles/global.css', axes: [ { id: 'scheme', label: 'Theme', values: ['light', 'dark'] }, { id: 'density', label: 'Density', values: ['airy', 'compact'] }, ], base: '/acme/', // for a GitHub project Pages deploy }; ``` ## More - Getting started: https://gabilungu.github.io/sdocs/explorer/getting-started - Configuration: https://gabilungu.github.io/sdocs/explorer/configuration - CLI commands: https://gabilungu.github.io/sdocs/cli/commands - Language overview: https://gabilungu.github.io/sdocs/language/overview - Component docs: https://gabilungu.github.io/sdocs/language/component-docs - Doc pages: https://gabilungu.github.io/sdocs/language/doc-pages - Svelte pages: https://gabilungu.github.io/sdocs/language/svelte-pages - Layout docs: https://gabilungu.github.io/sdocs/language/layout-docs

# sdocs — full reference > sdocs is a documentation tool for Svelte 5 components. It renders `.sdoc` > files into a documentation site: a `.sdoc` file is a documentation format that > *contains* Svelte — the file's structure is sdoc, and Svelte lives inside > designated blocks. This is a complete, self-contained reference — setup, > configuration, the CLI/build, and the full `.sdoc` authoring format — for > developers and coding assistants. Live docs: https://gabilungu.github.io/sdocs/ ## Requirements - **Node 22 or newer** (what the package declares and CI verifies). A `.ts` config additionally needs a Node with native type stripping. - Svelte 5 - Vite with `@sveltejs/vite-plugin-svelte` Install `@sveltejs/vite-plugin-svelte` in the project even when running via `npx`. sdocs takes the compiler from the project's plugin and pins the browser runtime to the project's `svelte`, so both halves come from ONE copy. Without the plugin, sdocs must compile with its own bundled svelte while your components run against yours; mismatched versions then break generated-code contracts (blank pages, `is not a function` from svelte internals). sdocs warns when it detects that split. ## Setup Install into a Svelte 5 project: ```bash npm install sdocs ``` Or skip installing entirely — with `.sdoc` files present, `npx sdocs run` fetches sdocs into the npx cache and serves them, resolving your components' dependencies (and your project's own `svelte`) from the project. Scaffold a config (optional — the defaults work with zero config): ```bash npx sdocs init ``` This writes a config with every option present but commented out. The file is `sdocs.config.js` when the project's package.json says `"type": "module"`, and `sdocs.config.mjs` otherwise — the config is an ES module, and Node reads a bare `.js` as a CommonJS script. Write a first doc next to a component (`src/lib/Button.svelte` → `src/lib/Button.sdoc`): ```sdoc [SHOWCASE title="Components / Button" description="A flexible button."] [COMPONENT component={Button} args={{ label: 'Click me', disabled: false }}]