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

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

1. 1Repeat 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?"

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

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