Documentation Style Guide

Use this guide for anything under docs/. It defines the repo standard for Docusaurus-formatted documentation and should be applied to new docs plus any touched legacy sections.

Core Rules

• Write for contributors and plugin users, not for marketing.
• Ground claims in live source, SOT facts, tests, or explicitly named live verification gaps.
• Prefer literal headings such as Configuration, Validation, and Workflow over decorative titles.
• Use fenced code blocks with a language tag when the snippet is executable or language-specific.
• Use tables for config maps, comparisons, and compact reference material; use plain lists for workflow steps and constraints.

Admonition Standard

Use Docusaurus admonitions for anything the reader could miss and later misuse. Do not use GitHub callout blockquotes such as > [!NOTE] or > [!WARNING].

Approved Types

Use case	Standard form
Neutral context or clarification	:::note
Recommended practice or shortcut	:::tip
Reference detail or API nuance	:::info
Risk, caveat, or easy footgun	:::warning[Caution]
High-risk, destructive, or account-risk action	:::danger

When the heading should read "Caution", keep the warning semantics and set the title explicitly:

:::warning[Caution]

Do not call `ActionPacer.isReady(...)` directly from plugin tick loops.

:::

Required Formatting

Leave a blank line after the opening directive and before the closing directive:

:::tip

This formatting survives Docusaurus and Prettier consistently.

:::

When To Use Inline Text Instead

Use a normal sentence instead of an admonition when all of these are true:

• the point is low-risk,
• the reader does not need to scan for it later,
• and skipping it would not produce incorrect behavior.

If the detail changes how code should be written, validated, or operated, use an admonition.

Pattern For Correctness Guides

For "do this, not that" guidance, standardize on:

• :::warning[Caution] for the incorrect pattern
• :::tip for the correct pattern

Keep labels literal and short, for example Improper and Proper.

Source-Grounded Claims

• State live verification as pending when the behavior is revision-sensitive and not observed in-client.
• Name exact APIs, classes, tasks, or files instead of vague references.
• Avoid filler lead-ins like "simply", "obviously", or "just".

Migration Rule

When you touch a section that still uses GitHub-style callouts or italicized Note: labels for important behavior, convert that touched section to this standard rather than preserving mixed formats.