diff --git a/docs/.envrc b/docs/.envrc
new file mode 100644
index 00000000..18267144
--- /dev/null
+++ b/docs/.envrc
@@ -0,0 +1,6 @@
+source_up
+
+watch_file flake-module.nix shell.nix default.nix
+
+# Because we depend on nixpkgs sources, uploading to builders takes a long time
+use flake .#docs --builders ''
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..d823e3fb
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,2 @@
+# build oputputs
+site
\ No newline at end of file
diff --git a/docs/admins/_index.md b/docs/admins/_index.md
deleted file mode 100644
index b2f084ad..00000000
--- a/docs/admins/_index.md
+++ /dev/null
@@ -1,10 +0,0 @@
-+++
-title = "Admin Documentation"
-description = "Documentation for administrators. Create and manage one or multiple cLANs"
-date = 2025-05-01T19:00:00+00:00
-updated = 2021-05-01T19:00:00+00:00
-template = "docs/section.html"
-weight = 15
-sort_by = "title"
-draft = false
-+++
diff --git a/docs/default.nix b/docs/default.nix
new file mode 100644
index 00000000..28fb890e
--- /dev/null
+++ b/docs/default.nix
@@ -0,0 +1,26 @@
+{ pkgs, ... }:
+pkgs.stdenv.mkDerivation {
+  name = "clan-documentation";
+
+  src = ./.;
+
+  nativeBuildInputs =
+    [ pkgs.python3 ]
+    ++ (with pkgs.python3Packages; [
+      mkdocs
+      mkdocs-material
+      mkdocs-drawio-exporter
+      mkdocs-swagger-ui-tag
+      plantuml-markdown
+    ]);
+
+  buildPhase = ''
+    mkdocs build --strict
+
+    ls -la .
+  '';
+
+  installPhase = ''
+    cp -a site/ $out/
+  '';
+}
diff --git a/docs/contributing/contributing.md b/docs/docs/contributing.md
similarity index 100%
rename from docs/contributing/contributing.md
rename to docs/docs/contributing.md
diff --git a/docs/admins/05-install-iso.md b/docs/docs/drafts/install-iso.md
similarity index 99%
rename from docs/admins/05-install-iso.md
rename to docs/docs/drafts/install-iso.md
index 9304a4de..5835b976 100644
--- a/docs/admins/05-install-iso.md
+++ b/docs/docs/drafts/install-iso.md
@@ -1,4 +1,4 @@
-# 03 Clan Hardware Installation
+# Hardware Installation
 
 For installations on physical hardware, create a NixOS installer image and transfer it to a bootable USB drive as described below.
 
diff --git a/docs/admins/07-backups.md b/docs/docs/getting-started/backups.md
similarity index 99%
rename from docs/admins/07-backups.md
rename to docs/docs/getting-started/backups.md
index cebd25e3..02571205 100644
--- a/docs/admins/07-backups.md
+++ b/docs/docs/getting-started/backups.md
@@ -1,4 +1,4 @@
-# 07 Backups
+# Backups
 
 ## Introduction to Backups
 
diff --git a/docs/admins/08-flake-parts.md b/docs/docs/getting-started/flake-parts.md
similarity index 97%
rename from docs/admins/08-flake-parts.md
rename to docs/docs/getting-started/flake-parts.md
index 3fcec3cd..5743a335 100644
--- a/docs/admins/08-flake-parts.md
+++ b/docs/docs/getting-started/flake-parts.md
@@ -1,4 +1,4 @@
-# 08 Clan with `flake-parts`
+# Clan with `flake-parts`
 
 Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows modular compositions.
 
