diff --git a/README.md b/README.md
index 8189a35e70..ed53076758 100644
--- a/README.md
+++ b/README.md
@@ -3415,7 +3415,7 @@ alias (e.g., `import A as B`) to wrap such that every line contains
 exactly one member. For example, this formatting would be retained,
 rather than condensing to a single line:
 
-```py
+```python
 from .utils import (
     test_directory as test_directory,
     test_id as test_id
diff --git a/crates/ruff/src/rules/eradicate/rules.rs b/crates/ruff/src/rules/eradicate/rules.rs
index dedba5d166..6c87bb1b44 100644
--- a/crates/ruff/src/rules/eradicate/rules.rs
+++ b/crates/ruff/src/rules/eradicate/rules.rs
@@ -10,14 +10,14 @@ use crate::source_code::Locator;
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for commented-out Python code.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Commented-out code is dead code, and is often included inadvertently.
     /// It should be removed.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// # print('foo')
     /// ```
diff --git a/crates/ruff/src/rules/flake8_annotations/rules.rs b/crates/ruff/src/rules/flake8_annotations/rules.rs
index db848fc7b8..0880727ae1 100644
--- a/crates/ruff/src/rules/flake8_annotations/rules.rs
+++ b/crates/ruff/src/rules/flake8_annotations/rules.rs
@@ -16,15 +16,15 @@ use crate::visibility;
 use crate::visibility::Visibility;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that function arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(x):
     ///     ...
@@ -48,15 +48,15 @@ impl Violation for MissingTypeFunctionArgument {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that function `*args` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(*args):
     ///     ...
@@ -80,15 +80,15 @@ impl Violation for MissingTypeArgs {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that function `**kwargs` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(**kwargs):
     ///     ...
@@ -112,10 +112,10 @@ impl Violation for MissingTypeKwargs {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that instance method `self` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
@@ -123,7 +123,7 @@ define_violation!(
     /// Note that many type checkers will infer the type of `self` automatically, so this
     /// annotation is not strictly necessary.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     def bar(self):
@@ -149,10 +149,10 @@ impl Violation for MissingTypeSelf {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that class method `cls` arguments have type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the types of function arguments. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any provided arguments match expectation.
@@ -160,7 +160,7 @@ define_violation!(
     /// Note that many type checkers will infer the type of `cls` automatically, so this
     /// annotation is not strictly necessary.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     @classmethod
@@ -188,15 +188,15 @@ impl Violation for MissingTypeCls {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that public functions and methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def add(a, b):
     ///     return a + b
@@ -220,15 +220,15 @@ impl Violation for MissingReturnTypePublicFunction {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that private functions and methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def _add(a, b):
     ///     return a + b
@@ -252,11 +252,11 @@ impl Violation for MissingReturnTypePrivateFunction {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that "special" methods, like `__init__`, `__new__`, and `__call__`, have
     /// return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
@@ -271,7 +271,7 @@ define_violation!(
     /// mypy-init-return = true
     /// ```
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     def __init__(self, x: int):
@@ -301,15 +301,15 @@ impl AlwaysAutofixableViolation for MissingReturnTypeSpecialMethod {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that static methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     @staticmethod
@@ -337,15 +337,15 @@ impl Violation for MissingReturnTypeStaticMethod {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that class methods have return type annotations.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Type annotations are a good way to document the return types of functions. They also
     /// help catch bugs, when used alongside a type checker, by ensuring that the types of
     /// any returned values, and the types expected by callers, match expectation.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class Foo:
     ///     @classmethod
@@ -373,11 +373,11 @@ impl Violation for MissingReturnTypeClassMethod {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that an expression is annotated with a more specific type than
     /// `Any`.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// `Any` is a special type indicating an unconstrained type. When an
     /// expression is annotated with type `Any`, type checkers will allow all
     /// operations on it.
@@ -385,7 +385,7 @@ define_violation!(
     /// It's better to be explicit about the type of an expression, and to use
     /// `Any` as an "escape hatch" only when it is really needed.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(x: Any):
     ///     ...
@@ -397,7 +397,7 @@ define_violation!(
     ///     ...
     /// ```
     ///
-    /// ### References
+    /// ## References
     /// * [PEP 484](https://www.python.org/dev/peps/pep-0484/#the-any-type)
     /// * [`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any)
     /// * [Mypy: The Any type](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#the-any-type)
diff --git a/crates/ruff/src/rules/flake8_bandit/rules/hardcoded_sql_expression.rs b/crates/ruff/src/rules/flake8_bandit/rules/hardcoded_sql_expression.rs
index f86287b258..0afd2eb872 100644
--- a/crates/ruff/src/rules/flake8_bandit/rules/hardcoded_sql_expression.rs
+++ b/crates/ruff/src/rules/flake8_bandit/rules/hardcoded_sql_expression.rs
@@ -16,23 +16,23 @@ static SQL_REGEX: Lazy<Regex> = Lazy::new(|| {
 });
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for strings that resemble SQL statements involved in some form
     /// string building operation.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// SQL injection is a common attack vector for web applications. Directly
     /// interpolating user input into SQL statements should always be avoided.
     /// Instead, favor parameterized queries, in which the SQL statement is
     /// provided separately from its parameters, as supported by `psycopg3`
     /// and other database drivers and ORMs.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// query = "DELETE FROM foo WHERE id = '%s'" % identifier
     /// ```
     ///
-    /// ### References
+    /// ## References
     /// * [B608: Test for SQL injection](https://bandit.readthedocs.io/en/latest/plugins/b608_hardcoded_sql_expressions.html)
     /// * [psycopg3: Server-side binding](https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html#server-side-binding)
     pub struct HardcodedSQLExpression {
diff --git a/crates/ruff/src/rules/flake8_bugbear/rules/assert_raises_exception.rs b/crates/ruff/src/rules/flake8_bugbear/rules/assert_raises_exception.rs
index ef0f109e56..ebb3703638 100644
--- a/crates/ruff/src/rules/flake8_bugbear/rules/assert_raises_exception.rs
+++ b/crates/ruff/src/rules/flake8_bugbear/rules/assert_raises_exception.rs
@@ -7,17 +7,17 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for `self.assertRaises(Exception)`.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// `assertRaises(Exception)` can lead to your test passing even if the
     /// code being tested is never executed due to a typo.
     ///
     /// Either assert for a more specific exception (builtin or custom), use
     /// `assertRaisesRegex` or the context manager form of `assertRaises`.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// self.assertRaises(Exception, foo)
     /// ```
diff --git a/crates/ruff/src/rules/flake8_import_conventions/rules.rs b/crates/ruff/src/rules/flake8_import_conventions/rules.rs
index 8e3eb6f310..b4c9cc0cc5 100644
--- a/crates/ruff/src/rules/flake8_import_conventions/rules.rs
+++ b/crates/ruff/src/rules/flake8_import_conventions/rules.rs
@@ -7,11 +7,11 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for imports that are typically imported using a common convention,
     /// like `import pandas as pd`, and enforces that convention.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use a common convention for imports to make your code
     /// more readable and idiomatic.
     ///
@@ -19,7 +19,7 @@ define_violation!(
     /// convention for importing the `pandas` library, and users typically expect
     /// Pandas to be aliased as `pd`.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// import pandas
     /// ```
diff --git a/crates/ruff/src/rules/flake8_no_pep420/rules.rs b/crates/ruff/src/rules/flake8_no_pep420/rules.rs
index eba6c4c545..db850480b6 100644
--- a/crates/ruff/src/rules/flake8_no_pep420/rules.rs
+++ b/crates/ruff/src/rules/flake8_no_pep420/rules.rs
@@ -8,10 +8,10 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for packages that are missing an `__init__.py` file.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Python packages are directories that contain a file named `__init__.py`.
     /// The existence of this file indicates that the directory is a Python
     /// package, and so it can be imported the same way a module can be
diff --git a/crates/ruff/src/rules/flake8_pyi/rules.rs b/crates/ruff/src/rules/flake8_pyi/rules.rs
index 4c94ab11d4..860431f512 100644
--- a/crates/ruff/src/rules/flake8_pyi/rules.rs
+++ b/crates/ruff/src/rules/flake8_pyi/rules.rs
@@ -26,15 +26,15 @@ impl fmt::Display for VarKind {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks that type `TypeVar`, `ParamSpec`, and `TypeVarTuple` definitions in
     /// stubs are prefixed with `_`.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// By prefixing type parameters with `_`, we can avoid accidentally exposing
     /// names internal to the stub.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// from typing import TypeVar
     ///
diff --git a/crates/ruff/src/rules/flake8_quotes/rules.rs b/crates/ruff/src/rules/flake8_quotes/rules.rs
index 07b3be4f57..66f18d2419 100644
--- a/crates/ruff/src/rules/flake8_quotes/rules.rs
+++ b/crates/ruff/src/rules/flake8_quotes/rules.rs
@@ -12,16 +12,16 @@ use crate::source_code::Locator;
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for inline strings that use single quotes or double quotes,
     /// depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes)
     /// setting.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use either single or double quotes for inline
     /// strings, but be consistent.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// foo = 'bar'
     /// ```
@@ -54,16 +54,16 @@ impl AlwaysAutofixableViolation for BadQuotesInlineString {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for multiline strings that use single quotes or double quotes,
     /// depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes)
     /// setting.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use either single or double quotes for multiline
     /// strings, but be consistent.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// foo = '''
     /// bar
@@ -100,15 +100,15 @@ impl AlwaysAutofixableViolation for BadQuotesMultilineString {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes)
     /// setting.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use either single or double quotes for docstring
     /// strings, but be consistent.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// '''
     /// bar
@@ -145,15 +145,15 @@ impl AlwaysAutofixableViolation for BadQuotesDocstring {
 }
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for strings that include escaped quotes, and suggests changing
     /// the quote style to avoid the need to escape them.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// It's preferable to avoid escaped quotes in strings. By changing the
     /// outer quote style, you can avoid escaping inner quotes.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// foo = 'bar\'s'
     /// ```
diff --git a/crates/ruff/src/rules/isort/rules/add_required_imports.rs b/crates/ruff/src/rules/isort/rules/add_required_imports.rs
index ad41c5c50a..557b83a80e 100644
--- a/crates/ruff/src/rules/isort/rules/add_required_imports.rs
+++ b/crates/ruff/src/rules/isort/rules/add_required_imports.rs
@@ -15,16 +15,16 @@ use crate::source_code::{Locator, Stylist};
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Adds any required imports, as specified by the user, to the top of the file.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// In some projects, certain imports are required to be present in all files. For
     /// example, some projects assume that `from __future__ import annotations` is enabled,
     /// and thus require that import to be present in all files. Omitting a "required" import
     /// (as specified by the user) can cause errors or unexpected behavior.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// import typing
     /// ```
diff --git a/crates/ruff/src/rules/isort/rules/organize_imports.rs b/crates/ruff/src/rules/isort/rules/organize_imports.rs
index 36ecc064d7..10f775ed7f 100644
--- a/crates/ruff/src/rules/isort/rules/organize_imports.rs
+++ b/crates/ruff/src/rules/isort/rules/organize_imports.rs
@@ -19,14 +19,14 @@ use crate::source_code::{Indexer, Locator, Stylist};
 use crate::violation::AlwaysAutofixableViolation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// De-duplicates, groups, and sorts imports based on the provided `isort` settings.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Consistency is good. Use a common convention for imports to make your code
     /// more readable and idiomatic.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// import pandas
     /// import numpy as np
diff --git a/crates/ruff/src/rules/isort/settings.rs b/crates/ruff/src/rules/isort/settings.rs
index aec716ecd2..794f51e71c 100644
--- a/crates/ruff/src/rules/isort/settings.rs
+++ b/crates/ruff/src/rules/isort/settings.rs
@@ -47,7 +47,7 @@ pub struct Options {
     /// exactly one member. For example, this formatting would be retained,
     /// rather than condensing to a single line:
     ///
-    /// ```py
+    /// ```python
     /// from .utils import (
     ///     test_directory as test_directory,
     ///     test_id as test_id
diff --git a/crates/ruff/src/rules/mccabe/rules.rs b/crates/ruff/src/rules/mccabe/rules.rs
index 62c50d51bc..e016d72e08 100644
--- a/crates/ruff/src/rules/mccabe/rules.rs
+++ b/crates/ruff/src/rules/mccabe/rules.rs
@@ -7,7 +7,7 @@ use crate::source_code::Locator;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for functions with a high `McCabe` complexity.
     ///
     /// The `McCabe` complexity of a function is a measure of the complexity of the
@@ -15,10 +15,10 @@ define_violation!(
     /// number of decision points in the function. A decision point is a place in
     /// the code where the program has a choice of two or more paths to follow.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Functions with a high complexity are hard to understand and maintain.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// def foo(a, b, c):
     ///     if a:
diff --git a/crates/ruff/src/rules/pylint/rules/bad_string_format_type.rs b/crates/ruff/src/rules/pylint/rules/bad_string_format_type.rs
index 52bcfcbcfe..e3ac38a03d 100644
--- a/crates/ruff/src/rules/pylint/rules/bad_string_format_type.rs
+++ b/crates/ruff/src/rules/pylint/rules/bad_string_format_type.rs
@@ -15,14 +15,14 @@ use crate::rules::pydocstyle::helpers::{leading_quote, trailing_quote};
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for mismatched argument types in "old-style" format strings.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// The format string is not checked at compile time, so it is easy to
     /// introduce bugs by mistyping the format string.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// print("%d" % "1")
     /// ```
diff --git a/crates/ruff/src/rules/pylint/rules/yield_in_init.rs b/crates/ruff/src/rules/pylint/rules/yield_in_init.rs
index d369f04115..452497baea 100644
--- a/crates/ruff/src/rules/pylint/rules/yield_in_init.rs
+++ b/crates/ruff/src/rules/pylint/rules/yield_in_init.rs
@@ -12,11 +12,11 @@ use crate::{
 };
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for `__init__` methods that are turned into generators by the
     /// inclusion of `yield` or `yield from` expressions.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// The `__init__` method is the constructor for a given Python class,
     /// responsible for initializing, rather than creating, new objects.
     ///
@@ -24,14 +24,14 @@ define_violation!(
     /// `yield from` expression in an `__init__`, the method will return a
     /// generator object when called at runtime, resulting in a runtime error.
     ///
-    /// ### Example
+    /// ## Example
     /// ```python
     /// class InitIsGenerator:
     ///     def __init__(self, i):
     ///         yield i
     /// ```
     ///
-    /// ### References
+    /// ## References
     /// * [`py-init-method-is-generator`](https://codeql.github.com/codeql-query-help/python/py-init-method-is-generator/)
     pub struct YieldInInit;
 );
diff --git a/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs b/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs
index 1fb2da139d..f4d276ac74 100644
--- a/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs
+++ b/crates/ruff/src/rules/tryceratops/rules/raise_vanilla_class.rs
@@ -7,10 +7,10 @@ use crate::registry::Diagnostic;
 use crate::violation::Violation;
 
 define_violation!(
-    /// ### What it does
+    /// ## What it does
     /// Checks for code that raises `Exception` directly.
     ///
-    /// ### Why is this bad?
+    /// ## Why is this bad?
     /// Handling such exceptions requires the use of `except Exception`, which
     /// captures _any_ raised exception, including failed assertions,
     /// division by zero, and more.
@@ -19,8 +19,8 @@ define_violation!(
     /// exception, so that you can avoid over-capturing exceptions that you
     /// don't intend to handle.
     ///
-    /// ### Example
-    /// ```py
+    /// ## Example
+    /// ```python
     /// def main_function():
     ///     if not cond:
     ///         raise Exception()
@@ -34,7 +34,7 @@ define_violation!(
     /// ```
     ///
     /// Use instead:
-    /// ```py
+    /// ```python
     /// def main_function():
     ///     if not cond:
     ///         raise CustomException()
@@ -47,6 +47,7 @@ define_violation!(
     ///         logger.error("Main function failed")
     ///     except Exception:
     ///         logger.error("Oops")
+    /// ```
     pub struct RaiseVanillaClass;
 );
 impl Violation for RaiseVanillaClass {
diff --git a/docs/rules/any-type.md b/docs/rules/any-type.md
index abd3a1e1dd..d70200e0e9 100644
--- a/docs/rules/any-type.md
+++ b/docs/rules/any-type.md
@@ -2,11 +2,11 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that an expression is annotated with a more specific type than
 `Any`.
 
-### Why is this bad?
+## Why is this bad?
 `Any` is a special type indicating an unconstrained type. When an
 expression is annotated with type `Any`, type checkers will allow all
 operations on it.
@@ -14,7 +14,7 @@ operations on it.
 It's better to be explicit about the type of an expression, and to use
 `Any` as an "escape hatch" only when it is really needed.
 
-### Example
+## Example
 ```python
 def foo(x: Any):
     ...
@@ -26,7 +26,7 @@ def foo(x: int):
     ...
 ```
 
-### References
+## References
 * [PEP 484](https://www.python.org/dev/peps/pep-0484/#the-any-type)
 * [`typing.Any`](https://docs.python.org/3/library/typing.html#typing.Any)
 * [Mypy: The Any type](https://mypy.readthedocs.io/en/stable/kinds_of_types.html#the-any-type)
\ No newline at end of file
diff --git a/docs/rules/assert-raises-exception.md b/docs/rules/assert-raises-exception.md
index 304d583b61..c8bc49c368 100644
--- a/docs/rules/assert-raises-exception.md
+++ b/docs/rules/assert-raises-exception.md
@@ -2,17 +2,17 @@
 
 Derived from the **flake8-bugbear** linter.
 
-### What it does
+## What it does
 Checks for `self.assertRaises(Exception)`.
 
-### Why is this bad?
+## Why is this bad?
 `assertRaises(Exception)` can lead to your test passing even if the
 code being tested is never executed due to a typo.
 
 Either assert for a more specific exception (builtin or custom), use
 `assertRaisesRegex` or the context manager form of `assertRaises`.
 
-### Example
+## Example
 ```python
 self.assertRaises(Exception, foo)
 ```
diff --git a/docs/rules/avoidable-escaped-quote.md b/docs/rules/avoidable-escaped-quote.md
index df204582d0..f2758e1d7e 100644
--- a/docs/rules/avoidable-escaped-quote.md
+++ b/docs/rules/avoidable-escaped-quote.md
@@ -4,15 +4,15 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for strings that include escaped quotes, and suggests changing
 the quote style to avoid the need to escape them.
 
-### Why is this bad?
+## Why is this bad?
 It's preferable to avoid escaped quotes in strings. By changing the
 outer quote style, you can avoid escaping inner quotes.
 
-### Example
+## Example
 ```python
 foo = 'bar\'s'
 ```
diff --git a/docs/rules/bad-quotes-docstring.md b/docs/rules/bad-quotes-docstring.md
index 3f1f5355be..534912952e 100644
--- a/docs/rules/bad-quotes-docstring.md
+++ b/docs/rules/bad-quotes-docstring.md
@@ -4,15 +4,15 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for docstrings that use single quotes or double quotes, depending on the value of the [`docstring-quotes`](https://github.com/charliermarsh/ruff#docstring-quotes)
 setting.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use either single or double quotes for docstring
 strings, but be consistent.
 
-### Example
+## Example
 ```python
 '''
 bar
diff --git a/docs/rules/bad-quotes-inline-string.md b/docs/rules/bad-quotes-inline-string.md
index be7908d6d9..047775275d 100644
--- a/docs/rules/bad-quotes-inline-string.md
+++ b/docs/rules/bad-quotes-inline-string.md
@@ -4,16 +4,16 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for inline strings that use single quotes or double quotes,
 depending on the value of the [`inline-quotes`](https://github.com/charliermarsh/ruff#inline-quotes)
 setting.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use either single or double quotes for inline
 strings, but be consistent.
 
-### Example
+## Example
 ```python
 foo = 'bar'
 ```
diff --git a/docs/rules/bad-quotes-multiline-string.md b/docs/rules/bad-quotes-multiline-string.md
index d2a1fed50b..d320ac2b84 100644
--- a/docs/rules/bad-quotes-multiline-string.md
+++ b/docs/rules/bad-quotes-multiline-string.md
@@ -4,16 +4,16 @@ Derived from the **flake8-quotes** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for multiline strings that use single quotes or double quotes,
 depending on the value of the [`multiline-quotes`](https://github.com/charliermarsh/ruff#multiline-quotes)
 setting.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use either single or double quotes for multiline
 strings, but be consistent.
 
-### Example
+## Example
 ```python
 foo = '''
 bar
diff --git a/docs/rules/bad-string-format-type.md b/docs/rules/bad-string-format-type.md
index 33e1c26a15..181be63ddb 100644
--- a/docs/rules/bad-string-format-type.md
+++ b/docs/rules/bad-string-format-type.md
@@ -2,14 +2,14 @@
 
 Derived from the **Pylint** linter.
 
-### What it does
+## What it does
 Checks for mismatched argument types in "old-style" format strings.
 
-### Why is this bad?
+## Why is this bad?
 The format string is not checked at compile time, so it is easy to
 introduce bugs by mistyping the format string.
 
-### Example
+## Example
 ```python
 print("%d" % "1")
 ```
diff --git a/docs/rules/commented-out-code.md b/docs/rules/commented-out-code.md
index a61abc4e93..09f2e0aa6b 100644
--- a/docs/rules/commented-out-code.md
+++ b/docs/rules/commented-out-code.md
@@ -4,14 +4,14 @@ Derived from the **eradicate** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks for commented-out Python code.
 
-### Why is this bad?
+## Why is this bad?
 Commented-out code is dead code, and is often included inadvertently.
 It should be removed.
 
-### Example
+## Example
 ```python
 # print('foo')
 ```
\ No newline at end of file
diff --git a/docs/rules/function-is-too-complex.md b/docs/rules/function-is-too-complex.md
index 3e09f63f11..daf6682f55 100644
--- a/docs/rules/function-is-too-complex.md
+++ b/docs/rules/function-is-too-complex.md
@@ -2,7 +2,7 @@
 
 Derived from the **mccabe** linter.
 
-### What it does
+## What it does
 Checks for functions with a high `McCabe` complexity.
 
 The `McCabe` complexity of a function is a measure of the complexity of the
@@ -10,10 +10,10 @@ control flow graph of the function. It is calculated by adding one to the
 number of decision points in the function. A decision point is a place in
 the code where the program has a choice of two or more paths to follow.
 
-### Why is this bad?
+## Why is this bad?
 Functions with a high complexity are hard to understand and maintain.
 
-### Example
+## Example
 ```python
 def foo(a, b, c):
     if a:
diff --git a/docs/rules/hardcoded-sql-expression.md b/docs/rules/hardcoded-sql-expression.md
index 2e06daa3cf..ebf8d1491d 100644
--- a/docs/rules/hardcoded-sql-expression.md
+++ b/docs/rules/hardcoded-sql-expression.md
@@ -2,22 +2,22 @@
 
 Derived from the **flake8-bandit** linter.
 
-### What it does
+## What it does
 Checks for strings that resemble SQL statements involved in some form
 string building operation.
 
-### Why is this bad?
+## Why is this bad?
 SQL injection is a common attack vector for web applications. Directly
 interpolating user input into SQL statements should always be avoided.
 Instead, favor parameterized queries, in which the SQL statement is
 provided separately from its parameters, as supported by `psycopg3`
 and other database drivers and ORMs.
 
-### Example
+## Example
 ```python
 query = "DELETE FROM foo WHERE id = '%s'" % identifier
 ```
 
-### References
+## References
 * [B608: Test for SQL injection](https://bandit.readthedocs.io/en/latest/plugins/b608_hardcoded_sql_expressions.html)
 * [psycopg3: Server-side binding](https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html#server-side-binding)
\ No newline at end of file
diff --git a/docs/rules/implicit-namespace-package.md b/docs/rules/implicit-namespace-package.md
index 1ef4a4f68e..07a561679b 100644
--- a/docs/rules/implicit-namespace-package.md
+++ b/docs/rules/implicit-namespace-package.md
@@ -2,10 +2,10 @@
 
 Derived from the **flake8-no-pep420** linter.
 
-### What it does
+## What it does
 Checks for packages that are missing an `__init__.py` file.
 
-### Why is this bad?
+## Why is this bad?
 Python packages are directories that contain a file named `__init__.py`.
 The existence of this file indicates that the directory is a Python
 package, and so it can be imported the same way a module can be
diff --git a/docs/rules/missing-required-import.md b/docs/rules/missing-required-import.md
index c76b0c249e..9de1b90200 100644
--- a/docs/rules/missing-required-import.md
+++ b/docs/rules/missing-required-import.md
@@ -4,16 +4,16 @@ Derived from the **isort** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Adds any required imports, as specified by the user, to the top of the file.
 
-### Why is this bad?
+## Why is this bad?
 In some projects, certain imports are required to be present in all files. For
 example, some projects assume that `from __future__ import annotations` is enabled,
 and thus require that import to be present in all files. Omitting a "required" import
 (as specified by the user) can cause errors or unexpected behavior.
 
-### Example
+## Example
 ```python
 import typing
 ```
diff --git a/docs/rules/missing-return-type-class-method.md b/docs/rules/missing-return-type-class-method.md
index ac2bbf91da..2d4e1e0f38 100644
--- a/docs/rules/missing-return-type-class-method.md
+++ b/docs/rules/missing-return-type-class-method.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that class methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 class Foo:
     @classmethod
diff --git a/docs/rules/missing-return-type-private-function.md b/docs/rules/missing-return-type-private-function.md
index 58b401f9d6..6d7ec5335d 100644
--- a/docs/rules/missing-return-type-private-function.md
+++ b/docs/rules/missing-return-type-private-function.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that private functions and methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 def _add(a, b):
     return a + b
diff --git a/docs/rules/missing-return-type-public-function.md b/docs/rules/missing-return-type-public-function.md
index 7048c12732..0ef9fa77c6 100644
--- a/docs/rules/missing-return-type-public-function.md
+++ b/docs/rules/missing-return-type-public-function.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that public functions and methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 def add(a, b):
     return a + b
diff --git a/docs/rules/missing-return-type-special-method.md b/docs/rules/missing-return-type-special-method.md
index ca78f5d732..e3041b9f58 100644
--- a/docs/rules/missing-return-type-special-method.md
+++ b/docs/rules/missing-return-type-special-method.md
@@ -4,11 +4,11 @@ Derived from the **flake8-annotations** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 Checks that "special" methods, like `__init__`, `__new__`, and `__call__`, have
 return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
@@ -23,7 +23,7 @@ or `ruff.toml` file:
 mypy-init-return = true
 ```
 
-### Example
+## Example
 ```python
 class Foo:
     def __init__(self, x: int):
diff --git a/docs/rules/missing-return-type-static-method.md b/docs/rules/missing-return-type-static-method.md
index cf44fc27b4..d952c5c726 100644
--- a/docs/rules/missing-return-type-static-method.md
+++ b/docs/rules/missing-return-type-static-method.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that static methods have return type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the return types of functions. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any returned values, and the types expected by callers, match expectation.
 
-### Example
+## Example
 ```python
 class Foo:
     @staticmethod
diff --git a/docs/rules/missing-type-args.md b/docs/rules/missing-type-args.md
index 2a8355630c..ce110ba94f 100644
--- a/docs/rules/missing-type-args.md
+++ b/docs/rules/missing-type-args.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that function `*args` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
 
-### Example
+## Example
 ```python
 def foo(*args):
     ...
diff --git a/docs/rules/missing-type-cls.md b/docs/rules/missing-type-cls.md
index 7f571d3b71..ea960f0cff 100644
--- a/docs/rules/missing-type-cls.md
+++ b/docs/rules/missing-type-cls.md
@@ -2,10 +2,10 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that class method `cls` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
@@ -13,7 +13,7 @@ any provided arguments match expectation.
 Note that many type checkers will infer the type of `cls` automatically, so this
 annotation is not strictly necessary.
 
-### Example
+## Example
 ```python
 class Foo:
     @classmethod
diff --git a/docs/rules/missing-type-function-argument.md b/docs/rules/missing-type-function-argument.md
index 9d5676efaf..3ffd588d57 100644
--- a/docs/rules/missing-type-function-argument.md
+++ b/docs/rules/missing-type-function-argument.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that function arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
 
-### Example
+## Example
 ```python
 def foo(x):
     ...
diff --git a/docs/rules/missing-type-kwargs.md b/docs/rules/missing-type-kwargs.md
index 899e6f0d7c..9baa68afa9 100644
--- a/docs/rules/missing-type-kwargs.md
+++ b/docs/rules/missing-type-kwargs.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that function `**kwargs` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
 
-### Example
+## Example
 ```python
 def foo(**kwargs):
     ...
diff --git a/docs/rules/missing-type-self.md b/docs/rules/missing-type-self.md
index fd31facd5f..a3fa287192 100644
--- a/docs/rules/missing-type-self.md
+++ b/docs/rules/missing-type-self.md
@@ -2,10 +2,10 @@
 
 Derived from the **flake8-annotations** linter.
 
-### What it does
+## What it does
 Checks that instance method `self` arguments have type annotations.
 
-### Why is this bad?
+## Why is this bad?
 Type annotations are a good way to document the types of function arguments. They also
 help catch bugs, when used alongside a type checker, by ensuring that the types of
 any provided arguments match expectation.
@@ -13,7 +13,7 @@ any provided arguments match expectation.
 Note that many type checkers will infer the type of `self` automatically, so this
 annotation is not strictly necessary.
 
-### Example
+## Example
 ```python
 class Foo:
     def bar(self):
diff --git a/docs/rules/prefix-type-params.md b/docs/rules/prefix-type-params.md
index b72095d97d..738e0478bd 100644
--- a/docs/rules/prefix-type-params.md
+++ b/docs/rules/prefix-type-params.md
@@ -2,15 +2,15 @@
 
 Derived from the **flake8-pyi** linter.
 
-### What it does
+## What it does
 Checks that type `TypeVar`, `ParamSpec`, and `TypeVarTuple` definitions in
 stubs are prefixed with `_`.
 
-### Why is this bad?
+## Why is this bad?
 By prefixing type parameters with `_`, we can avoid accidentally exposing
 names internal to the stub.
 
-### Example
+## Example
 ```python
 from typing import TypeVar
 
diff --git a/docs/rules/raise-vanilla-class.md b/docs/rules/raise-vanilla-class.md
index 60853d08a9..1023336649 100644
--- a/docs/rules/raise-vanilla-class.md
+++ b/docs/rules/raise-vanilla-class.md
@@ -2,10 +2,10 @@
 
 Derived from the **tryceratops** linter.
 
-### What it does
+## What it does
 Checks for code that raises `Exception` directly.
 
-### Why is this bad?
+## Why is this bad?
 Handling such exceptions requires the use of `except Exception`, which
 captures _any_ raised exception, including failed assertions,
 division by zero, and more.
@@ -14,8 +14,8 @@ Prefer to raise your own exception, or a more specific built-in
 exception, so that you can avoid over-capturing exceptions that you
 don't intend to handle.
 
-### Example
-```py
+## Example
+```python
 def main_function():
     if not cond:
         raise Exception()
@@ -29,7 +29,7 @@ def consumer_func():
 ```
 
 Use instead:
-```py
+```python
 def main_function():
     if not cond:
         raise CustomException()
@@ -41,4 +41,5 @@ def consumer_func():
     except CustomException:
         logger.error("Main function failed")
     except Exception:
-        logger.error("Oops")
\ No newline at end of file
+        logger.error("Oops")
+```
\ No newline at end of file
diff --git a/docs/rules/unconventional-import-alias.md b/docs/rules/unconventional-import-alias.md
index 8c2677b92c..8ac9f60ce8 100644
--- a/docs/rules/unconventional-import-alias.md
+++ b/docs/rules/unconventional-import-alias.md
@@ -2,11 +2,11 @@
 
 Derived from the **flake8-import-conventions** linter.
 
-### What it does
+## What it does
 Checks for imports that are typically imported using a common convention,
 like `import pandas as pd`, and enforces that convention.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use a common convention for imports to make your code
 more readable and idiomatic.
 
@@ -14,7 +14,7 @@ For example, `import pandas as pd` is a common
 convention for importing the `pandas` library, and users typically expect
 Pandas to be aliased as `pd`.
 
-### Example
+## Example
 ```python
 import pandas
 ```
diff --git a/docs/rules/unsorted-imports.md b/docs/rules/unsorted-imports.md
index 7ce576509f..570087b8f9 100644
--- a/docs/rules/unsorted-imports.md
+++ b/docs/rules/unsorted-imports.md
@@ -4,14 +4,14 @@ Derived from the **isort** linter.
 
 Autofix is always available.
 
-### What it does
+## What it does
 De-duplicates, groups, and sorts imports based on the provided `isort` settings.
 
-### Why is this bad?
+## Why is this bad?
 Consistency is good. Use a common convention for imports to make your code
 more readable and idiomatic.
 
-### Example
+## Example
 ```python
 import pandas
 import numpy as np
diff --git a/docs/rules/yield-in-init.md b/docs/rules/yield-in-init.md
index 17929b0cc6..77ce46c953 100644
--- a/docs/rules/yield-in-init.md
+++ b/docs/rules/yield-in-init.md
@@ -2,11 +2,11 @@
 
 Derived from the **Pylint** linter.
 
-### What it does
+## What it does
 Checks for `__init__` methods that are turned into generators by the
 inclusion of `yield` or `yield from` expressions.
 
-### Why is this bad?
+## Why is this bad?
 The `__init__` method is the constructor for a given Python class,
 responsible for initializing, rather than creating, new objects.
 
@@ -14,12 +14,12 @@ The `__init__` method has to return `None`. By including a `yield` or
 `yield from` expression in an `__init__`, the method will return a
 generator object when called at runtime, resulting in a runtime error.
 
-### Example
+## Example
 ```python
 class InitIsGenerator:
     def __init__(self, i):
         yield i
 ```
 
-### References
+## References
 * [`py-init-method-is-generator`](https://codeql.github.com/codeql-query-help/python/py-init-method-is-generator/)
\ No newline at end of file
diff --git a/ruff.schema.json b/ruff.schema.json
index 7bebf4c233..53afb04fb5 100644
--- a/ruff.schema.json
+++ b/ruff.schema.json
@@ -938,7 +938,7 @@
           ]
         },
         "force-wrap-aliases": {
-          "description": "Force `import from` statements with multiple members and at least one alias (e.g., `import A as B`) to wrap such that every line contains exactly one member. For example, this formatting would be retained, rather than condensing to a single line:\n\n```py from .utils import ( test_directory as test_directory, test_id as test_id ) ```\n\nNote that this setting is only effective when combined with `combine-as-imports = true`. When `combine-as-imports` isn't enabled, every aliased `import from` will be given its own line, in which case, wrapping is not necessary.",
+          "description": "Force `import from` statements with multiple members and at least one alias (e.g., `import A as B`) to wrap such that every line contains exactly one member. For example, this formatting would be retained, rather than condensing to a single line:\n\n```python from .utils import ( test_directory as test_directory, test_id as test_id ) ```\n\nNote that this setting is only effective when combined with `combine-as-imports = true`. When `combine-as-imports` isn't enabled, every aliased `import from` will be given its own line, in which case, wrapping is not necessary.",
           "type": [
             "boolean",
             "null"