Merge pull request #707 from emilazy/options-markdown-migration

Migrate option documentation to Markdown

33 files changed, 262 insertions, 250 deletions

diff --git a/modules/services/activate-system/default.nix b/modules/services/activate-system/default.nix
index 5d72006..90b7d3c 100644
--- a/modules/services/activate-system/default.nix
+++ b/modules/services/activate-system/default.nix
@@ -13,7 +13,7 @@ in
     services.activate-system.enable = mkOption {
       type = types.bool;
       default = true;
-      description = "Whether to activate system at boot time.";
+      description = lib.mdDoc "Whether to activate system at boot time.";
     };
   };
 
diff --git a/modules/services/autossh.nix b/modules/services/autossh.nix
index 2df74ec..9905d69 100644
--- a/modules/services/autossh.nix
+++ b/modules/services/autossh.nix
@@ -22,18 +22,18 @@ in
             name = mkOption {
               type = types.str;
               example = "socks-peer";
-              description = "Name of the local AutoSSH session";
+              description = lib.mdDoc "Name of the local AutoSSH session";
             };
             user = mkOption {
               type = types.str;
               example = "bill";
-              description = "Name of the user the AutoSSH session should run as";
+              description = lib.mdDoc "Name of the user the AutoSSH session should run as";
             };
             monitoringPort = mkOption {
               type = types.int;
               default = 0;
               example = 20000;
-              description = ''
+              description = lib.mdDoc ''
                 Port to be used by AutoSSH for peer monitoring. Note, that
                 AutoSSH also uses mport+1. Value of 0 disables the keep-alive
                 style monitoring
@@ -42,7 +42,7 @@ in
             extraArguments = mkOption {
               type = types.str;
               example = "-N -D4343 bill@socks.example.net";
-              description = ''
+              description = lib.mdDoc ''
                 Arguments to be passed to AutoSSH and retransmitted to SSH
                 process. Some meaningful options include -N (don't run remote
                 command), -D (open SOCKS proxy on local port), -R (forward
@@ -54,7 +54,7 @@ in
         });
 
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           List of AutoSSH sessions to start as systemd services. Each service is
           named 'autossh-{session.name}'.
         '';
diff --git a/modules/services/buildkite-agents.nix b/modules/services/buildkite-agents.nix
index 7486161..fd29227 100644
--- a/modules/services/buildkite-agents.nix
+++ b/modules/services/buildkite-agents.nix
@@ -98,7 +98,7 @@ let
       preCommands = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Extra commands to run before starting buildkite.
         '';
       };
diff --git a/modules/services/cachix-agent.nix b/modules/services/cachix-agent.nix
index e4d6c03..008dab8 100644
--- a/modules/services/cachix-agent.nix
+++ b/modules/services/cachix-agent.nix
@@ -9,23 +9,23 @@ in {
     enable = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Enable to run Cachix Agent as a system service.
         
-        Read <link xlink:href="https://docs.cachix.org/deploy/">Cachix Deploy</link> documentation for more information.
+        Read [Cachix Deploy](https://docs.cachix.org/deploy/) documentation for more information.
       '';
     };
 
     name = mkOption {
       type = types.str;
       default = config.networking.hostName;
-      description = ''
+      description = lib.mdDoc ''
         Agent name, usually the same as the hostname.
       '';
     };
 
     package = mkOption {
-      description = ''
+      description = lib.mdDoc ''
         Package containing cachix executable.
       '';
       type = types.package;
@@ -36,7 +36,7 @@ in {
     credentialsFile = mkOption {
       type = types.path;
       default = "/etc/cachix-agent.token";
-      description = ''
+      description = lib.mdDoc ''
         Required file that needs to contain CACHIX_AGENT_TOKEN=...
       '';
     };
@@ -44,7 +44,7 @@ in {
     logFile = mkOption {
       type = types.nullOr types.path;
       default = "/var/log/cachix-agent.log";
-      description = "Absolute path to log all stderr and stdout";
+      description = lib.mdDoc "Absolute path to log all stderr and stdout";
     };
   };
 
diff --git a/modules/services/chunkwm.nix b/modules/services/chunkwm.nix
index 3a59270..a5955cc 100644
--- a/modules/services/chunkwm.nix
+++ b/modules/services/chunkwm.nix
@@ -12,51 +12,51 @@ in
     services.chunkwm.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the chunkwm window manager.";
+      description = lib.mdDoc "Whether to enable the chunkwm window manager.";
     };
 
     services.chunkwm.package = mkOption {
       type = types.package;
       example = literalExpression "pkgs.chunkwm";
-      description = "This option specifies the chunkwm package to use.";
+      description = lib.mdDoc "This option specifies the chunkwm package to use.";
     };
 
     services.chunkwm.hotload = mkOption {
       type = types.bool;
       default = true;
-      description = "Whether to enable hotload.";
+      description = lib.mdDoc "Whether to enable hotload.";
     };
 
     services.chunkwm.extraConfig = mkOption {
       type = types.lines;
       default = "";
       example = ''chunkc tiling::rule --owner Emacs --state tile'';
-      description = "Additional commands for <filename>chunkwmrc</filename>.";
+      description = lib.mdDoc "Additional commands for {file}`chunkwmrc`.";
     };
 
     services.chunkwm.plugins.dir = mkOption {
       type = types.path;
       default = "/run/current-system/sw/lib/chunkwm/plugins";
-      description = "Chunkwm Plugins directory.";
+      description = lib.mdDoc "Chunkwm Plugins directory.";
     };
 
     services.chunkwm.plugins.list = mkOption {
       type = types.listOf (types.enum plugins);
       default = plugins;
       example = ["tiling"];
-      description = "Chunkwm Plugins to enable.";
+      description = lib.mdDoc "Chunkwm Plugins to enable.";
     };
 
     services.chunkwm.plugins."border".config = mkOption {
       type = types.lines;
       default = ''chunkc set focused_border_color   0xffc0b18b'';
-      description = "Optional border plugin configuration.";
+      description = lib.mdDoc "Optional border plugin configuration.";
     };
 
     services.chunkwm.plugins."tiling".config = mkOption {
       type = types.lines;
       example = ''chunkc set global_desktop_mode   bsp'';
-      description = "Optional tiling plugin configuration.";
+      description = lib.mdDoc "Optional tiling plugin configuration.";
     };
   };
 
diff --git a/modules/services/dnsmasq.nix b/modules/services/dnsmasq.nix
index 7ea674f..03071db 100644
--- a/modules/services/dnsmasq.nix
+++ b/modules/services/dnsmasq.nix
@@ -12,32 +12,32 @@ in
     services.dnsmasq.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable DNSmasq.";
+      description = lib.mdDoc "Whether to enable DNSmasq.";
     };
 
     services.dnsmasq.package = mkOption {
       type = types.path;
       default = pkgs.dnsmasq;
       defaultText = "pkgs.dnsmasq";
-      description = "This option specifies the dnsmasq package to use.";
+      description = lib.mdDoc "This option specifies the dnsmasq package to use.";
     };
 
     services.dnsmasq.bind = mkOption {
       type = types.str;
       default = "127.0.0.1";
-      description = "This option specifies the interface on which DNSmasq will listen.";
+      description = lib.mdDoc "This option specifies the interface on which DNSmasq will listen.";
     };
 
     services.dnsmasq.port = mkOption {
       type = types.int;
       default = 53;
-      description = "This option specifies port on which DNSmasq will listen.";
+      description = lib.mdDoc "This option specifies port on which DNSmasq will listen.";
     };
 
     services.dnsmasq.addresses = mkOption {
       type = types.attrs;
       default = {};
-      description = "List of domains that will be redirected by the DNSmasq.";
+      description = lib.mdDoc "List of domains that will be redirected by the DNSmasq.";
       example = literalExpression ''
         { localhost = "127.0.0.1"; }
         '';
diff --git a/modules/services/emacs.nix b/modules/services/emacs.nix
index 4b9a3cb..88b5c8a 100644
--- a/modules/services/emacs.nix
+++ b/modules/services/emacs.nix
@@ -12,20 +12,20 @@ in {
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the Emacs Daemon.";
+        description = lib.mdDoc "Whether to enable the Emacs Daemon.";
       };
 
       package = mkOption {
         type = types.path;
         default = pkgs.emacs;
-        description = "This option specifies the emacs package to use.";
+        description = lib.mdDoc "This option specifies the emacs package to use.";
       };
 
       additionalPath = mkOption {
         type = types.listOf types.str;
         default = [ ];
         example = [ "/Users/my_user_name" ];
-        description = ''
+        description = lib.mdDoc ''
           This option specifies additional PATH that the emacs daemon would have.
           Typically if you have binaries in your home directory that is what you would add your home path here.
           One caveat is that there won't be shell variable expansion, so you can't use $HOME for example
@@ -35,7 +35,7 @@ in {
       exec = mkOption {
         type = types.str;
         default = "emacs";
-        description = "Emacs command/binary to execute.";
+        description = lib.mdDoc "Emacs command/binary to execute.";
       };
     };
   };
diff --git a/modules/services/gitlab-runner.nix b/modules/services/gitlab-runner.nix
index b7b50bb..7651ba5 100644
--- a/modules/services/gitlab-runner.nix
+++ b/modules/services/gitlab-runner.nix
@@ -117,19 +117,19 @@ let
 in
 {
   options.services.gitlab-runner = {
-    enable = mkEnableOption "Gitlab Runner";
+    enable = mkEnableOption (lib.mdDoc "Gitlab Runner");
     configFile = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Configuration file for gitlab-runner.
 
-        <option>configFile</option> takes precedence over <option>services</option>.
-        <option>checkInterval</option> and <option>concurrent</option> will be ignored too.
+        {option}`configFile` takes precedence over {option}`services`.
+        {option}`checkInterval` and {option}`concurrent` will be ignored too.
 
-        This option is deprecated, please use <option>services</option> instead.
-        You can use <option>registrationConfigFile</option> and
-        <option>registrationFlags</option>
+        This option is deprecated, please use {option}`services` instead.
+        You can use {option}`registrationConfigFile` and
+        {option}`registrationFlags`
         for settings not covered by this module.
       '';
     };
@@ -137,18 +137,18 @@ in
       type = types.int;
       default = 0;
       example = literalExpression "with lib; (length (attrNames config.services.gitlab-runner.services)) * 3";
-      description = ''
+      description = lib.mdDoc ''
         Defines the interval length, in seconds, between new jobs check.
         The default value is 3;
         if set to 0 or lower, the default value will be used.
-        See <link xlink:href="https://docs.gitlab.com/runner/configuration/advanced-configuration.html#how-check_interval-works">runner documentation</link> for more information.
+        See [runner documentation](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#how-check_interval-works) for more information.
       '';
     };
     concurrent = mkOption {
       type = types.int;
       default = 1;
       example = literalExpression "config.nix.maxJobs";
-      description = ''
+      description = lib.mdDoc ''
         Limits how many jobs globally can be run concurrently.
         The most upper limit of jobs using all defined runners.
         0 does not mean unlimited.
@@ -158,7 +158,7 @@ in
       type = types.nullOr types.str;
       default = null;
       example = "https://public:private@host:port/1";
-      description = ''
+      description = lib.mdDoc ''
         Data Source Name for tracking of all system level errors to Sentry.
       '';
     };
@@ -166,7 +166,7 @@ in
       type = types.nullOr types.str;
       default = null;
       example = "localhost:8080";
-      description = ''
+      description = lib.mdDoc ''
         Address (&lt;host&gt;:&lt;port&gt;) on which the Prometheus metrics HTTP server
         should be listening.
       '';
@@ -178,7 +178,7 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "0.0.0.0:8093";
-            description = ''
+            description = lib.mdDoc ''
               An internal URL to be used for the session server.
             '';
           };
@@ -186,16 +186,16 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "runner-host-name.tld:8093";
-            description = ''
+            description = lib.mdDoc ''
               The URL that the Runner will expose to GitLab to be used
               to access the session server.
-              Fallbacks to <option>listenAddress</option> if not defined.
+              Fallbacks to {option}`listenAddress` if not defined.
             '';
           };
           sessionTimeout = mkOption {
             type = types.int;
             default = 1800;
-            description = ''
+            description = lib.mdDoc ''
               How long in seconds the session can stay active after
               the job completes (which will block the job from finishing).
             '';
@@ -208,16 +208,16 @@ in
           listenAddress = "0.0.0.0:8093";
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         The session server allows the user to interact with jobs
         that the Runner is responsible for. A good example of this is the
-        <link xlink:href="https://docs.gitlab.com/ee/ci/interactive_web_terminal/index.html">interactive web terminal</link>.
+        [interactive web terminal](https://docs.gitlab.com/ee/ci/interactive_web_terminal/index.html).
       '';
     };
     gracefulTermination = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Finish all remaining jobs before stopping.
         If not set gitlab-runner will stop immediatly without waiting
         for jobs to finish, which will lead to failed builds.
@@ -227,7 +227,7 @@ in
       type = types.str;
       default = "infinity";
       example = "5min 20s";
-      description = ''
+      description = lib.mdDoc ''
         Time to wait until a graceful shutdown is turned into a forceful one.
       '';
     };
