Add separate configuration for MkDocs Insiders plugins (#5544)

## Summary

This PR adds a separate configuration file to enable us to turn on
[Insiders-only
plugins](https://squidfunk.github.io/mkdocs-material/insiders/getting-started/#built-in-plugins).

I've turned on the `typeset` plugin which ensures that the settings on
the left-hand navigation pane render as code:

<img width="1792" alt="Screen Shot 2023-07-05 at 6 27 20 PM"
src="https://github.com/astral-sh/ruff/assets/1309177/c93676dd-bb48-417a-9d3b-528bf001e9b7">

.github/workflows/ci.yaml

@@ -271,4 +271,4 @@ jobs:
       - name: "Check docs formatting"
         run: python scripts/check_docs_formatted.py
       - name: "Build docs"
-        run: mkdocs build --strict -f mkdocs.generated.yml
+        run: mkdocs build --strict -f mkdocs.insiders.yml

.github/workflows/docs.yaml

@@ -26,7 +26,7 @@ jobs:
         run: |
           python scripts/transform_readme.py --target mkdocs
           python scripts/generate_mkdocs.py
-          mkdocs build --strict -f mkdocs.generated.yml
+          mkdocs build --strict -f mkdocs.insiders.yml
       - name: "Deploy to Cloudflare Pages"
         if: ${{ env.CF_API_TOKEN_EXISTS == 'true' }}
         uses: cloudflare/wrangler-action@2.0.0

CONTRIBUTING.md

@@ -256,7 +256,11 @@ To preview any changes to the documentation locally:
 1. Run the development server with:
 
    ```shell
+   # For contributors.
    mkdocs serve -f mkdocs.generated.yml
+
+   # For members of the Astral org, which has access to MkDocs Insiders via sponsorship.
+   mkdocs serve -f mkdocs.insiders.yml
    ```
 
 The documentation should then be available locally at

crates/ruff_dev/src/generate_options.rs

@@ -58,7 +58,7 @@ pub(crate) fn generate() -> String {
         let OptionEntry::Group(fields) = entry else {
             continue;
         };
-        output.push_str(&format!("### `{group_name}`\n"));
+        output.push_str(&format!("### {group_name}\n"));
         output.push('\n');
         for (name, entry) in fields.iter().sorted_by_key(|(name, _)| name) {
             let OptionEntry::Field(field) = entry else {

mkdocs.insiders.yml

@@ -0,0 +1,4 @@
+INHERIT: mkdocs.generated.yml
+plugins:
+  - search
+  - typeset

mkdocs.template.yml

@@ -5,6 +5,7 @@ theme:
   favicon: assets/ruff-favicon.png
   features:
     - navigation.instant
+    - navigation.instant.prefetch
     - navigation.tracking
     - content.code.annotate
     - toc.integrate