Fix broken links and markdown style (#3017)

.pre-commit-config.yaml

@@ -1,3 +1,4 @@
+fail_fast: true
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject
     rev: v0.10.1
@@ -12,6 +13,7 @@ repos:
           - --disable
           - MD013 # line-length
           - MD033 # no-inline-html
+          - MD041 # first-line-h1
           - --
 
   - repo: local

CODE_OF_CONDUCT.md

@@ -1,16 +1,16 @@
 # Contributor Covenant Code of Conduct
 
-- [Our Pledge](#our-pledge)
-- [Our Standards](#our-standards)
-- [Enforcement Responsibilities](#enforcement-responsibilities)
-- [Scope](#scope)
-- [Enforcement](#enforcement)
-- [Enforcement Guidelines](#enforcement-guidelines)
-  - [1. Correction](#1-correction)
-  - [2. Warning](#2-warning)
-  - [3. Temporary Ban](#3-temporary-ban)
-  - [4. Permanent Ban](#4-permanent-ban)
-- [Attribution](#attribution)
+* [Our Pledge](#our-pledge)
+* [Our Standards](#our-standards)
+* [Enforcement Responsibilities](#enforcement-responsibilities)
+* [Scope](#scope)
+* [Enforcement](#enforcement)
+* [Enforcement Guidelines](#enforcement-guidelines)
+  * [1. Correction](#1-correction)
+  * [2. Warning](#2-warning)
+  * [3. Temporary Ban](#3-temporary-ban)
+  * [4. Permanent Ban](#4-permanent-ban)
+* [Attribution](#attribution)
 
 ## Our Pledge
 

CONTRIBUTING.md

@@ -2,16 +2,16 @@
 
 Welcome! We're happy to have you here. Thank you in advance for your contribution to Ruff.
 
-- [The Basics](#the-basics)
-  - [Prerequisites](#prerequisites)
-  - [Development](#development)
-  - [Project Structure](#project-structure)
-  - [Example: Adding a new lint rule](#example-adding-a-new-lint-rule)
-    - [Rule naming convention](#rule-naming-convention)
-  - [Example: Adding a new configuration option](#example-adding-a-new-configuration-option)
-- [MkDocs](#mkdocs)
-- [Release Process](#release-process)
-- [Benchmarks](#benchmarks)
+* [The Basics](#the-basics)
+  * [Prerequisites](#prerequisites)
+  * [Development](#development)
+  * [Project Structure](#project-structure)
+  * [Example: Adding a new lint rule](#example-adding-a-new-lint-rule)
+    * [Rule naming convention](#rule-naming-convention)
+  * [Example: Adding a new configuration option](#example-adding-a-new-configuration-option)
+* [MkDocs](#mkdocs)
+* [Release Process](#release-process)
+* [Benchmarks](#benchmarks)
 
 ## The Basics
 
@@ -94,12 +94,12 @@ The vast majority of the code, including all lint rules, lives in the `ruff` cra
 
 At time of writing, the repository includes the following crates:
 
-- `crates/ruff`: library crate containing all lint rules and the core logic for running them.
-- `crates/ruff_cli`: binary crate containing Ruff's command-line interface.
-- `crates/ruff_dev`: binary crate containing utilities used in the development of Ruff itself (e.g., `cargo dev generate-all`).
-- `crates/ruff_macros`: library crate containing macros used by Ruff.
-- `crates/ruff_python`: library crate implementing Python-specific functionality (e.g., lists of standard library modules by versionb).
-- `crates/flake8_to_ruff`: binary crate for generating Ruff configuration from Flake8 configuration.
+* `crates/ruff`: library crate containing all lint rules and the core logic for running them.
+* `crates/ruff_cli`: binary crate containing Ruff's command-line interface.
+* `crates/ruff_dev`: binary crate containing utilities used in the development of Ruff itself (e.g., `cargo dev generate-all`).
+* `crates/ruff_macros`: library crate containing macros used by Ruff.
+* `crates/ruff_python`: library crate implementing Python-specific functionality (e.g., lists of standard library modules by versionb).
+* `crates/flake8_to_ruff`: binary crate for generating Ruff configuration from Flake8 configuration.
 
 ### Example: Adding a new lint rule
 
@@ -146,7 +146,7 @@ Finally, regenerate the documentation and generated code with `cargo dev generat
 
 #### Rule naming convention
 
-The rule name should make sense when read as "allow *rule-name*" or "allow *rule-name* items".
+The rule name should make sense when read as "allow _rule-name_" or "allow _rule-name_ items".
 
 This implies that rule names:
 
@@ -186,14 +186,19 @@ Finally, regenerate the documentation and generated code with `cargo dev generat
 To preview any changes to the documentation locally:
 
 1. Install MkDocs and Material for MkDocs with:
+
    ```shell
    pip install -r docs/requirements.txt
    ```
+
 2. Generate the MkDocs site with:
+
    ```shell
    python scripts/generate_mkdocs.py
    ```
+
 3. Run the development server with:
+
    ```shell
    mkdocs serve
    ```

docs/faq.md

@@ -172,8 +172,8 @@ Ruff can lint code for any Python version from 3.7 onwards. However, Ruff lacks
 language features that were introduced in Python 3.10 and later. Specifically, Ruff does not
 support:
 
-- "Structural Pattern Matching" ([PEP 622](https://peps.python.org/pep-0622/)), introduced in Python 3.10.
-- "Exception Groups and except* ([PEP 654](https://www.python.org/dev/peps/pep-0654/)), introduced in Python 3.11.
+* "Structural Pattern Matching" ([PEP 622](https://peps.python.org/pep-0622/)), introduced in Python 3.10.
+* "Exception Groups and except* ([PEP 654](https://www.python.org/dev/peps/pep-0654/)), introduced in Python 3.11.
 
 Support for these features is planned.
 
@@ -208,7 +208,7 @@ and in how Ruff and isort treat inline comments in some cases (see: [#1381](http
 Like isort, Ruff's import sorting is compatible with Black.
 
 Ruff does not yet support all of isort's configuration options, though it does support many of
-them. You can find the supported settings in the [API reference](#isort). For example, you can set
+them. You can find the supported settings in the [API reference](https://beta.ruff.rs/docs/settings/#isort). For example, you can set
 `known-first-party` like so:
 
 ```toml
@@ -324,7 +324,7 @@ have _complete_ certainty when making changes to code, even for the seemingly tr
 In the future, Ruff will support enabling autofix behavior based on the safety of the patch.
 
 In the meantime, if you find that the autofix is too aggressive, you can disable it on a per-rule or
-per-category basis using the [`unfixable`](#unfixable) mechanic. For example, to disable autofix
+per-category basis using the [`unfixable`](https://beta.ruff.rs/docs/settings/#unfixable) mechanic. For example, to disable autofix
 for some possibly-unsafe rules, you could add the following to your `pyproject.toml`:
 
 ```toml