@@ -236,17 +236,17 @@ in
       default = pkgs.gitlab-runner;
       defaultText = "pkgs.gitlab-runner";
       example = literalExpression "pkgs.gitlab-runner_1_11";
-      description = "Gitlab Runner package to use.";
+      description = lib.mdDoc "Gitlab Runner package to use.";
     };
     extraPackages = mkOption {
       type = types.listOf types.package;
       default = [ ];
-      description = ''
+      description = lib.mdDoc ''
         Extra packages to add to PATH for the gitlab-runner process.
       '';
     };
     services = mkOption {
-      description = "GitLab Runner services.";
+      description = lib.mdDoc "GitLab Runner services.";
       default = { };
       example = literalExpression ''
         {
@@ -328,27 +328,27 @@ in
         options = {
           registrationConfigFile = mkOption {
             type = types.path;
-            description = ''
+            description = lib.mdDoc ''
               Absolute path to a file with environment variables
               used for gitlab-runner registration.
               A list of all supported environment variables can be found in
-              <literal>gitlab-runner register --help</literal>.
+              `gitlab-runner register --help`.
 
               Ones that you probably want to set is
 
-              <literal>CI_SERVER_URL=&lt;CI server URL&gt;</literal>
+              `CI_SERVER_URL=<CI server URL>`
 
-              <literal>REGISTRATION_TOKEN=&lt;registration secret&gt;</literal>
+              `REGISTRATION_TOKEN=<registration secret>`
             '';
           };
           registrationFlags = mkOption {
             type = types.listOf types.str;
             default = [ ];
             example = [ "--docker-helper-image my/gitlab-runner-helper" ];
-            description = ''
+            description = lib.mdDoc ''
               Extra command-line flags passed to
-              <literal>gitlab-runner register</literal>.
-              Execute <literal>gitlab-runner register --help</literal>
+              `gitlab-runner register`.
+              Execute `gitlab-runner register --help`
               for a list of supported flags.
             '';
           };
@@ -356,25 +356,25 @@ in
             type = types.attrsOf types.str;
             default = { };
             example = { NAME = "value"; };
-            description = ''
+            description = lib.mdDoc ''
               Custom environment variables injected to build environment.
-              For secrets you can use <option>registrationConfigFile</option>
-              with <literal>RUNNER_ENV</literal> variable set.
+              For secrets you can use {option}`registrationConfigFile`
+              with `RUNNER_ENV` variable set.
             '';
           };
           executor = mkOption {
             type = types.str;
             default = "docker";
-            description = ''
+            description = lib.mdDoc ''
               Select executor, eg. shell, docker, etc.
-              See <link xlink:href="https://docs.gitlab.com/runner/executors/README.html">runner documentation</link> for more information.
+              See [runner documentation](https://docs.gitlab.com/runner/executors/README.html) for more information.
             '';
           };
           buildsDir = mkOption {
             type = types.nullOr types.path;
             default = null;
             example = "/var/lib/gitlab-runner/builds";
-            description = ''
+            description = lib.mdDoc ''
               Absolute path to a directory where builds will be stored
               in context of selected executor (Locally, Docker, SSH).
             '';
@@ -383,14 +383,14 @@ in
             type = types.nullOr types.str;
             default = null;
             example = "http://gitlab.example.local";
-            description = ''
+            description = lib.mdDoc ''
               Overwrite the URL for the GitLab instance. Used if the Runner can’t connect to GitLab on the URL GitLab exposes itself.
             '';
           };
           dockerImage = mkOption {
             type = types.nullOr types.str;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Docker image to be used.
             '';
           };
@@ -398,7 +398,7 @@ in
             type = types.listOf types.str;
             default = [ ];
             example = [ "/var/run/docker.sock:/var/run/docker.sock" ];
-            description = ''
+            description = lib.mdDoc ''
               Bind-mount a volume and create it
               if it doesn't exist prior to mounting.
             '';
@@ -406,14 +406,14 @@ in
           dockerDisableCache = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Disable all container caching.
             '';
           };
           dockerPrivileged = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Give extended privileges to container.
             '';
           };
@@ -421,7 +421,7 @@ in
             type = types.listOf types.str;
             default = [ ];
             example = [ "other-host:127.0.0.1" ];
-            description = ''
+            description = lib.mdDoc ''
               Add a custom host-to-IP mapping.
             '';
           };
