docs-update

name: docs-update description: Author, restructure, or update documentation for the Astro/Starlight docs site. Covers ADDING a new docs page or route (MDX + sidebar registration in astro.config.mjs + llms.txt/llms-full.txt inclusion), which prose/MDX and API-reference docs to check after a code change, how to write them, the <Audience> and llmsFull curation knobs, and regenerating typedoc API docs. Use whenever you create, move, rename, or edit any file under apps/docs/, or after any feature, fix, or refactor that touches user-visible behaviour. (For building a new interactive demo component, use the astro-demo skill instead.) argument-hint: optional what-changed description

Documentation Update Guide

Use this skill whenever you touch docs — authoring a brand-new page/route, restructuring or moving pages, or syncing existing docs after a code change. It is the authoritative reference for the docs site's structure, navigation, and the autogenerated LLM corpus — read it before writing, not only as a post-change checklist.

• Adding or moving a page? Start at Adding a new docs page — it covers the steps that are easy to miss (sidebar registration, llmsFull inclusion, redirects).
• Changed code and need to sync docs? Use the Quick Decision Matrix below.

llms.txt / llms-full.txt are autogenerated — never hand-edit them. Both are built at docs-build time by the Astro endpoints apps/docs/src/pages/llms.txt.ts and llms-full.txt.ts from the curated MDX/MD doc pages, the demo .astro sources, and JSDoc-derived TypeDoc MDX. You influence their content only by editing those sources — which makes keeping the MDX/curated/source docs accurate more important than before, not less. See Where LLM-file content comes from for the few curation knobs (page frontmatter, ordering, agent preamble). This skill does not manually update the root llms.txt / llms-full.txt.

Adding a New Docs Page

Adding a page is more than dropping an .mdx file — the page is invisible until you register it in the sidebar, and it silently joins the LLM corpus unless you opt it out. Work through all five steps:

