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

Migrate option documentation to Markdown

27 files changed, 276 insertions, 263 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 d57c6c0..9f4617c 100644
--- a/modules/system/defaults/ActivityMonitor.nix
+++ b/modules/system/defaults/ActivityMonitor.nix
@@ -8,16 +8,16 @@ with lib;
     system.defaults.ActivityMonitor.ShowCategory = mkOption {
       type = types.nullOr (types.enum [100 101 102 103 104 105 106 107]);
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           Change which processes to show.
-            100: All Processes
-            101: All Processes, Hierarchally
-            102: My Processes
-            103: System Processes
-            104: Other User Processes
-            105: Active Processes
-            106: Inactive Processes
-            107: Windowed Processes
+          * 100: All Processes
+          * 101: All Processes, Hierarchally
+          * 102: My Processes
+          * 103: System Processes
+          * 104: Other User Processes
+          * 105: Active Processes
+          * 106: Inactive Processes
+          * 107: Windowed Processes
           Default is 100.
         '';
     };
@@ -25,13 +25,13 @@ with lib;
     system.defaults.ActivityMonitor.IconType = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
           Change the icon in the dock when running.
-            0: Application Icon
-            2: Network Usage
-            3: Disk Activity
-            5: CPU Usage
-            6: CPU History
+          * 0: Application Icon
+          * 2: Network Usage
+          * 3: Disk Activity
+          * 5: CPU Usage
+          * 6: CPU History
           Default is null.
         '';
     };
@@ -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 3fb8db0..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,8 +228,9 @@ in {
     system.defaults.NSGlobalDomain.InitialKeyRepeat = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Keyboard
+      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.
         For example, the Delete key continues to remove text for as long as you hold it down.
 
@@ -240,8 +241,9 @@ in {
     system.defaults.NSGlobalDomain.KeyRepeat = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Keyboard
+      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.
         For example, the Delete key continues to remove text for as long as you hold it down.
 
@@ -252,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.
       '';
     };
@@ -260,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.
       '';
     };
@@ -268,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.
       '';
     };
@@ -276,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.
       '';
     };
@@ -284,8 +286,9 @@ in {
     system.defaults.NSGlobalDomain."com.apple.sound.beep.volume" = mkOption {
       type = types.nullOr floatWithDeprecationError;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Sound
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Sound
+
         Sets the beep/alert volume level from 0.000 (muted) to 1.000 (100% volume).
 
         75% = 0.7788008
@@ -299,8 +302,9 @@ in {
     system.defaults.NSGlobalDomain."com.apple.sound.beep.feedback" = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Sound
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Sound
+
         Make a feedback sound when the system volume changed. This setting accepts
         the integers 0 or 1. Defaults to 1.
       '';
@@ -309,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.
       '';
     };
@@ -317,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.
       '';
     };
@@ -325,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".
       '';
     };
@@ -333,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.
       '';
     };
@@ -342,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.
       '';
     };
@@ -350,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.
       '';
     };
@@ -358,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.
       '';
     };
@@ -366,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.
       '';
     };
@@ -374,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.
       '';
     };
@@ -382,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.
       '';
     };
@@ -390,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 f62ead2..6b82eca 100644
--- a/modules/system/defaults/alf.nix
+++ b/modules/system/defaults/alf.nix
@@ -7,8 +7,9 @@ with lib;
     system.defaults.alf.globalstate = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Security and Privacy > Firewall
+
         Enable the internal firewall to prevent unauthorised applications, programs
         and services from accepting incoming connections.
 
@@ -21,8 +22,9 @@ with lib;
     system.defaults.alf.allowsignedenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Security and Privacy > Firewall
+
         Allows any signed Application to accept incoming requests. Default is true.
 
         0 = disabled
@@ -33,8 +35,9 @@ with lib;
     system.defaults.alf.allowdownloadsignedenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+      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.
 
         0 = disabled
@@ -45,8 +48,9 @@ with lib;
     system.defaults.alf.loggingenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Security and Privacy > Firewall
+
         Enable logging of requests made to the firewall. Default is 0.
 
         0 = disabled
@@ -57,8 +61,9 @@ with lib;
     system.defaults.alf.stealthenabled = mkOption {
       type = types.nullOr types.int;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Security and firewall
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Security and firewall
+
         Drops incoming requests via ICMP such as ping requests. Default is 0.
 
         0 = disabled
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 ba62e7a..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.
       '';
     };