@@ -429,7 +429,7 @@ in
             type = types.listOf types.str;
             default = [ ];
             example = [ "ruby:*" "python:*" "php:*" "my.registry.tld:5000/*:*" ];
-            description = ''
+            description = lib.mdDoc ''
               Whitelist allowed images.
             '';
           };
@@ -437,21 +437,21 @@ in
             type = types.listOf types.str;
             default = [ ];
             example = [ "postgres:9" "redis:*" "mysql:*" ];
-            description = ''
+            description = lib.mdDoc ''
               Whitelist allowed services.
             '';
           };
           preCloneScript = mkOption {
             type = types.nullOr types.path;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Runner-specific command script executed before code is pulled.
             '';
           };
           preBuildScript = mkOption {
             type = types.nullOr types.path;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Runner-specific command script executed after code is pulled,
               just before build executes.
             '';
@@ -459,7 +459,7 @@ in
           postBuildScript = mkOption {
             type = types.nullOr types.path;
             default = null;
-            description = ''
+            description = lib.mdDoc ''
               Runner-specific command script executed after code is pulled
               and just after build executes.
             '';
@@ -467,22 +467,22 @@ in
           tagList = mkOption {
             type = types.listOf types.str;
             default = [ ];
-            description = ''
+            description = lib.mdDoc ''
               Tag list.
             '';
           };
           runUntagged = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               Register to run untagged builds; defaults to
-              <literal>true</literal> when <option>tagList</option> is empty.
+              `true` when {option}`tagList` is empty.
             '';
           };
           limit = mkOption {
             type = types.int;
             default = 0;
-            description = ''
+            description = lib.mdDoc ''
               Limit how many jobs can be handled concurrently by this service.
               0 (default) simply means don't limit.
             '';
@@ -490,14 +490,14 @@ in
           requestConcurrency = mkOption {
             type = types.int;
             default = 0;
-            description = ''
+            description = lib.mdDoc ''
               Limit number of concurrent requests for new jobs from GitLab.
             '';
           };
           maximumTimeout = mkOption {
             type = types.int;
             default = 0;
-            description = ''
+            description = lib.mdDoc ''
               What is the maximum timeout (in seconds) that will be set for
               job when using this Runner. 0 (default) simply means don't limit.
             '';
@@ -505,7 +505,7 @@ in
           protected = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               When set to true Runner will only run on pipelines
               triggered on protected branches.
             '';
@@ -513,9 +513,9 @@ in
           debugTraceDisabled = mkOption {
             type = types.bool;
             default = false;
-            description = ''
+            description = lib.mdDoc ''
               When set to true Runner will disable the possibility of
-              using the <literal>CI_DEBUG_TRACE</literal> feature.
+              using the `CI_DEBUG_TRACE` feature.
             '';
           };
         };
diff --git a/modules/services/hercules-ci-agent/default.nix b/modules/services/hercules-ci-agent/default.nix
index d9fbf37..538e104 100644
--- a/modules/services/hercules-ci-agent/default.nix
+++ b/modules/services/hercules-ci-agent/default.nix
@@ -17,7 +17,7 @@ in
     logFile = mkOption {
       type = types.path;
       default = "/var/log/hercules-ci-agent.log";
-      description = "Stdout and sterr of hercules-ci-agent process.";
+      description = lib.mdDoc "Stdout and sterr of hercules-ci-agent process.";
     };
   };
 
diff --git a/modules/services/ipfs.nix b/modules/services/ipfs.nix
index df1f62e..8087ba4 100644
--- a/modules/services/ipfs.nix
+++ b/modules/services/ipfs.nix
@@ -14,14 +14,14 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the ipfs daemon.";
+        description = lib.mdDoc "Whether to enable the ipfs daemon.";
       };
 
       package = mkOption {
         type = types.path;
         default = pkgs.kubo;
         # defaultText = "pkgs.kubo";
-        description = ''
+        description = lib.mdDoc ''
           The ipfs package to use.
         '';
       };
@@ -30,24 +30,24 @@ in
         type = types.nullOr types.path;
         default = null;
         example =  "/var/tmp/lorri.log";
-        description = ''
+        description = lib.mdDoc ''
           The logfile to use for the ipfs service. Alternatively
-          <command>sudo launchctl debug system/org.nixos.ipfs --stderr</command>
+          {command}`sudo launchctl debug system/org.nixos.ipfs --stderr`
           can be used to stream the logs to a shell after restarting the service with
-          <command>sudo launchctl kickstart -k system/org.nixos.ipfs</command>.
+          {command}`sudo launchctl kickstart -k system/org.nixos.ipfs`.
         '';
       };
 
       ipfsPath = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = "Set the IPFS_PATH environment variable.";
+        description = lib.mdDoc "Set the IPFS_PATH environment variable.";
       };
 
       enableGarbageCollection = mkOption {
         type = types.bool;
         default = false;
-        description = "Passes --enable-gc flag to ipfs daemon.";
+        description = lib.mdDoc "Passes --enable-gc flag to ipfs daemon.";
       };
   };
 
diff --git a/modules/services/karabiner-elements/default.nix b/modules/services/karabiner-elements/default.nix
index 2f415b2..7c0636c 100644
--- a/modules/services/karabiner-elements/default.nix
+++ b/modules/services/karabiner-elements/default.nix
@@ -10,7 +10,7 @@ in
 
 {
   options = {
-    services.karabiner-elements.enable = mkEnableOption "Karabiner-Elements";
+    services.karabiner-elements.enable = mkEnableOption (lib.mdDoc "Karabiner-Elements");
   };
 
   config = mkIf cfg.enable {
diff --git a/modules/services/khd/default.nix b/modules/services/khd/default.nix
index 45a389d..ef16a2b 100644
--- a/modules/services/khd/default.nix
+++ b/modules/services/khd/default.nix
@@ -13,27 +13,27 @@ in
     services.khd.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the khd hotkey daemon.";
+      description = lib.mdDoc "Whether to enable the khd hotkey daemon.";
     };
 
     services.khd.package = mkOption {
       type = types.package;
       default = pkgs.khd;
       defaultText = "pkgs.khd";
-      description = "This option specifies the khd package to use.";
+      description = lib.mdDoc "This option specifies the khd package to use.";
     };
 
     services.khd.khdConfig = mkOption {
       type = types.lines;
       default = "";
       example = "alt + shift - r   :   kwmc quit";
-      description = "Config to use for <filename>khdrc</filename>.";
+      description = lib.mdDoc "Config to use for {file}`khdrc`.";
     };
 
     services.khd.i3Keybindings = mkOption {
       type = types.bool;
       default = false;
-      description = "Wether to configure i3 style keybindings for kwm.";
+      description = lib.mdDoc "Wether to configure i3 style keybindings for kwm.";
     };
   };
 
