From 3c56ae1755a757237ce8912164e67127ce0ff7cb Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 20 May 2025 18:30:41 +0200
Subject: [PATCH 1/8] docs: consistent clan-core overview

---
 docs/nix/render_options/__init__.py | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py
index db8b54cae..201b7f431 100644
--- a/docs/nix/render_options/__init__.py
+++ b/docs/nix/render_options/__init__.py
@@ -206,7 +206,12 @@ Some modules are considered 'low-level' or 'expert modules' and are not availabl
 """
 
 
-clan_core_descr = """`clan.core` is always included in each machine `config`.
+clan_core_descr = """
+`clan.core` is always present in a clan machine
+
+* It is a module of class **`nixos`**
+* Provides a set of common options for every machine (in addition to the NixOS options)
+
 Your can customize your machines behavior with the configuration [options](#module-options) provided below.
 """
 
@@ -299,9 +304,13 @@ def produce_clan_core_docs() -> None:
 
         # Prepopulate the index file header
         indexfile = f"{module_name}/index.md"
-        core_outputs[indexfile] = (
-            module_header(module_name) + clan_core_descr + options_head
-        )
+        core_outputs[indexfile] = module_header(module_name) + clan_core_descr
+
+        core_outputs[indexfile] += """!!! info "# Submodules"\n"""
+        for submodule_name, _ in split.items():
+            core_outputs[indexfile] += f"      - {submodule_name}\n"
+
+        core_outputs[indexfile] += options_head
 
         for submodule_name, split_options in split.items():
             outfile = f"{module_name}/{submodule_name}.md"

From 8ad35c1bee78de524166972fd1cfd582978d0cb3 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 20 May 2025 18:33:40 +0200
Subject: [PATCH 2/8] docs: fix clan-core should be called clan.core

Consistent with the module name
---
 docs/nix/render_options/__init__.py                 | 2 +-
 docs/site/guides/getting-started/secrets.md         | 2 +-
 docs/site/guides/migrations/migration-facts-vars.md | 2 +-
 docs/site/guides/vars-backend.md                    | 4 ++--
 docs/site/index.md                                  | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py
index 201b7f431..a96f31b7a 100644
--- a/docs/nix/render_options/__init__.py
+++ b/docs/nix/render_options/__init__.py
@@ -297,7 +297,7 @@ def produce_clan_core_docs() -> None:
     core_outputs: dict[str, str] = {}
     with CLAN_CORE_DOCS.open() as f:
         options: dict[str, dict[str, Any]] = json.load(f)
-        module_name = "clan-core"
+        module_name = "clan.core"
 
         transform = {n.replace("clan.core.", ""): v for n, v in options.items()}
         split = split_options_by_root(transform)
