diff --git a/modules/misc/debug.nix b/modules/misc/debug.nix
index d27d496b4..7e4cf2a0e 100644
--- a/modules/misc/debug.nix
+++ b/modules/misc/debug.nix
@@ -4,12 +4,12 @@ with lib;
 
 {
   options.home = {
-    enableDebugInfo = mkEnableOption "" // {
-      description = ''
-        Some Nix-packages provide debug symbols for
-        <command>gdb</command> in the <literal>debug</literal>-output.
+    enableDebugInfo = mkEnableOption (lib.mdDoc "") // {
+      description = lib.mdDoc ''
+        Some Nix packages provide debug symbols for
+        {command}`gdb` in the `debug` output.
         This option ensures that those are automatically fetched from
-        the binary cache if available and <command>gdb</command> is
+        the binary cache if available and {command}`gdb` is
         configured to find those symbols.
       '';
     };
diff --git a/modules/misc/vte.nix b/modules/misc/vte.nix
index fbe38c016..0d828fb71 100644
--- a/modules/misc/vte.nix
+++ b/modules/misc/vte.nix
@@ -6,15 +6,19 @@ with lib;
   meta.maintainers = [ maintainers.rycee ];
 
   options.programs = let
-    description = ''
+    description = lib.mdDoc ''
       Whether to enable integration with terminals using the VTE
       library. This will let the terminal track the current working
       directory.
     '';
   in {
-    bash.enableVteIntegration = mkEnableOption "" // { inherit description; };
+    bash.enableVteIntegration = mkEnableOption (lib.mdDoc "") // {
+      inherit description;
+    };
 
-    zsh.enableVteIntegration = mkEnableOption "" // { inherit description; };
+    zsh.enableVteIntegration = mkEnableOption (lib.mdDoc "") // {
+      inherit description;
+    };
   };
 
   config = mkMerge [
diff --git a/modules/programs/atuin.nix b/modules/programs/atuin.nix
index 9205a5311..68f23ce84 100644
--- a/modules/programs/atuin.nix
+++ b/modules/programs/atuin.nix
@@ -30,7 +30,8 @@ in {
       '';
     };
 
-    enableZshIntegration = mkEnableOption "Zsh integration" // {
+    enableZshIntegration = mkOption {
+      type = types.bool;
       default = true;
       description = ''
         Whether to enable Atuin's Zsh integration.
diff --git a/modules/programs/git.nix b/modules/programs/git.nix
index 415f046d4..5e6bbd725 100644
--- a/modules/programs/git.nix
+++ b/modules/programs/git.nix
@@ -265,10 +265,10 @@ in {
       };
 
       difftastic = {
-        enable = mkEnableOption "" // {
-          description = ''
-            Enable the <command>difftastic</command> syntax highlighter.
-            See <link xlink:href="https://github.com/Wilfred/difftastic" />.
+        enable = mkEnableOption (lib.mdDoc "") // {
+          description = lib.mdDoc ''
+            Enable the {command}`difftastic` syntax highlighter.
+            See <https://github.com/Wilfred/difftastic>.
           '';
         };
 
@@ -303,10 +303,10 @@ in {
       };
 
       delta = {
-        enable = mkEnableOption "" // {
-          description = ''
-            Whether to enable the <command>delta</command> syntax highlighter.
-            See <link xlink:href="https://github.com/dandavison/delta" />.
+        enable = mkEnableOption (lib.mdDoc "") // {
+          description = lib.mdDoc ''
+            Whether to enable the {command}`delta` syntax highlighter.
+            See <https://github.com/dandavison/delta>.
           '';
         };
 
@@ -335,10 +335,10 @@ in {
       };
 
       diff-so-fancy = {
-        enable = mkEnableOption "" // {
-          description = ''
-            Enable the <command>diff-so-fancy</command> diff colorizer.
-            See <link xlink:href="https://github.com/so-fancy/diff-so-fancy" />.
+        enable = mkEnableOption (lib.mdDoc "") // {
+          description = lib.mdDoc ''
+            Enable the {command}`diff-so-fancy` diff colorizer.
+            See <https://github.com/so-fancy/diff-so-fancy>.
           '';
         };
 
diff --git a/modules/programs/java.nix b/modules/programs/java.nix
index d10f64c54..d2c9c96b6 100644
--- a/modules/programs/java.nix
+++ b/modules/programs/java.nix
@@ -14,10 +14,10 @@ in {
 
   options = {
     programs.java = {
-      enable = mkEnableOption "" // {
-        description = ''
-          Install the Java development kit and set the <envar>JAVA_HOME</envar>
-          variable.
+      enable = mkEnableOption (lib.mdDoc "") // {
+        description = lib.mdDoc ''
+          Install the Java development kit and set the
+          {env}`JAVA_HOME` variable.
         '';
       };
 
diff --git a/modules/services/autorandr.nix b/modules/services/autorandr.nix
index 84791a667..9ce668d7d 100644
--- a/modules/services/autorandr.nix
+++ b/modules/services/autorandr.nix
@@ -10,11 +10,11 @@ in {
 
   options = {
     services.autorandr = {
-      enable = mkEnableOption "" // {
-        description = ''
+      enable = mkEnableOption (lib.mdDoc "") // {
+        description = lib.mdDoc ''
           Whether to enable the Autorandr systemd service.
-          This module is complementary to <code>programs.autorandr</code> which handles the
-          configuration (profiles).
+          This module is complementary to {option}`programs.autorandr`
+          which handles the configuration (profiles).
         '';
       };
 
diff --git a/modules/services/blueman-applet.nix b/modules/services/blueman-applet.nix
index d81db1dbb..b410247d7 100644
--- a/modules/services/blueman-applet.nix
+++ b/modules/services/blueman-applet.nix
@@ -5,16 +5,16 @@ with lib;
 {
   options = {
     services.blueman-applet = {
-      enable = mkEnableOption "" // {
-        description = ''
+      enable = mkEnableOption (lib.mdDoc "") // {
+        description = lib.mdDoc ''
           Whether to enable the Blueman applet.
-          </para><para>
-          Note, for the applet to work, the 'blueman' service should
+
+          Note that for the applet to work, the `blueman` service should
           be enabled system-wide. You can enable it in the system
           configuration using
-          <programlisting language="nix">
-            services.blueman.enable = true;
-          </programlisting>
+          ```nix
+          services.blueman.enable = true;
+          ```
         '';
       };
     };
diff --git a/modules/services/random-background.nix b/modules/services/random-background.nix
index 16c869a9c..d7eed87b4 100644
--- a/modules/services/random-background.nix
+++ b/modules/services/random-background.nix
@@ -15,14 +15,14 @@ in {
 
   options = {
     services.random-background = {
-      enable = mkEnableOption "" // {
-        description = ''
+      enable = mkEnableOption (lib.mdDoc "") // {
+        description = lib.mdDoc ''
           Whether to enable random desktop background.
-          </para><para>
+
           Note, if you are using NixOS and have set up a custom
           desktop manager session for Home Manager, then the session
-          configuration must have the <option>bgSupport</option>
-          option set to <literal>true</literal> or the background
+          configuration must have the `bgSupport`
+          option set to `true` or the background
           image set by this module may be overwritten.
         '';
       };
diff --git a/modules/services/udiskie.nix b/modules/services/udiskie.nix
index 562297963..28cb4c247 100644
--- a/modules/services/udiskie.nix
+++ b/modules/services/udiskie.nix
@@ -25,12 +25,12 @@ in {
 
   options = {
     services.udiskie = {
-      enable = mkEnableOption "udiskie mount daemon" // {
-        description = ''
+      enable = mkEnableOption (lib.mdDoc "") // {
+        description = lib.mdDoc ''
           Whether to enable the udiskie mount daemon.
-          </para><para>
+
           Note, if you use NixOS then you must add
-          <code>services.udisks2.enable = true</code>
+          `services.udisks2.enable = true`
           to your system configuration. Otherwise mounting will fail because
           the Udisk2 DBus service is not found.
         '';
diff --git a/modules/targets/generic-linux.nix b/modules/targets/generic-linux.nix
index b5a07d5fa..38d502c73 100644
--- a/modules/targets/generic-linux.nix
+++ b/modules/targets/generic-linux.nix
@@ -20,8 +20,8 @@ in {
   ];
 
   options.targets.genericLinux = {
-    enable = mkEnableOption "" // {
-      description = ''
+    enable = mkEnableOption (lib.mdDoc "") // {
+      description = lib.mdDoc ''
         Whether to enable settings that make Home Manager work better on
         GNU/Linux distributions other than NixOS.
       '';