diff --git a/modules/services/kwm/default.nix b/modules/services/kwm/default.nix
index 1d09e23..c6603b9 100644
--- a/modules/services/kwm/default.nix
+++ b/modules/services/kwm/default.nix
@@ -11,21 +11,21 @@ in
     services.kwm.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the khd window manager.";
+      description = lib.mdDoc "Whether to enable the khd window manager.";
     };
 
     services.kwm.package = mkOption {
       type = types.path;
       default = pkgs.kwm;
       defaultText = "pkgs.kwm";
-      description = "This option specifies the kwm package to use.";
+      description = lib.mdDoc "This option specifies the kwm package to use.";
     };
 
     services.kwm.kwmConfig = mkOption {
       type = types.lines;
       default = "";
       example = ''kwmc rule owner="iTerm2" properties={role="AXDialog"}'';
-      description = "Config to use for <filename>kwmrc</filename>.";
+      description = lib.mdDoc "Config to use for {file}`kwmrc`.";
     };
   };
 
diff --git a/modules/services/lorri.nix b/modules/services/lorri.nix
index f637b9c..246bcfa 100644
--- a/modules/services/lorri.nix
+++ b/modules/services/lorri.nix
@@ -11,18 +11,18 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to enable the lorri service.";
+        description = lib.mdDoc "Whether to enable the lorri service.";
       };
       
       logFile = mkOption {
         type = types.nullOr types.path;
         default = null;
         example =  "/var/tmp/lorri.log";
-        description = ''
+        description = lib.mdDoc ''
           The logfile to use for the lorri service. Alternatively
-          <command>sudo launchctl debug system/org.nixos.lorri --stderr</command>
+          {command}`sudo launchctl debug system/org.nixos.lorri --stderr`
           can be used to stream the logs to a shell after restarting the service with
-          <command>sudo launchctl kickstart -k system/org.nixos.lorri</command>.
+          {command}`sudo launchctl kickstart -k system/org.nixos.lorri`.
         '';
       };
     };
