treewide: convert all option docs to Markdown

This process was automated by [my fork of `nix-doc-munge`]; thanks
to @pennae for writing this tool! It automatically checks that the
resulting documentation doesn't change, although my fork loosens
this a little to ignore some irrelevant whitespace and typographical
differences.

As of this commit there is no DocBook remaining in the options
documentation.

You can play along at home if you want to reproduce this commit:

    $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \
      nix shell nixpkgs#coreutils \
      -c find . -name '*.nix' \
      -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \
      {} +

[my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge

27 files changed, 167 insertions, 165 deletions

diff --git a/modules/system/activation-scripts.nix b/modules/system/activation-scripts.nix
index 8ade8ed..d5ca292 100644
--- a/modules/system/activation-scripts.nix
+++ b/modules/system/activation-scripts.nix
@@ -22,12 +22,12 @@ in
       internal = true;
       type = types.attrsOf (types.submodule script);
       default = {};
-      description = ''
+      description = lib.mdDoc ''
         A set of shell script fragments that are executed when a NixOS
         system configuration is activated.  Examples are updating
         /etc, creating accounts, and so on.  Since these are executed
         every time you boot the system or run
-        <command>nixos-rebuild</command>, it's important that they are
+        {command}`nixos-rebuild`, it's important that they are
         idempotent and fast.
       '';
     };
diff --git a/modules/system/checks.nix b/modules/system/checks.nix
index fa4b3ad..b1571ab 100644
--- a/modules/system/checks.nix
+++ b/modules/system/checks.nix
@@ -202,19 +202,19 @@ in
     system.checks.verifyNixPath = mkOption {
       type = types.bool;
       default = true;
-      description = "Whether to run the NIX_PATH validation checks.";
+      description = lib.mdDoc "Whether to run the NIX_PATH validation checks.";
     };
 
     system.checks.verifyNixChannels = mkOption {
       type = types.bool;
       default = true;
-      description = "Whether to run the nix-channels validation checks.";
+      description = lib.mdDoc "Whether to run the nix-channels validation checks.";
     };
 
     system.checks.verifyBuildUsers = mkOption {
       type = types.bool;
       default = true;
-      description = "Whether to run the Nix build users validation checks.";
+      description = lib.mdDoc "Whether to run the Nix build users validation checks.";
     };
 
     system.checks.text = mkOption {
diff --git a/modules/system/default.nix b/modules/system/default.nix
index 629760c..58369a8 100644
--- a/modules/system/default.nix
+++ b/modules/system/default.nix
@@ -22,7 +22,7 @@ in
       internal = true;
       type = types.attrsOf types.unspecified;
       default = {};
-      description = ''
+      description = lib.mdDoc ''
         Attribute set of derivation used to setup the system.
       '';
     };
@@ -30,7 +30,7 @@ in
     system.path = mkOption {
       internal = true;
       type = types.package;
-      description = ''
+      description = lib.mdDoc ''
         The packages you want in the system environment.
       '';
     };
@@ -38,7 +38,7 @@ in
     system.profile = mkOption {
       type = types.path;
       default = "/nix/var/nix/profiles/system";
-      description = ''
+      description = lib.mdDoc ''
         Profile to use for the system.
       '';
     };
@@ -48,7 +48,7 @@ in
       internal = true;
       default = [];
       example = [ { assertion = false; message = "you can't enable this for that reason"; } ];
-      description = ''
+      description = lib.mdDoc ''
         This option allows modules to express conditions that must
         hold for the evaluation of the system configuration to
         succeed, along with associated error messages for the user.
@@ -60,7 +60,7 @@ in
       default = [];
       type = types.listOf types.str;
       example = [ "The `foo' service is deprecated and will go away soon!" ];
-      description = ''
+      description = lib.mdDoc ''
         This option allows modules to show warnings to users during
         the evaluation of the system configuration.
       '';
diff --git a/modules/system/defaults/ActivityMonitor.nix b/modules/system/defaults/ActivityMonitor.nix
index 270c678..9f4617c 100644
--- a/modules/system/defaults/ActivityMonitor.nix
+++ b/modules/system/defaults/ActivityMonitor.nix
@@ -39,7 +39,7 @@ with lib;
     system.defaults.ActivityMonitor.SortColumn = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           Which column to sort the main activity page (such as "CPUUsage"). Default is null.
         '';
     };
@@ -47,7 +47,7 @@ with lib;
     system.defaults.ActivityMonitor.SortDirection = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           The sort direction of the sort column (0 is decending). Default is null.
         '';
     };
@@ -55,7 +55,7 @@ with lib;
     system.defaults.ActivityMonitor.OpenMainWindow = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           Open the main window when opening Activity Monitor. Default is true.
         '';
     };
diff --git a/modules/system/defaults/CustomPreferences.nix b/modules/system/defaults/CustomPreferences.nix
index 1b4b99b..134c8d0 100644
--- a/modules/system/defaults/CustomPreferences.nix
+++ b/modules/system/defaults/CustomPreferences.nix
@@ -14,7 +14,7 @@ with lib;
             true;
         };
       };
-      description = ''
+      description = lib.mdDoc ''
         Sets custom user preferences
       '';
     };
@@ -29,7 +29,7 @@ with lib;
             true;
         };
       };
