feat(docs): Add links to module docs (#479)

aos · web-flow · commit 95804de6d258 · 2024-08-07T17:36:05.000+02:00
Closes #476 Here's a first pass at linking to the modules. I thought about finding a way to automate this (eg. populating the links directly from the exposed flake modules) but couldn't find a clean solution.
diff --git a/docs/darwin/getting_started.md b/docs/darwin/getting_started.md
@@ -4,8 +4,8 @@
 
 This project exports four big categories of NixOS modules which are useful to define a server configuration:
 
-* Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
-* Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
+* [Machine type](./type.md) - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
+* [Configuration mixins](./mixins.md) - these define addons to be added to the machine configuration. One or more can be added.
 
 ## Example
 
diff --git a/docs/darwin/mixins.md b/docs/darwin/mixins.md
@@ -2,20 +2,20 @@ Config extensions for a given machine.
 
 One or more can be included per Darwin configuration.
 
-### `darwiModules.mixins-telegraf`
+### [`darwinModules.mixins-telegraf`]({{ repo_url }}/blob/main/darwin/mixins/telegraf.nix)
 
 Enables a generic telegraf configuration. `nixosModules.mixins-prometheus` for monitoring rules targeting this telegraf configuration.
 
-### `darwinModules.mixins-terminfo`
+### [`darwinModules.mixins-terminfo`]({{ repo_url }}/blob/main/darwin/mixins/terminfo.nix)
 
 Extends the terminfo database with often used terminal emulators.
 Terminfo is used by terminal applications to interfere supported features in the terminal.
 This is useful when connecting to a server via SSH.
 
-### `darwinModules.mixins-nix-experimental`
+### [`darwinModules.mixins-nix-experimental`]({{ repo_url }}/blob/main/darwin/mixins/nix-experimental.nix)
 
 Enables all experimental features in nix, that are known safe to use (i.e. are only used when explicitly requested in a build).
 
-### `darwinModules.mixins-trusted-nix-caches`
+### [`darwinModules.mixins-trusted-nix-caches`]({{ repo_url }}/blob/main/darwin/mixins/trusted-nix-caches.nix)
 
 Add the common list of public nix binary caches that we trust.
diff --git a/docs/darwin/type.md b/docs/darwin/type.md
@@ -2,7 +2,7 @@ Those high-level modules are used to define the type of machine.
 
 We expect only one of those to be imported per Darwin configuration.
 
-### Common (`darwinModules.common`)
+### Common ([`darwinModules.common`]({{ repo_url }}/blob/main/darwin/common/default.nix))
 
 Use this module if you are unsure if your darwin module will be used on server or desktop.
 
@@ -17,14 +17,14 @@ Use this module if you are unsure if your darwin module will be used on server o
 - Enable sudo for @wheel users.
 - ...
 
-### Server (`darwinModules.server`)
+### Server ([`darwinModules.server`]({{ repo_url }}/blob/main/darwin/server/default.nix))
 
 Use this for headless systems that are remotely managed via ssh.
 
 - Includes everything from common
 - So far nothing else, but this might change over time
 
-### Desktop (`darwinModules.desktop`)
+### Desktop ([`darwinModules.desktop`]({{ repo_url }}/blob/main/darwin/desktop/default.nix))
 
 Despite this project being about servers, we wanted to dogfood the common module.
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -4,6 +4,5 @@ This project is designed to work in combination with the Linux distribution [Nix
 
 In this documentation, we expect the reader to be already familiar with the base operating system, and introduce how to compose it with our own extensions.
 
-For NixOS continue reading [here](nixos/getting_started.md),
-for nix-darwin/macOS read [this](darwin/getting_started.md).
-
+For NixOS continue reading [here](./nixos/getting_started.md),
+for nix-darwin/macOS read [this](./darwin/getting_started.md).
diff --git a/docs/index.md b/docs/index.md
@@ -4,4 +4,4 @@ Welcome!
 
 SrvOS is a collection of NixOS modules that are optimized for servers. They includes many lessons that we gained over the years while deploying servers for our customers. As we like to share, we hope that this project will be useful to you.
 
-To get started, start by reading the [introductory tutorial](getting_started.md), then check the [User Guide](user_guide.md) for more information.
+To get started, start by reading the [introductory tutorial](./getting_started.md), then check the [User Guide](user_guide.md) for more information.
diff --git a/docs/nixos/getting_started.md b/docs/nixos/getting_started.md
@@ -4,10 +4,10 @@
 
 This project exports four big categories of NixOS modules which are useful to define a server configuration:
 
-* Machine type - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
-* Machine hardware - these define hardware-related settings for well known hardware. Only one of those would be included. (eg: AWS EC2 instances).
-* Machine role - theses take over a machine for a specific role. Only one of those would be included. (eg: GitHub Actions runner)
-* Configuration mixins - these define addons to be added to the machine configuration. One or more can be added.
+* [Machine type](./type.md) - these are high-level settings that define the machine type (Eg: common, server or desktop). Only one of those would be included.
+* [Machine hardware](./hardware.md) - these define hardware-related settings for well known hardware. Only one of those would be included. (eg: AWS EC2 instances).
+* [Machine role](./role.md) - theses take over a machine for a specific role. Only one of those would be included. (eg: GitHub Actions runner)
+* [Configuration mixins](./mixins.md) - these define addons to be added to the machine configuration. One or more can be added.
 
 ## Example
 
diff --git a/docs/nixos/hardware.md b/docs/nixos/hardware.md
@@ -4,45 +4,45 @@ We expect only one hardware module to be imported per NixOS configuration.
 
 Here are some of the hardwares that are supported:
 
-### `nixosModules.hardware-amazon`
+### [`nixosModules.hardware-amazon`]({{ repo_url }}/blob/main/nixos/hardware/amazon/default.nix)
 
 Hardware configuration for <https://aws.amazon.com/ec2> instances.
 
 The main difference here is that the default userdata service is replaced by cloud-init.
 
-### `nixosModules.hardware-digitalocean-droplet`
+### [`nixosModules.hardware-digitalocean-droplet`]({{ repo_url }}/blob/main/nixos/hardware/digitalocean/droplet.nix)
 
 Hardware configuration for <https://www.digitalocean.com/> instances.
 
 Enables cloud-init but turns of non-working dhcp.
 
-### `nixosModules.hardware-hetzner-cloud`
+### [`nixosModules.hardware-hetzner-cloud`]({{ repo_url }}/blob/main/nixos/hardware/hetzner-cloud/default.nix)
 
 Hardware configuration for <https://www.hetzner.com/cloud> instances.
 
 The main difference here is that:
 1. cloud-init is enabled.
 2. the qemu agent is running, to allow password reset to function.
 
-### `nixosModules.hardware-hetzner-cloud-arm`
+### [`nixosModules.hardware-hetzner-cloud-arm`]({{ repo_url }}/blob/main/nixos/hardware/hetzner-cloud/arm.nix)
 
 Hardware configuration for <https://www.hetzner.com/cloud> arm instances.
 
 The main difference from `nixosModules.hardware-hetzner-cloud` is using systemd-boot by default.
 
-### `nixosModules.hardware-hetzner-online-amd`
+### [`nixosModules.hardware-hetzner-online-amd`]({{ repo_url }}/blob/main/nixos/hardware/hetzner-online/amd.nix)
 
 Hardware configuration for <https://www.hetzner.com/dedicated-rootserver> bare-metal AMD servers.
 
 Introduces some workaround for the particular IPv6 configuration that Hetzner has.
 
-### `nixosModules.hardware-hetzner-online-intel`
+### [`nixosModules.hardware-hetzner-online-intel`]({{ repo_url }}/blob/main/nixos/hardware/hetzner-online/intel.nix)
 
 Hardware configuration for <https://www.hetzner.com/dedicated-rootserver> bare-metal Intel servers.
 
 Introduces some workaround for the particular IPv6 configuration that Hetzner has.
 
-### `nixosModules.hardware-hetzner-online-ex101`
+### [`nixosModules.hardware-hetzner-online-ex101`]({{ repo_url }}/blob/main/nixos/hardware/hetzner-online/ex101.nix)
 
 Hardware configuration for <https://www.hetzner.com/de/dedicated-rootserver/ex101> bare-metal Intel Core i9-13900 servers.
 
diff --git a/docs/nixos/mixins.md b/docs/nixos/mixins.md
@@ -2,41 +2,41 @@ Config extensions for a given machine.
 
 One or more can be included per NixOS configuration.
 
-### `nixosModules.mixins-cloud-init`
+### [`nixosModules.mixins-cloud-init`]({{ repo_url }}/blob/main/nixos/mixins/cloud-init.nix)
 
 Enables [cloud-init](https://cloud-init.io)
 
-### `nixosModules.mixins-systemd-boot`
+### [`nixosModules.mixins-systemd-boot`]({{ repo_url }}/blob/main/nixos/mixins/systemd-boot.nix)
 
 Configure systemd-boot as bootloader.
 
-### `nixosModules.mixins-telegraf`
+### [`nixosModules.mixins-telegraf`]({{ repo_url }}/blob/main/nixos/mixins/telegraf.nix)
 
 Enables a generic telegraf configuration. `nixosModules.mixins-prometheus` for monitoring rules targeting this telegraf configuration.
 
-### `nixosModules.mixins-terminfo`
+### [`nixosModules.mixins-terminfo`]({{ repo_url }}/blob/main/nixos/mixins/terminfo.nix)
 
 Extends the terminfo database with often used terminal emulators.
 Terminfo is used by terminal applications to interfere supported features in the terminal.
 This is useful when connecting to a server via SSH.
 
-### `nixosModules.mixins-prometheus`
+### [`nixosModules.mixins-prometheus`]({{ repo_url }}/blob/main/nixos/mixins/prometheus.nix)
 
 Enables a Prometheus and configures it with a set of alert rules targeting our `nixosModules.mixins-prometheus` module.
 
-### `nixosModules.mixins-nginx`
+### [`nixosModules.mixins-nginx`]({{ repo_url }}/blob/main/nixos/mixins/nginx.nix)
 
 Configure Nginx with recommended settings. Is quite useful when using nginx as a reverse-proxy on the machine to other services.
 
-### `nixosModules.mixins-nix-experimental`
+### [`nixosModules.mixins-nix-experimental`]({{ repo_url }}/blob/main/nixos/mixins/nix-experimental.nix)
 
 Enables all experimental features in nix, that are known safe to use (i.e. are only used when explicitly requested in a build).
 This for example unlocks use of containers in the nix sandbox.
 
-### `nixosModules.mixins-trusted-nix-caches`
+### [`nixosModules.mixins-trusted-nix-caches`]({{ repo_url }}/blob/main/nixos/mixins/trusted-nix-caches.nix)
 
 Add the common list of public nix binary caches that we trust.
 
-### `nixosModules.mixins-mdns`
+### [`nixosModules.mixins-mdns`]({{ repo_url }}/blob/main/nixos/mixins/mdns.nix)
 
-Enables mDNS support in systemd-networkd. Becomes a no-op if avahi is enabled on the same machine
+Enables mDNS support in systemd-networkd. Becomes a no-op if avahi is enabled on the same machine.
diff --git a/docs/nixos/role.md b/docs/nixos/role.md
@@ -4,10 +4,10 @@ We assume that only one role is assigned per machine.
 
 By making this assumption, we are able to make deeper change to the machine configuration, without having to worry about potential conflicts with other roles.
 
-### GitHub Actions runner (`nixosConfiguration.roles-github-actions-runner`)
+### GitHub Actions runner ([`nixosConfiguration.roles-github-actions-runner`]({{ repo_url }}/blob/main/nixos/roles/github-actions-runner.nix))
 
 Dedicates the machine to becoming a cluster of GitHub Actions runners. 
 
-### Nix Remote builder (`nixosConfiguration.roles-nix-remote-builder`)
+### Nix Remote builder ([`nixosConfiguration.roles-nix-remote-builder`]({{ repo_url }}/blob/main/nixos/roles/nix-remote-builder.nix))
 
-Dedicates the machine to acting as a remote builder for Nix. The main use-case we have is to add more build capacity to the GitHub Actions runners, in a star fashion.
+Dedicates the machine to acting as a remote builder for Nix. The main use-case we have is to add more build capacity to the GitHub Actions runners, in a star fashion.
diff --git a/docs/nixos/type.md b/docs/nixos/type.md
@@ -2,7 +2,7 @@ Those high-level modules are used to define the type of machine.
 
 We expect only one of those to be imported per NixOS configuration.
 
-### Common (`nixosModules.common`)
+### Common ([`nixosModules.common`]({{ repo_url }}/blob/main/nixos/common/default.nix))
 
 Use this module if you are unsure if your nixos module will be used on server or desktop.
 
@@ -17,7 +17,7 @@ Use this module if you are unsure if your nixos module will be used on server or
 - Enable sudo for @wheel users.
 - ...
 
-### Server (`nixosModules.server`)
+### Server ([`nixosModules.server`]({{ repo_url }}/blob/main/nixos/server/default.nix))
 
 Use this for headless systems that are remotely managed via ssh.
 
@@ -29,7 +29,7 @@ Use this for headless systems that are remotely managed via ssh.
 - Sets up sudo without password
 - ...
 
-### Desktop (`nixosModules.desktop`)
+### Desktop ([`nixosModules.desktop`]({{ repo_url }}/blob/main/nixos/desktop/default.nix))
 
 Despite this project being about servers, we wanted to dogfood the common module.
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -6,7 +6,7 @@ site_name: SrvOS
 site_description: NixOS profiles for servers
 site_url: https://nix-community.github.io/srvos/
 repo_name: 'nix-community/srvos'
-repo_url: https://github.com/nix-community/srvos
+repo_url: &repo_url https://github.com/nix-community/srvos
 edit_uri: edit/main/docs
 
 ### Navigation ###
@@ -36,3 +36,8 @@ nav:
         - Configuration mixins: darwin/mixins.md
     - FAQ: faq.md
   - Getting help: help.md
+
+### Extra variables
+
+extra:
+  repo_url: *repo_url

Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,4 @@ Welcome!`
`4`	`4`
`5`	`5`	`SrvOS is a collection of NixOS modules that are optimized for servers. They includes many lessons that we gained over the years while deploying servers for our customers. As we like to share, we hope that this project will be useful to you.`
`6`	`6`
`7`		`-To get started, start by reading the [introductory tutorial](getting_started.md), then check the [User Guide](user_guide.md) for more information.`
	`7`	`+To get started, start by reading the [introductory tutorial](./getting_started.md), then check the [User Guide](user_guide.md) for more information.`