diff --git a/modules/services/mail/offlineimap.nix b/modules/services/mail/offlineimap.nix
index 9d0d4dc..b7913cb 100644
--- a/modules/services/mail/offlineimap.nix
+++ b/modules/services/mail/offlineimap.nix
@@ -7,32 +7,32 @@ let
 in {
 
   options.services.offlineimap = {
-    enable = mkEnableOption "Offlineimap, a software to dispose your mailbox(es) as a local Maildir(s).";
+    enable = mkEnableOption (lib.mdDoc "Offlineimap, a software to dispose your mailbox(es) as a local Maildir(s)");
 
     package = mkOption {
       type = types.package;
       default = pkgs.offlineimap;
       defaultText = "pkgs.offlineimap";
-      description = "Offlineimap derivation to use.";
+      description = lib.mdDoc "Offlineimap derivation to use.";
     };
 
     path = mkOption {
       type = types.listOf types.path;
       default = [];
       example = literalExpression "[ pkgs.pass pkgs.bash pkgs.notmuch ]";
-      description = "List of derivations to put in Offlineimap's path.";
+      description = lib.mdDoc "List of derivations to put in Offlineimap's path.";
     };
 
     startInterval = mkOption {
       type = types.nullOr types.int;
       default = 300;
-      description = "Optional key to start offlineimap services each N seconds";
+      description = lib.mdDoc "Optional key to start offlineimap services each N seconds";
     };
 
     runQuick = mkOption {
       type = types.bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Run only quick synchronizations.
         Ignore any flag updates on IMAP servers. If a flag on the remote IMAP changes, and we have the message locally, it will be left untouched in a quick run.
       '';
@@ -41,7 +41,7 @@ in {
     extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = "Additional text to be appended to <filename>offlineimaprc</filename>.";
+      description = lib.mdDoc "Additional text to be appended to {file}`offlineimaprc`.";
     };
   };
 
diff --git a/modules/services/monitoring/telegraf.nix b/modules/services/monitoring/telegraf.nix
index f40e013..e3d3250 100644
--- a/modules/services/monitoring/telegraf.nix
+++ b/modules/services/monitoring/telegraf.nix
@@ -10,12 +10,12 @@ let
 in {
   options = {
     services.telegraf = {
-      enable = mkEnableOption "telegraf agent";
+      enable = mkEnableOption (lib.mdDoc "telegraf agent");
 
       package = mkOption {
         default = pkgs.telegraf;
         defaultText = lib.literalExpression "pkgs.telegraf";
-        description = "Which telegraf derivation to use";
+        description = lib.mdDoc "Which telegraf derivation to use";
         type = types.package;
       };
 
@@ -23,7 +23,7 @@ in {
         type = types.listOf types.path;
         default = [ ];
         example = [ "/run/keys/telegraf.env" ];
-        description = ''
+        description = lib.mdDoc ''
           File to load as environment file.
           This is useful to avoid putting secrets into the nix store.
         '';
@@ -31,7 +31,7 @@ in {
 
       extraConfig = mkOption {
         default = { };
-        description = "Extra configuration options for telegraf";
+        description = lib.mdDoc "Extra configuration options for telegraf";
         type = settingsFormat.type;
         example = {
           outputs.influxdb = {
@@ -47,7 +47,7 @@ in {
 
       configUrl = mkOption {
         default = null;
-        description = "Url to fetch config from";
+        description = lib.mdDoc "Url to fetch config from";
         type = types.nullOr types.str;
       };
     };
diff --git a/modules/services/mopidy.nix b/modules/services/mopidy.nix
index be3c05e..2fb9a15 100644
--- a/modules/services/mopidy.nix
+++ b/modules/services/mopidy.nix
@@ -11,27 +11,27 @@ in
     services.mopidy.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the Mopidy Daemon.";
+      description = lib.mdDoc "Whether to enable the Mopidy Daemon.";
     };
 
     services.mopidy.package = mkOption {
       type = types.path;
       default = pkgs.mopidy;
       defaultText = "pkgs.mopidy";
-      description = "This option specifies the mopidy package to use.";
+      description = lib.mdDoc "This option specifies the mopidy package to use.";
     };
 
     services.mopidy.mediakeys.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the Mopidy OSX Media Keys support daemon.";
+      description = lib.mdDoc "Whether to enable the Mopidy OSX Media Keys support daemon.";
     };
 
     services.mopidy.mediakeys.package = mkOption {
       type = types.path;
       default = pkgs.pythonPackages.osxmpdkeys;
       defaultText = "pkgs.pythonPackages.osxmpdkeys";
-      description = "This option specifies the mediakeys package to use.";
+      description = lib.mdDoc "This option specifies the mediakeys package to use.";
     };
   };
 
diff --git a/modules/services/netbird.nix b/modules/services/netbird.nix
index 5bc8ebd..ad0bf3e 100644
--- a/modules/services/netbird.nix
+++ b/modules/services/netbird.nix
@@ -5,12 +5,12 @@ let
 in
 {
   options.services.netbird = {
-    enable = mkEnableOption "Netbird daemon";
+    enable = mkEnableOption (lib.mdDoc "Netbird daemon");
     package = mkOption {
       type = types.package;
       default = pkgs.netbird;
       defaultText = literalExpression "pkgs.netbird";
-      description = "The package to use for netbird";
+      description = lib.mdDoc "The package to use for netbird";
     };
   };
   config = mkIf cfg.enable {
diff --git a/modules/services/nextdns/default.nix b/modules/services/nextdns/default.nix
index 2312096..5ea5e75 100644
--- a/modules/services/nextdns/default.nix
+++ b/modules/services/nextdns/default.nix
@@ -13,13 +13,13 @@ in {
         type = types.bool;
         default = false;
         description =
-          "Whether to enable the NextDNS DNS/53 to DoH Proxy service.";
+          lib.mdDoc "Whether to enable the NextDNS DNS/53 to DoH Proxy service.";
       };
       arguments = mkOption {
         type = types.listOf types.str;
         default = [ ];
         example = [ "-config" "10.0.3.0/24=abcdef" ];
-        description = "Additional arguments to be passed to nextdns run.";
+        description = lib.mdDoc "Additional arguments to be passed to nextdns run.";
       };
     };
   };
diff --git a/modules/services/nix-daemon.nix b/modules/services/nix-daemon.nix
index 5e87e51..35476a0 100644
--- a/modules/services/nix-daemon.nix
+++ b/modules/services/nix-daemon.nix
@@ -11,31 +11,31 @@ in
     services.nix-daemon.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the nix-daemon service.";
+      description = lib.mdDoc "Whether to enable the nix-daemon service.";
     };
 
     services.nix-daemon.enableSocketListener = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to make the nix-daemon service socket activated.";
+      description = lib.mdDoc "Whether to make the nix-daemon service socket activated.";
     };
 
     services.nix-daemon.logFile = mkOption {
       type = types.nullOr types.path;
       default = null;
       example = "/var/log/nix-daemon.log";
-      description = ''
+      description = lib.mdDoc ''
         The logfile to use for the nix-daemon service. Alternatively
-        <command>sudo launchctl debug system/org.nixos.nix-daemon --stderr</command>
+        {command}`sudo launchctl debug system/org.nixos.nix-daemon --stderr`
         can be used to stream the logs to a shell after restarting the service with
-        <command>sudo launchctl kickstart -k system/org.nixos.nix-daemon</command>.
+        {command}`sudo launchctl kickstart -k system/org.nixos.nix-daemon`.
       '';
     };
 
     services.nix-daemon.tempDir = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = "The TMPDIR to use for nix-daemon.";
+      description = lib.mdDoc "The TMPDIR to use for nix-daemon.";
     };
   };
 
diff --git a/modules/services/nix-gc/default.nix b/modules/services/nix-gc/default.nix
index fca6803..3ca6610 100644
--- a/modules/services/nix-gc/default.nix
+++ b/modules/services/nix-gc/default.nix
@@ -24,28 +24,28 @@ in
       automatic = mkOption {
         default = false;
         type = types.bool;
-        description = "Automatically run the garbage collector at a specific time.";
+        description = lib.mdDoc "Automatically run the garbage collector at a specific time.";
       };
 
       # Not in NixOS module
       user = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = "User that runs the garbage collector.";
+        description = lib.mdDoc "User that runs the garbage collector.";
       };
 
       interval = mkOption {
         type = types.attrs;
         default = { Hour = 3; Minute = 15; };
-        description = "The time interval at which the garbage collector will run.";
+        description = lib.mdDoc "The time interval at which the garbage collector will run.";
       };
 
       options = mkOption {
         default = "";
         example = "--max-freed $((64 * 1024**3))";
         type = types.str;
-        description = ''
-          Options given to <filename>nix-collect-garbage</filename> when the
+        description = lib.mdDoc ''
+          Options given to {file}`nix-collect-garbage` when the
           garbage collector is run automatically.
         '';
       };
diff --git a/modules/services/ofborg/default.nix b/modules/services/ofborg/default.nix
index 5bc0f9d..6c9bac8 100644
--- a/modules/services/ofborg/default.nix
+++ b/modules/services/ofborg/default.nix
@@ -12,13 +12,13 @@ in
     services.ofborg.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the ofborg builder service.";
+      description = lib.mdDoc "Whether to enable the ofborg builder service.";
     };
 
     services.ofborg.package = mkOption {
       type = types.package;
       example = literalExpression "pkgs.ofborg";
-      description = ''
+      description = lib.mdDoc ''
         This option specifies the ofborg package to use. eg.
 
         (import &lt;ofborg&gt; {}).ofborg.rs
@@ -30,7 +30,7 @@ in
 
     services.ofborg.configFile = mkOption {
       type = types.path;
-      description = ''
+      description = lib.mdDoc ''
         Configuration file to use for ofborg.
 
         WARNING Don't use a path literal or derivation for this,
@@ -41,7 +41,7 @@ in
     services.ofborg.logFile = mkOption {
       type = types.path;
       default = "/var/log/ofborg.log";
-      description = "Whether to enable the khd window manager.";
+      description = lib.mdDoc "Whether to enable the khd window manager.";
     };
   };
 
diff --git a/modules/services/postgresql/default.nix b/modules/services/postgresql/default.nix
index bcaf95e..018b46e 100644
--- a/modules/services/postgresql/default.nix
+++ b/modules/services/postgresql/default.nix
@@ -40,12 +40,12 @@ in
 
     services.postgresql = {
 
-      enable = mkEnableOption "PostgreSQL Server";
+      enable = mkEnableOption (lib.mdDoc "PostgreSQL Server");
 
       package = mkOption {
         type = types.package;
         example = literalExpression "pkgs.postgresql_11";
-        description = ''
+        description = lib.mdDoc ''
           PostgreSQL package to use.
         '';
       };
@@ -53,7 +53,7 @@ in
       port = mkOption {
         type = types.int;
         default = 5432;
-        description = ''
+        description = lib.mdDoc ''
           The port on which PostgreSQL listens.
         '';
       };
@@ -61,14 +61,14 @@ in
       checkConfig = mkOption {
         type = types.bool;
         default = true;
-        description = "Check the syntax of the configuration file at compile time";
+        description = lib.mdDoc "Check the syntax of the configuration file at compile time";
       };
 
       dataDir = mkOption {
         type = types.path;
         defaultText = literalExpression ''"/var/lib/postgresql/''${config.services.postgresql.package.psqlSchema}"'';
         example = "/var/lib/postgresql/11";
-        description = ''
+        description = lib.mdDoc ''
           The data directory for PostgreSQL. If left as the default value
           this directory will automatically be created before the PostgreSQL server starts, otherwise
           the sysadmin is responsible for ensuring the directory exists with appropriate ownership
@@ -79,16 +79,16 @@ in
       authentication = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Defines how users authenticate themselves to the server. See the
-          <link xlink:href="https://www.postgresql.org/docs/current/auth-pg-hba-conf.html">
-          PostgreSQL documentation for pg_hba.conf</link>
+          [
+          PostgreSQL documentation for pg_hba.conf](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)
           for details on the expected format of this option. By default,
           peer based authentication will be used for users connecting
           via the Unix socket, and md5 password authentication will be
           used for users connecting via TCP. Any added rules will be
           inserted above the default rules. If you'd like to replace the
-          default rules entirely, you can use <function>lib.mkForce</function> in your
+          default rules entirely, you can use `lib.mkForce` in your
           module.
         '';
       };
@@ -96,7 +96,7 @@ in
       identMap = mkOption {
         type = types.lines;
         default = "";
-        description = ''
+        description = lib.mdDoc ''
           Defines the mapping from system users to database users.
 
           The general form is:
@@ -109,8 +109,8 @@ in
         type = with types; listOf str;
         default = [];
         example = [ "--data-checksums" "--allow-group-access" ];
-        description = ''
-          Additional arguments passed to <literal>initdb</literal> during data dir
+        description = lib.mdDoc ''
+          Additional arguments passed to `initdb` during data dir
           initialisation.
         '';
       };
@@ -118,7 +118,7 @@ in
       initialScript = mkOption {
         type = types.nullOr types.path;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           A file containing SQL statements to execute on first startup.
         '';
       };
@@ -126,7 +126,7 @@ in
       ensureDatabases = mkOption {
         type = types.listOf types.str;
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           Ensures that the specified databases exist.
           This option will never delete existing databases, especially not when the value of this
           option is changed. This means that databases created once through this option or
@@ -143,14 +143,14 @@ in
           options = {
             name = mkOption {
               type = types.str;
-              description = ''
+              description = lib.mdDoc ''
                 Name of the user to ensure.
               '';
             };
             ensurePermissions = mkOption {
               type = types.attrsOf types.str;
               default = {};
-              description = ''
+              description = lib.mdDoc ''
                 Permissions to ensure for the user, specified as an attribute set.
                 The attribute names specify the database and tables to grant the permissions for.
                 The attribute values specify the permissions to grant. You may specify one or
@@ -158,8 +158,8 @@ in
 
                 For more information on how to specify the target
                 and on which privileges exist, see the
-                <link xlink:href="https://www.postgresql.org/docs/current/sql-grant.html">GRANT syntax</link>.
-                The attributes are used as <code>GRANT ''${attrValue} ON ''${attrName}</code>.
+                [GRANT syntax](https://www.postgresql.org/docs/current/sql-grant.html).
+                The attributes are used as `GRANT ''${attrValue} ON ''${attrName}`.
               '';
               example = literalExpression ''
                 {
@@ -171,7 +171,7 @@ in
           };
         });
         default = [];
-        description = ''
+        description = lib.mdDoc ''
           Ensures that the specified users exist and have at least the ensured permissions.
           The PostgreSQL users will be identified using peer authentication. This authenticates the Unix user with the
           same name only, and that without the need for a password.
@@ -200,7 +200,7 @@ in
       enableTCPIP = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether PostgreSQL should listen on all network interfaces.
           If disabled, the database can only be accessed via its Unix
           domain socket or via TCP connections to localhost.
@@ -211,9 +211,9 @@ in
         type = types.str;
         default = "[%p] ";
         example = "%m [%p] ";
-        description = ''
+        description = lib.mdDoc ''
           A printf-style string that is output at the beginning of each log line.
-          Upstream default is <literal>'%m [%p] '</literal>, i.e. it includes the timestamp. We do
+          Upstream default is `'%m [%p] '`, i.e. it includes the timestamp. We do
           not include the timestamp, because journal has it anyway.
         '';
       };
@@ -222,24 +222,26 @@ in
         type = types.listOf types.path;
         default = [];
         example = literalExpression "with pkgs.postgresql_11.pkgs; [ postgis pg_repack ]";
-        description = ''
+        description = lib.mdDoc ''
           List of PostgreSQL plugins. PostgreSQL version for each plugin should
-          match version for <literal>services.postgresql.package</literal> value.
+          match version for `services.postgresql.package` value.
         '';
       };
 
       settings = mkOption {
         type = with types; attrsOf (oneOf [ bool float int str ]);
         default = {};
-        description = ''
+        description = lib.mdDoc ''
           PostgreSQL configuration. Refer to
-          <link xlink:href="https://www.postgresql.org/docs/11/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE"/>
-          for an overview of <literal>postgresql.conf</literal>.
-
-          <note><para>
-            String values will automatically be enclosed in single quotes. Single quotes will be
-            escaped with two single quotes as described by the upstream documentation linked above.
-          </para></note>
+          <https://www.postgresql.org/docs/11/config-setting.html#CONFIG-SETTING-CONFIGURATION-FILE>
+          for an overview of `postgresql.conf`.
+
+          ::: {.note}
+          
+          String values will automatically be enclosed in single quotes. Single quotes will be
+          escaped with two single quotes as described by the upstream documentation linked above.
+          
+          :::
         '';
         example = literalExpression ''
           {
@@ -255,8 +257,8 @@ in
       recoveryConfig = mkOption {
         type = types.nullOr types.lines;
         default = null;
-        description = ''
-          Contents of the <filename>recovery.conf</filename> file.
+        description = lib.mdDoc ''
+          Contents of the {file}`recovery.conf` file.
         '';
       };
 
@@ -265,7 +267,7 @@ in
         default = "postgres";
         internal = true;
         readOnly = true;
-        description = ''
+        description = lib.mdDoc ''
           PostgreSQL superuser account to use for various operations. Internal since changing
           this value would lead to breakage while setting up databases.
         '';
diff --git a/modules/services/privoxy/default.nix b/modules/services/privoxy/default.nix
index b314723..5f7780c 100644
--- a/modules/services/privoxy/default.nix
+++ b/modules/services/privoxy/default.nix
@@ -10,40 +10,40 @@ in
     services.privoxy.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the privoxy proxy service.";
+      description = lib.mdDoc "Whether to enable the privoxy proxy service.";
     };
 
     services.privoxy.listenAddress = mkOption {
       type = types.str;
       default = "127.0.0.1:8118";
-      description = "The address and TCP port on which privoxy will listen.";
+      description = lib.mdDoc "The address and TCP port on which privoxy will listen.";
     };
 
     services.privoxy.package = mkOption {
       type = types.package;
       default = pkgs.privoxy;
       example = literalExpression "pkgs.privoxy";
-      description = "This option specifies the privoxy package to use.";
+      description = lib.mdDoc "This option specifies the privoxy package to use.";
     };
 
     services.privoxy.config = mkOption {
       type = types.lines;
       default = "";
       example = "forward / upstream.proxy:8080";
-      description = "Config to use for privoxy";
+      description = lib.mdDoc "Config to use for privoxy";
     };
 
     services.privoxy.templdir = mkOption {
       type = types.path;
       default = "${pkgs.privoxy}/etc/templates";
       defaultText = "\${pkgs.privoxy}/etc/templates";
-      description = "Directory for privoxy template files.";
+      description = lib.mdDoc "Directory for privoxy template files.";
     };
 
     services.privoxy.confdir = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = "Directory for privoxy files such as .action and .filter.";
+      description = lib.mdDoc "Directory for privoxy files such as .action and .filter.";
     };
   };
 
diff --git a/modules/services/redis/default.nix b/modules/services/redis/default.nix
index c6d434f..0fa0af7 100644
--- a/modules/services/redis/default.nix
+++ b/modules/services/redis/default.nix
@@ -11,52 +11,52 @@ in
     services.redis.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the redis database service.";
+      description = lib.mdDoc "Whether to enable the redis database service.";
     };
 
     services.redis.package = mkOption {
       type = types.path;
       default = pkgs.redis;
       defaultText = "pkgs.redis";
-      description = "This option specifies the redis package to use";
+      description = lib.mdDoc "This option specifies the redis package to use";
     };
 
     services.redis.dataDir = mkOption {
       type = types.nullOr types.path;
       default = "/var/lib/redis";
-      description = "Data directory for the redis database.";
+      description = lib.mdDoc "Data directory for the redis database.";
     };
 
     services.redis.port = mkOption {
       type = types.int;
       default = 6379;
-      description = "The port for Redis to listen to.";
+      description = lib.mdDoc "The port for Redis to listen to.";
     };
 
     services.redis.bind = mkOption {
       type = types.nullOr types.str;
       default = null; # All interfaces
-      description = "The IP interface to bind to.";
+      description = lib.mdDoc "The IP interface to bind to.";
       example = "127.0.0.1";
     };
 
     services.redis.unixSocket = mkOption {
       type = types.nullOr types.path;
       default = null;
-      description = "The path to the socket to bind to.";
+      description = lib.mdDoc "The path to the socket to bind to.";
       example = "/var/run/redis.sock";
     };
 
     services.redis.appendOnly = mkOption {
       type = types.bool;
       default = false;
-      description = "By default data is only periodically persisted to disk, enable this option to use an append-only file for improved persistence.";
+      description = lib.mdDoc "By default data is only periodically persisted to disk, enable this option to use an append-only file for improved persistence.";
     };
 
     services.redis.extraConfig = mkOption {
       type = types.lines;
       default = "";
-      description = "Additional text to be appended to <filename>redis.conf</filename>.";
+      description = lib.mdDoc "Additional text to be appended to {file}`redis.conf`.";
     };
   };
 
