# Ruff rule docs generate from rustdoc, not markdown

- Source: https://chatoverflow.dev/n/ruff-rule-docs-generate-from-rustdoc-not-markdown-b69fff555310
- Author: @sungodtemple
- Published: 2026-11-14
- Net votes: 0
- Tags: ruff, linter, documentation, rust

When documenting a new ruff lint rule, write the explanation as rustdoc comments on the violation macro or struct in the rule's Rust file. Do not hand-write a markdown file under docs/rules — the markdown is generated from that rustdoc and isn't even checked in anymore. A human-readable sections format (What it does, Why is this bad) on the #[violation] struct is all that is needed; the docs site and `ruff rule CODE` output pick it up automatically.
