# Sonik component docs site

The docs site is a VitePress app in `docs-site/` that documents Sonik components with design guidelines (from Notion), Sonik vs PrimeVue metadata, and live examples.

## Commands

- **`npm run docs:dev`** — Sync Notion + component metadata, generate component pages, then start the VitePress dev server. Open the URL shown (e.g. http://localhost:5173).
- **`npm run docs:build`** — Sync and build the static site into `docs-site/.vitepress/dist`.
- **`npm run docs:sync`** — Run only the sync steps (Notion, component metadata, component page generation). Use this when you want to refresh generated data without starting the server.

You must run `docs:sync` (or `docs:dev` / `docs:build`) at least once so that `docs-site/generated/` exists and component pages are generated under `docs-site/components/`.

## Adding documentation for a new component

**Component doc pages** are generated automatically: `generate-component-pages.ts` (run as part of `docs:sync`) creates `docs-site/components/<category>/<name>.md` for every component in the meta list. Each file is a minimal stub with `layout: doc`; the theme’s ComponentLayout renders the real content (Notion, metadata, examples). You don’t create or edit these `.md` files by hand.

1. **Notion**
   Add a row in the [component guidelines database](https://www.notion.so/loop-returns/95dc774f9afa4610b39b1ebbb2b59930?v=837f4f98103849769e63db10197a25c6) with:
   - **Component Key** (or Title/Name): same as the path in `lib/components/`, e.g. `form/autocomplete`.
   - Optionally: **Purpose**, **When to use**, **When not to use** (rich text), Status, Usage guidelines, Do, Don't, Figma link.
   Purpose / When to use / When not to use are rendered at the top of each component doc page (see sync script comments for full column list).

2. **Component metadata (optional)**
   If the Sonik wrapper differs from PrimeVue (removed/added props, behavior changes), add `lib/components/<category>/<name>/docs.ts` that exports a default object with:
   - `componentKey`, `primevueUrl`, `primevueComponentName`
   - `removedProps`, `addedProps`, `behaviorChanges`, `notes`
   See `lib/components/panel/card/docs.ts` for an example.

3. **Examples (optional)**
   Add one or more example Vue components under `lib/components/<category>/<name>/examples/`, e.g. `Basic.vue`. They should import from the public short path `@loophq/sonik/<name>` and are used in the component page’s Examples section.

4. **Regenerate**
   Run `npm run docs:sync` (or `docs:dev` / `docs:build`). The new component will appear in the sidebar and get its own page. To (re)generate minimal `Basic.vue` examples for all components, run `npm run docs:generate-examples`.

## Notion sync (optional)

To pull guidelines from Notion into the docs site, set:

- `NOTION_API_KEY` — Integration token (Settings → Connections in the database).
- `NOTION_DATABASE_ID` — From the database URL: the 32-character id (with or without dashes).

If these are not set, the sync script still runs and writes an empty Notion index; component pages will show only metadata and examples.

**Example (placeholder values):**

```bash
# Inline when running
NOTION_API_KEY=foo NOTION_DATABASE_ID=bar npm run docs:sync
```

Or copy `.env.example` to `.env`, replace `foo`/`bar` with your real values, then load env before running (e.g. `source .env` in bash, or use a tool that loads `.env`). The script reads `process.env.NOTION_API_KEY` and `process.env.NOTION_DATABASE_ID`; it does not load `.env` itself.

## CI

The docs site is built in CI (`npm run docs:build`) to catch broken mappings, missing imports, or invalid generated content. See `.gitlab-ci.yml`.