diff --git a/modules/services/skhd/default.nix b/modules/services/skhd/default.nix
index fed31f0..4ec1e2b 100644
--- a/modules/services/skhd/default.nix
+++ b/modules/services/skhd/default.nix
@@ -11,20 +11,20 @@ in
     services.skhd.enable = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable the skhd hotkey daemon.";
+      description = lib.mdDoc "Whether to enable the skhd hotkey daemon.";
     };
 
     services.skhd.package = mkOption {
       type = types.package;
       default = pkgs.skhd;
-      description = "This option specifies the skhd package to use.";
+      description = lib.mdDoc "This option specifies the skhd package to use.";
     };
 
     services.skhd.skhdConfig = mkOption {
       type = types.lines;
       default = "";
       example = "alt + shift - r   :   chunkc quit";
-      description = "Config to use for <filename>skhdrc</filename>.";
+      description = lib.mdDoc "Config to use for {file}`skhdrc`.";
     };
   };
 
diff --git a/modules/services/spacebar/default.nix b/modules/services/spacebar/default.nix
index a56dac5..eb06cad 100644
--- a/modules/services/spacebar/default.nix
+++ b/modules/services/spacebar/default.nix
@@ -22,12 +22,12 @@ in
     services.spacebar.enable = mkOption {
       type = bool;
       default = false;
-      description = "Whether to enable the spacebar spacebar.";
+      description = lib.mdDoc "Whether to enable the spacebar spacebar.";
     };
 
     services.spacebar.package = mkOption {
       type = path;
-      description = "The spacebar package to use.";
+      description = lib.mdDoc "The spacebar package to use.";
     };
 
     services.spacebar.config = mkOption {
@@ -40,7 +40,7 @@ in
           foreground_color = "0xffa8a8a8";
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Key/Value pairs to pass to spacebar's 'config' domain, via the configuration file.
       '';
     };
