# Write Docs

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

- Skill: `liveblocks/write-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add liveblocks/write-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/liveblocks/write-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: liveblocks (https://skillmd.com/u/liveblocks)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/liveblocks/write-docs

---


# Liveblocks Docs

## Quick Start

Before writing, identify the target page and check its directory for a local
template. If a `*.template.mdx` file exists, read it completely and use it as
the primary structure for pages in that directory. Also check for the current
legacy `*-template.mdx` naming used by some folders.

```bash
rg --files docs/pages/<section> -g '*.template.mdx' -g '*-template.mdx'
```

After reading any local template, inspect nearby docs and follow their current
terminology, components, and level of detail.

When creating or restructuring a page under `docs/pages/use-cases/`, read and
follow
[`_use-case-template.mdx`](../../../docs/pages/use-cases/_use-case-template.mdx).
Use Canvas, Flowchart, and Slideshow as the current reference pages.

```bash
rg --files docs/pages
sed -n '1,180p' docs/pages/api-reference/liveblocks-react.mdx
sed -n '1,180p' docs/pages/products/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,
     plus Authentication under `docs/pages/api-reference/authentication`.
   - Product pages: product concepts, features, and workflows under
     `docs/pages/products`, with canonical URLs under `/docs/products`.
   - Use case pages: explanations of how several Liveblocks features combine for
     an application type, under `docs/pages/use-cases`.
   - 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:
   - Follow a folder-local `*.template.mdx` or `*-template.mdx` before copying a
     neighboring 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:
   - Run the docs link checker after making changes:
     `node scripts/check-docs-links.mts`
     It validates internal `/docs/*` links and `#anchors` in `docs/pages`,
     `guides/pages`, and `tutorial` — the same check CI runs on docs PRs.
   - Inspect changed MDX for 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.

See
[`_use-case-template.mdx`](../../../docs/pages/use-cases/_use-case-template.mdx)
for the required structure, snippet patterns, and checks for use case pages.