docs: add mkdocs-awesome-pages-plugin

docs/mkdocs.yml

@@ -5,6 +5,7 @@ site_dir: !ENV out
 
 plugins:
   - search
+  - awesome-pages
 
 hooks:
   - hooks/render_options.py
@@ -12,20 +13,6 @@ hooks:
 extra_css:
   - style.css
 
-
-nav:
-  - "Home": index.md
-  - "Getting Started": gettingstarted.md
-  - Concepts:
-      - "Modules": modules.md
-      - "Overriding Dependencies": overrides.md
-  - Examples:
-      - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
-      - "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
-      - "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
-  - Reference:
-      - "pip": reference/pip/index.md
-
 markdown_extensions:
   - tables
   - admonition

docs/src/.pages

@@ -0,0 +1,14 @@
+nav:
+  - "Home": index.md
+  - "Getting Started": gettingstarted.md
+  - Concepts:
+      - "Modules": modules.md
+      - "Overriding Dependencies": overrides.md
+  - Reference: reference
+  - Examples:
+      - "👉 example repository": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages
+      - "👉 example repository using flakes": https://github.com/nix-community/dream2nix/tree/main/examples/repo-with-packages-flake)
+      - "👉 example packages": https://github.com/nix-community/dream2nix/tree/main/examples/packages)
+  - Notes:
+    - "v1 API design docs": v1-api
+    - development-roundups

docs/src/v1-api/.pages

@@ -0,0 +1,3 @@
+nav:
+    - summary.md
+    - ...

modules/flake-parts/reference-website/default.nix

@@ -84,6 +84,11 @@
         mkdir -p "$target_dir"
         ln -s ${sourcePath}/README.md "$target_dir/index.md"
         ln -s ${options.docs.${name}.optionsJSON}/share/doc/nixos/options.json "$target_dir"
+        cat > "$target_dir/.pages" <<EOF
+        collapse_single_pages: true
+        nav:
+          - ...
+        EOF
       '';
     in
       pkgs.runCommand "reference" {
@@ -96,6 +101,7 @@
         nativeBuildInputs = [
           pkgs.python3.pkgs.mkdocs
           pkgs.python3.pkgs.mkdocs-material
+          self.packages.${system}.mkdocs-awesome-pages-plugin
           referenceDocs
         ];
       } ''
@@ -104,6 +110,21 @@
         mkdocs build
       '';
   in {
+    packages.mkdocs-awesome-pages-plugin = pkgs.callPackage ./mkdocs-awesome-pages-plugin.nix {
+      inherit
+        (pkgs.python3.pkgs)
+        buildPythonPackage
+        mkdocs
+        wcmatch
+        natsort
+        beautifulsoup4
+        mock-open
+        importlib-metadata
+        poetry-core
+        pytestCheckHook
+        pythonOlder
+        ;
+    };
     packages.reference = referenceDocs;
     packages.website = website;
     devShells.website = let

modules/flake-parts/reference-website/mkdocs-awesome-pages-plugin.nix

@@ -0,0 +1,56 @@
+{
+  lib,
+  buildPythonPackage,
+  fetchFromGitHub,
+  poetry-core,
+  mkdocs,
+  wcmatch,
+  natsort,
+  pytestCheckHook,
+  beautifulsoup4,
+  mock-open,
+  importlib-metadata,
+  pythonOlder,
+}:
+buildPythonPackage rec {
+  pname = "mkdocs-awesome-pages-plugin";
+  version = "2.9.2";
+  pyproject = true;
+
+  disabled = pythonOlder "3.9";
+
+  src = fetchFromGitHub {
+    owner = "lukasgeiter";
+    repo = "mkdocs-awesome-pages-plugin";
+    rev = "refs/tags/v${version}";
+    hash = "sha256-pYyZ84eNrslxgLSBr3teQqmV7hA+LHwJ+Z99QgPdh6U=";
+  };
+
+  propagatedBuildInputs = [
+    mkdocs
+    wcmatch
+    natsort
+  ];
+
+  nativeBuildInputs = [poetry-core];
+
+  nativeCheckInputs = [
+    pytestCheckHook
+    beautifulsoup4
+    mock-open
+    importlib-metadata
+  ];
+
+  disabledTestPaths = [
+    # requires "generatedfiles" mkdocs plugin
+    "mkdocs_awesome_pages_plugin/tests/e2e/test_gen_files.py"
+  ];
+
+  meta = with lib; {
+    description = "An MkDocs plugin that simplifies configuring page titles and their order";
+    homepage = "https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin";
+    changelog = "https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/blob/v${version}/CHANGELOG";
+    license = licenses.mit;
+    maintainers = with maintainers; [phaer];
+  };
+}