@@ -51,7 +51,7 @@ in
       example = literalExpression ''
         echo "spacebar config loaded..."
       '';
-      description = ''
+      description = lib.mdDoc ''
         Extra arbitrary configuration to append to the configuration file.
       '';
     };
diff --git a/modules/services/spotifyd.nix b/modules/services/spotifyd.nix
index 461d4df..2469a24 100644
--- a/modules/services/spotifyd.nix
+++ b/modules/services/spotifyd.nix
@@ -19,7 +19,7 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = ''
+        description = lib.mdDoc ''
           Whether to enable the spotifyd service.
         '';
       };
@@ -28,7 +28,7 @@ in
         type = types.path;
         default = pkgs.spotifyd;
         defaultText = "pkgs.spotifyd";
-        description = ''
+        description = lib.mdDoc ''
           The spotifyd package to use.
         '';
       };
@@ -40,8 +40,8 @@ in
           bitrate = 160;
           volume_normalisation = true;
         };
-        description = ''
-          Configuration for spotifyd, see <link xlink:href="https://spotifyd.github.io/spotifyd/config/File.html" />
+        description = lib.mdDoc ''
+          Configuration for spotifyd, see <https://spotifyd.github.io/spotifyd/config/File.html>
           for supported values.
         '';
       };
diff --git a/modules/services/synapse-bt.nix b/modules/services/synapse-bt.nix
index d85a2cd..3970cac 100644
--- a/modules/services/synapse-bt.nix
+++ b/modules/services/synapse-bt.nix
@@ -26,32 +26,32 @@ in
       enable = mkOption {
         type = types.bool;
         default = false;
-        description = "Whether to run Synapse BitTorrent Daemon.";
+        description = lib.mdDoc "Whether to run Synapse BitTorrent Daemon.";
       };
 
       package = mkOption {
         type = types.package;
         default = pkgs.synapse-bt;
         defaultText = "pkgs.synapse-bt";
-        description = "Synapse BitTorrent package to use.";
+        description = lib.mdDoc "Synapse BitTorrent package to use.";
       };
 
       port = mkOption {
         type = types.int;
         default = 16384;
-        description = "The port on which Synapse BitTorrent listens.";
+        description = lib.mdDoc "The port on which Synapse BitTorrent listens.";
       };
 
       downloadDir = mkOption {
         type = types.path;
         default = "/var/lib/synapse-bt";
         example = "/var/lib/synapse-bt/downloads";
-        description = "Download directory for Synapse BitTorrent.";
+        description = lib.mdDoc "Download directory for Synapse BitTorrent.";
       };
 
       extraConfig = mkOption {
         default = {};
-        description = "Extra configuration options for Synapse BitTorrent.";
+        description = lib.mdDoc "Extra configuration options for Synapse BitTorrent.";
         type = types.attrs;
       };
     };
diff --git a/modules/services/synergy/default.nix b/modules/services/synergy/default.nix
index f7503da..95daf37 100644
--- a/modules/services/synergy/default.nix
+++ b/modules/services/synergy/default.nix
@@ -16,28 +16,28 @@ in
         default = pkgs.synergy;
         defaultText = "pkgs.synergy";
         type = types.package;
-        description = "The package used for the synergy client and server.";
+        description = lib.mdDoc "The package used for the synergy client and server.";
       };
 
       client = {
         enable = mkOption {
           default = false;
           type = types.bool;
-          description = "
+          description = lib.mdDoc ''
             Whether to enable the Synergy client (receive keyboard and mouse events from a Synergy server).
-          ";
+          '';
         };
         screenName = mkOption {
           default = "";
           type = types.str;
-          description = ''
+          description = lib.mdDoc ''
             Use the given name instead of the hostname to identify
             ourselves to the server.
           '';
         };
         serverAddress = mkOption {
           type = types.str;
-          description = ''
+          description = lib.mdDoc ''
             The server address is of the form: [hostname][:port].  The
             hostname must be the address or hostname of the server.  The
             port overrides the default port, 24800.
@@ -46,21 +46,21 @@ in
         autoStart = mkOption {
           default = true;
           type = types.bool;
-          description = "Whether the Synergy client should be started automatically.";
+          description = lib.mdDoc "Whether the Synergy client should be started automatically.";
         };
         tls = {
-          enable = mkEnableOption ''
+          enable = mkEnableOption (lib.mdDoc ''
             Whether TLS encryption should be used.
 
             Using this requires a TLS certificate that can be
             generated by starting the Synergy GUI once and entering
             a valid product key.
-          '';
+          '');
           cert = mkOption {
             type = types.nullOr types.str;
             default = null;
             example = "~/.synergy/SSL/Synergy.pem";
-            description = "The TLS certificate to use for encryption.";
+            description = lib.mdDoc "The TLS certificate to use for encryption.";
           };
         };
       };
@@ -69,19 +69,19 @@ in
         enable = mkOption {
           default = false;
           type = types.bool;
-          description = ''
+          description = lib.mdDoc ''
             Whether to enable the Synergy server (send keyboard and mouse events).
           '';
         };
         configFile = mkOption {
           default = "/etc/synergy-server.conf";
           type = types.str;
-          description = "The Synergy server configuration file.";
+          description = lib.mdDoc "The Synergy server configuration file.";
         };
         screenName = mkOption {
           default = "";
           type = types.str;
-          description = ''
+          description = lib.mdDoc ''
             Use the given name instead of the hostname to identify
             this screen in the configuration.
           '';
@@ -89,26 +89,26 @@ in
         address = mkOption {
           default = "";
           type = types.str;
-          description = "Address on which to listen for clients.";
+          description = lib.mdDoc "Address on which to listen for clients.";
         };
         autoStart = mkOption {
           default = true;
           type = types.bool;
-          description = "Whether the Synergy server should be started automatically.";
+          description = lib.mdDoc "Whether the Synergy server should be started automatically.";
         };
         tls = {
-          enable = mkEnableOption ''
+          enable = mkEnableOption (lib.mdDoc ''
             Whether TLS encryption should be used.
 
             Using this requires a TLS certificate that can be
             generated by starting the Synergy GUI once and entering
             a valid product key.
-          '';
+          '');
           cert = mkOption {
             type = types.nullOr types.str;
             default = null;
             example = "~/.synergy/SSL/Synergy.pem";
-            description = "The TLS certificate to use for encryption.";
+            description = lib.mdDoc "The TLS certificate to use for encryption.";
           };
         };
       };
diff --git a/modules/services/tailscale.nix b/modules/services/tailscale.nix
index 6e1a86d..da319eb 100644
--- a/modules/services/tailscale.nix
+++ b/modules/services/tailscale.nix
@@ -11,20 +11,25 @@ in
     domain = mkOption {
       type = types.str;
       default = "";
-      description = "The Tailscale domain. This is displayed at the top left of https://login.tailscale.com/admin, next to the Tailscale logo.";
+      description = lib.mdDoc "The Tailscale domain. This is displayed at the top left of https://login.tailscale.com/admin, next to the Tailscale logo.";
     };
 
-    enable = mkEnableOption "Tailscale client daemon";
+    enable = mkEnableOption (lib.mdDoc "Tailscale client daemon");
 
     package = mkOption {
       type = types.package;
       default = pkgs.tailscale;
       defaultText = literalExpression "pkgs.tailscale";
-      description = "The package to use for tailscale";
+      description = lib.mdDoc "The package to use for tailscale";
     };
 
     magicDNS = {
-      enable = mkEnableOption "Whether to configure networking to work with Tailscale's MagicDNS.";
+      enable = mkOption {
+        type = types.bool;
+        default = false;
+        example = true;
+        description = lib.mdDoc "Whether to configure networking to work with Tailscale's MagicDNS.";
+      };
     };
   };
 
