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.

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.

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.