1. Create the MDX page under apps/docs/src/content/docs/grid/ (or a subfolder like grid/plugins/, grid/guides/). Every page needs frontmatter title and description (the description is reused as the page's link blurb in llms.txt). Follow the conventions in How to Write Each Doc Type.

2. Register it in the sidebar — this is the step most easily forgotten. The navigation tree is hand-curated in apps/docs/astro.config.mjs under starlight({ sidebar: [...] }). A new page does not appear automatically unless it lands in a folder covered by an autogenerate: { directory: ... } entry (currently only grid/guides, grid/plugins, and the TypeDoc grid/api/** trees). For a top-level or curated page, add an explicit entry to the matching group:

   // apps/docs/astro.config.mjs → integrations → starlight → sidebar → 'Grid' group
   { label: 'Introduction', slug: 'grid/introduction' },
   { label: 'AI Assistance', slug: 'grid/ai' },   // ← your new page (slug = path under content/docs/, no extension)
   

   To create a brand-new collapsible section, push a { label, collapsed, items: [...] } object instead. Match the placement to the page's audience (top-level conceptual pages go in the Grid group near Introduction/Getting Started).

3. Decide LLM-corpus inclusion — by default every prose page is inlined into llms-full.txt and linked in llms.txt. Opt a page out of the full corpus (kept in the index, removed from the inlined dump) with frontmatter llmsFull: false. Use this for pages that teach an agent nothing about building with the grid — e.g. release history. Current opt-outs: grid/changelog.mdx and the three adapter changelog.mdx pages. For a page where only part of the content is human- or agent-only, prefer per-block <Audience> regions instead (see Audience-targeted content).

4. Place it in the generated ordering (only if it's a new top-level slug or a new section). apps/docs/src/pages/_llm-sources.ts controls how the generated files group and order pages: sectionOf() classifies a slug into a section, and CORE_ORDER sets the reading order for top-level grid/* pages. A new grid/<name>.mdx page that isn't listed in CORE_ORDER sorts to the alphabetical tail of "Core Documentation" — add it to CORE_ORDER if it needs a specific position.

5. If you moved or renamed a page, add a redirect in astro.config.mjs (redirects: { '/grid/old-path/': '/grid/new-path/' }) so inbound links and bookmarks keep working, and update any internal links per the Internal-link rules.

Then build and run the link check (see Verification).

Quick Decision Matrix

The matrix is grouped by change category. If your change spans multiple categories, apply each matching row — there is no precedence ordering between groups (you update all matching surfaces). The LLM files are intentionally absent: updating the MDX/source docs below regenerates them automatically.

Code / API changes

Plugin changes

Adapter changes

Theming / styling changes

Workspace / tooling changes

Documentation Inventory

Hand-Written (update manually)

Auto-Generated (regenerate, don't hand-edit)

The LLM files are derived from the MDX/MD doc pages, the demo .astro sources, and the JSDoc-generated TypeDoc MDX — so they stay in sync automatically when you update those sources. Never hand-edit the root llms.txt / llms-full.txt.

How to Write Each Doc Type

Multi-Path Features

When a feature has multiple configuration paths (e.g., CSS vs JS, declarative vs programmatic), apply this checklist to every documentation file that has a dedicated section explaining that feature, a configuration table for it, or a code example using it (not merely a passing hyperlink or index entry) (i.e. the feature's plugin/core MDX page, its README, and any adapter MDX page that documents it in detail). You do not need to touch unrelated documentation files. (The LLM files pick up the change automatically once the MDX is updated.)

For each such file, complete all four steps in order:

1. State that both paths exist — even if the file 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 <tbw-grid-column> 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:

---
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

<ShowSource component="plugin-name/PluginNameDefaultDemo">
  <PluginDefaultDemo />
</ShowSource>

## 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:

# @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.

Where LLM-file content comes from

llms.txt (concise index) and llms-full.txt (full guide) are autogenerated at docs-build time by apps/docs/src/pages/llms.txt.ts and llms-full.txt.ts. Do not hand-edit the root files — they are derived from:

So updating the MDX/curated/source docs is how you update the LLM files — keep them accurate and the generated files follow automatically. The only manual curation knobs (touch these only when adding/removing pages or changing ingestion behaviour, not for routine content):

• <Audience only="human|agent"> regions inside a page — split a single page's content by consumer (see Audience-targeted content below). This is the content-level knob; the three below are page-level / global.
• Page frontmatter llmsFull: false — omits a page from the llms-full.txt corpus while keeping it linked in llms.txt (used for pages that teach an agent nothing about building with the grid — currently the changelog.mdx pages). See _llm-markdown.ts.
• Ordering & section maps in apps/docs/src/pages/_llm-sources.ts — CORE_ORDER, SECTION_ORDER, API_AREA_ORDER, sectionOf(), apiAreaOf(). Adjust when a new doc section/area needs explicit placement.
• Agent preamble in apps/docs/src/pages/_llm-agent-preamble.ts — the hand-authored RULE 0 / critical-rules / anti-patterns block prepended to both files. Keep it in sync with the human docs it summarises (Getting Started, Plugins Overview) when those rules change.

To verify the generated output after a docs change, run bun nx build docs and inspect the emitted /llms.txt and /llms-full.txt.

Audience-targeted content

<Audience> (apps/docs/src/components/Audience.astro) lets one MDX page carry content meant for only one consumer. Import it in the page's frontmatter (import Audience from '@components/Audience.astro';) and wrap a block:

<Audience only="agent">

_## Steering heading (note the `_` prefix — see authoring rules)

Steering directive / extra gotcha / copy-paste recipe that helps a code-generating agent.

</Audience>

<Audience only="human">

## Steering heading (plain `##` — renders on the site)

Motivational aside, marketing prose, or screenshot-driven walkthrough that would only dilute agent guidance.

</Audience>

The two paths are independent: the HTML behaviour is in Audience.astro, the corpus behaviour is in resolveAudienceRegions() (apps/docs/src/pages/_llm-markdown.ts).

When to reach for it — use <Audience> for a portion of an otherwise-shared page. For a whole page that should stay out of the agent corpus, use frontmatter llmsFull: false instead.

Authoring rules (enforced by the regex transform):

• Leave a blank line after the opening tag and before the closing tag so MDX parses the children as Markdown blocks.
• Headings inside only="agent" blocks must be prefixed with _ — write _## Heading, not ## Heading. Starlight harvests real ## headings into the human page's table-of-contents at compile time (before the runtime conditional render), so a bare ## in an agent-only block leaks a phantom TOC link on the human page. The _ sentinel makes it a non-heading for the human build; the agent-markdown transform (out.replace(/^_(#{1,6} )/, …) in _llm-markdown.ts) strips the _ to restore a real, navigable heading in the corpus. The strip runs in prose only, so _# inside a code fence is left intact. (Human-only blocks render normally, so they use plain ##.)
• Do not nest <Audience> blocks — the non-greedy match stops at the first </Audience>.
• Keep agent-only directives consistent with the human docs they shadow; don't let the two audiences drift into contradicting each other.
• After adding/editing an <Audience> block, run bun nx build docs and confirm the agent content lands in /llms-full.txt (and the human content does not, and vice-versa).

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. :::

Core MDX Docs (apps/docs/src/content/docs/grid/)

Regenerating API Docs

When public API changes (new exports, changed signatures, updated JSDoc):

# 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:

/**
 * 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/. After updating the categorization list, run bun nx typedoc grid-<adapter> (e.g., bun nx typedoc grid-angular) to regenerate the adapter API MDX pages.

Verification

After updating docs:

# Verify docs site builds cleanly
bun nx build docs

# Authoritative broken-link gate (NOT an nx target — Astro does NOT fail on broken links)
node .github/skills/docs-update/check-doc-links.mjs

bun nx build docs passing (EXIT=0) does not mean links are valid — Astro silently renders dead links. node .github/skills/docs-update/check-doc-links.mjs is the real gate; it must report "No broken internal links found." If the script reports broken links, fix every broken link in files you modified as part of this change before committing. For a broken link in a file you did not modify, treat it as pre-existing — do not fix it in this change; note the file and line in your PR description so it can be tracked separately.

Internal-link rules (avoid the common 404s)

• trailingSlash: 'always' — every internal link MUST end with / (/grid/plugins/shell/, not /grid/plugins/shell).
• Anchors must match a real heading slug — grep the target page's ^#{1,4} headings before linking to #some-anchor; renamed/removed headings are a frequent source of dead anchors.
• TypeDoc generates NO page for area roots or export const objects. tools/typedoc-mdx-shared.ts KIND_FOLDER_MAP only emits Classes/, Interfaces/, Functions/, Types/ — there is no per-area index page and no Variables/ folder.
  • ❌ /grid/api/framework-adapters/ (area root) · ❌ /grid/api/plugin-development/ · ❌ /grid/api/core/variables/gridclasses/
  • ✅ link to a concrete generated child page (/grid/api/<area>/<kind>/<symbol>/, slug lowercased), e.g. /grid/api/framework-adapters/interfaces/frameworkadapter/ or /grid/api/plugin-development/classes/basegridplugin/.
  • Exported const objects (GridClasses, GridDataAttrs, GridSelectors, GridCSSVars in core/constants.ts) are public API but have NO generated page — keep them as inline code, don't link. Only their TYPE aliases (GridClassName, GridDataAttr) get Types/ pages.

Pre-Commit Documentation Review

Before each commit, quickly scan:

1. Did I change any public API? → Update api-reference.mdx + JSDoc; regenerate TypeDoc
2. Did I change any plugin? → Update plugin .mdx and README
3. Did I add/remove CSS variables? → Update theming.mdx, grid.css registry comment
4. Did I change events? → Update api-reference.mdx, plugin .mdx, JSDoc on DataGridEventMap
5. Did I change conventions? → Update copilot-instructions.md

The llms.txt / llms-full.txt files are regenerated from the above sources at docs-build time — there is nothing to hand-edit for them.