Order the documentation navigation (#2993)

* sort the website navigation nicely

* update uv lock

docs/.nav.yml

@@ -0,0 +1,14 @@
+# Managed by the awesome-nav plugin.
+# https://lukasgeiter.github.io/mkdocs-awesome-nav/
+# Allows us to specify the order of these pages (default is alphabetical)
+# without having to write the whole nav.
+nav:
+  - index.md
+  - setup.md
+  - commands
+  - functions
+  - configuration
+  - contributing
+  - misc
+  - reference
+  - blog

mkdocs.yml

@@ -142,6 +142,9 @@ plugins:
       version_selector: true
       canonical_version: latest
 
+  # Fine-grained nav control
+  - awesome-nav:
+
   - rss:
 # https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage/#rss-feeds
 # https://guts.github.io/mkdocs-rss-plugin/configuration/#plugin-options
@@ -235,9 +238,4 @@ markdown_extensions:
   - pymdownx.tasklist
 
 # We intentionally do not include `nav:` so that it gets autogenerated using
-# the folder structure.
-
-# It would be nice to add a hook that populates docs/commands/index.md
-# with a nice table of contents with command descriptions.
-# https://github.com/squidfunk/mkdocs-material/discussions/7000
-# TODO: modify scripts/gen_command_docs.py
+# the folder structure. See also docs/.nav.yml

pyproject.toml

@@ -16,6 +16,8 @@ dependencies = [
     "pyelftools>=0.29,<0.30",
     "pygments>=2.18.0,<3",
     "psutil>=6.1.1,<7",
+    # for the (unused) inform_unmet_dependencies function
+    "setuptools>=80.8.0",
     # Optional? only for 'ipi' command
     "ipython>=8.27.0,<9",
     # Optional? only for 'ropgadget' command
@@ -73,6 +75,7 @@ docs = [
     # Used by mkdocstrings to format source.
     "ruff",
     "mike",
+    "mkdocs-awesome-nav",
 ]
 
 [tool.ruff]