Merge pull request 'docs: check init htmlproofer' (#5392) from docs-simplify into main

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

docs/mkdocs.yml

@@ -233,7 +233,7 @@ extra:
     - icon: fontawesome/brands/github
       link: https://github.com/clan-lol/clan-core
     - icon: fontawesome/solid/rss
-      link: /feed_rss_created.xml
+      link: https://clan.lol/feed.xml
 
 plugins:
   - search

docs/nix/flake-module.nix

@@ -88,8 +88,12 @@
           ;
       };
       devShells.docs = self'.packages.docs.overrideAttrs (_old: {
-        nativeBuildInputs =
+        nativeBuildInputs = [
-          self'.devShells.default.nativeBuildInputs ++ self'.packages.docs.nativeBuildInputs;
+          # Run: htmlproofer --disable-external
+          pkgs.html-proofer
+        ]
+        ++ self'.devShells.default.nativeBuildInputs
+        ++ self'.packages.docs.nativeBuildInputs;
         shellHook = ''
           ${self'.devShells.default.shellHook}
           git_root=$(git rev-parse --show-toplevel)
@@ -113,5 +117,17 @@
         deploy-docs = pkgs.callPackage ./deploy-docs.nix { inherit (config.packages) docs; };
         inherit module-docs;
       };
+      checks.docs-integrity =
+        pkgs.runCommand "docs-integrity"
+          {
+            nativeBuildInputs = [ pkgs.html-proofer ];
+          }
+          ''
+            # External links should be avoided in the docs, because they often break
+            # and we cannot statically control them. Thus we disable checking them
+            htmlproofer --disable-external ${self'.packages.docs}
+
+            touch $out
+          '';
     };
 }

docs/site/decisions/template.md

@@ -1,6 +1,6 @@
 ## Decision record template by Michael Nygard
 
-This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+This is the template in [Documenting architecture decisions - Michael Nygard](https://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
 You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the ADR files.
 
 In each ADR file, write these sections:

docs/site/index.md

@@ -78,7 +78,7 @@ hide:
     /guides/backups/backup-intro/">Backups</a>.</p>
     <p>Whether you're running a homelab or maintaining critical computing infrastructure, Clan will help reduce maintenance burden</strong> by allowing a git repository to define your whole network</strong> of computers.</p>
     <p>In combination with <a href="https://github.com/Mic92/sops-nix">sops-nix</a>, <a href="https://github.com/nix-community/nixos-anywhere">nixos-anywhere</a> and <a href="https://github.com/nix-community/disko">disko</a>, Clan makes it possible to have collaborative infrastructure</strong>.</p>
-    <p>At the heart of Clan are <a href="/services/official/">Clan Services</a> - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, everyone can <a href="/guides/services/community/">create custom services</a> tailored to your specific needs.</p>
+    <p>At the heart of Clan are <a href="/services/definition">Clan Services</a> - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, everyone can <a href="/guides/services/community/">create custom services</a> tailored to your specific needs.</p>
   </div>
   <label class="clamp-more" for="clan-readmore"></label>
 </div>

docs/site/reference/index.md

@@ -5,9 +5,9 @@ This section of the site provides an overview of available options and commands
 ---
 
 - [Clan Configuration Option](/options) - for defining a Clan
-- Learn how to use the [Clan CLI](/reference/cli/index.md)
+- Learn how to use the [Clan CLI](../reference/cli/index.md)
-- Explore available [services](/services/index.md)
+- Explore available [services](../services/definition.md)
-- [NixOS Configuration Options](/reference/clan.core/index.md) - Additional options avilable on a NixOS machine.
+- [NixOS Configuration Options](../reference/clan.core/index.md) - Additional options avilable on a NixOS machine.
 
 ---
 

lib/modules/inventoryClass/inventory.nix

@@ -84,7 +84,7 @@ in
             - The module MUST have at least `features = [ "inventory" ]` in the frontmatter section.
             - The module MUST have a subfolder `roles` with at least one `{roleName}.nix` file.
 
-            For further information see: [Module Authoring Guide](/guides/services/community.md).
+            For further information see: [Module Authoring Guide](../../guides/services/community.md).
 
         ???+ example
             ```nix

pkgs/clan-cli/clan_cli/hyperlink.py

@@ -32,7 +32,9 @@ def help_hyperlink(description: str, url: str) -> str:
 
 def docs_hyperlink(description: str, url: str) -> str:
     """Returns a markdown hyperlink"""
-    url = url.replace("https://docs.clan.lol", "/")
+    # Attention: this code assumes the URL maps directly to the filetree structure of the docs
+    # We should probably enforce this
+    url = url.replace("https://docs.clan.lol", "../..")
     url = url.replace("index.html", "index")
     url += ".md"
     return f"[{description}]({url})"