Merge pull request 'docs: self host documentation with mkDocs' (#1176) from hsjobeki-tutorials into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/1176

.gitea/workflows/checks.yaml

@@ -10,11 +10,6 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - run: nix run --refresh github:Mic92/nix-fast-build -- --no-nom --eval-workers 10
-  check-links:
-    runs-on: nix
-    steps:
-      - uses: actions/checkout@v3
-      - run: nix run --refresh --inputs-from .# nixpkgs#lychee .
   checks-impure:
     runs-on: nix
     steps:

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to cLAN
+
+## Live-reloading documentation
+
+Enter the `docs` directory:
+
+```shell-session
+cd docs
+```
+
+Enter the development shell or enable `direnv`:
+
+```shell-session
+direnv allow
+```
+
+Run a local server:
+
+```shell-session
+mkdocs serve
+```

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 ''

docs/.gitignore

@@ -0,0 +1,2 @@
+# build oputputs
+site

docs/admins/_index.md

@@ -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
-+++

docs/default.nix

@@ -0,0 +1,23 @@
+{ pkgs, ... }:
+pkgs.stdenv.mkDerivation {
+  name = "clan-documentation";
+
+  src = ./.;
+
+  nativeBuildInputs =
+    [ pkgs.python3 ]
+    ++ (with pkgs.python3Packages; [
+      mkdocs
+      mkdocs-material
+    ]);
+
+  buildPhase = ''
+    mkdocs build --strict
+
+    ls -la .
+  '';
+
+  installPhase = ''
+    cp -a site/ $out/
+  '';
+}

docs/deploy-docs.nix

@@ -0,0 +1,36 @@
+{
+  writeShellScriptBin,
+  coreutils,
+  openssh,
+  rsync,
+  lib,
+  docs,
+}:
+
+writeShellScriptBin "deploy-docs" ''
+  set -eux -o pipefail
+  export PATH="${
+    lib.makeBinPath [
+      coreutils
+      openssh
+      rsync
+    ]
+  }"
+
+  if [ -n "$SSH_HOMEPAGE_KEY" ]; then
+    echo "$SSH_HOMEPAGE_KEY" > ./ssh_key
+    chmod 600 ./ssh_key
+    sshExtraArgs="-i ./ssh_key"
+  else
+    sshExtraArgs=
+  fi
+
+  rsync \
+    -e "ssh -o StrictHostKeyChecking=no $sshExtraArgs" \
+    -a ${docs}/ \
+    www@clan.lol:/var/www/docs.clan.lol
+
+  if [ -e ./ssh_key ]; then
+    rm ./ssh_key
+  fi
+''

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.
 

docs/docs/getting-started/backups.md

@@ -1,4 +1,4 @@
-# 07 Backups
+# Backups
 
 ## Introduction to Backups
 

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).
 
 ---
 

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.
 
 ---

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] **Machine configuration**: You want to deploy. [Check out our templates](../templates/index.md)
-- [x] Initialized secrets: See [secrets](./06-secrets.md) for how to initialize your secrets.
+- [x] Initialized secrets: See [secrets](secrets.md) for how to initialize your secrets.
-- [x] (Optional) USB Flash Drive with the [Clan Installer](./03-Installer.md)
+- [x] (Optional) USB Flash Drive with the [Clan Installer](installer.md)
 
 ### Step 1. Identify Target Disk-ID
 

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

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.
 

docs/docs/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**](getting-started/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](getting-started/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](getting-started/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](getting-started/machines.md).
 
 ---

docs/docs/stylesheets/extra.css

@@ -0,0 +1,5 @@
+:root {
+    --md-primary-fg-color:        #5d2f86;
+    --md-primary-fg-color--light: #9965f4;
+    --md-primary-fg-color--dark:  #3d00e0;
+}

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.

docs/flake-module.nix

@@ -0,0 +1,17 @@
+{ inputs, ... }:
+{
+  perSystem =
+    {
+      config,
+      self',
+      pkgs,
+      ...
+    }:
+    {
+      devShells.docs = pkgs.callPackage ./shell.nix { inherit (self'.packages) docs; };
+      packages = {
+        docs = pkgs.python3.pkgs.callPackage ./default.nix { inherit (inputs) nixpkgs; };
+        deploy-docs = pkgs.callPackage ./deploy-docs.nix { inherit (config.packages) docs; };
+      };
+    };
+}

docs/mkdocs.yml

@@ -0,0 +1,68 @@
+site_name: cLAN documentation
+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
+  - toc:
+      title: On this page
+
+exclude_docs: |
+  .*
+  !templates/
+  /drafts/
+
+nav:
+  - 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:
+  logo: static/logo.png
+  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

docs/shell.nix

@@ -0,0 +1 @@
+{ docs, pkgs, ... }: pkgs.mkShell { inputsFrom = [ docs ]; }

flake.nix

@@ -38,7 +38,9 @@
           ./flakeModules/flake-module.nix
           (import ./flakeModules/clan.nix inputs.self)
           ./devShell.nix
-          ./docs/flake-module
+          # TODO: migrate this @davHau
+          # ./docs/flake-module
+          ./docs/flake-module.nix
           ./formatter.nix
           ./lib/flake-module.nix
           ./nixosModules/flake-module.nix