From fcfd56c00c12f7c683f223c30182ceaeccca6902 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sun, 5 Oct 2025 13:07:57 +0200 Subject: [PATCH 1/3] docs: check init htmlproofer Checks integrity of internal links post-rendering for problems that might have slipped through we noticed a set of edge cases where the builtin link checking doesnt work --- docs/nix/flake-module.nix | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/nix/flake-module.nix b/docs/nix/flake-module.nix index 7a94a4e37..2d70b9fc2 100644 --- a/docs/nix/flake-module.nix +++ b/docs/nix/flake-module.nix @@ -88,8 +88,12 @@ ; }; devShells.docs = self'.packages.docs.overrideAttrs (_old: { - nativeBuildInputs = - self'.devShells.default.nativeBuildInputs ++ self'.packages.docs.nativeBuildInputs; + 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 + ''; }; } From 75c8feb42a4b90fd9bde3e001e564c924ee8f201 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sun, 5 Oct 2025 13:08:12 +0200 Subject: [PATCH 2/3] docs: fix rss link --- docs/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 7e8649b15..51e748387 100644 --- a/docs/mkdocs.yml +++ b/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 From 359582118c8cb543f5d101d0ebee4144979e7f23 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Sun, 5 Oct 2025 13:59:50 +0200 Subject: [PATCH 3/3] docs: fix broken links --- docs/site/decisions/template.md | 2 +- docs/site/index.md | 2 +- docs/site/reference/index.md | 6 +++--- lib/modules/inventoryClass/inventory.nix | 2 +- pkgs/clan-cli/clan_cli/hyperlink.py | 4 +++- 5 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/site/decisions/template.md b/docs/site/decisions/template.md index 5c7d6fe68..445754347 100644 --- a/docs/site/decisions/template.md +++ b/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: diff --git a/docs/site/index.md b/docs/site/index.md index b964f169b..5ae8b870a 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -78,7 +78,7 @@ hide: /guides/backups/backup-intro/">Backups.

Whether you're running a homelab or maintaining critical computing infrastructure, Clan will help reduce maintenance burden by allowing a git repository to define your whole network of computers.

In combination with sops-nix, nixos-anywhere and disko, Clan makes it possible to have collaborative infrastructure.

-

At the heart of Clan are Clan Services - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, everyone can create custom services tailored to your specific needs.

+

At the heart of Clan are Clan Services - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, everyone can create custom services tailored to your specific needs.

diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md index 41742feb6..a7be7f90a 100644 --- a/docs/site/reference/index.md +++ b/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) -- Explore available [services](/services/index.md) -- [NixOS Configuration Options](/reference/clan.core/index.md) - Additional options avilable on a NixOS machine. +- Learn how to use the [Clan CLI](../reference/cli/index.md) +- Explore available [services](../services/definition.md) +- [NixOS Configuration Options](../reference/clan.core/index.md) - Additional options avilable on a NixOS machine. --- diff --git a/lib/modules/inventoryClass/inventory.nix b/lib/modules/inventoryClass/inventory.nix index 339d8d44c..833de5f1b 100644 --- a/lib/modules/inventoryClass/inventory.nix +++ b/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 diff --git a/pkgs/clan-cli/clan_cli/hyperlink.py b/pkgs/clan-cli/clan_cli/hyperlink.py index f74350c54..5d52210ea 100644 --- a/pkgs/clan-cli/clan_cli/hyperlink.py +++ b/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})"