# Docs Update > Keep documentation up-to-date after code changes. Covers which docs to check, how to write them, and how to regenerate API docs. Use after any feature, fix, or refactor. Use when this capability is needed. - Skill: `tomevault-io/docs-update-6` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/docs-update-6` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/docs-update-6/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/docs-update-6 --- # Documentation Update Guide After any code change, use this checklist to identify which documentation needs updating and how. ## Quick Decision Matrix | What Changed | Update These Docs | | -------------------------- | -------------------------------------------------------------------------- | | New plugin | Plugin README, plugin `.mdx`, `llms.txt`, `llms-full.txt`, `Plugins.mdx` | | New public API | `API.mdx`, `llms.txt`, `llms-full.txt`, regenerate TypeDoc | | New CSS variable | `Theming.mdx`, `llms-full.txt`, `grid.css` registry comment | | New event | `API.mdx`, `events.mdx`, `llms-full.txt`, plugin `.mdx` if plugin-specific | | Plugin config change | Plugin `.mdx`, plugin README, `llms-full.txt` | | Breaking change | CHANGELOG (migration guide), `llms.txt`, `llms-full.txt` | | New adapter feature | Adapter README, adapter MDX docs, `llms-full.txt` | | Workflow/convention change | `.github/copilot-instructions.md`, `AGENTS.md` | | New skill or tooling | `.github/skills/`, `AGENTS.md` if Nx-related | ## Documentation Inventory ### Hand-Written (update manually) | Category | Location | When to Update | | ------------------------ | ------------------------------------------------ | ------------------------------------------------------ | | **Grid README** | `libs/grid/README.md` | New features, API changes, install instructions | | **Adapter READMEs** | `libs/grid-{angular,react,vue}/README.md` | Adapter feature changes | | **Plugin READMEs** | `libs/grid/src/lib/plugins/*/README.md` | Plugin feature changes | | **Core MDX docs** | `apps/docs/src/content/docs/grid/*.mdx` | Core features, theming, architecture, getting started | | **Plugin MDX docs** | `apps/docs/src/content/docs/grid/plugins/*.mdx` | Plugin features, config options, examples | | **Adapter MDX docs** | `apps/docs/src/content/docs/grid/adapters/*.mdx` | Framework-specific usage, examples | | **Demo components** | `apps/docs/src/components/demos/**/*.astro` | New demos, interactive feature showcases | | **LLM index** | `llms.txt` | Public API, plugin list, events, CSS vars changed | | **LLM full guide** | `llms-full.txt` | Any user-facing change (code examples, config, events) | | **Copilot instructions** | `.github/copilot-instructions.md` | Workflow, conventions, architecture changes | | **Agent instructions** | `AGENTS.md` | Nx or workspace convention changes | | **Contributing guide** | `CONTRIBUTING.md` | Development workflow changes | | **Architecture doc** | `libs/grid/ARCHITECTURE.md` | Internal design changes | ### Auto-Generated (regenerate, don't hand-edit) | Category | Generated By | Command | | ---------------------------- | ------------------------------------ | -------------------------- | | **TypeDoc API pages** | `typedoc-to-mdx.ts` scripts | `bun nx typedoc ` | | **CHANGELOGs** | `release-please` | Automatic on release PR | | **Custom elements manifest** | `@custom-elements-manifest/analyzer` | `bun run cem` | ## How to Write Each Doc Type ### Multi-Path Features When a feature has multiple configuration paths (e.g., CSS vs JS, declarative vs programmatic), **every documentation surface that covers the feature must:** 1. **State that both paths exist** — even if it only covers one in detail 2. **Explain when to use which** — include a comparison table with trade-offs 3. **Cross-reference** — link to the other doc surface that covers the other path in detail 4. **Identify the recommended default** — guide developers toward the simpler path unless they have specific needs Apply this to: icons (CSS vars vs `gridConfig.icons`), column config (declarative `` vs JS `columns`), features (declarative `features` vs manual `plugins`), styling (CSS custom properties vs `registerStyles()` vs `cellClass`/`rowClass`), etc. ### Plugin MDX (`.mdx`) Plugin MDX pages live in `apps/docs/src/content/docs/grid/plugins/`. Structure: ```mdx --- title: Plugin Name description: One-line description. --- import PluginDefaultDemo from '@components/demos/plugin-name/PluginNameDefaultDemo.astro'; import ShowSource from '@components/ShowSource.astro'; ## Installation \`\`\`typescript import { MyPlugin } from '@toolbox-web/grid/plugins/my-plugin'; \`\`\` ## Basic Usage ## Configuration Auto-generated from the plugin's config interface by \`genPluginConfigTable()\`. ## Events | Event | Detail | Description | | ----- | ------ | ----------- | ## API Public methods and properties. ``` > **Plugin JSDoc conventions for auto-generated API docs:** > - `## Configuration Options` tables are **auto-generated** from the constructor's config interface — do not hand-write them in JSDoc > - `## Programmatic API` tables are redundant with auto-generated Methods — do not hand-write them in JSDoc > - Use `{@link TypeName}` in hand-written sections (Column Configuration, CSS Custom Properties, Events) to cross-link types > - Run `bun nx typedoc grid` after changing JSDoc to regenerate MDX ### Plugin README (`README.md`) Keep concise — links to docs site for live examples: ```markdown # @toolbox-web/grid — Plugin Name Brief description. ## Usage \`\`\`typescript import { MyPlugin } from '@toolbox-web/grid/plugins/my-plugin'; \`\`\` ## Options | Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | ## Documentation See the [docs site](https://toolboxjs.com/grid/plugins/my-plugin/) for live examples. ``` ### LLM Files (`llms.txt` / `llms-full.txt`) These are AI-consumable documentation. `llms.txt` is a concise index (~120 lines); `llms-full.txt` is the full guide (~1600 lines). **`llms.txt`** — Update when: - New plugin added (add to plugin list) - New public export (add to API summary) - New event (add to events list) - New CSS variable (add to theming section) **`api-reference.mdx`** (`apps/docs/src/content/docs/grid/api-reference.mdx`) Events section — Update when: - Event cancelability changes (the cancelable events table is curated) - Framework-specific listening patterns change :::note Individual event descriptions, payload types, and code examples are auto-generated from JSDoc in `DataGridEventMap` — update the JSDoc, not the curated docs. Run `bun nx typedoc grid` to regenerate. ::: **`llms-full.txt`** — Update when: - Any user-facing change (contains full code examples for all frameworks) - New plugin config options - Changed event payloads - New CSS custom properties - New adapter features ### Core MDX Docs (`apps/docs/src/content/docs/grid/`) | File | Contents | | --------------------- | -------------------------------------------------- | | `index.mdx` | Landing page, key features | | `getting-started.mdx` | Installation, first grid setup | | `api-reference.mdx` | Public API reference (properties, methods, events) | | `theming.mdx` | CSS custom properties, theme files | | `core.mdx` | Core features guide (columns, rows, etc.) | | `custom-plugins.mdx` | How to write a plugin | | `performance.mdx` | Performance tips | | `accessibility.mdx` | A11y features | | `troubleshooting.mdx` | Common issues and fixes | | `demos.mdx` | Full-featured demo applications | | `comparison.mdx` | Feature comparison table | | `architecture.mdx` | Internal architecture documentation | ## Regenerating API Docs When public API changes (new exports, changed signatures, updated JSDoc): ```bash # Generate TypeDoc JSON and convert to MDX bun nx typedoc grid bun nx typedoc grid-angular bun nx typedoc grid-react bun nx typedoc grid-vue ``` Output goes to `libs/*/docs/api/` (MDX pages) and `libs/*/docs/api-generated/api.json`. **Do NOT hand-edit** files in `docs/api/` or `docs/api-generated/` — they are regenerated. ## Writing Good JSDoc JSDoc comments feed into TypeDoc API docs: ````typescript /** * Configuration for the grid component. * * @example * ```typescript * const config: GridConfig = { * columns: [{ field: 'name', header: 'Name' }], * }; * ``` * * @remarks * The config is merged with defaults via `mergeEffectiveConfig()`. * * @see {@link ColumnConfig} for column-level options */ export interface GridConfig { ... } ```` **Key tags:** - `@example` — Code examples (rendered in docs) - `@remarks` — Extended description - `@see` — Cross-references - `@deprecated` — Mark deprecated APIs with migration info - `@internal` — Exclude from public API docs - `@since` — Version when feature was added - `@category` — Routes exports to different TypeDoc sidebar sections (grid core only, see below) - `@group` — Organizes class members into subsection headings within a page (see below) - `@fires` — Documents events emitted by a method; collected into Events tables ## `@category` and `@group` — Controlling API Doc Output The `typedoc-to-mdx.ts` scripts convert TypeDoc JSON into MDX pages. Two JSDoc tags control **where** and **how** exports appear. > `@category` and `@group` are only processed by the **grid core** script (`libs/grid/scripts/typedoc-to-mdx.ts`). Adapter scripts use hard-coded name lists instead (see below). ### `@category` — API Doc Routing (Grid Core) Add `@category` to **top-level exports** in `types.ts`, `constants.ts`, or `grid.ts` to control which API docs section they land in. The routing logic lives in `processCoreModule()`: - `@category Plugin Development` → `Grid/API/Plugin Development/{Kind}/{Name}` - `@category Framework Adapters` → `Grid/API/Framework Adapters/{Kind}/{Name}` - Any other value or no `@category` → `Grid/API/Core/{Kind}/{Name}` Only `Plugin Development` and `Framework Adapters` cause routing changes. Other values (e.g., `Data Management`, `Events`) are informational — they still route to `Core`. Check `processCoreModule()` in `libs/grid/scripts/typedoc-to-mdx.ts` for the current routing logic. **DataGridElement split**: The `DataGridElement` class is special-cased by `genDataGridSplit()` — it produces **3 separate MDX documents** by filtering members: - **Public API** (`DataGridElement.mdx`) — members without `_` prefix, without `@internal`, without `@category Framework Adapters` - **Plugin API** (`DataGridElement-PluginAPI.mdx`) — `_`-prefixed members (not `__`) or `@internal Plugin API` - **Framework Adapters** (`DataGridElement-Adapters.mdx`) — members tagged `@category Framework Adapters` When adding a new member to `DataGridElement`, choose the right tag/prefix to place it in the correct document. ### `@group` — Section Headings Within a Page Add `@group GroupName` to **class members** (accessors, methods) to organize them under headings within a generated MDX page. Currently used on `DataGridElement` members. The `genMembersSectionByGroup()` function renders groups in a defined order — check the `groupOrder` array in that function for the current list. Members without `@group` fall into a generic section at the end. When adding a new member, use an existing `@group` value if it fits. If no group fits, create a new one — it will be appended after the ordered groups. If the new group should appear in a specific position, add it to the `groupOrder` array in `genMembersSectionByGroup()`. ### `@internal` Modifier — Visibility Control - `@internal` alone → excluded from all generated docs - `@internal Plugin API` → included only in the Plugin API document - `_` prefix (without `@internal`) → same as `@internal Plugin API` by convention - `__` prefix → excluded from all docs (deeply internal) ### Adapter Scripts — Hard-Coded Categorization Adapter scripts (`libs/grid-{angular,react,vue}/scripts/typedoc-to-mdx.ts`) do **NOT** use `@category`. They categorize by checking export names against hard-coded lists (e.g., `isDirective()` checks a `directiveNames` array in Angular). Each adapter sorts into folders like `Directives/`, `Components/`, `Hooks/`, `Types/`, `Utilities/`, etc. **When adding a new export to an adapter**: check the script's categorization functions. If your export doesn't match an existing check (e.g., a new Angular directive), add its name to the corresponding list so it lands in the right folder instead of the catch-all `Utilities/`. ## Verification After updating docs: ```bash # Verify docs site builds cleanly bun nx build docs # Check for broken links or missing pages bun nx serve docs # Navigate to updated pages in browser (http://localhost:4401) ``` ## Pre-Commit Documentation Review Before each commit, quickly scan: 1. Did I change any **public API**? → Update `API.mdx`, `llms.txt`, `llms-full.txt` 2. Did I change any **plugin**? → Update plugin `.mdx` and README 3. Did I add/remove **CSS variables**? → Update `Theming.mdx`, `llms-full.txt` 4. Did I change **events**? → Update `API.mdx`, plugin `.mdx`, `llms-full.txt` 5. Did I change **conventions**? → Update `copilot-instructions.md` ## LLM Files Cross-Check When updating `llms-full.txt`, verify these sections stay in sync with the codebase: 1. **Plugin list** — Cross-check the plugin table in "Correct Plugin Class Names" against the actual plugins in `libs/grid/src/lib/plugins/`. Any new plugin must be added with its class name and import path. 2. **Feature props table** — Verify every plugin with a feature prop entry in `libs/grid-*/src/lib/features/` is listed. 3. **Events table** — Check `DGEvents` enum in `libs/grid/src/lib/core/types.ts` for new/removed events. 4. **CSS variables** — Scan `libs/grid/src/lib/core/grid.css` for new `--tbw-*` variables. 5. **Framework recipes** — Ensure code examples compile against the current API (import paths, prop names, type names). Quick validation command: ```bash # List all plugin directories (compare against llms-full.txt plugin table) ls libs/grid/src/lib/plugins/ # List all feature prop modules (compare against feature props table) ls libs/grid-react/src/lib/features/ 2>/dev/null ls libs/grid-angular/src/lib/features/ 2>/dev/null ls libs/grid-vue/src/lib/features/ 2>/dev/null ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/oysteinamundsen) — claim your Tome and manage your conversions.