@@ -166,92 +166,84 @@ in {
     system.defaults.dock.wvous-tl-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for top left corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
     system.defaults.dock.wvous-bl-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for bottom left corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
     system.defaults.dock.wvous-tr-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for top right corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
     system.defaults.dock.wvous-br-corner = mkOption {
       type = types.nullOr types.ints.positive;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Hot corner action for bottom right corner. Valid values include:
 
-        <itemizedlist>
-        <listitem><para><literal>1</literal>: Disabled</para></listitem>
-        <listitem><para><literal>2</literal>: Mission Control</para></listitem>
-        <listitem><para><literal>3</literal>: Application Windows</para></listitem>
-        <listitem><para><literal>4</literal>: Desktop</para></listitem>
-        <listitem><para><literal>5</literal>: Start Screen Saver</para></listitem>
-        <listitem><para><literal>6</literal>: Disable Screen Saver</para></listitem>
-        <listitem><para><literal>7</literal>: Dashboard</para></listitem>
-        <listitem><para><literal>10</literal>: Put Display to Sleep</para></listitem>
-        <listitem><para><literal>11</literal>: Launchpad</para></listitem>
-        <listitem><para><literal>12</literal>: Notification Center</para></listitem>
-        <listitem><para><literal>13</literal>: Lock Screen</para></listitem>
-        <listitem><para><literal>14</literal>: Quick Note</para></listitem>
-        </itemizedlist>
+        * `1`: Disabled
+        * `2`: Mission Control
+        * `3`: Application Windows
+        * `4`: Desktop
+        * `5`: Start Screen Saver
+        * `6`: Disable Screen Saver
+        * `7`: Dashboard
+        * `10`: Put Display to Sleep
+        * `11`: Launchpad
+        * `12`: Notification Center
+        * `13`: Lock Screen
+        * `14`: Quick Note
       '';
     };
 
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 0194cc1..81f7dfa 100644
--- a/modules/system/defaults/loginwindow.nix
+++ b/modules/system/defaults/loginwindow.nix
@@ -7,8 +7,9 @@ with lib;
     system.defaults.loginwindow.SHOWFULLNAME = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      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.
         Default is false.
       '';
@@ -17,8 +18,9 @@ with lib;
     system.defaults.loginwindow.autoLoginUser = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Auto login the supplied user on boot. Default is Off.
       '';
     };
@@ -26,8 +28,9 @@ with lib;
     system.defaults.loginwindow.GuestEnabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      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.
       '';
     };
@@ -35,16 +38,17 @@ with lib;
     system.defaults.loginwindow.LoginwindowText = mkOption {
       type = types.nullOr types.str;
       default = null;
-      description = ''
-        Text to be shown on the login window. Default is "\\U03bb".
+      description = lib.mdDoc ''
+        Text to be shown on the login window. Default is "\\\\U03bb".
       '';
     };
 
     system.defaults.loginwindow.ShutDownDisabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Hides the Shut Down button on the login screen. Default is false.
       '';
     };
@@ -52,8 +56,9 @@ with lib;
     system.defaults.loginwindow.SleepDisabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Hides the Sleep button on the login screen. Default is false.
       '';
     };
@@ -61,8 +66,9 @@ with lib;
     system.defaults.loginwindow.RestartDisabled = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Hides the Restart button on the login screen. Default is false.
       '';
     };
@@ -70,8 +76,9 @@ with lib;
     system.defaults.loginwindow.ShutDownDisabledWhileLoggedIn = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Disables the "Shutdown" option when users are logged in. Default is false.
       '';
     };
@@ -79,8 +86,9 @@ with lib;
     system.defaults.loginwindow.PowerOffDisabledWhileLoggedIn = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      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.
       '';
     };
@@ -88,8 +96,9 @@ with lib;
     system.defaults.loginwindow.RestartDisabledWhileLoggedIn = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Disables the “Restart” option when users are logged in. Default is false.
       '';
     };
@@ -97,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 8f256f3..4b535d1 100644
--- a/modules/system/defaults/spaces.nix
+++ b/modules/system/defaults/spaces.nix
@@ -7,8 +7,9 @@ with lib;
     system.defaults.spaces.spans-displays = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
-        # Apple menu > System Preferences > Mission Control
+      description = lib.mdDoc ''
+        Apple menu > System Preferences > Mission Control
+
         Displays have separate Spaces (note a logout is required before
         this setting will take effect).
 
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 6d6a974..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.
       '';
@@ -37,7 +37,7 @@ with lib;
     system.defaults.universalaccess.closeViewZoomFollowsFocus = mkOption {
       type = types.nullOr types.bool;
       default = null;
-      description = ''
+      description = lib.mdDoc ''
         Follow the keyboard focus while zoomed in.
         Without setting `closeViewScrollWheelToggle` this has no effect.
         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 452ed3b..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>This can modify everything so use with caution.</para>
-        </warning>
+        ::: {.warning}
+        
+        This can modify everything so use with caution.
+        
+        :::
 
         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.";
     };
   };