-      description = ''
+      description = lib.mdDoc ''
         Sets custom system preferences
       '';
     };
diff --git a/modules/system/defaults/GlobalPreferences.nix b/modules/system/defaults/GlobalPreferences.nix
index 5cce419..e6964aa 100644
--- a/modules/system/defaults/GlobalPreferences.nix
+++ b/modules/system/defaults/GlobalPreferences.nix
@@ -19,7 +19,7 @@ in {
       mkOption {
         type = types.nullOr (types.path);
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Sets the system-wide alert sound. Found under "Sound Effects" in the
           "Sound" section of "System Preferences". Look in
           "/System/Library/Sounds" for possible candidates.
@@ -30,7 +30,7 @@ in {
       mkOption {
         type = types.nullOr float;
         default = null;
-        description = ''
+        description = lib.mdDoc ''
           Sets the mouse tracking speed. Found in the "Mouse" section of
           "System Preferences". Set to -1 to disable mouse acceleration.
         '';
diff --git a/modules/system/defaults/LaunchServices.nix b/modules/system/defaults/LaunchServices.nix
index d9ffcda..b76231f 100644
--- a/modules/system/defaults/LaunchServices.nix
+++ b/modules/system/defaults/LaunchServices.nix
@@ -8,7 +8,7 @@ with lib;
     system.defaults.LaunchServices.LSQuarantine = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable quarantine for downloaded applications.  The default is true.
       '';
     };
diff --git a/modules/system/defaults/NSGlobalDomain.nix b/modules/system/defaults/NSGlobalDomain.nix
index a23737e..4f08d4a 100644
--- a/modules/system/defaults/NSGlobalDomain.nix
+++ b/modules/system/defaults/NSGlobalDomain.nix
@@ -11,7 +11,7 @@ in {
     system.defaults.NSGlobalDomain.AppleShowAllFiles = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to always show hidden files. The default is false.
       '';
     };
@@ -19,7 +19,7 @@ in {
     system.defaults.NSGlobalDomain.AppleEnableMouseSwipeNavigateWithScrolls = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Enables swiping left or right with two fingers to navigate backward or forward. The default is true.
       '';
     };
@@ -27,7 +27,7 @@ in {
     system.defaults.NSGlobalDomain.AppleEnableSwipeNavigateWithScrolls = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Enables swiping left or right with two fingers to navigate backward or forward. The default is true.
       '';
     };
@@ -35,7 +35,7 @@ in {
     system.defaults.NSGlobalDomain.AppleFontSmoothing = mkOption {
       type = types.nullOr (types.enum [ 0 1 2 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Sets the level of font smoothing (sub-pixel font rendering).
       '';
     };
@@ -43,7 +43,7 @@ in {
     system.defaults.NSGlobalDomain.AppleInterfaceStyle = mkOption {
       type = types.nullOr (types.enum [ "Dark" ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Set to 'Dark' to enable dark mode, or leave unset for normal mode.
       '';
     };
@@ -51,7 +51,7 @@ in {
     system.defaults.NSGlobalDomain.AppleInterfaceStyleSwitchesAutomatically = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to automatically switch between light and dark mode. The default is false.
       '';
     };
@@ -59,7 +59,7 @@ in {
     system.defaults.NSGlobalDomain.AppleKeyboardUIMode = mkOption {
       type = types.nullOr (types.enum [ 3 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Configures the keyboard control behavior.  Mode 3 enables full keyboard control.
       '';
     };
@@ -67,7 +67,7 @@ in {
     system.defaults.NSGlobalDomain.ApplePressAndHoldEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable the press-and-hold feature.  The default is true.
       '';
     };
@@ -75,7 +75,7 @@ in {
     system.defaults.NSGlobalDomain.AppleShowAllExtensions = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to show all file extensions in Finder. The default is false.
       '';
     };
@@ -83,7 +83,7 @@ in {
     system.defaults.NSGlobalDomain.AppleShowScrollBars = mkOption {
       type = types.nullOr (types.enum [ "WhenScrolling" "Automatic" "Always" ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         When to show the scrollbars. Options are 'WhenScrolling', 'Automatic' and 'Always'.
       '';
     };
@@ -91,7 +91,7 @@ in {
     system.defaults.NSGlobalDomain.AppleScrollerPagingBehavior = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Jump to the spot that's clicked on the scroll bar. The default is false.
       '';
     };
@@ -99,7 +99,7 @@ in {
     system.defaults.NSGlobalDomain.NSAutomaticCapitalizationEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable automatic capitalization.  The default is true.
       '';
     };
@@ -107,7 +107,7 @@ in {
     system.defaults.NSGlobalDomain.NSAutomaticDashSubstitutionEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable smart dash substitution.  The default is true.
       '';
     };
@@ -115,7 +115,7 @@ in {
     system.defaults.NSGlobalDomain.NSAutomaticPeriodSubstitutionEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable smart period substitution.  The default is true.
       '';
     };
@@ -123,7 +123,7 @@ in {
     system.defaults.NSGlobalDomain.NSAutomaticQuoteSubstitutionEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable smart quote substitution.  The default is true.
       '';
     };
@@ -131,7 +131,7 @@ in {
     system.defaults.NSGlobalDomain.NSAutomaticSpellingCorrectionEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable automatic spelling correction.  The default is true.
       '';
     };
@@ -139,7 +139,7 @@ in {
     system.defaults.NSGlobalDomain.NSAutomaticWindowAnimationsEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to animate opening and closing of windows and popovers.  The default is true.
       '';
     };
@@ -147,7 +147,7 @@ in {
     system.defaults.NSGlobalDomain.NSDisableAutomaticTermination = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to disable the automatic termination of inactive apps.
       '';
     };
@@ -155,7 +155,7 @@ in {
     system.defaults.NSGlobalDomain.NSDocumentSaveNewDocumentsToCloud = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to save new documents to iCloud by default.  The default is true.
       '';
     };
@@ -163,7 +163,7 @@ in {
     system.defaults.NSGlobalDomain.AppleWindowTabbingMode = mkOption {
       type = types.nullOr (types.enum [ "manual" "always" "fullscreen" ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Sets the window tabbing when opening a new document: 'manual', 'always', or 'fullscreen'.  The default is 'fullscreen'.
       '';
     };
@@ -171,7 +171,7 @@ in {
     system.defaults.NSGlobalDomain.NSNavPanelExpandedStateForSaveMode = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use expanded save panel by default.  The default is false.
       '';
     };
@@ -179,7 +179,7 @@ in {
     system.defaults.NSGlobalDomain.NSNavPanelExpandedStateForSaveMode2 = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use expanded save panel by default.  The default is false.
       '';
     };
@@ -187,7 +187,7 @@ in {
     system.defaults.NSGlobalDomain.NSTableViewDefaultSizeMode = mkOption {
       type = types.nullOr (types.enum [ 1 2 3 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Sets the size of the finder sidebar icons: 1 (small), 2 (medium) or 3 (large). The default is 3.
       '';
     };
@@ -195,7 +195,7 @@ in {
     system.defaults.NSGlobalDomain.NSTextShowsControlCharacters = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to display ASCII control characters using caret notation in standard text views. The default is false.
       '';
     };
@@ -203,7 +203,7 @@ in {
     system.defaults.NSGlobalDomain.NSUseAnimatedFocusRing = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable the focus ring animation. The default is true.
       '';
     };
@@ -211,7 +211,7 @@ in {
     system.defaults.NSGlobalDomain.NSScrollAnimationEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable smooth scrolling. The default is true.
       '';
     };
@@ -220,7 +220,7 @@ in {
       type = types.nullOr floatWithDeprecationError;
       default = null;
       example = 0.20;
-      description = ''
+      description = lib.mdDoc ''
         Sets the speed speed of window resizing. The default is given in the example.
       '';
     };
@@ -228,7 +228,7 @@ in {
     system.defaults.NSGlobalDomain.InitialKeyRepeat = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Keyboard
 
         If you press and hold certain keyboard keys when in a text area, the key’s character begins to repeat.
@@ -241,7 +241,7 @@ in {
     system.defaults.NSGlobalDomain.KeyRepeat = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Keyboard
 
         If you press and hold certain keyboard keys when in a text area, the key’s character begins to repeat.
@@ -254,7 +254,7 @@ in {
     system.defaults.NSGlobalDomain.PMPrintingExpandedStateForPrint = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use the expanded print panel by default. The default is false.
       '';
     };
@@ -262,7 +262,7 @@ in {
     system.defaults.NSGlobalDomain.PMPrintingExpandedStateForPrint2 = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use the expanded print panel by default. The default is false.
       '';
     };
@@ -270,7 +270,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.keyboard.fnState" = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Use F1, F2, etc. keys as standard function keys.
       '';
     };
@@ -278,7 +278,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.mouse.tapBehavior" = mkOption {
       type = types.nullOr (types.enum [ 1 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Configures the trackpad tap behavior.  Mode 1 enables tap to click.
       '';
     };
@@ -286,7 +286,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.sound.beep.volume" = mkOption {
       type = types.nullOr floatWithDeprecationError;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Sound
 
         Sets the beep/alert volume level from 0.000 (muted) to 1.000 (100% volume).
@@ -302,7 +302,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.sound.beep.feedback" = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Sound
 
         Make a feedback sound when the system volume changed. This setting accepts
@@ -313,7 +313,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.trackpad.enableSecondaryClick" = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable trackpad secondary click.  The default is true.
       '';
     };
@@ -321,7 +321,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.trackpad.trackpadCornerClickBehavior" = mkOption {
       type = types.nullOr (types.enum [ 1 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Configures the trackpad corner click behavior.  Mode 1 enables right click.
       '';
     };
@@ -329,7 +329,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.trackpad.scaling" = mkOption {
       type = types.nullOr floatWithDeprecationError;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Configures the trackpad tracking speed (0 to 3).  The default is "1".
       '';
     };
@@ -337,7 +337,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.springing.enabled" = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable spring loading (expose) for directories.
       '';
     };
@@ -346,7 +346,7 @@ in {
       type = types.nullOr floatWithDeprecationError;
       default = null;
       example = 1.0;
-      description = ''
+      description = lib.mdDoc ''
         Set the spring loading delay for directories. The default is given in the example.
       '';
     };
@@ -354,7 +354,7 @@ in {
     system.defaults.NSGlobalDomain."com.apple.swipescrolldirection" = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable "Natural" scrolling direction.  The default is true.
       '';
     };
@@ -362,7 +362,7 @@ in {
     system.defaults.NSGlobalDomain.AppleMeasurementUnits = mkOption {
       type = types.nullOr (types.enum [ "Centimeters" "Inches" ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use centimeters (metric) or inches (US, UK) as the measurement unit.  The default is based on region settings.
       '';
     };
@@ -370,7 +370,7 @@ in {
     system.defaults.NSGlobalDomain.AppleMetricUnits = mkOption {
       type = types.nullOr (types.enum [ 0 1 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use the metric system.  The default is based on region settings.
       '';
     };
@@ -378,7 +378,7 @@ in {
     system.defaults.NSGlobalDomain.AppleTemperatureUnit = mkOption {
       type = types.nullOr (types.enum [ "Celsius" "Fahrenheit" ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use Celsius or Fahrenheit.  The default is based on region settings.
       '';
     };
@@ -386,7 +386,7 @@ in {
     system.defaults.NSGlobalDomain.AppleICUForce24HourTime = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to use 24-hour or 12-hour time.  The default is based on region settings.
       '';
     };
@@ -394,7 +394,7 @@ in {
     system.defaults.NSGlobalDomain._HIHideMenuBar = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to autohide the menu bar.  The default is false.
       '';
     };
diff --git a/modules/system/defaults/SoftwareUpdate.nix b/modules/system/defaults/SoftwareUpdate.nix
index ec89bce..2882e8c 100644
--- a/modules/system/defaults/SoftwareUpdate.nix
+++ b/modules/system/defaults/SoftwareUpdate.nix
@@ -7,7 +7,7 @@ with lib;
     system.defaults.SoftwareUpdate.AutomaticallyInstallMacOSUpdates = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Automatically install Mac OS software updates. Defaults to false.
       '';
     };
diff --git a/modules/system/defaults/alf.nix b/modules/system/defaults/alf.nix
index 96a9806..6b82eca 100644
--- a/modules/system/defaults/alf.nix
+++ b/modules/system/defaults/alf.nix
@@ -7,7 +7,7 @@ with lib;
     system.defaults.alf.globalstate = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Security and Privacy > Firewall
 
         Enable the internal firewall to prevent unauthorised applications, programs
@@ -22,7 +22,7 @@ with lib;
     system.defaults.alf.allowsignedenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Security and Privacy > Firewall
 
         Allows any signed Application to accept incoming requests. Default is true.
@@ -35,7 +35,7 @@ with lib;
     system.defaults.alf.allowdownloadsignedenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Security and Privacy > Firewall
 
         Allows any downloaded Application that has been signed to accept incoming requests. Default is 0.
@@ -48,7 +48,7 @@ with lib;
     system.defaults.alf.loggingenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Security and Privacy > Firewall
 
         Enable logging of requests made to the firewall. Default is 0.
@@ -61,7 +61,7 @@ with lib;
     system.defaults.alf.stealthenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Security and firewall
 
         Drops incoming requests via ICMP such as ping requests. Default is 0.
diff --git a/modules/system/defaults/clock.nix b/modules/system/defaults/clock.nix
index ef2cac4..cd5c0e8 100644
--- a/modules/system/defaults/clock.nix
+++ b/modules/system/defaults/clock.nix
@@ -8,7 +8,7 @@ with lib;
     system.defaults.menuExtraClock.IsAnalog = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show an analog clock instead of a digital one. Default is null.
       '';
     };
@@ -16,7 +16,7 @@ with lib;
     system.defaults.menuExtraClock.Show24Hour = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show a 24-hour clock, instead of a 12-hour clock. Default is null.
       '';
     };
@@ -24,7 +24,7 @@ with lib;
     system.defaults.menuExtraClock.ShowAMPM = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show the AM/PM label. Useful if Show24Hour is false. Default is null.
       '';
     };
@@ -32,7 +32,7 @@ with lib;
     system.defaults.menuExtraClock.ShowDayOfMonth = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show the day of the month. Default is null.
       '';
     };
@@ -40,7 +40,7 @@ with lib;
     system.defaults.menuExtraClock.ShowDayOfWeek = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show the day of the week. Default is null.
       '';
     };
@@ -48,7 +48,7 @@ with lib;
     system.defaults.menuExtraClock.ShowDate = mkOption {
       type = types.nullOr (types.enum [ 0 1 2 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show the full date. Default is null.
 
         0 = Show the date
@@ -62,7 +62,7 @@ with lib;
     system.defaults.menuExtraClock.ShowSeconds = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show the clock with second precision, instead of minutes. Default is null.
       '';
     };
diff --git a/modules/system/defaults/dock.nix b/modules/system/defaults/dock.nix
index 82c8bef..34fc857 100644
--- a/modules/system/defaults/dock.nix
+++ b/modules/system/defaults/dock.nix
@@ -11,7 +11,7 @@ in {
     system.defaults.dock.appswitcher-all-displays = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to display the appswitcher on all displays or only the main one. The default is false.
       '';
     };
@@ -19,7 +19,7 @@ in {
     system.defaults.dock.autohide = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to automatically hide and show the dock.  The default is false.
       '';
     };
@@ -28,7 +28,7 @@ in {
       type = types.nullOr floatWithDeprecationError;
       default = null;
       example = 0.24;
-      description = ''
+      description = lib.mdDoc ''
         Sets the speed of the autohide delay. The default is given in the example.
       '';
     };
@@ -37,7 +37,7 @@ in {
       type = types.nullOr floatWithDeprecationError;
       default = null;
       example = 1.0;
-      description = ''
+      description = lib.mdDoc ''
         Sets the speed of the animation when hiding/showing the Dock. The default is given in the example.
       '';
     };
@@ -45,7 +45,7 @@ in {
     system.defaults.dock.dashboard-in-overlay = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to hide Dashboard as a Space. The default is false.
       '';
     };
@@ -53,7 +53,7 @@ in {
     system.defaults.dock.enable-spring-load-actions-on-all-items = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Enable spring loading for all Dock items. The default is false.
       '';
     };
@@ -62,7 +62,7 @@ in {
       type = types.nullOr floatWithDeprecationError;
       default = null;
       example = 1.0;
-      description = ''
+      description = lib.mdDoc ''
         Sets the speed of the Mission Control animations. The default is given in the example.
       '';
     };
@@ -70,7 +70,7 @@ in {
     system.defaults.dock.expose-group-by-app = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to group windows by application in Mission Control's Exposé. The default is true.
       '';
     };
@@ -78,7 +78,7 @@ in {
     system.defaults.dock.launchanim = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Animate opening applications from the Dock. The default is true.
       '';
     };
@@ -86,7 +86,7 @@ in {
     system.defaults.dock.mineffect = mkOption {
       type = types.nullOr (types.enum [ "genie" "suck" "scale" ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Set the minimize/maximize window effect. The default is genie.
       '';
     };
@@ -94,7 +94,7 @@ in {
     system.defaults.dock.minimize-to-application = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to minimize windows into their application icon.  The default is false.
       '';
     };
@@ -102,7 +102,7 @@ in {
     system.defaults.dock.mouse-over-hilite-stack = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Enable highlight hover effect for the grid view of a stack in the Dock.
       '';
     };
@@ -110,7 +110,7 @@ in {
     system.defaults.dock.mru-spaces = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to automatically rearrange spaces based on most recent use.  The default is true.
       '';
     };
@@ -118,7 +118,7 @@ in {
     system.defaults.dock.orientation = mkOption {
       type = types.nullOr (types.enum [ "bottom" "left" "right" ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Position of the dock on screen.  The default is "bottom".
       '';
     };
@@ -126,7 +126,7 @@ in {
     system.defaults.dock.show-process-indicators = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show indicator lights for open applications in the Dock. The default is true.
       '';
     };
@@ -134,7 +134,7 @@ in {
     system.defaults.dock.showhidden = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to make icons of hidden applications tranclucent.  The default is false.
       '';
     };
@@ -142,7 +142,7 @@ in {
     system.defaults.dock.show-recents = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show recent applications in the dock. The default is true.
       '';
     };
@@ -150,7 +150,7 @@ in {
     system.defaults.dock.static-only = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show only open applications in the Dock. The default is false.
       '';
     };
@@ -158,7 +158,7 @@ in {
     system.defaults.dock.tilesize = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Size of the icons in the dock.  The default is 64.
       '';
     };
diff --git a/modules/system/defaults/finder.nix b/modules/system/defaults/finder.nix
index a4bfd21..422e888 100644
--- a/modules/system/defaults/finder.nix
+++ b/modules/system/defaults/finder.nix
@@ -8,7 +8,7 @@ with lib;
     system.defaults.finder.AppleShowAllFiles = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to always show hidden files. The default is false.
       '';
     };
@@ -16,7 +16,7 @@ with lib;
     system.defaults.finder.ShowStatusBar = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show status bar at bottom of finder windows with item/disk space stats. The default is false.
       '';
     };
@@ -24,7 +24,7 @@ with lib;
     system.defaults.finder.ShowPathbar = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Show path breadcrumbs in finder windows. The default is false.
       '';
     };
@@ -32,7 +32,7 @@ with lib;
     system.defaults.finder.FXDefaultSearchScope = mkOption {
       type = types.nullOr types.string;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Change the default search scope. Use "SCcf" to default to current folder.
         The default is unset ("This Mac").
       '';
@@ -41,7 +41,7 @@ with lib;
     system.defaults.finder.FXPreferredViewStyle = mkOption {
       type = types.nullOr types.string;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Change the default finder view.
         "icnv" = Icon view, "Nlsv" = List view, "clmv" = Column View, "Flwv" = Gallery View
         The default is icnv.
@@ -51,7 +51,7 @@ with lib;
     system.defaults.finder.AppleShowAllExtensions = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to always show file extensions.  The default is false.
       '';
     };
@@ -59,7 +59,7 @@ with lib;
     system.defaults.finder.CreateDesktop = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to show icons on the desktop or not. The default is true.
       '';
     };
@@ -67,7 +67,7 @@ with lib;
     system.defaults.finder.QuitMenuItem = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to allow quitting of the Finder.  The default is false.
       '';
     };
@@ -75,7 +75,7 @@ with lib;
     system.defaults.finder._FXShowPosixPathInTitle = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to show the full POSIX filepath in the window title.  The default is false.
       '';
     };
@@ -83,7 +83,7 @@ with lib;
     system.defaults.finder.FXEnableExtensionChangeWarning = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to show warnings when change the file extension of files.  The default is true.
       '';
     };
diff --git a/modules/system/defaults/loginwindow.nix b/modules/system/defaults/loginwindow.nix
index 0fb7096..81f7dfa 100644
--- a/modules/system/defaults/loginwindow.nix
+++ b/modules/system/defaults/loginwindow.nix
@@ -7,7 +7,7 @@ with lib;
     system.defaults.loginwindow.SHOWFULLNAME = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Displays login window as a name and password field instead of a list of users.
@@ -18,7 +18,7 @@ with lib;
     system.defaults.loginwindow.autoLoginUser = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Auto login the supplied user on boot. Default is Off.
@@ -28,7 +28,7 @@ with lib;
     system.defaults.loginwindow.GuestEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Allow users to login to the machine as guests using the Guest account. Default is true.
@@ -46,7 +46,7 @@ with lib;
     system.defaults.loginwindow.ShutDownDisabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Hides the Shut Down button on the login screen. Default is false.
@@ -56,7 +56,7 @@ with lib;
     system.defaults.loginwindow.SleepDisabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Hides the Sleep button on the login screen. Default is false.
@@ -66,7 +66,7 @@ with lib;
     system.defaults.loginwindow.RestartDisabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Hides the Restart button on the login screen. Default is false.
@@ -76,7 +76,7 @@ with lib;
     system.defaults.loginwindow.ShutDownDisabledWhileLoggedIn = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Disables the "Shutdown" option when users are logged in. Default is false.
@@ -86,7 +86,7 @@ with lib;
     system.defaults.loginwindow.PowerOffDisabledWhileLoggedIn = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         If set to true, the Power Off menu item will be disabled when the user is logged in. Default is false.
@@ -96,7 +96,7 @@ with lib;
     system.defaults.loginwindow.RestartDisabledWhileLoggedIn = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Users and Groups > Login Options
 
         Disables the “Restart” option when users are logged in. Default is false.
@@ -106,7 +106,7 @@ with lib;
     system.defaults.loginwindow.DisableConsoleAccess = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Disables the ability for a user to access the console by typing “>console”
         for a username at the login window. Default is false.
       '';
diff --git a/modules/system/defaults/magicmouse.nix b/modules/system/defaults/magicmouse.nix
index 9344ffe..56d7f71 100644
--- a/modules/system/defaults/magicmouse.nix
+++ b/modules/system/defaults/magicmouse.nix
@@ -11,7 +11,7 @@ with lib;
         "TwoButton"
       ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         "OneButton": any tap is a left click.  "TwoButton": allow left-
         and right-clicking.
       '';
diff --git a/modules/system/defaults/screencapture.nix b/modules/system/defaults/screencapture.nix
index f7b926a..4483fd6 100644
--- a/modules/system/defaults/screencapture.nix
+++ b/modules/system/defaults/screencapture.nix
@@ -8,7 +8,7 @@ with lib;
     system.defaults.screencapture.location = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           The filesystem path to which screencaptures should be written.
         '';
     };
@@ -16,7 +16,7 @@ with lib;
     system.defaults.screencapture.type = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           The image format to use, such as "jpg".
         '';
     };
@@ -24,7 +24,7 @@ with lib;
     system.defaults.screencapture.disable-shadow = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           Disable drop shadow border around screencaptures. The default is false.
         '';
     };
diff --git a/modules/system/defaults/screensaver.nix b/modules/system/defaults/screensaver.nix
index 3e5032b..68bd1e0 100644
--- a/modules/system/defaults/screensaver.nix
+++ b/modules/system/defaults/screensaver.nix
@@ -8,7 +8,7 @@ with lib;
     system.defaults.screensaver.askForPassword = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           If true, the user is prompted for a password when the screen saver is unlocked or stopped. The default is false.
         '';
     };
@@ -16,7 +16,7 @@ with lib;
     system.defaults.screensaver.askForPasswordDelay = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           The number of seconds to delay before the password will be required to unlock or stop the screen saver (the grace period).
         '';
     };
diff --git a/modules/system/defaults/smb.nix b/modules/system/defaults/smb.nix
index 0bc8be5..b694059 100644
--- a/modules/system/defaults/smb.nix
+++ b/modules/system/defaults/smb.nix
@@ -7,13 +7,13 @@ with lib;
     system.defaults.smb.NetBIOSName = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = "Hostname to use for NetBIOS.";
+      description = lib.mdDoc "Hostname to use for NetBIOS.";
     };
 
     system.defaults.smb.ServerDescription = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = "Hostname to use for sharing services.";
+      description = lib.mdDoc "Hostname to use for sharing services.";
     };
   };
 }
diff --git a/modules/system/defaults/spaces.nix b/modules/system/defaults/spaces.nix
index ac2355b..4b535d1 100644
--- a/modules/system/defaults/spaces.nix
+++ b/modules/system/defaults/spaces.nix
@@ -7,7 +7,7 @@ with lib;
     system.defaults.spaces.spans-displays = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Apple menu > System Preferences > Mission Control
 
         Displays have separate Spaces (note a logout is required before
diff --git a/modules/system/defaults/trackpad.nix b/modules/system/defaults/trackpad.nix
index edb6375..ff5e2bb 100644
--- a/modules/system/defaults/trackpad.nix
+++ b/modules/system/defaults/trackpad.nix
@@ -8,7 +8,7 @@ with lib;
     system.defaults.trackpad.Clicking = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable trackpad tap to click.  The default is false.
       '';
     };
@@ -16,7 +16,7 @@ with lib;
     system.defaults.trackpad.Dragging = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable tap-to-drag. The default is false.
       '';
     };
@@ -24,7 +24,7 @@ with lib;
     system.defaults.trackpad.TrackpadRightClick = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable trackpad right click.  The default is false.
       '';
     };
@@ -32,7 +32,7 @@ with lib;
     system.defaults.trackpad.TrackpadThreeFingerDrag = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Whether to enable three finger drag.  The default is false.
       '';
     };
@@ -40,7 +40,7 @@ with lib;
     system.defaults.trackpad.ActuationStrength = mkOption {
       type = types.nullOr (types.enum [ 0 1 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         0 to enable Silent Clicking, 1 to disable.  The default is 1.
       '';
     };
@@ -48,7 +48,7 @@ with lib;
     system.defaults.trackpad.FirstClickThreshold = mkOption {
       type = types.nullOr (types.enum [ 0 1 2 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         For normal click: 0 for light clicking, 1 for medium, 2 for firm.
         The default is 1.
       '';
@@ -57,7 +57,7 @@ with lib;
     system.defaults.trackpad.SecondClickThreshold = mkOption {
       type = types.nullOr (types.enum [ 0 1 2 ]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         For force touch: 0 for light clicking, 1 for medium, 2 for firm.
         The default is 1.
       '';
diff --git a/modules/system/defaults/universalaccess.nix b/modules/system/defaults/universalaccess.nix
index bb4bec9..51a1fb7 100644
--- a/modules/system/defaults/universalaccess.nix
+++ b/modules/system/defaults/universalaccess.nix
@@ -9,7 +9,7 @@ with lib;
       type = types.nullOr types.float;
       default = null;
       example = 1.5;
-      description = ''
+      description = lib.mdDoc ''
         Set the size of cursor. 1 for normal, 4 for maximum.
         The default is 1.
       '';
@@ -18,7 +18,7 @@ with lib;
     system.defaults.universalaccess.reduceTransparency = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Disable transparency in the menu bar and elsewhere.
         Requires macOS Yosemite or later.
         The default is false.
@@ -28,7 +28,7 @@ with lib;
     system.defaults.universalaccess.closeViewScrollWheelToggle = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Use scroll gesture with the Ctrl (^) modifier key to zoom.
         The default is false.
       '';
diff --git a/modules/system/etc.nix b/modules/system/etc.nix
index 4b45e3a..b6c5827 100644
--- a/modules/system/etc.nix
+++ b/modules/system/etc.nix
@@ -23,8 +23,8 @@ in
     environment.etc = mkOption {
       type = types.attrsOf (types.submodule text);
       default = { };
-      description = ''
-        Set of files that have to be linked in <filename>/etc</filename>.
+      description = lib.mdDoc ''
+        Set of files that have to be linked in {file}`/etc`.
       '';
     };
 
diff --git a/modules/system/keyboard.nix b/modules/system/keyboard.nix
index c637f04..6e4275e 100644
--- a/modules/system/keyboard.nix
+++ b/modules/system/keyboard.nix
@@ -11,40 +11,40 @@ in
     system.keyboard.enableKeyMapping = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to enable keyboard mappings.";
+      description = lib.mdDoc "Whether to enable keyboard mappings.";
     };
 
     system.keyboard.remapCapsLockToControl = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to remap the Caps Lock key to Control.";
+      description = lib.mdDoc "Whether to remap the Caps Lock key to Control.";
     };
 
     system.keyboard.remapCapsLockToEscape = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to remap the Caps Lock key to Escape.";
+      description = lib.mdDoc "Whether to remap the Caps Lock key to Escape.";
     };
 
     system.keyboard.nonUS.remapTilde = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to remap the Tilde key on non-us keyboards.";
+      description = lib.mdDoc "Whether to remap the Tilde key on non-us keyboards.";
     };
 
     system.keyboard.swapLeftCommandAndLeftAlt = mkOption {
       type = types.bool;
       default = false;
-      description = "Whether to swap the left Command key and left Alt key.";
+      description = lib.mdDoc "Whether to swap the left Command key and left Alt key.";
     };
 
     system.keyboard.userKeyMapping = mkOption {
       internal = true;
       type = types.listOf (types.attrsOf types.int);
       default = [];
-      description = ''
+      description = lib.mdDoc ''
         List of keyboard mappings to apply, for more information see
-        <link xlink:href="https://developer.apple.com/library/content/technotes/tn2450/_index.html"/>.
+        <https://developer.apple.com/library/content/technotes/tn2450/_index.html>.
       '';
     };
   };
diff --git a/modules/system/launchd.nix b/modules/system/launchd.nix
index e11c663..7f6b485 100644
--- a/modules/system/launchd.nix
+++ b/modules/system/launchd.nix
@@ -59,24 +59,24 @@ in
     environment.launchAgents = mkOption {
       type = types.attrsOf (types.submodule text);
       default = { };
-      description = ''
-        Set of files that have to be linked in <filename>/Library/LaunchAgents</filename>.
+      description = lib.mdDoc ''
+        Set of files that have to be linked in {file}`/Library/LaunchAgents`.
       '';
     };
 
     environment.launchDaemons = mkOption {
       type = types.attrsOf (types.submodule text);
       default = { };
-      description = ''
-        Set of files that have to be linked in <filename>/Library/LaunchDaemons</filename>.
+      description = lib.mdDoc ''
+        Set of files that have to be linked in {file}`/Library/LaunchDaemons`.
       '';
     };
 
     environment.userLaunchAgents = mkOption {
       type = types.attrsOf (types.submodule text);
       default = { };
-      description = ''
-        Set of files that have to be linked in <filename>~/Library/LaunchAgents</filename>.
+      description = lib.mdDoc ''
+        Set of files that have to be linked in {file}`~/Library/LaunchAgents`.
       '';
     };
 
diff --git a/modules/system/patches.nix b/modules/system/patches.nix
index 0b56681..9ac15ec 100644
--- a/modules/system/patches.nix
+++ b/modules/system/patches.nix
@@ -26,12 +26,14 @@ in
           '''')
         ]
       '';
-      description = ''
-        Set of patches to apply to <filename>/</filename>.
+      description = lib.mdDoc ''
+        Set of patches to apply to {file}`/`.
 
-        <warning><para>
+        ::: {.warning}
+        
         This can modify everything so use with caution.
-        </para></warning>
+        
+        :::
 
         Useful for safely changing system files.  Unlike the etc module this
         won't remove or modify files with unexpected content.
diff --git a/modules/system/shells.nix b/modules/system/shells.nix
index ac9d619..b3ecf30 100644
--- a/modules/system/shells.nix
+++ b/modules/system/shells.nix
@@ -12,9 +12,9 @@ in
       type = types.listOf (types.either types.shellPackage types.path);
       default = [];
       example = literalExpression "[ pkgs.bashInteractive pkgs.zsh ]";
-      description = ''
+      description = lib.mdDoc ''
         A list of permissible login shells for user accounts.
-        No need to mention <literal>/bin/sh</literal>
+        No need to mention `/bin/sh`
         and other shells that are available by default on
         macOS.
       '';
diff --git a/modules/system/version.nix b/modules/system/version.nix
index 7b9236d..6801918 100644
--- a/modules/system/version.nix
+++ b/modules/system/version.nix
@@ -35,7 +35,7 @@ in
     system.stateVersion = mkOption {
       type = types.int;
       default = 4;
-      description = ''
+      description = lib.mdDoc ''
         Every once in a while, a new NixOS release may change
         configuration defaults in a way incompatible with stateful
         data. For instance, if the default version of PostgreSQL
@@ -50,50 +50,50 @@ in
 
     system.darwinLabel = mkOption {
       type = types.str;
-      description = "Label to be used in the names of generated outputs.";
+      description = lib.mdDoc "Label to be used in the names of generated outputs.";
     };
 
     system.darwinVersion = mkOption {
       internal = true;
       type = types.str;
-      description = "The full darwin version (e.g. <literal>darwin4.master</literal>).";
+      description = lib.mdDoc "The full darwin version (e.g. `darwin4.master`).";
     };
 
     system.darwinVersionSuffix = mkOption {
       internal = true;
       type = types.str;
-      description = "The short darwin version suffix (e.g. <literal>.2abdb5a</literal>).";
+      description = lib.mdDoc "The short darwin version suffix (e.g. `.2abdb5a`).";
     };
 
     system.darwinRevision = mkOption {
       internal = true;
       type = types.str;
       default = "master";
-      description = "The darwin git revision from which this configuration was built.";
+      description = lib.mdDoc "The darwin git revision from which this configuration was built.";
     };
 
     system.nixpkgsRelease = mkOption {
       readOnly = true;
       type = types.str;
-      description = "The nixpkgs release (e.g. <literal>16.03</literal>).";
+      description = lib.mdDoc "The nixpkgs release (e.g. `16.03`).";
     };
 
     system.nixpkgsVersion = mkOption {
       internal = true;
       type = types.str;
-      description = "The full nixpkgs version (e.g. <literal>16.03.1160.f2d4ee1</literal>).";
+      description = lib.mdDoc "The full nixpkgs version (e.g. `16.03.1160.f2d4ee1`).";
     };
 
     system.nixpkgsVersionSuffix = mkOption {
       internal = true;
       type = types.str;
-      description = "The short nixpkgs version suffix (e.g. <literal>.1160.f2d4ee1</literal>).";
+      description = lib.mdDoc "The short nixpkgs version suffix (e.g. `.1160.f2d4ee1`).";
     };
 
     system.nixpkgsRevision = mkOption {
       internal = true;
       type = types.str;
-      description = "The nixpkgs git revision from which this configuration was built.";
+      description = lib.mdDoc "The nixpkgs git revision from which this configuration was built.";
     };
   };