diff --git a/docs/site/guides/getting-started/secrets.md b/docs/site/guides/getting-started/secrets.md
index 55b6b99a0..0fa9bb710 100644
--- a/docs/site/guides/getting-started/secrets.md
+++ b/docs/site/guides/getting-started/secrets.md
@@ -3,7 +3,7 @@ Clan enables encryption of secrets (such as passwords & keys) ensuring security
 
 By default, Clan uses the [sops](https://github.com/getsops/sops) format
 and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
-Clan can also be configured to be used with other secret store [backends](https://docs.clan.lol/reference/clan-core/vars/#clan.core.vars.settings.secretStore).
+Clan can also be configured to be used with other secret store [backends](../../reference/clan.core/vars.md#clan.core.vars.settings.secretStore).
 
 This guide will walk you through:
 
diff --git a/docs/site/guides/migrations/migration-facts-vars.md b/docs/site/guides/migrations/migration-facts-vars.md
index 708b722f4..14e24aad7 100644
--- a/docs/site/guides/migrations/migration-facts-vars.md
+++ b/docs/site/guides/migrations/migration-facts-vars.md
@@ -5,7 +5,7 @@ For a high level overview about `vars` see our [blog post](https://clan.lol/blog
 This guide will help you migrate your modules that still use our [`facts`](../../guides/secrets.md) backend
 to the [`vars`](../../guides/vars-backend.md) backend.
 
-The `vars` [module](../../reference/clan-core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
+The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
 
 ## Keep Existing Values
 
diff --git a/docs/site/guides/vars-backend.md b/docs/site/guides/vars-backend.md
index eae7ff225..fb37bf336 100644
--- a/docs/site/guides/vars-backend.md
+++ b/docs/site/guides/vars-backend.md
@@ -7,7 +7,7 @@ Defining a linux user's password via the nixos configuration previously required
 
 In this example, we will guide you through automating that interaction using clan `vars`.
 
-For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](https://docs.clan.lol/reference/clan-core/vars/)
+For a more general explanation of what clan vars are and how it works, see the intro of the [Reference Documentation for vars](../reference/clan.core/vars.md)
 
 This guide assumes
 - clan is set up already (see [Getting Started](../guides/getting-started/index.md))
@@ -147,5 +147,5 @@ Updated var root-password/password-hash
 
 ## Further Reading
 
-- [Reference Documentation for `clan.core.vars` nixos options](../reference/clan-core/vars.md)
+- [Reference Documentation for `clan.core.vars` nixos options](../reference/clan.core/vars.md)
 - [Reference Documentation for the `clan vars` cli command](../reference/cli/vars.md)
diff --git a/docs/site/index.md b/docs/site/index.md
index 4b20c3d70..9121702e4 100644
--- a/docs/site/index.md
+++ b/docs/site/index.md
@@ -70,7 +70,7 @@ hide:
 
     An overview of available service modules
 
--   [Core](./reference/clan-core/index.md)
+-   [Core](./reference/clan.core/index.md)
 
     ---
 

From d3fc1725f033b188b36317562e0d61500c8d1955 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 20 May 2025 18:34:33 +0200
Subject: [PATCH 3/8] docs: replace outdates reference links to 'guides' in the
 cli

---
 pkgs/clan-cli/clan_cli/__init__.py          | 20 ++++++++++----------
 pkgs/clan-cli/clan_cli/facts/cli.py         |  8 ++++----
 pkgs/clan-cli/clan_cli/machines/cli.py      |  8 ++++----
 pkgs/clan-cli/clan_cli/machines/machines.py |  2 +-
 pkgs/clan-cli/clan_cli/state/__init__.py    |  2 +-
 pkgs/clan-cli/clan_cli/vars/cli.py          |  2 +-
 templates/clan/flake-parts/flake.nix        |  2 +-
 templates/clan/new-clan/flake.nix           |  2 +-
 8 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/pkgs/clan-cli/clan_cli/__init__.py b/pkgs/clan-cli/clan_cli/__init__.py
index b95c5baa1..f70401827 100644
--- a/pkgs/clan-cli/clan_cli/__init__.py
+++ b/pkgs/clan-cli/clan_cli/__init__.py
@@ -119,7 +119,7 @@ def create_parser(prog: str | None = None) -> argparse.ArgumentParser:
         description="The clan cli tool",
         epilog=(
             f"""
-Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli/")}
+Online reference for the clan cli tool: {help_hyperlink("cli reference", "https://docs.clan.lol/reference/cli")}
 For more detailed information, visit: {help_hyperlink("docs", "https://docs.clan.lol")}
         """
         ),
@@ -171,7 +171,7 @@ Examples:
   The backup to restore for the machine [MACHINE] with the configured [PROVIDER]
   with the name [NAME].
 
-For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/getting-started/backups")}.
+For more detailed information visit: {help_hyperlink("backups", "https://docs.clan.lol/guides/backups")}.
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -190,7 +190,7 @@ Examples:
   Will create a new clan flake in the specified directory and create it if it
   doesn't exist yet. The flake will be created from a default template.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/index.html")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -208,7 +208,7 @@ Examples:
   $ clan flash write mymachine --disk main /dev/sd<X> --ssh-pubkey ~/.ssh/id_rsa.pub
   Will flash the machine 'mymachine' to the disk '/dev/sd<X>' with the ssh public key '~/.ssh/id_rsa.pub'.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/getting-started/installer")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/installer")}
             """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -235,7 +235,7 @@ Examples:
   the json string. [JSON] can either be a json formatted string itself, or point
   towards a file containing the deployment information
 
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/deploy")}
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -259,7 +259,7 @@ Examples:
   $ clan secrets get [SECRET]
   Will display the content of the specified secret.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -296,7 +296,7 @@ Examples:
   This is especially useful for resetting certain passwords while leaving the rest
   of the facts for a machine in place.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -334,7 +334,7 @@ Examples:
     This is especially useful for resetting certain passwords while leaving the rest
     of the vars for a machine in place.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -364,7 +364,7 @@ Examples:
   If the `--target-host` flag is omitted will try to find host information by
   checking the deployment configuration inside the specified machine.
 
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/getting-started/deploy")}
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -427,7 +427,7 @@ Examples:
   $ clan state list [MACHINE]
   List state of the machines managed by Clan.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/backups")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/backups")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
diff --git a/pkgs/clan-cli/clan_cli/facts/cli.py b/pkgs/clan-cli/clan_cli/facts/cli.py
index 9009da79d..d8a7447ab 100644
--- a/pkgs/clan-cli/clan_cli/facts/cli.py
+++ b/pkgs/clan-cli/clan_cli/facts/cli.py
@@ -31,7 +31,7 @@ Examples:
   Will check facts for the specified machine.
 
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -61,7 +61,7 @@ Examples:
   Will list facts for the specified machine.
 
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -101,7 +101,7 @@ Examples:
   This is especially useful for resetting certain passwords while leaving the rest
   of the facts for a machine in place.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -125,7 +125,7 @@ Examples:
   $ clan facts upload [MACHINE]
   Will upload secrets to a specific machine.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
diff --git a/pkgs/clan-cli/clan_cli/machines/cli.py b/pkgs/clan-cli/clan_cli/machines/cli.py
index 10d88776e..9ddb53fdf 100644
--- a/pkgs/clan-cli/clan_cli/machines/cli.py
+++ b/pkgs/clan-cli/clan_cli/machines/cli.py
@@ -37,7 +37,7 @@ Examples:
   To exclude machines being updated `clan.deployment.requireExplicitUpdate = true;`
   can be set in the machine config.
 
-For more detailed information, visit: https://docs.clan.lol/getting-started/deploy
+For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -93,7 +93,7 @@ Examples:
   $ clan machines update-hardware-config [MACHINE] [TARGET_HOST]
   Will generate hardware specifics for the the specified `[TARGET_HOST]` and place the result in hardware.nix for the given machine `[MACHINE]`.
 
-For more detailed information, visit: https://docs.clan.lol/getting-started/configure/#machine-configuration
+For more detailed information, visit: https://docs.clan.lol/guides/getting-started/configure/#machine-configuration
 
 """
         ),
@@ -123,8 +123,8 @@ Examples:
   Will install the specified machine [MACHINE] to the host exposed by
   the deployment information of the [JSON] deployment string.
 
-For information on how to set up the installer see: https://docs.clan.lol/getting-started/installer/
-For more detailed information, visit: https://docs.clan.lol/getting-started/deploy
+For information on how to set up the installer see: https://docs.clan.lol/guides/getting-started/installer/
+For more detailed information, visit: https://docs.clan.lol/guides/getting-started/deploy
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
diff --git a/pkgs/clan-cli/clan_cli/machines/machines.py b/pkgs/clan-cli/clan_cli/machines/machines.py
index 71a725f57..fd2fb87bb 100644
--- a/pkgs/clan-cli/clan_cli/machines/machines.py
+++ b/pkgs/clan-cli/clan_cli/machines/machines.py
@@ -93,7 +93,7 @@ class Machine:
             msg = f"'targetHost' is not set for machine '{self.name}'"
             raise ClanError(
                 msg,
-                description="See https://docs.clan.lol/getting-started/deploy/#setting-the-target-host for more information.",
+                description="See https://docs.clan.lol/guides/getting-started/deploy/#setting-the-target-host for more information.",
             )
         return val
 
diff --git a/pkgs/clan-cli/clan_cli/state/__init__.py b/pkgs/clan-cli/clan_cli/state/__init__.py
index c68569013..3ad27b0c0 100644
--- a/pkgs/clan-cli/clan_cli/state/__init__.py
+++ b/pkgs/clan-cli/clan_cli/state/__init__.py
@@ -29,7 +29,7 @@ def register_parser(parser: argparse.ArgumentParser) -> None:
   List state of the machine [MACHINE] managed by Clan.
 
 
-  For more detailed information, visit: https://docs.clan.lol/getting-started/backups/
+  For more detailed information, visit: https://docs.clan.lol/guides/backups
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
diff --git a/pkgs/clan-cli/clan_cli/vars/cli.py b/pkgs/clan-cli/clan_cli/vars/cli.py
index ae0303ea9..91a4bc3ee 100644
--- a/pkgs/clan-cli/clan_cli/vars/cli.py
+++ b/pkgs/clan-cli/clan_cli/vars/cli.py
@@ -197,7 +197,7 @@ Examples:
   $ clan vars upload [MACHINE]
   Will upload secrets to a specific machine.
 
-For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/getting-started/secrets")}
+For more detailed information, visit: {help_hyperlink("secrets", "https://docs.clan.lol/guides/getting-started/secrets")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
diff --git a/templates/clan/flake-parts/flake.nix b/templates/clan/flake-parts/flake.nix
index 60c7982ad..18a1bb00d 100644
--- a/templates/clan/flake-parts/flake.nix
+++ b/templates/clan/flake-parts/flake.nix
@@ -19,7 +19,7 @@
         "aarch64-darwin"
       ];
       imports = [ inputs.clan-core.flakeModules.default ];
-      # https://docs.clan.lol/getting-started/flake-parts/
+      # https://docs.clan.lol/guides/getting-started/flake-parts/
       clan = {
         meta.name = "__CHANGE_ME__"; # Ensure this is unique among all clans you want to use.
 
diff --git a/templates/clan/new-clan/flake.nix b/templates/clan/new-clan/flake.nix
index 74be24c73..3459ee14c 100644
--- a/templates/clan/new-clan/flake.nix
+++ b/templates/clan/new-clan/flake.nix
@@ -14,7 +14,7 @@
         # All machines in ./machines will be imported.
 
         # Prerequisite: boot into the installer.
-        # See: https://docs.clan.lol/getting-started/installer
+        # See: https://docs.clan.lol/guides/getting-started/installer
         # local> mkdir -p ./machines/machine1
         # local> Edit ./machines/<machine>/configuration.nix to your liking.
         machines = {

From b7c6e8917b3bb67d44050d18a576e275c6e4b5e4 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 20 May 2025 18:35:06 +0200
Subject: [PATCH 4/8] docs: replace remote url by local file links to allow for
 checking

---
 pkgs/clan-cli/clan_cli/hyperlink.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/pkgs/clan-cli/clan_cli/hyperlink.py b/pkgs/clan-cli/clan_cli/hyperlink.py
index 1d032e33e..55402a63d 100644
--- a/pkgs/clan-cli/clan_cli/hyperlink.py
+++ b/pkgs/clan-cli/clan_cli/hyperlink.py
@@ -37,4 +37,7 @@ def docs_hyperlink(description: str, url: str) -> str:
     """
     Returns a markdown hyperlink
     """
+    url = url.replace("https://docs.clan.lol", "../..")
+    url = url.replace("index.html", "index")
+    url += ".md"
     return f"[{description}]({url})"

From 7d883893902b65dc71a33ac35c932d6710406db1 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 20 May 2025 18:35:52 +0200
Subject: [PATCH 5/8] Refactor(docs): consistent structure across references

---
 docs/mkdocs.yml | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 919c5fd44..6fdac3cb6 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -81,14 +81,14 @@ nav:
   - Reference:
       - Overview: reference/index.md
       - Clan Services:
-          - reference/clanServices/index.md
+          - Overview: reference/clanServices/index.md
           - reference/clanServices/admin.md
           - reference/clanServices/hello-world.md
           - reference/clanServices/wifi.md
       - Clan Modules:
-          - Overview:
-              - reference/clanModules/index.md
-              - reference/clanModules/frontmatter/index.md
+          - Overview: reference/clanModules/index.md
+          - Frontmatter Format: reference/clanModules/frontmatter/index.md
+          - reference/clanModules/frontmatter/index.md
           # TODO: display the docs of the clan.service modules
           - reference/clanModules/admin.md
           # This is the module overview and should stay at the top
@@ -132,7 +132,7 @@ nav:
           - reference/clanModules/zerotier.md
           - reference/clanModules/zt-tcp-relay.md
       - CLI:
-          - reference/cli/index.md
+          - Overview: reference/cli/index.md
 
           - reference/cli/backups.md
           - reference/cli/facts.md
@@ -146,17 +146,18 @@ nav:
           - reference/cli/state.md
           - reference/cli/vars.md
           - reference/cli/vms.md
-      - Clan Core:
-          - reference/clan-core/index.md
+      - NixOS Modules:
+          - clan.core:
+              - Overview: reference/clan.core/index.md
 
-          - reference/clan-core/backups.md
-          - reference/clan-core/deployment.md
-          - reference/clan-core/facts.md
-          - reference/clan-core/networking.md
-          - reference/clan-core/settings.md
-          - reference/clan-core/sops.md
-          - reference/clan-core/state.md
-          - reference/clan-core/vars.md
+              - reference/clan.core/backups.md
+              - reference/clan.core/deployment.md
+              - reference/clan.core/facts.md
+              - reference/clan.core/networking.md
+              - reference/clan.core/settings.md
+              - reference/clan.core/sops.md
+              - reference/clan.core/state.md
+              - reference/clan.core/vars.md
       - Nix API:
           - buildClan: reference/nix-api/buildclan.md
           - Inventory: reference/nix-api/inventory.md

From d5c3b45404b3120691cc0f920c60a020314cd18e Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 20 May 2025 18:38:48 +0200
Subject: [PATCH 6/8] Fix(docs): rename reference to clan.core

---
 docs/site/reference/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md
index 31c565a25..511ffda9f 100644
--- a/docs/site/reference/index.md
+++ b/docs/site/reference/index.md
@@ -6,7 +6,7 @@ This section of the site provides an overview of available options and commands
 
 - Learn how to use the [Clan CLI](./cli/index.md)
 - Explore available services and application [modules](./clanModules/index.md)
-- Discover [configuration options](./clan-core/index.md) that manage essential features
+- Discover [configuration options](./clan.core/index.md) that manage essential features
 - Find descriptions of the [Nix interfaces](./nix-api/buildclan.md) for defining a Clan
 
 ---

From 464e3c33cffaec47548b61e07428e4edc4a6607f Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 20 May 2025 18:44:04 +0200
Subject: [PATCH 7/8] Docs: add links to submodules

---
 docs/nix/render_options/__init__.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py
index a96f31b7a..ad04b1575 100644
--- a/docs/nix/render_options/__init__.py
+++ b/docs/nix/render_options/__init__.py
@@ -306,9 +306,11 @@ def produce_clan_core_docs() -> None:
         indexfile = f"{module_name}/index.md"
         core_outputs[indexfile] = module_header(module_name) + clan_core_descr
 
-        core_outputs[indexfile] += """!!! info "# Submodules"\n"""
+        core_outputs[indexfile] += """!!! info "Submodules"\n"""
         for submodule_name, _ in split.items():
-            core_outputs[indexfile] += f"      - {submodule_name}\n"
+            core_outputs[indexfile] += (
+                f"      - [{submodule_name}](./{submodule_name}.md)\n"
+            )
 
         core_outputs[indexfile] += options_head
 

From 2ba110d35448dc5fec2fe45f9d968961e1f155df Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Wed, 21 May 2025 09:11:18 +0200
Subject: [PATCH 8/8] docs: exclude options that are not modules from clan.core
 submodule index

---
 docs/nix/render_options/__init__.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py
index ad04b1575..d72322e2a 100644
--- a/docs/nix/render_options/__init__.py
+++ b/docs/nix/render_options/__init__.py
@@ -307,7 +307,13 @@ def produce_clan_core_docs() -> None:
         core_outputs[indexfile] = module_header(module_name) + clan_core_descr
 
         core_outputs[indexfile] += """!!! info "Submodules"\n"""
-        for submodule_name, _ in split.items():
+
+        for submodule_name, split_options in split.items():
+            root = options_to_tree(split_options, debug=True)
+            module = root.suboptions[0]
+            module_type = module.info.get("type")
+            if module_type is not None and "submodule" not in module_type:
+                continue
             core_outputs[indexfile] += (
                 f"      - [{submodule_name}](./{submodule_name}.md)\n"
             )
@@ -328,7 +334,6 @@ def produce_clan_core_docs() -> None:
             print("type", module.info.get("type"))
 
             module_type = module.info.get("type")
-
             if module_type is not None and "submodule" not in module_type:
                 outfile = indexfile
                 init_level = 2