docs: document Markdown aside syntax for rule documentation #8419

nka21 · 2025-12-10T20:01:02Z

AI Assistance Disclosure: This PR was developed with assistance from Claude (Cursor AI). The implementation approach and content were collaboratively developed through discussion.

Summary

This PR adds documentation for Markdown aside syntax (also known as "admonitions" or "callouts") to help rule authors highlight important notes, warnings, or tips in their documentation.

While the :::note, :::caution, etc. syntax is already supported and used in several existing rules (e.g., useNodejsImportProtocol, noImportCycles), it was not documented in the CONTRIBUTING guide.

Changes:

Added "Callout blocks (Asides)" section to crates/biome_analyze/CONTRIBUTING.md with examples
Updated all rule templates in xtask/codegen/src/generate_new_analyzer_rule.rs to include aside syntax examples

Fixes #8402

Test Plan

✅ Verified no linter errors with just l
✅ Confirmed formatting with just f
✅ Checked that existing documentation builds correctly
✅ Reviewed existing rules that already use this syntax (useNodejsImportProtocol, noImportCycles, useSortedClasses) to ensure documentation matches actual usage

Docs

Documentation changes are included in this PR as part of the CONTRIBUTING guide updates. No website documentation PR is needed since this is internal contributor documentation.

changeset-bot · 2025-12-10T20:01:07Z

⚠️ No Changeset found

Latest commit: cd89931

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

coderabbitai · 2025-12-10T20:04:54Z

Walkthrough

This PR documents Starlight/aside (callout) blocks — :::note, :::tip, :::caution, :::danger — in the analyzer CONTRIBUTING.md and adds example callout blocks to the new-analyzer-rule codegen templates across all LanguageKind variants. Changes are documentation-only (markdown and inline doc comments) and do not modify runtime logic, public APIs, or exported declarations.

Possibly related PRs

feat(schema): add docs URLs to rule description #8098: Modifies codegen/documentation generation for analyzer rules; both PRs add structured documentation content to generated rule docs.

Suggested labels

A-Project

Suggested reviewers

ematipico

Pre-merge checks and finishing touches

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: documenting Markdown aside syntax for rule documentation.
Description check	✅ Passed	The description is well-related to the changeset, clearly explaining the purpose (documenting aside syntax), listing affected files, and detailing the testing performed.
Linked Issues check	✅ Passed	The PR fully addresses issue #8402 by adding documentation for Starlight aside blocks to CONTRIBUTING.md and updating rule templates with examples.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to documenting aside syntax in the CONTRIBUTING guide and rule templates; no extraneous modifications detected.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

ematipico

The documentation is too long and falls short with the Starlight documentation.

Instead:

let's provide a link to starlight docs when we mention the aside
the syntax isn't markdown, but a starlight thing, let's fix that
let's provide only one example

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

xtask/codegen/src/generate_new_analyzer_rule.rs (1)

97-101: Nice aside examples and placement in all templates

The new :::note snippets are consistent across languages and sit in a sensible spot between the description and ## Examples, which should make the “you can use asides” guidance very discoverable for contributors. If you ever want to go further, you could also briefly name the other supported variants (e.g. :::tip, :::caution, :::danger) in the CONTRIBUTING docs rather than repeating them in every template, but what you have here is already perfectly fine boilerplate. Based on learnings, this keeps rule docs aligned with the documented structure for rule comments.

Also applies to: 177-181, 260-264, 343-347, 423-427, 503-507

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e0bde62 and cd89931.

📒 Files selected for processing (2)

crates/biome_analyze/CONTRIBUTING.md (1 hunks)
xtask/codegen/src/generate_new_analyzer_rule.rs (6 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

crates/biome_analyze/CONTRIBUTING.md

🧰 Additional context used

📓 Path-based instructions (1)

**/*.rs

📄 CodeRabbit inference engine (CONTRIBUTING.md)

**/*.rs: Use the dbg!() macro for debugging output during testing, and pass the --show-output flag to cargo to view debug output
Use cargo t or cargo test to run tests; for a single test, pass the test name after the test command
Use snapshot testing with the insta crate; run cargo insta accept, cargo insta reject, or cargo insta review to manage snapshot changes
Write doctests as doc comments with code blocks; the code inside code blocks will be run during the testing phase
Use just f (alias for just format) to format Rust and TOML files before committing

Files:

xtask/codegen/src/generate_new_analyzer_rule.rs

🧠 Learnings (11)

📓 Common learnings

Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-27T23:04:02.022Z
Learning: Applies to crates/biome_analyze/**/*analyze/src/lint/**/*.rs : Document rules with a one-line brief description in the first paragraph of the doc comment, followed by detailed paragraphs, `## Examples` section with `### Invalid` and `### Valid` subsections, and optional `## Options` section

Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-28T09:08:10.091Z
Learning: Applies to .changeset/**/*.md : For new lint rules, show an example of an invalid case in an inline code snippet or code block; for rule changes, demonstrate what is now invalid or valid; for formatter changes, use a `diff` code block

Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-27T23:04:02.022Z
Learning: Applies to crates/biome_analyze/**/*analyze/src/lint/**/*.rs : In rule documentation code blocks, mark invalid examples with the `expect_diagnostic` property and valid examples without it; each invalid example must emit exactly one diagnostic

Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-27T23:04:02.022Z
Learning: Applies to crates/biome_analyze/**/*analyze/src/lint/**/*.rs : Use language tags in documentation code blocks (js, ts, tsx, json, css) and order properties consistently as: language, then `expect_diagnostic`, then options modifiers, then `ignore`, then `file=path`

Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_analyze/CONTRIBUTING.md:0-0
Timestamp: 2025-11-27T23:04:02.022Z
Learning: Commit rule changes with message format: `feat(biome_<crate>): <ruleName>` to follow Biome's conventional commit style

Learnt from: CR
Repo: biomejs/biome PR: 0
File: crates/biome_parser/CONTRIBUTING.md:0-0
Timestamp: 2025-11-24T18:06:03.545Z
Learning: Applies to crates/biome_parser/**/*.ungram : Add a legend comment to `.ungram` files explaining the grammar syntax including comments, non-terminals, tokens, sequences, alternations, repetitions, and optional elements

📚 Learning: 2025-11-28T09:08:10.091Z

Learnt from: CR
Repo: biomejs/biome PR: 0
File: CONTRIBUTING.md:0-0
Timestamp: 2025-11-28T09:08:10.091Z
Learning: Applies to .changeset/**/*.md : For new lint rules, show an example of an invalid case in an inline code snippet or code block; for rule changes, demonstrate what is now invalid or valid; for formatter changes, use a `diff` code block

Applied to files:

xtask/codegen/src/generate_new_analyzer_rule.rs