@@ -82,7 +82,7 @@ refer to the Clan module documentation located [here](https://git.clan.lol/clan/
 
 ### Next Steps
 
-With your flake created, explore how to add new machines by reviewing the documentation provided [here](./02-machines.md).
+With your flake created, explore how to add new machines by reviewing the documentation provided [here](machines.md).
 
 ---
 
diff --git a/docs/admins/01-quickstart.md b/docs/docs/getting-started/index.md
similarity index 88%
rename from docs/admins/01-quickstart.md
rename to docs/docs/getting-started/index.md
index 8ed1b918..afd8816b 100644
--- a/docs/admins/01-quickstart.md
+++ b/docs/docs/getting-started/index.md
@@ -1,4 +1,4 @@
-# 01 Getting Started
+# Getting Started
 
 Welcome to your simple guide on starting a new Clan project!
 
@@ -7,7 +7,7 @@ Welcome to your simple guide on starting a new Clan project!
 We've put together a straightforward guide to help you out:
 
 - [**Starting with a New Clan Project**](#starting-with-a-new-clan-project): Create a new Clan from scratch.
-- [**Integrating Clan using Flake-Parts**](./08-flake-parts.md)
+- [**Integrating Clan using Flake-Parts**](flake-parts.md)
 
 ---
 
@@ -80,7 +80,7 @@ Open the `flake.nix` file and set a unique `clanName` if you want you can also s
 
 **Right now clan assumes that you already have NixOS running on the target machine.**
 
-If that is not the case you can use our [installer image](./05-install-iso.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
+If that is not the case you can use our [installer image](installer.md) that automatically generates an endpoint reachable over TOR with a random ssh password.
 
 On the remote execute:
 1. Generate a hardware-config.nix 
@@ -107,11 +107,11 @@ On the remote execute:
     ```
 
 ### **Next Steps**
-Ready to expand? Explore how to install a new machine with the helpful documentation [here](./02-machines.md).
+Ready to expand? Explore how to install a new machine with the helpful documentation [here](machines.md).
 Ready to explore more?
 
-- **Adding New Machines to your setup**. [Following our templates](./99-templates.md)
+- **Adding New Machines to your setup**. [Following our templates](../templates/index.md)
 
-- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how](./02-machines.md).
+- **Use a USB drive to Set Up Machines**: Setting up new computers remotely is easy with a USB stick. [Learn how](machines.md).
 
 ---
diff --git a/docs/admins/03-Installer.md b/docs/docs/getting-started/installer.md
similarity index 97%
rename from docs/admins/03-Installer.md
rename to docs/docs/getting-started/installer.md
index 2da7159a..d2d94844 100644
--- a/docs/admins/03-Installer.md
+++ b/docs/docs/getting-started/installer.md
@@ -1,4 +1,4 @@
-# 03 Clan Installer
+# Installer
 
 We offer a dedicated installer to assist remote installations.
 
@@ -84,7 +84,7 @@ See: Guide for Wifi Below
 
 ### Whats next?
 
-- [Deploying Machines](./02-machines.md): Deploying a Machine configuration
+- [Deploying Machines](machines.md): Deploying a Machine configuration
 - [WiFi](#optional-connect-to-wifi): Guide for connecting to Wifi.
 
 ---
diff --git a/docs/admins/02-machines.md b/docs/docs/getting-started/machines.md
similarity index 93%
rename from docs/admins/02-machines.md
rename to docs/docs/getting-started/machines.md
index 9d588cbc..6a4e8cbd 100644
--- a/docs/admins/02-machines.md
+++ b/docs/docs/getting-started/machines.md
@@ -1,4 +1,4 @@
-# 02 Machines with Clan
+# Deploy Machine
 
 Integrating a new machine into your Clan environment is a very easy yet flexible process, allowing for a straight forward management of multiple NixOS configurations.
 
@@ -12,7 +12,7 @@ This process involves preparing a suitable hardware and disk partitioning config
 
 ### Step 0. Prerequisites
 
-Boot the target machine using our [Clan Installer](./03-Installer.md). Which is recommended for ensuring most efficient workflows.
+Boot the target machine using our [Clan Installer](installer.md). Which is recommended for ensuring most efficient workflows.
 
 Alternatively you can use any linux machine if it is reachable via SSH and supports `kexec`.
 
@@ -23,9 +23,9 @@ ssh root@<your_target_machine_ip>
 ```
 
 - [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
-- [x] **Machine configuration**: You want to deploy. [Check out our templates](./99-templates.md)
-- [x] Initialized secrets: See [secrets](./06-secrets.md) for how to initialize your secrets.
-- [x] (Optional) USB Flash Drive with the [Clan Installer](./03-Installer.md)
+- [x] **Machine configuration**: You want to deploy. [Check out our templates](../templates/index.md)
+- [x] Initialized secrets: See [secrets](secrets.md) for how to initialize your secrets.
+- [x] (Optional) USB Flash Drive with the [Clan Installer](installer.md)
 
 ### Step 1. Identify Target Disk-ID
 
diff --git a/docs/admins/04-networking.md b/docs/docs/getting-started/networking.md
similarity index 98%
rename from docs/admins/04-networking.md
rename to docs/docs/getting-started/networking.md
index 308a3b4d..e1a4dfcc 100644
--- a/docs/admins/04-networking.md
+++ b/docs/docs/getting-started/networking.md
@@ -1,4 +1,4 @@
-# 04 Overlay Networks in Clan
+# Overlay Networks
 
 This guide provides detailed instructions for configuring
 [ZeroTier VPN](https://zerotier.com) within Clan. Follow the
diff --git a/docs/admins/06-secrets.md b/docs/docs/getting-started/secrets.md
similarity index 99%
rename from docs/admins/06-secrets.md
rename to docs/docs/getting-started/secrets.md
index 447aafcc..35378dba 100644
--- a/docs/admins/06-secrets.md
+++ b/docs/docs/getting-started/secrets.md
@@ -1,4 +1,4 @@
-# 06 Secrets with Clan
+# Secrets
 
 Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
 
diff --git a/docs/admins/99-templates.md b/docs/docs/templates/index.md
similarity index 62%
rename from docs/admins/99-templates.md
rename to docs/docs/templates/index.md
index 6d76de74..12c6bce2 100644
--- a/docs/admins/99-templates.md
+++ b/docs/docs/templates/index.md
@@ -1,13 +1,17 @@
-# 99 Templates
+# Templates
 
 We provide some starting templates you can easily use one of those via `nix flakes`.
 
 They showcase best practices and guide you through setting up and using Clan's modules
 
-To use the `new-clan` template run the following command:
+I.e. To use the `new-clan` template run the following command:
 
 `nix flake init -t git+https://git.clan.lol/clan/clan-core#new-clan`.
 
 ## Available Templates
 
+We offer the following templates:
+
+To initialize a clan with one of those run `nix flake init -t git+https://git.clan.lol/clan/clan-core#TEMPLATE_NAME`
+
 - **new-clan**:  Perfect for beginners, this template shows you how to link two machines in a basic setup.
diff --git a/docs/flake-module.nix b/docs/flake-module.nix
new file mode 100644
index 00000000..0d07108d
--- /dev/null
+++ b/docs/flake-module.nix
@@ -0,0 +1,13 @@
+{ inputs, ... }:
+{
+  perSystem =
+    { self', pkgs, ... }:
+    {
+      devShells.docs = pkgs.callPackage ./shell.nix { inherit (self'.packages) docs; };
+      packages = {
+        docs = pkgs.python3.pkgs.callPackage ./default.nix { inherit (inputs) nixpkgs; };
+      };
+
+      checks = self'.packages.clan-cli.tests;
+    };
+}
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
new file mode 100644
index 00000000..de2f6314
--- /dev/null
+++ b/docs/mkdocs.yml
@@ -0,0 +1,68 @@
+site_name: Design
+site_url: https://docs.clan.lol
+repo_url: https://git.clan.lol/clan/clan-core/
+repo_name: clan-core
+edit_uri: _edit/main/docs/docs/
+
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+
+markdown_extensions:
+  - footnotes
+  - meta
+  - admonition
+  - pymdownx.details
+  - pymdownx.highlight:
+      use_pygments: true
+  - pymdownx.superfences
+  - plantuml_markdown
+  - toc:
+      title: On this page
+
+exclude_docs: |
+  .*
+  !templates/
+  /drafts/
+
+nav:
+  - Getting started:
+      - getting-started/index.md
+      - Deploy Machine: getting-started/machines.md
+      - Installer: getting-started/installer.md
+      - Setup Networking: getting-started/networking.md
+      - Provision Secrets & Passwords: getting-started/secrets.md
+      - Backup & Restore: getting-started/backups.md
+      - Flake-parts: getting-started/flake-parts.md
+  - Templates: templates/index.md
+  - Contributing: contributing.md
+
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.tabs
+  icon:
+    repo: fontawesome/brands/git
+
+  palette:
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
+# extra_css:
+#   - stylesheets/extra.css
+
+plugins:
+  - search
diff --git a/docs/shell.nix b/docs/shell.nix
new file mode 100644
index 00000000..a4728b7f
--- /dev/null
+++ b/docs/shell.nix
@@ -0,0 +1 @@
+{ docs, pkgs, ... }: pkgs.mkShell { inputsFrom = [ docs ]; }
diff --git a/flake.nix b/flake.nix
index 343c23d2..99163743 100644
--- a/flake.nix
+++ b/flake.nix
@@ -39,6 +39,7 @@
           (import ./flakeModules/clan.nix inputs.self)
           ./devShell.nix
           ./docs/flake-module
+          ./docs/flake-module.nix
           ./formatter.nix
           ./lib/flake-module.nix
           ./nixosModules/flake-module.nix