chore: add initial docs setup

ci.nix

@@ -1,6 +1,6 @@
 {
   ci = {
-    stages = ["check" "upload"];
+    stages = ["check" "build" "deploy"];
     jobs = {
       "check" = {
         stage = "check";
@@ -8,8 +8,32 @@
           "nix flake check --impure"
         ];
       };
+      "docs" = {
+        stage = "build";
+        script = [
+          # sh
+          ''
+            nix build .#docs:default
+            mkdir -p public
+            cp -r result/. public/
+          ''
+        ];
+        artifacts.paths = ["public"];
+      };
+      "pages" = {
+        nix.enable = false;
+        image = "alpine:latest";
+        stage = "deploy";
+        script = ["true"];
+        artifacts.paths = ["public"];
+        rules = [
+          {
+            "if" = "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH";
+          }
+        ];
+      };
       "upload" = {
-        stage = "upload";
+        stage = "deploy";
         rules = [
           {"if" = ''$CI_COMMIT_REF_NAME == "main"'';}
         ];

docs/index.md

@@ -0,0 +1 @@
+Hello World!

flake.lock

@@ -221,6 +221,21 @@
         "type": "github"
       }
     },
+    "mkdocs-material-umami": {
+      "locked": {
+        "lastModified": 1745163020,
+        "narHash": "sha256-eYKx9b50bRbTHSbGusEB3HECJwZvLshW1SavFkN0foE=",
+        "owner": "technofab",
+        "repo": "mkdocs-material-umami",
+        "rev": "e09ad45e921b8c1a30a47d599dcb8e8cb4468200",
+        "type": "gitlab"
+      },
+      "original": {
+        "owner": "technofab",
+        "repo": "mkdocs-material-umami",
+        "type": "gitlab"
+      }
+    },
     "nix": {
       "inputs": {
         "flake-compat": [
@@ -272,6 +287,23 @@
         "type": "gitlab"
       }
     },
+    "nix-mkdocs": {
+      "locked": {
+        "dir": "lib",
+        "lastModified": 1745501687,
+        "narHash": "sha256-v0BE519o4zjZ8I7ZULjjIIj7HG5NPFo9JCO0HqyiEec=",
+        "owner": "TECHNOFAB",
+        "repo": "nixmkdocs",
+        "rev": "6c4bff339003ab0197a6dda96eea847996f21a63",
+        "type": "gitlab"
+      },
+      "original": {
+        "dir": "lib",
+        "owner": "TECHNOFAB",
+        "repo": "nixmkdocs",
+        "type": "gitlab"
+      }
+    },
     "nixpkgs": {
       "locked": {
         "lastModified": 1730531603,
@@ -402,7 +434,9 @@
         "flake-parts": "flake-parts_2",
         "git-hooks": "git-hooks",
         "kubenix": "kubenix",
+        "mkdocs-material-umami": "mkdocs-material-umami",
         "nix-gitlab-ci": "nix-gitlab-ci",
+        "nix-mkdocs": "nix-mkdocs",
         "nixpkgs": "nixpkgs_5",
         "systems": "systems_2",
         "treefmt-nix": "treefmt-nix"

flake.nix

@@ -15,6 +15,7 @@
       imports = [
         inputs.devenv.flakeModule
         inputs.nix-gitlab-ci.flakeModule
+        inputs.nix-mkdocs.flakeModule
         inputs.treefmt-nix.flakeModule
       ];
       systems = import systems;
@@ -50,6 +51,84 @@
           };
         };
 
+        doc = {
+          path = ./docs;
+          deps = pp: [pp.mkdocs-material (pp.callPackage inputs.mkdocs-material-umami {})];
+          config = {
+            site_name = "Nixlets";
+            repo_name = "TECHNOFAB/nixlets";
+            repo_url = "https://gitlab.com/TECHNOFAB/nixlets";
+            edit_uri = "edit/main/docs/";
+            theme = {
+              name = "material";
+              features = ["content.code.copy" "content.action.edit"];
+              icon = {
+                logo = "simple/kubernetes";
+                repo = "simple/gitlab";
+              };
+              palette = [
+                {
+                  scheme = "default";
+                  media = "(prefers-color-scheme: light)";
+                  primary = "blue";
+                  accent = "light blue";
+                  toggle = {
+                    icon = "material/brightness-7";
+                    name = "Switch to dark mode";
+                  };
+                }
+                {
+                  scheme = "slate";
+                  media = "(prefers-color-scheme: dark)";
+                  primary = "blue";
+                  accent = "light blue";
+                  toggle = {
+                    icon = "material/brightness-4";
+                    name = "Switch to light mode";
+                  };
+                }
+              ];
+            };
+            plugins = ["search" "material-umami"];
+            nav = [
+              {
+                "Introduction" = "index.md";
+              }
+            ];
+            markdown_extensions = [
+              {
+                "pymdownx.highlight".pygments_lang_class = true;
+              }
+              "pymdownx.inlinehilite"
+              "pymdownx.snippets"
+              "pymdownx.superfences"
+              "fenced_code"
+            ];
+            extra.analytics = {
+              provider = "umami";
+              site_id = "a4181010-317a-45e3-978c-5d07a93e0cd2";
+              src = "https://analytics.tf/umami";
+              feedback = {
+                title = "Was this page helpful?";
+                ratings = [
+                  {
+                    icon = "material/thumb-up-outline";
+                    name = "This page is helpful";
+                    data = "good";
+                    note = "Thanks for your feedback!";
+                  }
+                  {
+                    icon = "material/thumb-down-outline";
+                    name = "This page could be improved";
+                    data = "bad";
+                    note = "Thanks for your feedback!";
+                  }
+                ];
+              };
+            };
+          };
+        };
+
         # check if every nixlet successfully renders with default values
         checks =
           builtins.mapAttrs (
@@ -93,6 +172,8 @@
     git-hooks.url = "github:cachix/git-hooks.nix";
     treefmt-nix.url = "github:numtide/treefmt-nix";
     nix-gitlab-ci.url = "gitlab:TECHNOFAB/nix-gitlab-ci/feat/v2?dir=lib";
+    nix-mkdocs.url = "gitlab:TECHNOFAB/nixmkdocs?dir=lib";
+    mkdocs-material-umami.url = "gitlab:technofab/mkdocs-material-umami";
 
     kubenix = {
       url = "github:TECHNOFAB11/kubenix";