diff --git a/.agents/skills/.gitkeep b/.agents/skills/.gitkeep deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/.agents/skills/write-docs/REFERENCE.md b/.agents/skills/write-docs/REFERENCE.md new file mode 100644 index 00000000000..db931ec5e75 --- /dev/null +++ b/.agents/skills/write-docs/REFERENCE.md @@ -0,0 +1,176 @@ +# Liveblocks Docs Reference + +## Documentation Structure + +Docs pages live under `docs/pages`, with navigation in `docs/routes.json`. New +docs `.mdx` files are not routable until they are registered. Most pages use +frontmatter like: + +```mdx +--- +meta: + title: "Hooks" + parentTitle: "AI Copilots" + description: "React hooks for building custom AI interfaces" +--- +``` + +API reference pages are usually long package pages under +`docs/pages/api-reference`. Feature docs live under +`docs/pages/collaboration-features`, but many URLs are still written as +`/docs/ready-made-features/...`; follow nearby links when editing. + +Guides live outside the docs tree under `guides/pages`, and new guides must be +registered in `guides/guides.json`. Use guides for focused, task-specific +instructions or features that need one single page connecting multiple APIs. + +Interactive tutorials live under `tutorial`, with tutorial metadata in +`tutorial/tutorials.json`. Use these only for step-by-step learning experiences +with editable project files. + +## Where To Document Features + +Large features, such as major components or product areas: + +- Add API reference coverage first. +- Add or update a prominent feature page. +- Update relevant feature overview pages so users can understand what the + feature enables before reading API details. +- Add or update focused feature pages for the main workflows, especially when + the feature has setup, configuration, permissions, or product concepts. +- Link from every related API reference and feature page to one canonical page + that explains how the pieces fit together. +- Include setup requirements, limits, errors, permissions, and dashboard steps + when they affect whether the feature works. + +Medium and small features: + +- Add API reference coverage first. +- Add a section to relevant feature docs. +- Mention the feature wherever the same user would naturally search: related + hooks, React UI components, Node APIs, webhooks, dashboard pages, and general + usage snippets. + +Tiny features: + +- Usually add one API reference mention. +- Prefer a dedicated subsection unless the feature is truly one line. + +Features using many parts of Liveblocks: + +- Create one single guide or overview that connects the pieces. +- Link from each fragmented API reference section back to that single place. +- Include setup order, permissions, dashboard steps, backend calls, frontend + calls, and webhook behavior as needed. + +Dashboard-related features: + +- Product-important features should be mentioned on a feature overview with + links to details. +- Simple dashboard workflows can live in `docs/pages/platform`. +- If the feature is too specific for an overview, write a focused guide. + +## API Reference Pattern + +Use this order unless nearby docs do something more specific: + +1. Heading with API name and optional anchor. +2. One or two sentence description. +3. Minimal code snippet. +4. Practical snippets for common use cases. +5. Props, arguments, options, and returns in `PropertiesList`. +6. Error handling, pagination, limits, permissions, or caveats. +7. Links to related APIs or feature pages. + +API section skeleton: + +````mdx +### useStatus + +Returns the current status. + +```tsx +import { useStatus } from "@liveblocks/react/suspense"; + +function Component() { + const { status } = useStatus(); + + return
{status}
; +} +``` + +#### Error handling + +Use `error` to display a message if the initial fetch fails. + + + + The current status. + + +```` + +## MDX Conventions + +- Use `+++` markers inside code fences to highlight important lines. + - Prefer `+++` markers over the `highlight="5-10"` syntax + - When editing a code fence that already uses the `highlight="5-10"` syntax, + convert it to use `+++` markers instead. +- Use code fence metadata already present nearby, such as `file`, `title`, + `showLineNumbers={false}`, `isCollapsed`, and `isCollapsable`. +- Use `Banner` for warnings, constraints, important notes, or conceptual + callouts. +- Use `Figure` and `Image` for visual dashboard or component documentation. +- Use `Steps`, `Step`, and `StepCompact` for ordered setup flows or process + explanations. +- Use link reference definitions at the bottom of a section or page when a term + is repeated. +- Keep links local and explicit: + [`useThreads`](/docs/api-reference/liveblocks-react#useThreads). +- Use heading syntax from `docs/README.md` when needed: `[#custom-id]`, + `[@hidden]`, and `[@keywords=[...]]`. +- Store docs images in `/assets` and reference them with root-relative paths + such as `/assets/projects/create-project.jpg`. +- Do not invent component APIs. Search existing docs and source first. + +## Voice And Structure + +Liveblocks docs are plain, factual, and product-aware. + +- Lead with what the API does and why a developer would use it. +- Avoid internal implementation details unless they affect user behavior. +- Avoid marketing claims such as "powerful", "seamless", or "revolutionary". +- Use "we recommend" when choosing a default for users. +- Use short paragraphs, often one to three sentences. +- Progress from basic usage to realistic usage to edge cases. +- Prefer "Use X to..." over abstract descriptions. +- Make code snippets copyable and remove unrelated setup. + +## Repeat Yourself + +Users often land directly on an API reference section. When releasing a feature, +repeat the important information in multiple places: + +- Overview page: what the feature enables. +- React API reference: hook shape, common usage, loading and errors. +- React UI API reference: rendering with default components. +- Node API reference: server-side creation, mutation, or triggering. +- Feature pages: end-to-end workflow and links to API details. +- Platform pages: dashboard or project settings, if involved. + +Each repetition should be short and contextual, not copied wholesale. + +## Checks Before Finishing + +- New public APIs have arguments, options, returns, and snippets. +- New docs pages are added to `docs/routes.json`. +- New guides are added under `guides/pages` and registered in + `guides/guides.json`. +- New interactive tutorials are added under `tutorial` and registered in + `tutorial/tutorials.json`. +- Feature docs link to API reference and API reference links back to feature + docs. +- The docs answer likely user questions: setup, common use, errors, limits, + permissions, and next steps. +- Snippets use current package imports and match local conventions. +- The feature has one canonical link that explains how the pieces fit together. diff --git a/.agents/skills/write-docs/SKILL.md b/.agents/skills/write-docs/SKILL.md new file mode 100644 index 00000000000..024c71517b0 --- /dev/null +++ b/.agents/skills/write-docs/SKILL.md @@ -0,0 +1,89 @@ +--- +name: write-docs +description: + Write and review Liveblocks documentation, API reference, guides, and + quickstarts. Use when editing files under docs/, documenting a new Liveblocks + feature, updating API reference pages, adding docs routes, or reviewing + documentation for clarity, discoverability, and consistency. +--- + +# Liveblocks Docs + +## Quick Start + +Before writing, inspect nearby docs and copy their structure. + +```bash +rg --files docs/pages +sed -n '1,180p' docs/pages/api-reference/liveblocks-react.mdx +sed -n '1,180p' docs/pages/collaboration-features/comments/users-and-mentions.mdx +``` + +Then write the smallest docs update that makes the feature findable from the +places users are likely to look. + +## Workflow + +1. Identify the docs surface: + - API reference: every new public API, prop, option, return value, or type. + - Ready-made feature pages: user-facing workflows and common combinations. + - Guides: task-specific docs under `guides/pages`, registered in + `guides/guides.json`. + - Platform pages: dashboard, account, project, webhook, REST, limits, or + infrastructure behavior. + - Get started pages: only when the setup flow changes or a feature should be + part of onboarding. + - Interactive tutorials: step-by-step learning content under `tutorial`, + registered in `tutorial/tutorials.json`. + +2. Decide the release size: + - Large features need API docs, a prominent feature page, and updates across + every relevant docs surface. + - Medium and small features need API docs plus every relevant usage page. + - Tiny features can usually live in one API reference section. + - Features spanning client, server, dashboard, webhooks, or packages need one + single overview or guide that ties the pieces together. + +3. Repeat intentionally: + - Do not assume users read the overview first. + - Mention the feature in each relevant API reference and feature page. + - Link each mention to the canonical page or section. + - Check: "Can I link to one place that explains this feature?" + +4. Match the existing page: + - Keep existing frontmatter shape. + - Use the same heading depth and anchor style, such as + `### Name [#custom-anchor]`. + - Use existing MDX components such as `PropertiesList`, `Banner`, `Figure`, + `Steps`, `StepCompact`, and `ListGrid`. + - Register new docs pages in `docs/routes.json`, guides in + `guides/guides.json`, and interactive tutorials in + `tutorial/tutorials.json`. + +5. Verify: + - Inspect changed MDX for broken links, malformed JSX, heading hierarchy, and + route or guide registration. + +## Style Rules + +- Write simply, neutrally, and directly. Avoid marketing language. +- Start each section with the simplest useful snippet, then add optional + behavior in later subsections. +- Pick strong defaults instead of presenting equivalent options for the user to + choose between. +- Optimize for skimming with clear headings, short paragraphs, and code + comments. +- Link API names, components, hooks, and related concepts whenever mentioned. +- Include limits, pagination, loading states, error states, and permissions + where relevant. +- Prefer Suspense imports in React snippets unless the surrounding page uses + regular hooks. +- Keep snippets realistic but compact, with placeholders like `// ...` for + unrelated app code. +- Use public package names in docs prose, avoid presenting `@liveblocks/core` as + user-facing. + +## More Detail + +See [REFERENCE.md](REFERENCE.md) for placement rules, API reference structure, +MDX conventions, and review checklists. diff --git a/scripts/for-all-e2e.sh b/scripts/for-all-e2e.sh index 0c53a154b2d..38289b3ba1e 100755 --- a/scripts/for-all-e2e.sh +++ b/scripts/for-all-e2e.sh @@ -1,5 +1,6 @@ #!/bin/sh set -eu +CDPATH='' # Don't let inherited CDPATHs hijack our relative cd's # Ensure this script can assume it's run from the repo's # root directory, even if the current working directory is diff --git a/scripts/for-all-examples.sh b/scripts/for-all-examples.sh index cd287f071a9..e99bbc76a7b 100755 --- a/scripts/for-all-examples.sh +++ b/scripts/for-all-examples.sh @@ -1,5 +1,6 @@ #!/bin/sh set -eu +CDPATH='' # Don't let inherited CDPATHs hijack our relative cd's # Ensure this script can assume it's run from the repo's # root directory, even if the current working directory is diff --git a/scripts/for-all-packages.sh b/scripts/for-all-packages.sh index f2dbe3e7149..47100d3063a 100755 --- a/scripts/for-all-packages.sh +++ b/scripts/for-all-packages.sh @@ -1,5 +1,6 @@ #!/bin/sh set -eu +CDPATH='' # Don't let inherited CDPATHs hijack our relative cd's # Ensure this script can assume it's run from the repo's # root directory, even if the current working directory is