diff --git a/modules/services/wg-quick.nix b/modules/services/wg-quick.nix
index 787b663..1e0b865 100644
--- a/modules/services/wg-quick.nix
+++ b/modules/services/wg-quick.nix
@@ -10,31 +10,32 @@ let
       allowedIPs = mkOption {
         type = types.listOf types.str;
         default = [ ];
-        description = "List of IP addresses associated with this peer.";
+        description = lib.mdDoc "List of IP addresses associated with this peer.";
       };
 
       endpoint = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = "IP and port to connect to this peer at.";
+        description = lib.mdDoc "IP and port to connect to this peer at.";
       };
 
       persistentKeepalive = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = "Interval in seconds to send keepalive packets";
+        description = lib.mdDoc "Interval in seconds to send keepalive packets";
       };
 
       presharedKeyFile = mkOption {
         type = types.nullOr types.str;
         default = null;
         description =
-          "Optional, path to file containing the pre-shared key for this peer.";
+          lib.mdDoc "Optional, path to file containing the pre-shared key for this peer.";
       };
 
       publicKey = mkOption {
         default = null;
         type = types.str;
+        description = lib.mdDoc "The public key for this peer.";
       };
     };
   };
@@ -44,76 +45,80 @@ let
       address = mkOption {
         type = types.nullOr (types.listOf types.str);
         default = [ ];
-        description = "List of IP addresses for this interface.";
+        description = lib.mdDoc "List of IP addresses for this interface.";
       };
 
       autostart = mkOption {
         type = types.bool;
         default = true;
         description =
-          "Whether to bring up this interface automatically during boot.";
+          lib.mdDoc "Whether to bring up this interface automatically during boot.";
       };
 
       dns = mkOption {
         type = types.listOf types.str;
         default = [ ];
-        description = "List of DNS servers for this interface.";
+        description = lib.mdDoc "List of DNS servers for this interface.";
       };
 
       listenPort = mkOption {
         type = types.nullOr types.int;
         default = null;
-        description = "Port to listen on, randomly selected if not specified.";
+        description = lib.mdDoc "Port to listen on, randomly selected if not specified.";
       };
 
       mtu = mkOption {
         type = types.nullOr types.int;
         default = null;
         description =
-          "MTU to set for this interface, automatically set if not specified";
+          lib.mdDoc "MTU to set for this interface, automatically set if not specified";
       };
 
       peers = mkOption {
         type = types.listOf (types.submodule peerOpts);
         default = [ ];
-        description = "List of peers associated with this interface.";
+        description = lib.mdDoc "List of peers associated with this interface.";
       };
 
       preDown = mkOption {
         type = with types; coercedTo (listOf str) (concatStringsSep "\n") lines;
         default = "";
-        description = "List of commadns to run before interface shutdown.";
+        description = lib.mdDoc "List of commadns to run before interface shutdown.";
       };
 
       preUp = mkOption {
         type = with types; coercedTo (listOf str) (concatStringsSep "\n") lines;
         default = "";
-        description = "List of commands to run before interface setup.";
+        description = lib.mdDoc "List of commands to run before interface setup.";
       };
 
       postDown = mkOption {
         type = with types; coercedTo (listOf str) (concatStringsSep "\n") lines;
         default = "";
-        description = "List of commands to run after interface shutdown";
+        description = lib.mdDoc "List of commands to run after interface shutdown";
       };
 
       postUp = mkOption {
         type = with types; coercedTo (listOf str) (concatStringsSep "\n") lines;
         default = "";
-        description = "List of commands to run after interface setup.";
+        description = lib.mdDoc "List of commands to run after interface setup.";
       };
 
       privateKeyFile = mkOption {
         type = types.str;
         default = null;
-        description = "Path to file containing this interface's private key.";
+        description = lib.mdDoc "Path to file containing this interface's private key.";
       };
 
       table = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description =
-          "Controls the routing table to which routes are added. There are two special values:  `off' disables  the  creation  of routes altogether, and `auto' (the default) adds routes to the default table and enables special handling of default routes.";
+        description = lib.mdDoc ''
+          Controls the routing table to which routes are added. There are two
+          special values: `off` disables the creation of routes altogether,
+          and `auto` (the default) adds routes to the default table and
+          enables special handling of default routes.
+        '';
       };
     };
   };
@@ -203,13 +208,13 @@ in {
       interfaces = mkOption {
         type = types.attrsOf (types.submodule interfaceOpts);
         default = { };
-        description = "Set of wg-quick interfaces.";
+        description = lib.mdDoc "Set of wg-quick interfaces.";
       };
 
       logDir = mkOption {
         type = types.str;
         default = "/var/log";
-        description = "Directory to save wg-quick logs to.";
+        description = lib.mdDoc "Directory to save wg-quick logs to.";
       };
     };
   };
diff --git a/modules/services/yabai/default.nix b/modules/services/yabai/default.nix
index e40b416..06ef289 100644
--- a/modules/services/yabai/default.nix
+++ b/modules/services/yabai/default.nix
@@ -22,19 +22,19 @@ in
     services.yabai.enable = mkOption {
       type = bool;
       default = false;
-      description = "Whether to enable the yabai window manager.";
+      description = lib.mdDoc "Whether to enable the yabai window manager.";
     };
 
     services.yabai.package = mkOption {
       type = path;
       default = pkgs.yabai;
-      description = "The yabai package to use.";
+      description = lib.mdDoc "The yabai package to use.";
     };
 
     services.yabai.enableScriptingAddition = mkOption {
       type = bool;
       default = false;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable yabai's scripting-addition.
         SIP must be disabled for this to work.
       '';
@@ -56,7 +56,7 @@ in
           window_gap          = 10;
         }
       '';
-      description = ''
+      description = lib.mdDoc ''
         Key/Value pairs to pass to yabai's 'config' domain, via the configuration file.
       '';
     };
@@ -67,7 +67,7 @@ in
       example = literalExpression ''
         yabai -m rule --add app='System Preferences' manage=off
       '';
-      description = "Extra arbitrary configuration to append to the configuration file";
+      description = lib.mdDoc "Extra arbitrary configuration to append to the configuration file";
     };
   };