Documentation Style Guide

Verification boundary

This page describes the committed source guideline. It skips certifying revision-sensitive RuneLite UI, packet, or in-game outcomes; treat those as live-client verification pending unless the page records direct evidence.

Use this guide for anything under docs/. It defines the repo standard for Docusaurus-formatted documentation. Apply it to new docs and touched legacy sections.

Validation And Automatic Fixes

After changing docs/**, run:

python scripts/fix-docs-frontmatter.py <changed-paths>
.\gradlew.bat auditDocs --console plain

The fixer adds missing frontmatter, ensures one top-level page heading, demotes extra level-one headings, and reports malformed files that need manual work. Use --check in read-only validation. Fix auditDocs errors before finalizing; warnings remain advisory.

The documentation audit runs in a dedicated, non-blocking pull-request workflow. Docusaurus build and deployment stay separate from the normal Gradle build, so documentation checks do not turn Java compilation into a site build.

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.
• Use literal headings such as Configuration, Validation, and Workflow instead of decorative titles.
• Use fenced code blocks with a language tag when the snippet runs as code or uses a specific language.
• Use plain lists for workflow steps and constraints.

Admonition Standard

Use Docusaurus admonitions for anything the reader could miss and later misuse. Avoid 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 footgun	:::warning[Caution]
High-risk, destructive, or account-risk action	:::danger

When the heading requires "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 apply:

• the point carries low risk,
• the reader skips scanning for it later,
• and missing it creates no incorrect behavior.

If the detail changes how contributors write, validate, or operate code, 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, such as Improper and Proper.

Source-Grounded Claims

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

For an API page, inspect the owning class and its tests. For a plugin guide, inspect the plugin, config, and panel/controller that expose the workflow. Keep three kinds of evidence separate:

Evidence	What it establishes	What it omits
In-client observation	Current RuneLite/game UI and packet behavior	A replacement for source-level tests

Run the complete documentation checks in Validation after claiming verification.

Migration Rule

When you touch a section that uses GitHub-style callouts or italicized Note: labels, convert that section to this standard. Avoid preserving mixed formats.