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.

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. 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 for placement rules, API reference structure, MDX conventions, and review checklists.

See _use-case-template.mdx for the required structure, snippet patterns, and checks for use case pages.