diff --git a/default.nix b/default.nix
index b665b7a6..541a5a38 100644
--- a/default.nix
+++ b/default.nix
@@ -1,7 +1,11 @@
 { pkgs ? import <nixpkgs> { } }:
 
 rec {
-  docs = with import ./docs { inherit pkgs; }; {
+  docs = let releaseInfo = pkgs.lib.importJSON ./release.json;
+  in with import ./docs {
+    inherit pkgs;
+    inherit (releaseInfo) release isReleaseBranch;
+  }; {
     html = manual.html;
     manPages = manPages;
     json = options.json;
diff --git a/docs/contributing.adoc b/docs/contributing.adoc
index 54dc2692..3a1805f2 100644
--- a/docs/contributing.adoc
+++ b/docs/contributing.adoc
@@ -94,11 +94,11 @@ All contributed code _must_ pass the test suite.
 [[sec-guidelines-module-maintainer]]
 
 ==== Add relevant documentation
+:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
 :docbook: https://tdg.docbook.org/
 :asciidoc: https://asciidoc.org/
-:docbook-rocks: https://berbiche.github.io/docbook.rocks/
 
-Many code changes require changing the documentation as well. Module options should be documented with DocBook. See {docbook-rocks}[DocBook rocks!] for a quick introduction and {docbook}[DocBook 5: The Definitive Guide] for in-depth information of DocBook. Home Manager is itself documented using a combination of DocBook and {asciidoc}[AsciiDoc]. All text is hosted in Home Manager's Git repository.
+Many code changes require changing the documentation as well. Module options should be documented with {nixpkgs-markdown}[Nixpkgs-flavoured Markdown]. Home Manager is itself documented using a combination of {docbook}[DocBook] and {asciidoc}[AsciiDoc]. All text is hosted in Home Manager's Git repository.
 
 The HTML version of the manual containing both the module option descriptions and the documentation of Home Manager can be generated and opened by typing the following in a shell within a clone of the Home Manager Git repository:
 
diff --git a/docs/default.nix b/docs/default.nix
index fb51a751..c6c92bd2 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -1,7 +1,9 @@
 { pkgs
 
 # Note, this should be "the standard library" + HM extensions.
-, lib ? import ../modules/lib/stdlib-extended.nix pkgs.lib }:
+, lib ? import ../modules/lib/stdlib-extended.nix pkgs.lib
+
+, release, isReleaseBranch }:
 
 let
 
@@ -11,7 +13,16 @@ let
     sha256 = "0vvj40k6bw8ssra8wil9rqbsznmfy1kwy7cihvm13rajwdg9ycgg";
   };
 
-  nmd = import nmdSrc { inherit lib pkgs; };
+  nmd = import nmdSrc {
+    inherit lib;
+    # The DocBook output of `nixos-render-docs` doesn't have the change
+    # `nmd` uses to work around the broken stylesheets in
+    # `docbook-xsl-ns`, so we restore the patched version here.
+    pkgs = pkgs // {
+      docbook-xsl-ns =
+        pkgs.docbook-xsl-ns.override { withManOptDedupPatch = true; };
+    };
+  };
 
   # Make sure the used package is scrubbed to avoid actually
   # instantiating derivations.
@@ -26,42 +37,66 @@ let
 
   dontCheckDefinitions = { _module.check = false; };
 
-  buildModulesDocs = args:
-    nmd.buildModulesDocs ({
-      moduleRootPaths = [ ./.. ];
-      mkModuleUrl = path:
-        "https://github.com/nix-community/home-manager/blob/master/${path}#blob-path";
-      channelName = "home-manager";
-    } // args);
+  gitHubDeclaration = user: repo: subpath:
+    let urlRef = if isReleaseBranch then "release-${release}" else "master";
+    in {
+      url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}";
+      name = "<${repo}/${subpath}>";
+    };
 
-  hmModulesDocs = buildModulesDocs {
+  hmPath = toString ./..;
+
+  buildOptionsDocs = args@{ modules, ... }:
+    pkgs.buildPackages.nixosOptionsDoc ({
+      options = (lib.evalModules { inherit modules; }).options;
+      transformOptions = opt:
+        opt // {
+          # Clean up declaration sites to not refer to the Home Manager
+          # source tree.
+          declarations = map (decl:
+            if lib.hasPrefix hmPath (toString decl) then
+              gitHubDeclaration "nix-community" "home-manager"
+              (lib.removePrefix "/" (lib.removePrefix hmPath (toString decl)))
+            else if decl == "lib/modules.nix" then
+            # TODO: handle this in a better way (may require upstream
+            # changes to nixpkgs)
+              gitHubDeclaration "NixOS" "nixpkgs" decl
+            else
+              decl) opt.declarations;
+        };
+    } // builtins.removeAttrs args [ "modules" ]);
+
+  hmOptionsDocs = buildOptionsDocs {
     modules = import ../modules/modules.nix {
       inherit lib pkgs;
       check = false;
     } ++ [ scrubbedPkgsModule ];
-    docBook.id = "home-manager-options";
+    variablelistId = "home-manager-options";
   };
 
-  nixosModuleDocs = buildModulesDocs {
+  nixosOptionsDocs = buildOptionsDocs {
     modules = [ ../nixos scrubbedPkgsModule dontCheckDefinitions ];
-    docBook = {
-      id = "nixos-options";
-      optionIdPrefix = "nixos-opt";
-    };
+    variablelistId = "nixos-options";
+    optionIdPrefix = "nixos-opt-";
   };
 
-  nixDarwinModuleDocs = buildModulesDocs {
+  nixDarwinOptionsDocs = buildOptionsDocs {
     modules = [ ../nix-darwin scrubbedPkgsModule dontCheckDefinitions ];
-    docBook = {
-      id = "nix-darwin-options";
-      optionIdPrefix = "nix-darwin-opt";
-    };
+    variablelistId = "nix-darwin-options";
+    optionIdPrefix = "nix-darwin-opt-";
   };
 
   docs = nmd.buildDocBookDocs {
     pathName = "home-manager";
     projectName = "Home Manager";
-    modulesDocs = [ hmModulesDocs nixDarwinModuleDocs nixosModuleDocs ];
+    modulesDocs = [{
+      docBook = pkgs.linkFarm "hm-module-docs-for-nmd" {
+        "nmd-result/home-manager-options.xml" = hmOptionsDocs.optionsDocBook;
+        "nmd-result/nix-darwin-options.xml" =
+          nixDarwinOptionsDocs.optionsDocBook;
+        "nmd-result/nixos-options.xml" = nixosOptionsDocs.optionsDocBook;
+      };
+    }];
     documentsDirectory = ./.;
     documentType = "book";
     chunkToc = ''
@@ -81,9 +116,20 @@ in {
   inherit nmdSrc;
 
   options = {
-    json = hmModulesDocs.json.override {
-      path = "share/doc/home-manager/options.json";
-    };
+    # TODO: Use `hmOptionsDocs.optionsJSON` directly once upstream
+    # `nixosOptionsDoc` is more customizable.
+    json = pkgs.runCommand "options.json" {
+      meta.description = "List of Home Manager options in JSON format";
+    } ''
+      mkdir -p $out/{share/doc,nix-support}
+      cp -a ${hmOptionsDocs.optionsJSON}/share/doc/nixos $out/share/doc/home-manager
+      substitute \
+        ${hmOptionsDocs.optionsJSON}/nix-support/hydra-build-products \
+        $out/nix-support/hydra-build-products \
+        --replace \
+          '${hmOptionsDocs.optionsJSON}/share/doc/nixos' \
+          "$out/share/doc/home-manager"
+    '';
   };
 
   manPages = docs.manPages;
diff --git a/docs/man-configuration.xml b/docs/man-configuration.xml
index ce35feb7..a7d1f511 100644
--- a/docs/man-configuration.xml
+++ b/docs/man-configuration.xml
@@ -26,7 +26,7 @@
    You can use the following options in
    <filename>home-configuration.nix</filename>:
   </para>
-  <xi:include href="./nmd-result/home-manager-options.xml" />
+  <xi:include href="./nmd-result/home-manager-options.xml" xpointer="home-manager-options" />
  </refsection>
  <refsection>
    <title>See also</title>
diff --git a/docs/manual.xml b/docs/manual.xml
index 22cfd970..af757caf 100644
--- a/docs/manual.xml
+++ b/docs/manual.xml
@@ -39,15 +39,15 @@
  <xi:include href="faq.xml" />
  <appendix xml:id="ch-options">
   <title>Configuration Options</title>
-  <xi:include href="./nmd-result/home-manager-options.xml" />
+  <xi:include href="./nmd-result/home-manager-options.xml" xpointer="home-manager-options" />
  </appendix>
  <appendix xml:id="ch-nixos-options">
   <title>NixOS Module Options</title>
-  <xi:include href="./nmd-result/nixos-options.xml" />
+  <xi:include href="./nmd-result/nixos-options.xml" xpointer="nixos-options" />
  </appendix>
  <appendix xml:id="ch-nix-darwin-options">
   <title>nix-darwin Module Options</title>
-  <xi:include href="./nmd-result/nix-darwin-options.xml" />
+  <xi:include href="./nmd-result/nix-darwin-options.xml" xpointer="nix-darwin-options" />
  </appendix>
  <appendix xml:id="ch-tools">
   <title>Tools</title>
diff --git a/docs/release-notes/rl-2311.adoc b/docs/release-notes/rl-2311.adoc
index 4ac3a647..4947b809 100644
--- a/docs/release-notes/rl-2311.adoc
+++ b/docs/release-notes/rl-2311.adoc
@@ -5,17 +5,33 @@ This is the current unstable branch and the information in this section is there
 
 [[sec-release-23.11-highlights]]
 === Highlights
+:babelfish: https://github.com/bouk/babelfish
+:nixpkgs-markdown: https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
 
 This release has the following notable changes:
 
 * When using <<opt-programs.fish.enable>>, the setup code
 for <<opt-home.sessionVariables>> is now translated
-with https://github.com/bouk/babelfish[babelfish].
+with {babelfish}[babelfish].
 This should result in significantly faster shell startup times
 but could theoretically break
 if you have very complex bash expressions in a session variable.
 Please report any issues you experience.
 
+* The `.release` file in the Home Manager source tree
+has been supplanted by `release.json`,
+which contains more information about the branch.
+If you have any external code reading this file,
+please switch to consuming `release.json` instead.
+The `.release` file will be removed in 24.05.
+
+* Home Manager has migrated to using
+the upstream Nixpkgs `lib.nixosOptionsDoc` processor
+for option documentation.
+If you have any external Home Manager modules,
+their option descriptions and literal examples should be translated
+to {nixpkgs-markdown}[Nixpkgs-flavoured Markdown].
+
 [[sec-release-23.11-state-version-changes]]
 === State Version Changes
 
diff --git a/flake.lock b/flake.lock
index e9fa54e6..5ef1dda7 100644
--- a/flake.lock
+++ b/flake.lock
@@ -2,15 +2,15 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1689373857,
-        "narHash": "sha256-mtBksyvhhT98Zsm9tYHuMKuLwUKDwv+BGTl6K5nOGhY=",
-        "owner": "nixos",
+        "lastModified": 1689534811,
+        "narHash": "sha256-jnSUdzD/414d94plCyNlvTJJtiTogTep6t7ZgIKIHiE=",
+        "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "dfdbcc428f365071f0ca3888f6ec8c25c3792885",
+        "rev": "6cee3b5893090b0f5f0a06b4cf42ca4e60e5d222",
         "type": "github"
       },
       "original": {
-        "owner": "nixos",
+        "owner": "NixOS",
         "ref": "nixos-unstable",
         "repo": "nixpkgs",
         "type": "github"
diff --git a/flake.nix b/flake.nix
index 5e354f78..a1c81635 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1,7 +1,7 @@
 {
   description = "Home Manager for Nix";
 
-  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
 
   outputs = { self, nixpkgs, ... }:
     {
@@ -103,7 +103,11 @@
       packages = forAllSystems (system:
         let
           pkgs = nixpkgs.legacyPackages.${system};
-          docs = import ./docs { inherit pkgs; };
+          releaseInfo = nixpkgs.lib.importJSON ./release.json;
+          docs = import ./docs {
+            inherit pkgs;
+            inherit (releaseInfo) release isReleaseBranch;
+          };
           hmPkg = pkgs.callPackage ./home-manager { path = toString ./.; };
         in {
           default = hmPkg;
diff --git a/modules/accounts/email.nix b/modules/accounts/email.nix
index 897aef6d..f33b3ffe 100644
--- a/modules/accounts/email.nix
+++ b/modules/accounts/email.nix
@@ -11,7 +11,7 @@ let
       key = mkOption {
         type = types.str;
         description = ''
-          The key to use as listed in <command>gpg --list-keys</command>.
+          The key to use as listed in {command}`gpg --list-keys`.
         '';
       };
 
@@ -99,7 +99,7 @@ let
         description = ''
           Path to file containing certificate authorities that should
           be used to validate the connection authenticity. If
-          <literal>null</literal> then the system default is used.
+          `null` then the system default is used.
           Note, if set then the system default may still be accepted.
         '';
       };
@@ -122,7 +122,7 @@ let
         example = 993;
         description = ''
           The port on which the IMAP server listens. If
-          <literal>null</literal> then the default port is used.
+          `null` then the default port is used.
         '';
       };
 
@@ -144,10 +144,9 @@ let
         example = "jmap.example.org";
         description = ''
           Hostname of JMAP server.
-          </para><para>
-          If both this option and <xref
-          linkend="opt-accounts.email.accounts._name_.jmap.sessionUrl"/> are specified,
-          <code>host</code> is preferred by applications when establishing a
+
+          If both this option and [](#opt-accounts.email.accounts._name_.jmap.sessionUrl) are specified,
+          `host` is preferred by applications when establishing a
           session.
         '';
       };
@@ -158,10 +157,9 @@ let
         example = "https://jmap.example.org:443/.well-known/jmap";
         description = ''
           URL for the JMAP Session resource.
-          </para><para>
-          If both this option and <xref
-          linkend="opt-accounts.email.accounts._name_.jmap.host"/> are specified,
-          <code>host</code> is preferred by applications when establishing a
+
+          If both this option and [](#opt-accounts.email.accounts._name_.jmap.host) are specified,
+          `host` is preferred by applications when establishing a
           session.
         '';
       };
@@ -184,7 +182,7 @@ let
         example = 465;
         description = ''
           The port on which the SMTP server listens. If
-          <literal>null</literal> then the default port is used.
+          `null` then the default port is used.
         '';
       };
 
@@ -255,7 +253,7 @@ let
           Some email providers have peculiar behavior that require
           special treatment. This option is therefore intended to
           indicate the nature of the provider.
-          </para><para>
+
           When this indicates a specific provider then, for example,
           the IMAP, SMTP, and JMAP server configuration may be set
           automatically.
diff --git a/modules/config/home-cursor.nix b/modules/config/home-cursor.nix
index ee0f2555..a64ccc50 100644
--- a/modules/config/home-cursor.nix
+++ b/modules/config/home-cursor.nix
@@ -29,7 +29,7 @@ let
 
       x11 = {
         enable = mkEnableOption ''
-          x11 config generation for <option>home.pointerCursor</option>
+          x11 config generation for {option}`home.pointerCursor`
         '';
 
         defaultCursor = mkOption {
@@ -42,7 +42,7 @@ let
 
       gtk = {
         enable = mkEnableOption ''
-          gtk config generation for <option>home.pointerCursor</option>
+          gtk config generation for {option}`home.pointerCursor`
         '';
       };
     };
@@ -95,20 +95,20 @@ in {
       type = types.nullOr pointerCursorModule;
       default = null;
       description = ''
-        Cursor configuration. Set to <literal>null</literal> to disable.
-        </para><para>
+        Cursor configuration. Set to `null` to disable.
+
         Top-level options declared under this submodule are backend independent
-        options. Options declared under namespaces such as <literal>x11</literal>
+        options. Options declared under namespaces such as `x11`
         are backend specific options. By default, only backend independent cursor
         configurations are generated. If you need configurations for specific
         backends, you can toggle them via the enable option. For example,
-        <xref linkend="opt-home.pointerCursor.x11.enable"/>
+        [](#opt-home.pointerCursor.x11.enable)
         will enable x11 cursor configurations.
-        </para><para>
+
         Note that this will merely generate the cursor configurations.
         To apply the configurations, the relevant subsytems must also be configured.
-        For example, <xref linkend="opt-home.pointerCursor.gtk.enable"/> will generate
-        the gtk cursor configuration, but <xref linkend="opt-gtk.enable"/> needs
+        For example, [](#opt-home.pointerCursor.gtk.enable) will generate
+        the gtk cursor configuration, but [](#opt-gtk.enable) needs
         to be set for it to be applied.
       '';
     };
diff --git a/modules/config/i18n.nix b/modules/config/i18n.nix
index d5619afb..2efb53d6 100644
--- a/modules/config/i18n.nix
+++ b/modules/config/i18n.nix
@@ -41,13 +41,13 @@ in {
     i18n.glibcLocales = mkOption {
       type = types.path;
       description = ''
-        Customized <literal>glibcLocales</literal> package providing
-        the <literal>LOCALE_ARCHIVE_*</literal> environment variable.
-        </para><para>
+        Customized `glibcLocales` package providing
+        the `LOCALE_ARCHIVE_*` environment variable.
+
         This option only applies to the Linux platform.
-        </para><para>
+
         When Home Manager is configured with NixOS, the default value
-        will be set to <varname>i18n.glibcLocales</varname> from the
+        will be set to {var}`i18n.glibcLocales` from the
         system configuration.
       '';
       example = literalExpression ''
diff --git a/modules/files.nix b/modules/files.nix
index af52b58c..c869df1d 100644
--- a/modules/files.nix
+++ b/modules/files.nix
@@ -28,7 +28,7 @@ in
     home.file = mkOption {
       description = "Attribute set of files to link into the user home.";
       default = {};
-      type = fileType "home.file" "<envar>HOME</envar>" homeDirectory;
+      type = fileType "home.file" "{env}`HOME`" homeDirectory;
     };
 
     home-files = mkOption {
diff --git a/modules/home-environment.nix b/modules/home-environment.nix
index 48d08580..722812cc 100644
--- a/modules/home-environment.nix
+++ b/modules/home-environment.nix
@@ -119,11 +119,11 @@ let
           else "us";
         defaultText = literalExpression "null";
         description = ''
-          Keyboard layout. If <literal>null</literal>, then the system
+          Keyboard layout. If `null`, then the system
           configuration will be used.
-          </para><para>
-          This defaults to <literal>null</literal> for state
-          version ≥ 19.09 and <literal>"us"</literal> otherwise.
+
+          This defaults to `null` for state
+          version ≥ 19.09 and `"us"` otherwise.
         '';
       };
 
@@ -154,11 +154,11 @@ let
         defaultText = literalExpression "null";
         example = "colemak";
         description = ''
-          X keyboard variant. If <literal>null</literal>, then the
+          X keyboard variant. If `null`, then the
           system configuration will be used.
-          </para><para>
-          This defaults to <literal>null</literal> for state
-          version ≥ 19.09 and <literal>""</literal> otherwise.
+
+          This defaults to `null` for state
+          version ≥ 19.09 and `""` otherwise.
         '';
       };
     };
@@ -229,7 +229,7 @@ in
         "null" for state version ≥ 21.11
       '';
       description = ''
-        Keyboard configuration. Set to <literal>null</literal> to
+        Keyboard configuration. Set to `null` to
         disable Home Manager keyboard management.
       '';
     };
@@ -246,11 +246,11 @@ in
       description = ''
         An attribute set that maps aliases (the top level attribute names
         in this option) to command strings or directly to build outputs.
-        </para><para>
+
         This option should only be used to manage simple aliases that are
         compatible across all shells. If you need to use a shell specific
         feature then make sure to use a shell specific option, for example
-        <xref linkend="opt-programs.bash.shellAliases"/> for Bash.
+        [](#opt-programs.bash.shellAliases) for Bash.
       '';
     };
 
@@ -260,34 +260,34 @@ in
       example = { EDITOR = "emacs"; GS_OPTIONS = "-sPAPERSIZE=a4"; };
       description = ''
         Environment variables to always set at login.
-        </para><para>
+
         The values may refer to other environment variables using
         POSIX.2 style variable references. For example, a variable
-        <varname>parameter</varname> may be referenced as
-        <code>$parameter</code> or <code>''${parameter}</code>. A
-        default value <literal>foo</literal> may be given as per
-        <code>''${parameter:-foo}</code> and, similarly, an alternate
-        value <literal>bar</literal> can be given as per
-        <code>''${parameter:+bar}</code>.
-        </para><para>
+        {var}`parameter` may be referenced as
+        `$parameter` or `''${parameter}`. A
+        default value `foo` may be given as per
+        `''${parameter:-foo}` and, similarly, an alternate
+        value `bar` can be given as per
+        `''${parameter:+bar}`.
+
         Note, these variables may be set in any order so no session
         variable may have a runtime dependency on another session
         variable. In particular code like
-        <programlisting language="nix">
+        ```nix
         home.sessionVariables = {
           FOO = "Hello";
           BAR = "$FOO World!";
         };
-        </programlisting>
+        ```
         may not work as expected. If you need to reference another
         session variable, then do so inside Nix instead. The above
         example then becomes
-        <programlisting language="nix">
+        ```nix
         home.sessionVariables = {
           FOO = "Hello";
           BAR = "''${config.home.sessionVariables.FOO} World!";
         };
-        </programlisting>
+        ```
       '';
     };
 
@@ -296,7 +296,7 @@ in
       internal = true;
       description = ''
         The package containing the
-        <filename>hm-session-vars.sh</filename> file.
+        {file}`hm-session-vars.sh` file.
       '';
     };
 
@@ -309,14 +309,12 @@ in
         ".git/safe/../../bin"
       ];
       description = ''
-        Extra directories to add to <envar>PATH</envar>.
+        Extra directories to add to {env}`PATH`.
 
-        </para><para>
-
-        These directories are added to the <envar>PATH</envar> variable in a
-        double-quoted context, so expressions like <code>$HOME</code> are
-        expanded by the shell. However, since expressions like <code>~</code> or
-        <code>*</code> are escaped, they will end up in the <envar>PATH</envar>
+        These directories are added to the {env}`PATH` variable in a
+        double-quoted context, so expressions like `$HOME` are
+        expanded by the shell. However, since expressions like `~` or
+        `*` are escaped, they will end up in the {env}`PATH`
         verbatim.
       '';
     };
@@ -327,7 +325,7 @@ in
       internal = true;
       description = ''
         Extra configuration to add to the
-        <filename>hm-session-vars.sh</filename> file.
+        {file}`hm-session-vars.sh` file.
       '';
     };
 
@@ -343,7 +341,7 @@ in
       example = [ "doc" "info" "devdoc" ];
       description = ''
         List of additional package outputs of the packages
-        <varname>home.packages</varname> that should be installed into
+        {var}`home.packages` that should be installed into
         the user environment.
       '';
     };
@@ -363,9 +361,9 @@ in
       '';
       description = ''
         Whether the activation script should start with an empty
-        <envar>PATH</envar> variable. When <literal>false</literal> then the
-        user's <envar>PATH</envar> will be accessible in the script. It is
-        recommended to keep this at <literal>true</literal> to avoid
+        {env}`PATH` variable. When `false` then the
+        user's {env}`PATH` will be accessible in the script. It is
+        recommended to keep this at `true` to avoid
         uncontrolled use of tools found in PATH.
       '';
     };
@@ -387,35 +385,29 @@ in
         meaning running twice or more times produces the same result
         as running it once.
 
-        </para><para>
-
         If the script block produces any observable side effect, such
         as writing or deleting files, then it
-        <emphasis>must</emphasis> be placed after the special
-        <literal>writeBoundary</literal> script block. Prior to the
+        *must* be placed after the special
+        `writeBoundary` script block. Prior to the
         write boundary one can place script blocks that verifies, but
         does not modify, the state of the system and exits if an
         unexpected state is found. For example, the
-        <literal>checkLinkTargets</literal> script block checks for
+        `checkLinkTargets` script block checks for
         collisions between non-managed files and files defined in
-        <xref linkend="opt-home.file"/>.
+        [](#opt-home.file).
 
-        </para><para>
-
-        A script block should respect the <varname>DRY_RUN</varname>
+        A script block should respect the {var}`DRY_RUN`
         variable, if it is set then the actions taken by the script
         should be logged to standard out and not actually performed.
-        The variable <varname>DRY_RUN_CMD</varname> is set to
-        <command>echo</command> if dry run is enabled.
-
-        </para><para>
+        The variable {var}`DRY_RUN_CMD` is set to
+        {command}`echo` if dry run is enabled.
 
         A script block should also respect the
-        <varname>VERBOSE</varname> variable, and if set print
+        {var}`VERBOSE` variable, and if set print
         information on standard out that may be useful for debugging
         any issue that may arise. The variable
-        <varname>VERBOSE_ARG</varname> is set to
-        <option>--verbose</option> if verbose output is enabled.
+        {var}`VERBOSE_ARG` is set to
+        {option}`--verbose` if verbose output is enabled.
       '';
     };
 
@@ -430,7 +422,7 @@ in
       type = types.listOf types.package;
       default = [ ];
       description = ''
-        Extra packages to add to <envar>PATH</envar> within the activation
+        Extra packages to add to {env}`PATH` within the activation
         script.
       '';
     };
@@ -462,7 +454,7 @@ in
         and unexpected behavior. It is therefore highly recommended to use a
         release of Home Manager that corresponds with your chosen release of
         Nixpkgs.
-        </para><para>
+
         When this option is enabled and a mismatch is detected then a warning
         will be printed when the user configuration is being built.
       '';
@@ -483,8 +475,8 @@ in
 
     warnings =
       let
-        hmRelease = fileContents ../.release;
-        nixpkgsRelease = pkgs.lib.trivial.release;
+        hmRelease = config.home.version.release;
+        nixpkgsRelease = lib.trivial.release;
         releaseMismatch =
           config.home.enableNixpkgsReleaseCheck
           && hmRelease != nixpkgsRelease;
diff --git a/modules/i18n/input-method/default.nix b/modules/i18n/input-method/default.nix
index e0d95e6f..5e3a89b3 100644
--- a/modules/i18n/input-method/default.nix
+++ b/modules/i18n/input-method/default.nix
@@ -32,46 +32,32 @@ in {
         default = null;
         example = "fcitx5";
         description = ''
-          Select the enabled input method. Input methods is a software to input
+          Select the enabled input method. Input methods are software to input
           symbols that are not available on standard input devices.
-          </para><para>
-          Input methods are specially used to input Chinese, Japanese and Korean
-          characters.
-          </para><para>
+
+          Input methods are especially used to input Chinese, Japanese and
+          Korean characters.
+
           Currently the following input methods are available in Home Manager:
 
-          <variablelist>
-          <varlistentry>
-            <term><literal>fcitx5</literal></term>
-            <listitem><para>
-              A customizable lightweight input method.
-              The next generation of fcitx,
-              addons (including engines, dictionaries, skins) can be added using
-              <literal>i18n.inputMethod.fcitx5.addons</literal>.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>nabi</literal></term>
-            <listitem><para>
-              A Korean input method based on XIM. Nabi doesn't support Qt 5.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>uim</literal></term>
-            <listitem><para>
-              The universal input method, is a library with a XIM bridge.
-              uim mainly support Chinese, Japanese and Korean.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>hime</literal></term>
-            <listitem><para>An extremely easy-to-use input method framework.</para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>kime</literal></term>
-            <listitem><para>A Korean IME.</para></listitem>
-          </varlistentry>
-          </variablelist>
+          `fcitx5`
+          : A customizable lightweight input method.
+            The next generation of fcitx.
+            Addons (including engines, dictionaries, skins) can be added using
+            [](#opt-i18n.inputMethod.fcitx5.addons).
+
+          `nabi`
+          : A Korean input method based on XIM. Nabi doesn't support Qt 5.
+
+          `uim`
+          : The "universal input method" is a library with an XIM bridge.
+            uim mainly supports Chinese, Japanese and Korean.
+
+          `hime`
+          : An extremely easy-to-use input method framework.
+
+          `kime`
+          : A Korean IME.
         '';
       };
 
diff --git a/modules/i18n/input-method/kime.nix b/modules/i18n/input-method/kime.nix
index 70f32190..5608b54e 100644
--- a/modules/i18n/input-method/kime.nix
+++ b/modules/i18n/input-method/kime.nix
@@ -28,7 +28,7 @@ in {
         '';
         description = ''
           kime configuration. Refer to
-          <link xlink:href="https://github.com/Riey/kime/blob/develop/docs/CONFIGURATION.md"/>
+          <https://github.com/Riey/kime/blob/develop/docs/CONFIGURATION.md>
           for details on supported values.
         '';
       };
diff --git a/modules/launchd/default.nix b/modules/launchd/default.nix
index 3d849bef..90e5360d 100644
--- a/modules/launchd/default.nix
+++ b/modules/launchd/default.nix
@@ -28,9 +28,7 @@ let
           }
         '';
         description = ''
-          Define a launchd job. See <citerefentry>
-          <refentrytitle>launchd.plist</refentrytitle><manvolnum>5</manvolnum>
-          </citerefentry> for details.
+          Define a launchd job. See {manpage}`launchd.plist(5)` for details.
         '';
       };
     };
diff --git a/modules/launchd/launchd.nix b/modules/launchd/launchd.nix
index 4ecdad4e..9c9b5445 100644
--- a/modules/launchd/launchd.nix
+++ b/modules/launchd/launchd.nix
@@ -40,17 +40,17 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        This optional key is used as a hint to <literal>launchctl(1)</literal> that it should not submit this job to launchd when
+        This optional key is used as a hint to `launchctl(1)` that it should not submit this job to launchd when
         loading a job or jobs. The value of this key does NOT reflect the current state of the job on the running
         system. If you wish to know whether a job is loaded in launchd, reading this key from a configuration
         file yourself is not a sufficient test. You should query launchd for the presence of the job using
-        the <literal>launchctl(1)</literal> list subcommand or use the ServiceManagement framework's
-        <literal>SMJobCopyDictionary()</literal> method.
+        the `launchctl(1)` list subcommand or use the ServiceManagement framework's
+        `SMJobCopyDictionary()` method.
 
         Note that as of Mac OS X v10.6, this key's value in a configuration file conveys a default value, which
-        is changed with the [-w] option of the <literal>launchctl(1)</literal> load and unload subcommands. These subcommands no
+        is changed with the [-w] option of the `launchctl(1)` load and unload subcommands. These subcommands no
         longer modify the configuration file, so the value displayed in the configuration file is not necessarily
-        the value that <literal>launchctl(1)</literal> will apply. See <literal>launchctl(1)</literal> for more information.
+        the value that `launchctl(1)` will apply. See `launchctl(1)` for more information.
 
         Please also be mindful that you should only use this key if the provided on-demand and KeepAlive criteria
         are insufficient to describe the conditions under which your job needs to run. The cost to have a
@@ -91,7 +91,7 @@ with lib;
             default = null;
             description = ''
               This flag corresponds to the "wait" or "nowait" option of inetd. If true, then the listening
-              socket is passed via the standard in/out/error file descriptors. If false, then <literal>accept(2)</literal> is
+              socket is passed via the standard in/out/error file descriptors. If false, then `accept(2)` is
               called on behalf of the job, and the result is passed via the standard in/out/error descriptors.
             '';
           };
@@ -104,7 +104,7 @@ with lib;
       default = null;
       description = ''
         This configuration file only applies to the hosts listed with this key. Note: One should set kern.hostname
-        in <literal>sysctl.conf(5)</literal> for this feature to work reliably.
+        in `sysctl.conf(5)` for this feature to work reliably.
       '';
     };
 
@@ -113,7 +113,7 @@ with lib;
       default = null;
       description = ''
         This configuration file only applies to hosts NOT listed with this key. Note: One should set kern.hostname
-        in <literal>sysctl.conf(5)</literal> for this feature to work reliably.
+        in `sysctl.conf(5)` for this feature to work reliably.
       '';
     };
 
@@ -122,7 +122,7 @@ with lib;
       default = null;
       description = ''
         This configuration file only applies to sessions of the type specified. This key is used in concert
-        with the -S flag to <command>launchctl</command>.
+        with the -S flag to {command}`launchctl`.
       '';
     };
 
@@ -130,7 +130,7 @@ with lib;
       type = types.nullOr types.path;
       default = null;
       description = ''
-        This key maps to the first argument of <literal>execvp(3)</literal>.  If this key is missing, then the first element of
+        This key maps to the first argument of `execvp(3)`.  If this key is missing, then the first element of
         the array of strings provided to the ProgramArguments will be used instead.  This key is required in
         the absence of the ProgramArguments key.
       '';
@@ -140,8 +140,8 @@ with lib;
       type = types.nullOr (types.listOf types.str);
       default = null;
       description = ''
-        This key maps to the second argument of <literal>execvp(3)</literal>.  This key is required in the absence of the Program
-        key. Please note: many people are confused by this key. Please read <literal>execvp(3)</literal> very carefully!
+        This key maps to the second argument of `execvp(3)`.  This key is required in the absence of the Program
+        key. Please note: many people are confused by this key. Please read `execvp(3)` very carefully!
       '';
     };
 
@@ -149,7 +149,7 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        This flag causes launchd to use the <literal>glob(3)</literal> mechanism to update the program arguments before invocation.
+        This flag causes launchd to use the `glob(3)` mechanism to update the program arguments before invocation.
       '';
     };
 
@@ -157,8 +157,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        This flag instructs launchd that the job promises to use <literal>vproc_transaction_begin(3)</literal> and
-        <literal>vproc_transaction_end(3)</literal> to track outstanding transactions that need to be reconciled before the
+        This flag instructs launchd that the job promises to use `vproc_transaction_begin(3)` and
+        `vproc_transaction_end(3)` to track outstanding transactions that need to be reconciled before the
         process can safely terminate. If no outstanding transactions are in progress, then launchd is free to
         send the SIGKILL signal.
       '';
@@ -263,7 +263,7 @@ with lib;
       type = types.nullOr types.str;
       default = null;
       description = ''
-        This optional key is used to specify a directory to <literal>chroot(2)</literal> to before running the job.
+        This optional key is used to specify a directory to `chroot(2)` to before running the job.
       '';
     };
 
@@ -271,7 +271,7 @@ with lib;
       type = types.nullOr types.str;
       default = null;
       description = ''
-        This optional key is used to specify a directory to <literal>chdir(2)</literal> to before running the job.
+        This optional key is used to specify a directory to `chdir(2)` to before running the job.
       '';
     };
 
@@ -288,7 +288,7 @@ with lib;
       type = types.nullOr types.int;
       default = null;
       description = ''
-        This optional key specifies what value should be passed to <literal>umask(2)</literal> before running the job. Known bug:
+        This optional key specifies what value should be passed to `umask(2)` before running the job. Known bug:
         Property lists don't support octal, so please convert the value to decimal.
       '';
     };
@@ -327,7 +327,7 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        This optional key specifies whether <literal>initgroups(3)</literal> should be called before running the job.  The default
+        This optional key specifies whether `initgroups(3)` should be called before running the job.  The default
         is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set.
       '';
     };
@@ -375,7 +375,7 @@ with lib;
       };
       description = ''
         This optional key causes the job to be started every calendar interval as specified. Missing arguments
-        are considered to be wildcard. The semantics are much like <literal>crontab(5)</literal>.  Unlike cron which skips job
+        are considered to be wildcard. The semantics are much like `crontab(5)`.  Unlike cron which skips job
         invocations when the computer is asleep, launchd will start the job the next time the computer wakes
         up.  If multiple intervals transpire before the computer is woken, those events will be coalesced into
         one event upon wake from sleep.
@@ -430,7 +430,7 @@ with lib;
       default = null;
       description = ''
         This optional key specifies what file should be used for data being supplied to stdin when using
-        <literal>stdio(3)</literal>.
+        `stdio(3)`.
       '';
     };
 
@@ -438,7 +438,7 @@ with lib;
       type = types.nullOr types.path;
       default = null;
       description = ''
-        This optional key specifies what file should be used for data being sent to stdout when using <literal>stdio(3)</literal>.
+        This optional key specifies what file should be used for data being sent to stdout when using `stdio(3)`.
       '';
     };
 
@@ -446,7 +446,7 @@ with lib;
       type = types.nullOr types.path;
       default = null;
       description = ''
-        This optional key specifies what file should be used for data being sent to stderr when using <literal>stdio(3)</literal>.
+        This optional key specifies what file should be used for data being sent to stderr when using `stdio(3)`.
       '';
     };
 
@@ -471,7 +471,7 @@ with lib;
     SoftResourceLimits = mkOption {
       default = null;
       description = ''
-        Resource limits to be imposed on the job. These adjust variables set with <literal>setrlimit(2)</literal>.  The following
+        Resource limits to be imposed on the job. These adjust variables set with `setrlimit(2)`.  The following
         keys apply:
       '';
       type = types.nullOr (types.submodule {
@@ -497,7 +497,7 @@ with lib;
             default = null;
             description = ''
               The maximum size (in bytes) of the data segment for a process; this defines how far a program may
-              extend its break with the <literal>sbrk(2)</literal> system call.
+              extend its break with the `sbrk(2)` system call.
             '';
           };
 
@@ -522,8 +522,8 @@ with lib;
             default = null;
             description = ''
               The maximum number of open files for this process.  Setting this value in a system wide daemon
-              will set the <literal>sysctl(3)</literal> kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
-              value in addition to the <literal>setrlimit(2)</literal> values.
+              will set the `sysctl(3)` kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
+              value in addition to the `setrlimit(2)` values.
             '';
           };
 
@@ -532,8 +532,8 @@ with lib;
             default = null;
             description = ''
               The maximum number of simultaneous processes for this user id.  Setting this value in a system
-              wide daemon will set the <literal>sysctl(3)</literal> kern.maxproc (SoftResourceLimits) or kern.maxprocperuid
-              (HardResourceLimits) value in addition to the <literal>setrlimit(2)</literal> values.
+              wide daemon will set the `sysctl(3)` kern.maxproc (SoftResourceLimits) or kern.maxprocperuid
+              (HardResourceLimits) value in addition to the `setrlimit(2)` values.
             '';
           };
 
@@ -563,7 +563,7 @@ with lib;
       default = null;
       example = { NumberOfFiles = 4096; };
       description = ''
-        Resource limits to be imposed on the job. These adjust variables set with <literal>setrlimit(2)</literal>.  The following
+        Resource limits to be imposed on the job. These adjust variables set with `setrlimit(2)`.  The following
         keys apply:
       '';
       type = types.nullOr (types.submodule {
@@ -589,7 +589,7 @@ with lib;
             default = null;
             description = ''
               The maximum size (in bytes) of the data segment for a process; this defines how far a program may
-              extend its break with the <literal>sbrk(2)</literal> system call.
+              extend its break with the `sbrk(2)` system call.
             '';
           };
 
@@ -605,7 +605,7 @@ with lib;
             type = types.nullOr types.int;
             default = null;
             description = ''
-              The maximum size (in bytes) which a process may lock into memory using the <literal>mlock(2)</literal> function.
+              The maximum size (in bytes) which a process may lock into memory using the `mlock(2)` function.
             '';
           };
 
@@ -614,8 +614,8 @@ with lib;
             default = null;
             description = ''
               The maximum number of open files for this process.  Setting this value in a system wide daemon
-              will set the <literal>sysctl(3)</literal> kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
-              value in addition to the <literal>setrlimit(2)</literal> values.
+              will set the `sysctl(3)` kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits)
+              value in addition to the `setrlimit(2)` values.
             '';
           };
 
@@ -624,8 +624,8 @@ with lib;
             default = null;
             description = ''
               The maximum number of simultaneous processes for this user id.  Setting this value in a system
-              wide daemon will set the <literal>sysctl(3)</literal> kern.maxproc (SoftResourceLimits) or kern.maxprocperuid
-              (HardResourceLimits) value in addition to the <literal>setrlimit(2)</literal> values.
+              wide daemon will set the `sysctl(3)` kern.maxproc (SoftResourceLimits) or kern.maxprocperuid
+              (HardResourceLimits) value in addition to the `setrlimit(2)` values.
             '';
           };
 
@@ -670,21 +670,21 @@ with lib;
         resource limits to the job, throttling its CPU usage and I/O bandwidth. The following are valid values:
 
            Background
-           Background jobs are generally processes that do work that was not directly requested by the user.
-           The resource limits applied to Background jobs are intended to prevent them from disrupting the
-           user experience.
+           : Background jobs are generally processes that do work that was not directly requested by the user.
+             The resource limits applied to Background jobs are intended to prevent them from disrupting the
+             user experience.
 
            Standard
-           Standard jobs are equivalent to no ProcessType being set.
+           :  Standard jobs are equivalent to no ProcessType being set.
 
            Adaptive
-           Adaptive jobs move between the Background and Interactive classifications based on activity over
-           XPC connections. See <literal>xpc_transaction_begin(3)</literal> for details.
+           :  Adaptive jobs move between the Background and Interactive classifications based on activity over
+              XPC connections. See {manpage}`xpc_transaction_begin(3)` for details.
 
            Interactive
-           Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive
-           jobs are critical to maintaining a responsive user experience, and this key should only be
-           used if an app's ability to be responsive depends on it, and cannot be made Adaptive.
+           :  Interactive jobs run with the same resource limitations as apps, that is to say, none. Interactive
+              jobs are critical to maintaining a responsive user experience, and this key should only be
+              used if an app's ability to be responsive depends on it, and cannot be made Adaptive.
       '';
     };
 
@@ -790,7 +790,7 @@ with lib;
         to be effectively equivalent, even though each file descriptor likely represents a different networking
         protocol which conforms to the criteria specified in the job configuration file.
 
-        The parameters below are used as inputs to call <literal>getaddrinfo(3)</literal>.
+        The parameters below are used as inputs to call `getaddrinfo(3)`.
       '';
       type = types.nullOr (types.attrsOf (types.submodule {
         options = {
@@ -807,7 +807,7 @@ with lib;
             type = types.nullOr types.bool;
             default = null;
             description = ''
-              This optional key specifies whether <literal>listen(2)</literal> or <literal>connect(2)</literal> should be called on the created file
+              This optional key specifies whether `listen(2)` or `connect(2)` should be called on the created file
               descriptor. The default is true ("to listen").
             '';
           };
@@ -816,7 +816,7 @@ with lib;
             type = types.nullOr types.str;
             default = null;
             description = ''
-              This optional key specifies the node to <literal>connect(2)</literal> or <literal>bind(2)</literal> to.
+              This optional key specifies the node to `connect(2)` or `bind(2)` to.
             '';
           };
 
@@ -824,7 +824,7 @@ with lib;
             type = types.nullOr types.str;
             default = null;
             description = ''
-              This optional key specifies the service on the node to <literal>connect(2)</literal> or <literal>bind(2)</literal> to.
+              This optional key specifies the service on the node to `connect(2)` or `bind(2)` to.
             '';
           };
 
@@ -840,7 +840,7 @@ with lib;
             type = types.nullOr (types.enum [ "TCP" ]);
             default = null;
             description = ''
-              This optional key specifies the protocol to be passed to <literal>socket(2)</literal>.  The only value understood by
+              This optional key specifies the protocol to be passed to `socket(2)`.  The only value understood by
               this key at the moment is "TCP".
             '';
           };
@@ -849,8 +849,8 @@ with lib;
             type = types.nullOr types.path;
             default = null;
             description = ''
-              This optional key implies SockFamily is set to "Unix". It specifies the path to <literal>connect(2)</literal> or
-              <literal>bind(2)</literal> to.
+              This optional key implies SockFamily is set to "Unix". It specifies the path to `connect(2)` or
+              `bind(2)` to.
             '';
           };
 
@@ -879,7 +879,7 @@ with lib;
             default = null;
             description = ''
               This optional key can be used to request that the service be registered with the
-              <literal>mDNSResponder(8)</literal>.  If the value is boolean, the service name is inferred from the SockServiceName.
+              `mDNSResponder(8)`.  If the value is boolean, the service name is inferred from the SockServiceName.
             '';
           };
 
@@ -888,7 +888,7 @@ with lib;
             default = null;
             description = ''
               This optional key can be used to request that the datagram socket join a multicast group.  If the
-              value is a hostname, then <literal>getaddrinfo(3)</literal> will be used to join the correct multicast address for a
+              value is a hostname, then `getaddrinfo(3)` will be used to join the correct multicast address for a
               given socket family.  If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily
               family also be set, otherwise the results are undefined.
             '';
diff --git a/modules/lib/file-type.nix b/modules/lib/file-type.nix
index a67f6bb0..cd3a3a62 100644
--- a/modules/lib/file-type.nix
+++ b/modules/lib/file-type.nix
@@ -42,7 +42,7 @@ in
           type = types.nullOr types.lines;
           description = ''
             Text of the file. If this option is null then
-            <xref linkend="opt-${opt}._name_.source"/>
+            [](#opt-${opt}._name_.source)
             must be set.
           '';
         };
@@ -51,7 +51,7 @@ in
           type = types.path;
           description = ''
             Path of the source file or directory. If
-            <xref linkend="opt-${opt}._name_.text"/>
+            [](#opt-${opt}._name_.text)
             is non-null then this option will automatically point to a file
             containing that text.
           '';
@@ -61,9 +61,9 @@ in
           type = types.nullOr types.bool;
           default = null;
           description = ''
-            Set the execute bit. If <literal>null</literal>, defaults to the mode
-            of the <varname>source</varname> file or to <literal>false</literal>
-            for files created through the <varname>text</varname> option.
+            Set the execute bit. If `null`, defaults to the mode
+            of the {var}`source` file or to `false`
+            for files created through the {var}`text` option.
           '';
         };
 
@@ -75,10 +75,10 @@ in
             determines whether the directory should be recursively
             linked to the target location. This option has no effect
             if the source is a file.
-            </para><para>
-            If <literal>false</literal> (the default) then the target
+
+            If `false` (the default) then the target
             will be a symbolic link to the source directory. If
-            <literal>true</literal> then the target will be a
+            `true` then the target will be a
             directory structure matching the source's but whose leafs
             are symbolic links to the files of the source directory.
           '';
@@ -90,10 +90,10 @@ in
           description = ''
             Shell commands to run when file has changed between
             generations. The script will be run
-            <emphasis>after</emphasis> the new files have been linked
+            *after* the new files have been linked
             into place.
-            </para><para>
-            Note, this code is always run when <literal>recursive</literal> is
+
+            Note, this code is always run when `recursive` is
             enabled.
           '';
         };
diff --git a/modules/lib/types.nix b/modules/lib/types.nix
index 671f3d7e..056d3165 100644
--- a/modules/lib/types.nix
+++ b/modules/lib/types.nix
@@ -41,7 +41,7 @@ in rec {
         example = literalExpression "pkgs.dejavu_fonts";
         description = ''
           Package providing the font. This package will be installed
-          to your profile. If <literal>null</literal> then the font
+          to your profile. If `null` then the font
           is assumed to already be available in your profile.
         '';
       };
diff --git a/modules/manual.nix b/modules/manual.nix
index 356f311a..84ec7eda 100644
--- a/modules/manual.nix
+++ b/modules/manual.nix
@@ -6,7 +6,10 @@ let
 
   cfg = config.manual;
 
-  docs = import ../docs { inherit lib pkgs; };
+  docs = import ../docs {
+    inherit pkgs lib;
+    inherit (config.home.version) release isReleaseBranch;
+  };
 
 in {
   options = {
@@ -15,7 +18,7 @@ in {
       default = false;
       description = ''
         Whether to install the HTML manual. This also installs the
-        <command>home-manager-help</command> tool, which opens a local
+        {command}`home-manager-help` tool, which opens a local
         copy of the Home Manager manual in the system web browser.
       '';
     };
@@ -26,8 +29,8 @@ in {
       example = false;
       description = ''
         Whether to install the configuration manual page. The manual can
-        be reached by <command>man home-configuration.nix</command>.
-        </para><para>
+        be reached by {command}`man home-configuration.nix`.
+
         When looking at the manual page pretend that all references to
         NixOS stuff are actually references to Home Manager stuff.
         Thanks!
@@ -41,7 +44,7 @@ in {
       description = ''
         Whether to install a JSON formatted list of all Home Manager
         options. This can be located at
-        <filename>&lt;profile directory&gt;/share/doc/home-manager/options.json</filename>,
+        {file}`<profile directory>/share/doc/home-manager/options.json`,
         and may be used for navigating definitions, auto-completing,
         and other miscellaneous tasks.
       '';
diff --git a/modules/misc/dconf.nix b/modules/misc/dconf.nix
index 8aa8e8d8..24e02a12 100644
--- a/modules/misc/dconf.nix
+++ b/modules/misc/dconf.nix
@@ -35,9 +35,9 @@ in {
         visible = false;
         description = ''
           Whether to enable dconf settings.
-          </para><para>
+
           Note, if you use NixOS then you must add
-          <code>programs.dconf.enable = true</code>
+          `programs.dconf.enable = true`
           to your system configuration. Otherwise you will see a systemd error
           message when your configuration is activated.
         '';
@@ -59,16 +59,16 @@ in {
         '';
         description = ''
           Settings to write to the dconf configuration system.
-          </para><para>
+
           Note that the database is strongly-typed so you need to use the same types
           as described in the GSettings schema. For example, if an option is of type
-          <literal>uint32</literal> (<literal>u</literal>), you need to wrap the number
-          using the <literal>lib.hm.gvariant.mkUint32</literal> constructor.
-          Otherwise, since Nix integers are implicitly coerced to <literal>int32</literal>
-          (<literal>i</literal>), it would get stored in the database as such, and GSettings
+          `uint32` (`u`), you need to wrap the number
+          using the `lib.hm.gvariant.mkUint32` constructor.
+          Otherwise, since Nix integers are implicitly coerced to `int32`
+          (`i`), it would get stored in the database as such, and GSettings
           might be confused when loading the setting.
-          </para><para>
-          You might want to use <link xlink:href="https://github.com/gvolpe/dconf2nix">dconf2nix</link>
+
+          You might want to use [dconf2nix](https://github.com/gvolpe/dconf2nix)
           to convert dconf database dumps into compatible Nix expression.
         '';
       };
diff --git a/modules/misc/debug.nix b/modules/misc/debug.nix
index d27d496b..fc0d8946 100644
--- a/modules/misc/debug.nix
+++ b/modules/misc/debug.nix
@@ -6,10 +6,10 @@ with lib;
   options.home = {
     enableDebugInfo = mkEnableOption "" // {
       description = ''
-        Some Nix-packages provide debug symbols for
-        <command>gdb</command> in the <literal>debug</literal>-output.
+        Some Nix packages provide debug symbols for
+        {command}`gdb` in the `debug` output.
         This option ensures that those are automatically fetched from
-        the binary cache if available and <command>gdb</command> is
+        the binary cache if available and {command}`gdb` is
         configured to find those symbols.
       '';
     };
diff --git a/modules/misc/editorconfig.nix b/modules/misc/editorconfig.nix
index 579ef1f8..a6dfb570 100644
--- a/modules/misc/editorconfig.nix
+++ b/modules/misc/editorconfig.nix
@@ -18,10 +18,10 @@ in {
       type = iniFormat.type;
       default = { };
       description = ''
-        Configuration written to <filename>$HOME/.editorconfig</filename>.
-        <code>root = true</code> is automatically added to the file,
+        Configuration written to {file}`$HOME/.editorconfig`.
+        `root = true` is automatically added to the file,
         it must not be added here.
-        See <link xlink:href="https://editorconfig.org"/> for documentation.
+        See <https://editorconfig.org> for documentation.
       '';
       example = literalExpression ''
         {
diff --git a/modules/misc/fontconfig.nix b/modules/misc/fontconfig.nix
index 74415c2f..49fef96a 100644
--- a/modules/misc/fontconfig.nix
+++ b/modules/misc/fontconfig.nix
@@ -28,8 +28,8 @@ in {
           Whether to enable fontconfig configuration. This will, for
           example, allow fontconfig to discover fonts and
           configurations installed through
-          <varname>home.packages</varname> and
-          <command>nix-env</command>.
+          {var}`home.packages` and
+          {command}`nix-env`.
         '';
       };
     };
diff --git a/modules/misc/gtk.nix b/modules/misc/gtk.nix
index 035cafae..c20424b1 100644
--- a/modules/misc/gtk.nix
+++ b/modules/misc/gtk.nix
@@ -33,7 +33,7 @@ let
         example = literalExpression "pkgs.gnome.gnome-themes-extra";
         description = ''
           Package providing the theme. This package will be installed
-          to your profile. If <literal>null</literal> then the theme
+          to your profile. If `null` then the theme
           is assumed to already be available in your profile.
         '';
       };
@@ -54,7 +54,7 @@ let
         example = literalExpression "pkgs.gnome.adwaita-icon-theme";
         description = ''
           Package providing the icon theme. This package will be installed
-          to your profile. If <literal>null</literal> then the theme
+          to your profile. If `null` then the theme
           is assumed to already be available in your profile.
         '';
       };
@@ -75,7 +75,7 @@ let
         example = literalExpression "pkgs.vanilla-dmz";
         description = ''
           Package providing the cursor theme. This package will be installed
-          to your profile. If <literal>null</literal> then the theme
+          to your profile. If `null` then the theme
           is assumed to already be available in your profile.
         '';
       };
@@ -143,7 +143,7 @@ in {
           example = "gtk-can-change-accels = 1";
           description = ''
             Extra configuration lines to add verbatim to
-            <filename>~/.gtkrc-2.0</filename>.
+            {file}`~/.gtkrc-2.0`.
           '';
         };
 
@@ -177,7 +177,7 @@ in {
           };
           description = ''
             Extra configuration options to add to
-            <filename>$XDG_CONFIG_HOME/gtk-3.0/settings.ini</filename>.
+            {file}`$XDG_CONFIG_HOME/gtk-3.0/settings.ini`.
           '';
         };
 
@@ -186,7 +186,7 @@ in {
           default = "";
           description = ''
             Extra configuration lines to add verbatim to
-            <filename>$XDG_CONFIG_HOME/gtk-3.0/gtk.css</filename>.
+            {file}`$XDG_CONFIG_HOME/gtk-3.0/gtk.css`.
           '';
         };
       };
@@ -201,7 +201,7 @@ in {
           };
           description = ''
             Extra configuration options to add to
-            <filename>$XDG_CONFIG_HOME/gtk-4.0/settings.ini</filename>.
+            {file}`$XDG_CONFIG_HOME/gtk-4.0/settings.ini`.
           '';
         };
 
@@ -210,7 +210,7 @@ in {
           default = "";
           description = ''
             Extra configuration lines to add verbatim to
-            <filename>$XDG_CONFIG_HOME/gtk-4.0/gtk.css</filename>.
+            {file}`$XDG_CONFIG_HOME/gtk-4.0/gtk.css`.
           '';
         };
       };
diff --git a/modules/misc/news.nix b/modules/misc/news.nix
index ef1bc741..9248ee4f 100644
--- a/modules/misc/news.nix
+++ b/modules/misc/news.nix
@@ -59,44 +59,23 @@ in
         default = "notify";
         description = ''
           How unread and relevant news should be presented when
-          running <command>home-manager build</command> and
-          <command>home-manager switch</command>.
-
-          </para><para>
+          running {command}`home-manager build` and
+          {command}`home-manager switch`.
 
           The options are
 
-          <variablelist>
-          <varlistentry>
-            <term><literal>silent</literal></term>
-            <listitem>
-              <para>
-                Do not print anything during build or switch. The
-                <command>home-manager news</command> command still
-                works for viewing the entries.
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>notify</literal></term>
-            <listitem>
-              <para>
-                The number of unread and relevant news entries will be
-                printed to standard output. The <command>home-manager
-                news</command> command can later be used to view the
-                entries.
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>show</literal></term>
-            <listitem>
-              <para>
-                A pager showing unread news entries is opened.
-              </para>
-            </listitem>
-          </varlistentry>
-          </variablelist>
+          `silent`
+          : Do not print anything during build or switch. The
+            {command}`home-manager news` command still
+            works for viewing the entries.
+
+          `notify`
+          : The number of unread and relevant news entries will be
+            printed to standard output. The {command}`home-manager
+            news` command can later be used to view the entries.
+
+          `show`
+          : A pager showing unread news entries is opened.
         '';
       };
 
diff --git a/modules/misc/nix.nix b/modules/misc/nix.nix
index e98df2e0..9e249143 100644
--- a/modules/misc/nix.nix
+++ b/modules/misc/nix.nix
@@ -120,23 +120,23 @@ in {
               repo = "my-nixpkgs";
             };
             description =
-              "The flake reference to which <option>from></option> is to be rewritten.";
+              "The flake reference to which {option}`from>` is to be rewritten.";
           };
           flake = mkOption {
             type = types.nullOr types.attrs;
             default = null;
             example = literalExpression "nixpkgs";
             description = ''
-              The flake input to which <option>from></option> is to be rewritten.
+              The flake input to which {option}`from>` is to be rewritten.
             '';
           };
           exact = mkOption {
             type = types.bool;
             default = true;
             description = ''
-              Whether the <option>from</option> reference needs to match exactly. If set,
-              a <option>from</option> reference like <literal>nixpkgs</literal> does not
-              match with a reference like <literal>nixpkgs/nixos-20.03</literal>.
+              Whether the {option}`from` reference needs to match exactly. If set,
+              a {option}`from` reference like `nixpkgs` does not
+              match with a reference like `nixpkgs/nixos-20.03`.
             '';
           };
         };
@@ -182,8 +182,7 @@ in {
         keep-outputs = true
         keep-derivations = true
       '';
-      description =
-        "Additional text appended to <filename>nix.conf</filename>.";
+      description = "Additional text appended to {file}`nix.conf`.";
     };
 
     settings = mkOption {
@@ -197,16 +196,10 @@ in {
         }
       '';
       description = ''
-        Configuration for Nix, see
-        <link xlink:href="https://nixos.org/manual/nix/stable/#sec-conf-file"/> or
-        <citerefentry>
-          <refentrytitle>nix.conf</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry> for available options.
+        Configuration for Nix; see {manpage}`nix.conf(5)` for available options.
         The value declared here will be translated directly to the key-value pairs Nix expects.
-        </para>
-        <para>
-        Configuration specified in <option>nix.extraOptions</option> which will be appended
+
+        Configuration specified in [](#opt-nix.extraOptions) will be appended
         verbatim to the resulting config file.
       '';
     };
diff --git a/modules/misc/nixpkgs.nix b/modules/misc/nixpkgs.nix
index 42f6724c..efbbba96 100644
--- a/modules/misc/nixpkgs.nix
+++ b/modules/misc/nixpkgs.nix
@@ -53,24 +53,20 @@ in {
         details, see the Nixpkgs documentation.) It allows you to set
         package configuration options.
 
-        </para><para>
-
-        If <literal>null</literal>, then configuration is taken from
+        If `null`, then configuration is taken from
         the fallback location, for example,
-        <filename>~/.config/nixpkgs/config.nix</filename>.
-
-        </para><para>
+        {file}`~/.config/nixpkgs/config.nix`.
 
         Note, this option will not apply outside your Home Manager
         configuration like when installing manually through
-        <command>nix-env</command>. If you want to apply it both
+        {command}`nix-env`. If you want to apply it both
         inside and outside Home Manager you can put it in a separate
         file and include something like
 
-        <programlisting language="nix">
+        ```nix
           nixpkgs.config = import ./nixpkgs-config.nix;
           xdg.configFile."nixpkgs/config.nix".source = ./nixpkgs-config.nix;
-        </programlisting>
+        ```
 
         in your Home Manager configuration.
       '';
@@ -94,21 +90,17 @@ in {
         List of overlays to use with the Nix Packages collection. (For
         details, see the Nixpkgs documentation.) It allows you to
         override packages globally. This is a function that takes as
-        an argument the <emphasis>original</emphasis> Nixpkgs. The
+        an argument the *original* Nixpkgs. The
         first argument should be used for finding dependencies, and
         the second should be used for overriding recipes.
 
-        </para><para>
-
-        If <literal>null</literal>, then the overlays are taken from
+        If `null`, then the overlays are taken from
         the fallback location, for example,
-        <filename>~/.config/nixpkgs/overlays</filename>.
+        {file}`~/.config/nixpkgs/overlays`.
 
-        </para><para>
-
-        Like <varname>nixpkgs.config</varname> this option only
+        Like {var}`nixpkgs.config` this option only
         applies within the Home Manager configuration. See
-        <varname>nixpkgs.config</varname> for a suggested setup that
+        {var}`nixpkgs.config` for a suggested setup that
         works both internally and externally.
       '';
     };
diff --git a/modules/misc/pam.nix b/modules/misc/pam.nix
index cf3321ff..22a5daf0 100644
--- a/modules/misc/pam.nix
+++ b/modules/misc/pam.nix
@@ -17,11 +17,8 @@ in {
       description = ''
         Environment variables that will be set for the PAM session.
         The variable values must be as described in
-        <citerefentry>
-          <refentrytitle>pam_env.conf</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>.
-        </para><para>
+        {manpage}`pam_env.conf(5)`.
+
         Note, this option will become deprecated in the future and its use is
         therefore discouraged.
       '';
@@ -39,7 +36,7 @@ in {
         default = [ ];
         description = ''
           List of authorized YubiKey token IDs. Refer to
-          <link xlink:href="https://developers.yubico.com/yubico-pam"/>
+          <https://developers.yubico.com/yubico-pam>
           for details on how to obtain the token ID of a YubiKey.
         '';
       };
@@ -49,7 +46,7 @@ in {
         default = ".yubico/authorized_yubikeys";
         description = ''
           File path to write the authorized YubiKeys,
-          relative to <envar>HOME</envar>.
+          relative to {env}`HOME`.
         '';
       };
     };
diff --git a/modules/misc/qt.nix b/modules/misc/qt.nix
index d009b3e6..554072e2 100644
--- a/modules/misc/qt.nix
+++ b/modules/misc/qt.nix
@@ -56,34 +56,26 @@ in {
           [ "libsForQt5" "systemsettings" ]
         ];
         description = ''
-          Platform theme to use for Qt applications.</para>
-          <para>The options are
-          <variablelist>
-            <varlistentry>
-              <term><literal>gtk</literal></term>
-              <listitem><para>Use GTK theme with
-                <link xlink:href="https://github.com/qt/qtstyleplugins">qtstyleplugins</link>
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>gnome</literal></term>
-              <listitem><para>Use GNOME theme with
-                <link xlink:href="https://github.com/FedoraQt/QGnomePlatform">qgnomeplatform</link>
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>qtct</literal></term>
-              <listitem><para>Use Qt style set using
-                <link xlink:href="https://github.com/desktop-app/qt5ct">qt5ct</link>
-                and
-                <link xlink:href="https://github.com/trialuser02/qt6ct">qt6ct</link>
-              applications</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>kde</literal></term>
-              <listitem><para>Use Qt settings from Plasma</para></listitem>
-            </varlistentry>
-          </variablelist>
+          Platform theme to use for Qt applications.
+
+          The options are
+
+          `gtk`
+          : Use GTK theme with
+            [`qtstyleplugins`](https://github.com/qt/qtstyleplugins)
+
+          `gnome`
+          : Use GNOME theme with
+            [`qgnomeplatform`](https://github.com/FedoraQt/QGnomePlatform)
+
+          `qtct`
+          : Use Qt style set using
+            [`qt5ct`](https://github.com/desktop-app/qt5ct)
+            and [`qt6ct`](https://github.com/trialuser02/qt6ct)
+            applications
+
+          `kde`
+          : Use Qt settings from Plasma
         '';
       };
 
@@ -102,43 +94,24 @@ in {
           ];
           description = ''
             Style to use for Qt5/Qt6 applications. Case-insensitive.
-            </para>
-            <para>Some examples are
-            <variablelist>
-              <varlistentry>
-                <term><literal>adwaita</literal></term>
-                <term><literal>adwaita-dark</literal></term>
-                <term><literal>adwaita-highcontrast</literal></term>
-                <term><literal>adwaita-highcontrastinverse</literal></term>
-                <listitem><para>Use the Adwaita style from
-                  <link xlink:href="https://github.com/FedoraQt/adwaita-qt">adwaita</link>
-                </para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>breeze</literal></term>
-                <listitem><para>Use the Breeze style from
-                  <link xlink:href="https://github.com/KDE/breeze">breeze</link>
-                </para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>bb10bright</literal></term>
-                <term><literal>bb10dark</literal></term>
-                <term><literal>cde</literal></term>
-                <term><literal>cleanlooks</literal></term>
-                <term><literal>gtk2</literal></term>
-                <term><literal>motif</literal></term>
-                <term><literal>plastique</literal></term>
-                <listitem><para>Use styles from
-                  <link xlink:href="https://github.com/qt/qtstyleplugins">qtstyleplugins</link>
-                </para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>kvantum</literal></term>
-                <listitem><para>Use styles from
-                  <link xlink:href="https://github.com/tsujan/Kvantum">kvantum</link>
-                </para></listitem>
-              </varlistentry>
-            </variablelist>
+
+            Some examples are
+
+            `adwaita`, `adwaita-dark`, `adwaita-highcontrast`, `adwaita-highcontrastinverse`
+            : Use the Adwaita style from
+              [`adwaita-qt`](https://github.com/FedoraQt/adwaita-qt)
+
+            `breeze`
+            : Use the Breeze style from
+              [`breeze`](https://github.com/KDE/breeze)
+
+            `bb10bright`, `bb10dark`, `cde`, `cleanlooks`, `gtk2`, `motif`, `plastique`
+            : Use styles from
+              [`qtstyleplugins`](https://github.com/qt/qtstyleplugins)
+
+            `kvantum`
+            : Use styles from
+              [`kvantum`](https://github.com/tsujan/Kvantum)
           '';
         };
 
@@ -148,7 +121,7 @@ in {
           example = literalExpression "pkgs.adwaita-qt";
           description = ''
             Theme package to be used in Qt5/Qt6 applications.
-            Auto-detected from <option>qt.style.name</option> if possible.
+            Auto-detected from {option}`qt.style.name` if possible.
           '';
         };
       };
diff --git a/modules/misc/specialisation.nix b/modules/misc/specialisation.nix
index e9844f2d..dc5f78e1 100644
--- a/modules/misc/specialisation.nix
+++ b/modules/misc/specialisation.nix
@@ -37,38 +37,36 @@ with lib;
     description = ''
       A set of named specialized configurations. These can be used to extend
       your base configuration with additional settings. For example, you can
-      have specialisations named <quote>light</quote> and <quote>dark</quote>
-      that applies light and dark color theme configurations.
+      have specialisations named "light" and "dark"
+      that apply light and dark color theme configurations.
 
-      </para><para>
-
-      Note, this is an experimental option for now and you therefore have to
+      ::: {.note}
+      This is an experimental option for now and you therefore have to
       activate the specialisation by looking up and running the activation
-      script yourself. Note, running the activation script will create a new
+      script yourself. Running the activation script will create a new
       Home Manager generation.
+      :::
 
-      </para><para>
-
-      For example, to activate the <quote>dark</quote> specialisation. You can
+      For example, to activate the "dark" specialisation, you can
       first look up your current Home Manager generation by running
 
-      <programlisting language="console">
-        $ home-manager generations | head -1
-        2022-05-02 22:49 : id 1758 -> /nix/store/jy…ac-home-manager-generation
-      </programlisting>
+      ```console
+      $ home-manager generations | head -1
+      2022-05-02 22:49 : id 1758 -> /nix/store/jy…ac-home-manager-generation
+      ```
 
       then run
 
-      <programlisting language="console">
-        $ /nix/store/jy…ac-home-manager-generation/specialisation/dark/activate
-        Starting Home Manager activation
-        …
-      </programlisting>
+      ```console
+      $ /nix/store/jy…ac-home-manager-generation/specialisation/dark/activate
+      Starting Home Manager activation
+      …
+      ```
 
-      </para><para>
-
-      WARNING! Since this option is experimental, the activation process may
+      ::: {.warning}
+      Since this option is experimental, the activation process may
       change in backwards incompatible ways.
+      :::
     '';
   };
 
diff --git a/modules/misc/submodule-support.nix b/modules/misc/submodule-support.nix
index ff80291c..400e234c 100644
--- a/modules/misc/submodule-support.nix
+++ b/modules/misc/submodule-support.nix
@@ -21,11 +21,11 @@ with lib;
       default = false;
       internal = true;
       description = ''
-        Whether the packages of <option>home.packages</option> are
+        Whether the packages of {option}`home.packages` are
         installed separately from the Home Manager activation script.
         In NixOS, for example, this may be accomplished by installing
         the packages through
-        <option>users.users.‹name?›.packages</option>.
+        {option}`users.users.‹name?›.packages`.
       '';
     };
   };
diff --git a/modules/misc/tmpfiles.nix b/modules/misc/tmpfiles.nix
index 24884302..c5f4a975 100644
--- a/modules/misc/tmpfiles.nix
+++ b/modules/misc/tmpfiles.nix
@@ -16,10 +16,7 @@ in {
     description = ''
       Rules for creating and cleaning up temporary files
       automatically. See
-      <citerefentry>
-        <refentrytitle>tmpfiles.d</refentrytitle>
-        <manvolnum>5</manvolnum>
-      </citerefentry>
+      {manpage}`tmpfiles.d(5)`
       for the exact format.
     '';
   };
diff --git a/modules/misc/version.nix b/modules/misc/version.nix
index 9720ddf2..f82fc3a4 100644
--- a/modules/misc/version.nix
+++ b/modules/misc/version.nix
@@ -2,7 +2,9 @@
 
 with lib;
 
-{
+let releaseInfo = lib.importJSON ../../release.json;
+
+in {
   options = {
     home.stateVersion = mkOption {
       type = types.enum [
@@ -24,8 +26,8 @@ with lib;
         configuration defaults in a way that is incompatible with
         stateful data. This could, for example, include switching the
         default data format or location of a file.
-        </para><para>
-        The <emphasis>state version</emphasis> indicates which default
+
+        The *state version* indicates which default
         settings are in effect and will therefore help avoid breaking
         program configurations. Switching to a higher state version
         typically requires performing some manual steps, such as data
@@ -51,11 +53,22 @@ with lib;
         internal = true;
         readOnly = true;
         type = types.str;
-        default = fileContents ../../.release;
+        default = releaseInfo.release;
         example = "22.11";
         description = "The Home Manager release.";
       };
 
+      isReleaseBranch = mkOption {
+        internal = true;
+        readOnly = true;
+        type = types.bool;
+        default = releaseInfo.isReleaseBranch;
+        description = ''
+          Whether the Home Manager version is from a versioned
+          release branch.
+        '';
+      };
+
       revision = mkOption {
         internal = true;
         type = types.nullOr types.str;
diff --git a/modules/misc/xdg-desktop-entries.nix b/modules/misc/xdg-desktop-entries.nix
index c538eda3..a810796f 100644
--- a/modules/misc/xdg-desktop-entries.nix
+++ b/modules/misc/xdg-desktop-entries.nix
@@ -82,7 +82,7 @@ let
       startupNotify = mkOption {
         description = ''
           If true, it is KNOWN that the application will send a "remove"
-          message when started with the <literal>DESKTOP_STARTUP_ID</literal>
+          message when started with the `DESKTOP_STARTUP_ID`
           environment variable set. If false, it is KNOWN that the application
           does not work with startup notification at all.'';
         type = types.nullOr types.bool;
@@ -109,7 +109,7 @@ let
       settings = mkOption {
         type = types.attrsOf types.string;
         description = ''
-          Extra key-value pairs to add to the <literal>[Desktop Entry]</literal> section.
+          Extra key-value pairs to add to the `[Desktop Entry]` section.
           This may override other values.
         '';
         default = { };
@@ -181,9 +181,11 @@ in {
 
   options.xdg.desktopEntries = mkOption {
     description = ''
-      Desktop Entries allow applications to be shown in your desktop environment's app launcher. </para><para>
-      You can define entries for programs without entries or override existing entries. </para><para>
-      See <link xlink:href="https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys" /> for more information on options.
+      Desktop Entries allow applications to be shown in your desktop environment's app launcher.
+
+      You can define entries for programs without entries or override existing entries.
+
+      See <https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#recognized-keys> for more information on options.
     '';
     default = { };
     type = types.attrsOf (types.submodule desktopEntry);
diff --git a/modules/misc/xdg-mime-apps.nix b/modules/misc/xdg-mime-apps.nix
index 2093caa2..c9fd3e8b 100644
--- a/modules/misc/xdg-mime-apps.nix
+++ b/modules/misc/xdg-mime-apps.nix
@@ -17,9 +17,8 @@ in {
       type = types.bool;
       default = false;
       description = ''
-        Whether to manage <filename>$XDG_CONFIG_HOME/mimeapps.list</filename>.
-        </para>
-        <para>
+        Whether to manage {file}`$XDG_CONFIG_HOME/mimeapps.list`.
+
         The generated file is read-only.
       '';
     };
@@ -49,7 +48,7 @@ in {
       example = { "mimetype1" = "foo5.desktop"; };
       description = ''
         Removes associations of applications with mimetypes, as if the
-        .desktop file was <emphasis>not</emphasis> listing this
+        .desktop file was *not* listing this
         mimetype in the first place.
       '';
     };
diff --git a/modules/misc/xdg-mime.nix b/modules/misc/xdg-mime.nix
index c9c7658d..09f62aaf 100644
--- a/modules/misc/xdg-mime.nix
+++ b/modules/misc/xdg-mime.nix
@@ -17,9 +17,9 @@ in {
         Whether to install programs and files to support the
         XDG Shared MIME-info specification and XDG MIME Applications
         specification at
-        <link xlink:href="https://specifications.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html"/>
+        <https://specifications.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html>
         and
-        <link xlink:href="https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-latest.html"/>,
+        <https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-latest.html>,
         respectively.
       '';
     };
diff --git a/modules/misc/xdg-system-dirs.nix b/modules/misc/xdg-system-dirs.nix
index 989131c5..0be5e26d 100644
--- a/modules/misc/xdg-system-dirs.nix
+++ b/modules/misc/xdg-system-dirs.nix
@@ -19,7 +19,7 @@ in {
       default = [ ];
       example = literalExpression ''[ "/etc/xdg" ]'';
       description = ''
-        Directory names to add to <envar>XDG_CONFIG_DIRS</envar>
+        Directory names to add to {env}`XDG_CONFIG_DIRS`
         in the user session.
       '';
     };
@@ -29,7 +29,7 @@ in {
       default = [ ];
       example = literalExpression ''[ "/usr/share" "/usr/local/share" ]'';
       description = ''
-        Directory names to add to <envar>XDG_DATA_DIRS</envar>
+        Directory names to add to {env}`XDG_DATA_DIRS`
         in the user session.
       '';
     };
diff --git a/modules/misc/xdg-user-dirs.nix b/modules/misc/xdg-user-dirs.nix
index 2ea07709..fcc0742c 100644
--- a/modules/misc/xdg-user-dirs.nix
+++ b/modules/misc/xdg-user-dirs.nix
@@ -22,9 +22,8 @@ in {
       type = types.bool;
       default = false;
       description = ''
-        Whether to manage <filename>$XDG_CONFIG_HOME/user-dirs.dirs</filename>.
-        </para>
-        <para>
+        Whether to manage {file}`$XDG_CONFIG_HOME/user-dirs.dirs`.
+
         The generated file is read-only.
       '';
     };
diff --git a/modules/misc/xdg.nix b/modules/misc/xdg.nix
index 3d2a72a0..23cbe72a 100644
--- a/modules/misc/xdg.nix
+++ b/modules/misc/xdg.nix
@@ -34,8 +34,7 @@ in {
     };
 
     configFile = mkOption {
-      type = fileType "xdg.configFile" "<varname>xdg.configHome</varname>"
-        cfg.configHome;
+      type = fileType "xdg.configFile" "{var}`xdg.configHome`" cfg.configHome;
       default = { };
       description = ''
         Attribute set of files to link into the user's XDG
diff --git a/modules/misc/xfconf.nix b/modules/misc/xfconf.nix
index f9858c5f..ec0cd82d 100644
--- a/modules/misc/xfconf.nix
+++ b/modules/misc/xfconf.nix
@@ -65,9 +65,9 @@ in {
       visible = false;
       description = ''
         Whether to enable Xfconf settings.
-        </para><para>
+
         Note, if you use NixOS then you must add
-        <code>programs.xfconf.enable = true</code>
+        `programs.xfconf.enable = true`
         to your system configuration. Otherwise you will see a systemd error
         message when your configuration is activated.
       '';
diff --git a/modules/programs/abook.nix b/modules/programs/abook.nix
index bdbf7e87..a9945d0e 100644
--- a/modules/programs/abook.nix
+++ b/modules/programs/abook.nix
@@ -19,9 +19,9 @@ in {
         set autosave=true
       '';
       description = ''
-        Extra lines added to <filename>$HOME/.config/abook/abookrc</filename>.
+        Extra lines added to {file}`$HOME/.config/abook/abookrc`.
         Available configuration options are described in the abook repository:
-        <link xlink:href="https://sourceforge.net/p/abook/git/ci/master/tree/sample.abookrc" />.
+        <https://sourceforge.net/p/abook/git/ci/master/tree/sample.abookrc>.
       '';
     };
   };
diff --git a/modules/programs/aerc-accounts.nix b/modules/programs/aerc-accounts.nix
index 4e852eb8..a40877f5 100644
--- a/modules/programs/aerc-accounts.nix
+++ b/modules/programs/aerc-accounts.nix
@@ -18,18 +18,22 @@ let
           token_endpoint = mkOption {
             type = nullOr str;
             default = null;
+            description = "The OAuth2 token endpoint.";
           };
           client_id = mkOption {
             type = nullOr str;
             default = null;
+            description = "The OAuth2 client identifier.";
           };
           client_secret = mkOption {
             type = nullOr str;
             default = null;
+            description = "The OAuth2 client secret.";
           };
           scope = mkOption {
             type = nullOr str;
             default = null;
+            description = "The OAuth2 requested scope.";
           };
         };
       });
@@ -38,7 +42,7 @@ let
     description = ''
       Sets the oauth2 params if authentication mechanism oauthbearer or
       xoauth2 is used.
-      See <citerefentry><refentrytitle>aerc-imap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      See {manpage}`aerc-imap(5)`.
     '';
   };
 
@@ -54,8 +58,8 @@ in {
             literalExpression ''{ source = "maildir://~/Maildir/example"; }'';
           description = ''
             Extra config added to the configuration section for this account in
-            <filename>$HOME/.config/aerc/accounts.conf</filename>.
-            See <citerefentry><refentrytitle>aerc-accounts</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            {file}`$HOME/.config/aerc/accounts.conf`.
+            See {manpage}`aerc-accounts(5)`.
           '';
         };
 
@@ -66,8 +70,8 @@ in {
             ''{ messages = { d = ":move ''${folder.trash}<Enter>"; }; }'';
           description = ''
             Extra bindings specific to this account, added to
-            <filename>$HOME/.config/aerc/binds.conf</filename>.
-            See <citerefentry><refentrytitle>aerc-binds</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            {file}`$HOME/.config/aerc/binds.conf`.
+            See {manpage}`aerc-binds(5)`.
           '';
         };
 
@@ -76,11 +80,11 @@ in {
           default = { };
           example = literalExpression "{ ui = { sidebar-width = 25; }; }";
           description = ''
-            Config specific to this account, added to <filename>$HOME/.config/aerc/aerc.conf</filename>.
+            Config specific to this account, added to {file}`$HOME/.config/aerc/aerc.conf`.
             Aerc only supports per-account UI configuration.
-            For other sections of <filename>$HOME/.config/aerc/aerc.conf</filename>,
-            use <literal>programs.aerc.extraConfig</literal>.
-            See <citerefentry><refentrytitle>aerc-config</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            For other sections of {file}`$HOME/.config/aerc/aerc.conf`,
+            use `programs.aerc.extraConfig`.
+            See {manpage}`aerc-config(5)`.
           '';
         };
 
@@ -91,7 +95,7 @@ in {
           description = ''
             Sets the authentication mechanism if imap is used as the incoming
             method.
-            See <citerefentry><refentrytitle>aerc-imap</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            See {manpage}`aerc-imap(5)`.
           '';
         };
 
@@ -105,7 +109,7 @@ in {
           description = ''
             Sets the authentication mechanism if smtp is used as the outgoing
             method.
-            See <citerefentry><refentrytitle>aerc-smtp</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+            See {manpage}`aerc-smtp(5)`.
           '';
         };
 
diff --git a/modules/programs/aerc.nix b/modules/programs/aerc.nix
index ccd26e21..662ab5b1 100644
--- a/modules/programs/aerc.nix
+++ b/modules/programs/aerc.nix
@@ -41,8 +41,9 @@ in {
       example = literalExpression
         ''{ Work = { source = "maildir://~/Maildir/work"; }; }'';
       description = ''
-        Extra lines added to <filename>$HOME/.config/aerc/accounts.conf</filename>.
-        See aerc-config(5).
+        Extra lines added to {file}`$HOME/.config/aerc/accounts.conf`.
+
+        See {manpage}`aerc-config(5)`.
       '';
     };
 
@@ -51,9 +52,10 @@ in {
       default = { };
       example = literalExpression ''{ messages = { q = ":quit<Enter>"; }; }'';
       description = ''
-        Extra lines added to <filename>$HOME/.config/aerc/binds.conf</filename>.
+        Extra lines added to {file}`$HOME/.config/aerc/binds.conf`.
         Global keybindings can be set in the `global` section.
-        See aerc-config(5).
+
+        See {manpage}`aerc-config(5)`.
       '';
     };
 
@@ -62,8 +64,9 @@ in {
       default = { };
       example = literalExpression ''{ ui = { sort = "-r date"; }; }'';
       description = ''
-        Extra lines added to <filename>$HOME/.config/aerc/aerc.conf</filename>.
-        See aerc-config(5).
+        Extra lines added to {file}`$HOME/.config/aerc/aerc.conf`.
+
+        See {manpage}`aerc-config(5)`.
       '';
     };
 
@@ -74,8 +77,9 @@ in {
         { default = { ui = { "tab.selected.reverse" = toggle; }; }; };
       '';
       description = ''
-        Stylesets added to <filename>$HOME/.config/aerc/stylesets/</filename>.
-        See aerc-stylesets(7).
+        Stylesets added to {file}`$HOME/.config/aerc/stylesets/`.
+
+        See {manpage}`aerc-stylesets(7)`.
       '';
     };
 
@@ -86,8 +90,9 @@ in {
         { new_message = "Hello!"; };
       '';
       description = ''
-        Templates added to <filename>$HOME/.config/aerc/templates/</filename>.
-        See aerc-templates(7).
+        Templates added to {file}`$HOME/.config/aerc/templates/`.
+
+        See {manpage}`aerc-templates(7)`.
       '';
     };
   };
diff --git a/modules/programs/afew.nix b/modules/programs/afew.nix
index 6c480f03..e0bb2604 100644
--- a/modules/programs/afew.nix
+++ b/modules/programs/afew.nix
@@ -32,7 +32,7 @@ in {
       description = ''
         Extra lines added to afew configuration file. Available
         configuration options are described in the afew manual:
-        <link xlink:href="https://afew.readthedocs.io/en/latest/configuration.html" />.
+        <https://afew.readthedocs.io/en/latest/configuration.html>.
       '';
     };
   };
diff --git a/modules/programs/alacritty.nix b/modules/programs/alacritty.nix
index eaf30414..56beb6d4 100644
--- a/modules/programs/alacritty.nix
+++ b/modules/programs/alacritty.nix
@@ -37,8 +37,8 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/alacritty/alacritty.yml</filename>. See
-          <link xlink:href="https://github.com/alacritty/alacritty/blob/master/alacritty.yml"/>
+          {file}`$XDG_CONFIG_HOME/alacritty/alacritty.yml`. See
+          <https://github.com/alacritty/alacritty/blob/master/alacritty.yml>
           for the default configuration.
         '';
       };
diff --git a/modules/programs/alot-accounts.nix b/modules/programs/alot-accounts.nix
index 9dee3c83..0a51bfde 100644
--- a/modules/programs/alot-accounts.nix
+++ b/modules/programs/alot-accounts.nix
@@ -10,7 +10,7 @@ with lib;
       description = ''
         Command to send a mail. If msmtp is enabled for the account,
         then this is set to
-        <command>msmtpq --read-envelope-from --read-recipients</command>.
+        {command}`msmtpq --read-envelope-from --read-recipients`.
       '';
     };
 
@@ -35,7 +35,7 @@ with lib;
       '';
       description = ''
         Contact completion configuration as expected per alot.
-        See <link xlink:href="http://alot.readthedocs.io/en/latest/configuration/contacts_completion.html">alot's wiki</link> for
+        See [alot's wiki](http://alot.readthedocs.io/en/latest/configuration/contacts_completion.html) for
         explanation about possible values.
       '';
     };
diff --git a/modules/programs/alot.nix b/modules/programs/alot.nix
index 22a29be1..d0f552f9 100644
--- a/modules/programs/alot.nix
+++ b/modules/programs/alot.nix
@@ -28,7 +28,7 @@ let
         description = ''
           Fixed string representation for this tag. The tag can be
           hidden from view, if the key translated is set to
-          <literal>""</literal>, the empty string.
+          `""`, the empty string.
         '';
       };
 
@@ -38,7 +38,7 @@ let
         description = ''
           A pair of strings that define a regular substitution to
           compute the string representation on the fly using
-          <literal>re.sub</literal>.
+          `re.sub`.
         '';
       };
 
@@ -48,7 +48,7 @@ let
         example = "'','', 'white','light red', 'white','#d66'";
         description = ''
           How to display the tag when unfocused.
-          See <link xlink:href="https://alot.readthedocs.io/en/latest/configuration/theming.html#tagstring-formatting"/>.
+          See <https://alot.readthedocs.io/en/latest/configuration/theming.html#tagstring-formatting>.
         '';
       };
 
diff --git a/modules/programs/aria2.nix b/modules/programs/aria2.nix
index 25727cea..549e6baf 100644
--- a/modules/programs/aria2.nix
+++ b/modules/programs/aria2.nix
@@ -23,12 +23,9 @@ in {
       type = with types; attrsOf (oneOf [ bool float int str ]);
       default = { };
       description = ''
-        Options to add to <filename>aria2.conf</filename> file.
+        Options to add to {file}`aria2.conf` file.
         See
-        <citerefentry>
-          <refentrytitle>aria2c</refentrytitle>
-          <manvolnum>1</manvolnum>
-        </citerefentry>
+        {manpage}`aria2c(1)`
         for options.
       '';
       example = literalExpression ''
@@ -46,7 +43,7 @@ in {
       type = types.lines;
       default = "";
       description = ''
-        Extra lines added to <filename>aria2.conf</filename> file.
+        Extra lines added to {file}`aria2.conf` file.
       '';
     };
   };
diff --git a/modules/programs/astroid-accounts.nix b/modules/programs/astroid-accounts.nix
index fb803867..b9b1fac0 100644
--- a/modules/programs/astroid-accounts.nix
+++ b/modules/programs/astroid-accounts.nix
@@ -11,7 +11,7 @@ with lib;
       description = ''
         Command to send a mail. If msmtp is enabled for the account,
         then this is set to
-        <command>msmtpq --read-envelope-from --read-recipients</command>.
+        {command}`msmtpq --read-envelope-from --read-recipients`.
       '';
     };
 
diff --git a/modules/programs/astroid.nix b/modules/programs/astroid.nix
index 4e79ea4d..911ce491 100644
--- a/modules/programs/astroid.nix
+++ b/modules/programs/astroid.nix
@@ -80,14 +80,19 @@ in {
         example =
           "nvim-qt -- -c 'set ft=mail' '+set fileencoding=utf-8' '+set ff=unix' '+set enc=utf-8' '+set fo+=w' %1";
         description = ''
-          You can use <code>%1</code>, <code>%2</code>, and
-          <code>%3</code> to refer respectively to:
-          <orderedlist numeration="arabic">
-            <listitem><para>file name</para></listitem>
-            <listitem><para>server name</para></listitem>
-            <listitem><para>socket ID</para></listitem>
-          </orderedlist>
-          See <link xlink:href='https://github.com/astroidmail/astroid/wiki/Customizing-editor' />.
+          You can use the following variables:
+
+          `%1`
+          : file name
+
+          `%2`
+          : server name
+
+          `%3`
+          : socket ID
+
+          See [Customizing editor](https://github.com/astroidmail/astroid/wiki/Customizing-editor)
+          on the Astroid wiki.
         '';
       };
 
diff --git a/modules/programs/atuin.nix b/modules/programs/atuin.nix
index 9205a531..bd907ac0 100644
--- a/modules/programs/atuin.nix
+++ b/modules/programs/atuin.nix
@@ -26,16 +26,17 @@ in {
       default = true;
       description = ''
         Whether to enable Atuin's Bash integration. This will bind
-        <literal>ctrl-r</literal> to open the Atuin history.
+        `ctrl-r` to open the Atuin history.
       '';
     };
 
-    enableZshIntegration = mkEnableOption "Zsh integration" // {
+    enableZshIntegration = mkOption {
+      type = types.bool;
       default = true;
       description = ''
         Whether to enable Atuin's Zsh integration.
-        </para><para>
-        If enabled, this will bind <literal>ctrl-r</literal> and the up-arrow
+
+        If enabled, this will bind `ctrl-r` and the up-arrow
         key to open the Atuin history.
       '';
     };
@@ -45,7 +46,7 @@ in {
       type = types.bool;
       description = ''
         Whether to enable Atuin's Fish integration.
-        </para><para>
+
         If enabled, this will bind the up-arrow key to open the Atuin history.
       '';
     };
@@ -79,9 +80,9 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/atuin/config.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://atuin.sh/docs/config/" /> for the full list
+        {file}`$XDG_CONFIG_HOME/atuin/config.toml`.
+
+        See <https://atuin.sh/docs/config/> for the full list
         of options.
       '';
     };
diff --git a/modules/programs/autorandr.nix b/modules/programs/autorandr.nix
index 9e7c6fcc..edbe83de 100644
--- a/modules/programs/autorandr.nix
+++ b/modules/programs/autorandr.nix
@@ -28,7 +28,7 @@ let
         type = types.attrsOf types.str;
         description = ''
           Output name to EDID mapping.
-          Use <code>autorandr --fingerprint</code> to get current setup values.
+          Use `autorandr --fingerprint` to get current setup values.
         '';
         default = { };
       };
@@ -115,10 +115,7 @@ let
         '';
         description = ''
           Refer to
-          <citerefentry>
-            <refentrytitle>xrandr</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>
+          {manpage}`xrandr(1)`
           for the documentation of the transform matrix.
         '';
       };
@@ -153,18 +150,15 @@ let
         });
         description = ''
           Output scale configuration.
-          </para><para>
+
           Either configure by pixels or a scaling factor. When using pixel method the
-          <citerefentry>
-            <refentrytitle>xrandr</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>
+          {manpage}`xrandr(1)`
           option
-          <parameter class="command">--scale-from</parameter>
+          `--scale-from`
           will be used; when using factor method the option
-          <parameter class="command">--scale</parameter>
+          `--scale`
           will be used.
-          </para><para>
+
           This option is a shortcut version of the transform option and they are mutually
           exclusive.
         '';
diff --git a/modules/programs/bash.nix b/modules/programs/bash.nix
index 0c0643da..b48dc312 100644
--- a/modules/programs/bash.nix
+++ b/modules/programs/bash.nix
@@ -35,17 +35,15 @@ in {
         description = ''
           Whether to enable Bash completion for all interactive Bash shells.
 
-          </para><para>
-
           Note, if you use NixOS or nix-darwin and do not have Bash completion
           enabled in the system configuration, then make sure to add
 
-          <programlisting language="nix">
+          ```nix
             environment.pathsToLink = [ "/share/bash-completion" ];
-          </programlisting>
+          ```
 
           to your system configuration to get completion for system packages.
-          Note, the legacy <filename>/etc/bash_completion.d</filename> path is
+          Note, the legacy {file}`/etc/bash_completion.d` path is
           not supported by Home Manager.
         '';
       };
@@ -103,7 +101,7 @@ in {
         example = [ "extglob" "-cdspell" ];
         description = ''
           Shell options to set. Prefix an option with
-          <quote><literal>-</literal></quote> to unset.
+          "`-`" to unset.
         '';
       };
 
@@ -153,7 +151,7 @@ in {
         default = "";
         type = types.lines;
         description = ''
-          Extra commands that should be placed in <filename>~/.bashrc</filename>.
+          Extra commands that should be placed in {file}`~/.bashrc`.
           Note that these commands will be run even in non-interactive shells.
         '';
       };
diff --git a/modules/programs/bashmount.nix b/modules/programs/bashmount.nix
index 38d57456..66c5809b 100644
--- a/modules/programs/bashmount.nix
+++ b/modules/programs/bashmount.nix
@@ -17,8 +17,8 @@ in {
       default = "";
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/bashmount/config</filename>. Look at
-        <link xlink:href="https://github.com/jamielinux/bashmount/blob/master/bashmount.conf" />
+        {file}`$XDG_CONFIG_HOME/bashmount/config`. Look at
+        <https://github.com/jamielinux/bashmount/blob/master/bashmount.conf>
         for explanation about possible values.
       '';
     };
diff --git a/modules/programs/beets.nix b/modules/programs/beets.nix
index 6cadcf9c..dab98c30 100644
--- a/modules/programs/beets.nix
+++ b/modules/programs/beets.nix
@@ -22,9 +22,9 @@ in {
         defaultText = "false";
         description = ''
           Whether to enable the beets music library manager. This
-          defaults to <literal>false</literal> for state
+          defaults to `false` for state
           version ≥ 19.03. For earlier versions beets is enabled if
-          <option>programs.beets.settings</option> is non-empty.
+          {option}`programs.beets.settings` is non-empty.
         '';
       };
 
@@ -35,7 +35,7 @@ in {
         example =
           literalExpression "(pkgs.beets.override { enableCheck = true; })";
         description = ''
-          The <literal>beets</literal> package to use.
+          The `beets` package to use.
           Can be used to specify extensions.
         '';
       };
@@ -45,7 +45,7 @@ in {
         default = { };
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/beets/config.yaml</filename>
+          {file}`$XDG_CONFIG_HOME/beets/config.yaml`
         '';
       };
 
diff --git a/modules/programs/bottom.nix b/modules/programs/bottom.nix
index cb09256c..810307b1 100644
--- a/modules/programs/bottom.nix
+++ b/modules/programs/bottom.nix
@@ -19,7 +19,7 @@ in {
         type = types.package;
         default = pkgs.bottom;
         defaultText = literalExpression "pkgs.bottom";
-        description = "Package providing <command>bottom</command>.";
+        description = "Package providing {command}`bottom`.";
       };
 
       settings = mkOption {
@@ -27,9 +27,9 @@ in {
         default = { };
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/bottom/bottom.toml</filename>.
-          </para><para>
-          See <link xlink:href="https://github.com/ClementTsang/bottom/blob/master/sample_configs/default_config.toml"/>
+          {file}`$XDG_CONFIG_HOME/bottom/bottom.toml`.
+
+          See <https://github.com/ClementTsang/bottom/blob/master/sample_configs/default_config.toml>
           for the default configuration.
         '';
         example = literalExpression ''
diff --git a/modules/programs/broot.nix b/modules/programs/broot.nix
index f90ed308..179b1224 100644
--- a/modules/programs/broot.nix
+++ b/modules/programs/broot.nix
@@ -32,42 +32,31 @@ let
         '';
         description = ''
           Define new verbs. For more information, see
-          <link xlink:href="https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes"/>.
-          </para><para>
-          The possible attributes are:
-          </para>
+          [Verb Definition Attributes](https://dystroy.org/broot/documentation/configuration/#verb-definition-attributes)
+          in the broot documentation.
 
-          <para>
-          <variablelist>
-            <varlistentry>
-              <term><literal>invocation</literal> (optional)</term>
-              <listitem><para>how the verb is called by the user, with placeholders for arguments</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>execution</literal> (mandatory)</term>
-              <listitem><para>how the verb is executed</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>key</literal> (optional)</term>
-              <listitem><para>a keyboard key triggering execution</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>shortcut</literal> (optional)</term>
-              <listitem><para>an alternate way to call the verb (without
-              the arguments part)</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>leave_broot</literal> (optional)</term>
-              <listitem><para>whether to quit broot on execution
-              (default: <literal>true</literal>)</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>from_shell</literal> (optional)</term>
-              <listitem><para>whether the verb must be executed from the
-              parent shell (default:
-              <literal>false</literal>)</para></listitem>
-            </varlistentry>
-          </variablelist>
+          The possible attributes are:
+
+          `invocation` (optional)
+          : how the verb is called by the user, with placeholders for arguments
+
+          `execution` (mandatory)
+          : how the verb is executed
+
+          `key` (optional)
+          : a keyboard key triggering execution
+
+          `shortcut` (optional)
+          : an alternate way to call the verb (without
+            the arguments part)
+
+          `leave_broot` (optional)
+          : whether to quit broot on execution
+            (default: `true`)
+
+          `from_shell` (optional)</term>
+          : whether the verb must be executed from the
+            parent shell (default: `false`)
         '';
       };
 
@@ -94,36 +83,33 @@ let
         '';
         description = ''
           Color configuration.
-          </para><para>
+
           Complete list of keys (expected to change before the v1 of broot):
 
-          <itemizedlist>
-            <listitem><para><literal>char_match</literal></para></listitem>
-            <listitem><para><literal>code</literal></para></listitem>
-            <listitem><para><literal>directory</literal></para></listitem>
-            <listitem><para><literal>exe</literal></para></listitem>
-            <listitem><para><literal>file</literal></para></listitem>
-            <listitem><para><literal>file_error</literal></para></listitem>
-            <listitem><para><literal>flag_label</literal></para></listitem>
-            <listitem><para><literal>flag_value</literal></para></listitem>
-            <listitem><para><literal>input</literal></para></listitem>
-            <listitem><para><literal>link</literal></para></listitem>
-            <listitem><para><literal>permissions</literal></para></listitem>
-            <listitem><para><literal>selected_line</literal></para></listitem>
-            <listitem><para><literal>size_bar_full</literal></para></listitem>
-            <listitem><para><literal>size_bar_void</literal></para></listitem>
-            <listitem><para><literal>size_text</literal></para></listitem>
-            <listitem><para><literal>spinner</literal></para></listitem>
-            <listitem><para><literal>status_error</literal></para></listitem>
-            <listitem><para><literal>status_normal</literal></para></listitem>
-            <listitem><para><literal>table_border</literal></para></listitem>
-            <listitem><para><literal>tree</literal></para></listitem>
-            <listitem><para><literal>unlisted</literal></para></listitem>
-          </itemizedlist></para>
+          * `char_match`
+          * `code`
+          * `directory`
+          * `exe`
+          * `file`
+          * `file_error`
+          * `flag_label`
+          * `flag_value`
+          * `input`
+          * `link`
+          * `permissions`
+          * `selected_line`
+          * `size_bar_full`
+          * `size_bar_void`
+          * `size_text`
+          * `spinner`
+          * `status_error`
+          * `status_normal`
+          * `table_border`
+          * `tree`
+          * `unlisted`
 
-          <para>
-          Add <literal>_fg</literal> for a foreground color and
-          <literal>_bg</literal> for a background colors.
+          Add `_fg` for a foreground color and
+          `_bg` for a background color.
         '';
       };
     };
diff --git a/modules/programs/btop.nix b/modules/programs/btop.nix
index cdf011e7..e30a9f43 100644
--- a/modules/programs/btop.nix
+++ b/modules/programs/btop.nix
@@ -40,8 +40,8 @@ in {
         theme_background = false;
       };
       description = ''
-        Options to add to <filename>btop.conf</filename> file.
-        See <link xlink:href="https://github.com/aristocratos/btop#configurability"/>
+        Options to add to {file}`btop.conf` file.
+        See <https://github.com/aristocratos/btop#configurability>
         for options.
       '';
     };
@@ -50,7 +50,7 @@ in {
       type = types.lines;
       default = "";
       description = ''
-        Extra lines added to the <filename>btop.conf</filename> file.
+        Extra lines added to the {file}`btop.conf` file.
       '';
     };
   };
diff --git a/modules/programs/chromium.nix b/modules/programs/chromium.nix
index c97fd059..11a10547 100644
--- a/modules/programs/chromium.nix
+++ b/modules/programs/chromium.nix
@@ -41,12 +41,12 @@ let
         example = [ "--enable-logging=stderr" "--ignore-gpu-blocklist" ];
         description = ''
           List of command-line arguments to be passed to ${name}.
-          </para><para>
+
           For a list of common switches, see
-          <link xlink:href="https://chromium.googlesource.com/chromium/src/+/refs/heads/main/chrome/common/chrome_switches.cc">Chrome switches</link>.
-          </para><para>
+          [Chrome switches](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/chrome/common/chrome_switches.cc).
+
           To search switches for other components, see
-          <link xlink:href="https://source.chromium.org/search?q=file:switches.cc&amp;ss=chromium%2Fchromium%2Fsrc">Chromium codesearch</link>.
+          [Chromium codesearch](https://source.chromium.org/search?q=file:switches.cc&ss=chromium%2Fchromium%2Fsrc).
         '';
       };
     } // optionalAttrs (!isProprietaryChrome) {
@@ -114,13 +114,13 @@ let
         description = ''
           List of ${name} extensions to install.
           To find the extension ID, check its URL on the
-          <link xlink:href="https://chrome.google.com/webstore/category/extensions">Chrome Web Store</link>.
-          </para><para>
+          [Chrome Web Store](https://chrome.google.com/webstore/category/extensions).
+
           To install extensions outside of the Chrome Web Store set
-          <literal>updateUrl</literal> or <literal>crxPath</literal> and
-          <literal>version</literal> as explained in the
-          <link xlink:href="https://developer.chrome.com/docs/extensions/mv2/external_extensions">Chrome
-          documentation</link>.
+          `updateUrl` or `crxPath` and
+          `version` as explained in the
+          [Chrome
+          documentation](https://developer.chrome.com/docs/extensions/mv2/external_extensions).
         '';
       };
     };
diff --git a/modules/programs/command-not-found/command-not-found.nix b/modules/programs/command-not-found/command-not-found.nix
index a4917bbf..f1a79023 100644
--- a/modules/programs/command-not-found/command-not-found.nix
+++ b/modules/programs/command-not-found/command-not-found.nix
@@ -37,7 +37,7 @@ in {
       default =
         "/nix/var/nix/profiles/per-user/root/channels/nixos/programs.sqlite";
       description = ''
-        Absolute path to <filename>programs.sqlite</filename>. By
+        Absolute path to {file}`programs.sqlite`. By
         default this file will be provided by your channel
         (nixexprs.tar.xz).
       '';
diff --git a/modules/programs/comodoro.nix b/modules/programs/comodoro.nix
index 5c9fa358..fba0bce8 100644
--- a/modules/programs/comodoro.nix
+++ b/modules/programs/comodoro.nix
@@ -17,7 +17,7 @@ in {
       default = { };
       description = ''
         Comodoro configuration.
-        See <link xlink:href="https://pimalaya.org/comodoro/cli/configuration/"/> for supported values.
+        See <https://pimalaya.org/comodoro/cli/configuration/> for supported values.
       '';
     };
   };
diff --git a/modules/programs/dircolors.nix b/modules/programs/dircolors.nix
index 655d71e5..de461089 100644
--- a/modules/programs/dircolors.nix
+++ b/modules/programs/dircolors.nix
@@ -14,8 +14,8 @@ in {
       type = types.bool;
       default = false;
       description = ''
-        Whether to manage <filename>.dir_colors</filename>
-        and set <code>LS_COLORS</code>.
+        Whether to manage {file}`.dir_colors`
+        and set `LS_COLORS`.
       '';
     };
 
@@ -47,8 +47,8 @@ in {
       type = with types; attrsOf str;
       default = { };
       description = ''
-        Options to add to <filename>.dir_colors</filename> file.
-        See <command>dircolors --print-database</command>
+        Options to add to {file}`.dir_colors` file.
+        See {command}`dircolors --print-database`
         for options.
       '';
       example = literalExpression ''
@@ -64,7 +64,7 @@ in {
       type = types.lines;
       default = "";
       description = ''
-        Extra lines added to <filename>.dir_colors</filename> file.
+        Extra lines added to {file}`.dir_colors` file.
       '';
     };
   };
diff --git a/modules/programs/direnv.nix b/modules/programs/direnv.nix
index 676a762d..89ba2bf9 100644
--- a/modules/programs/direnv.nix
+++ b/modules/programs/direnv.nix
@@ -29,13 +29,10 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/direnv/direnv.toml</filename>.
-        </para><para>
+        {file}`$XDG_CONFIG_HOME/direnv/direnv.toml`.
+
         See
-        <citerefentry>
-          <refentrytitle>direnv.toml</refentrytitle>
-          <manvolnum>1</manvolnum>
-        </citerefentry>.
+        {manpage}`direnv.toml(1)`.
         for the full list of options.
       '';
     };
@@ -45,7 +42,7 @@ in {
       default = "";
       description = ''
         Custom stdlib written to
-        <filename>$XDG_CONFIG_HOME/direnv/direnvrc</filename>.
+        {file}`$XDG_CONFIG_HOME/direnv/direnvrc`.
       '';
     };
 
@@ -73,9 +70,9 @@ in {
         Whether to enable Fish integration. Note, enabling the direnv module
         will always active its functionality for Fish since the direnv package
         automatically gets loaded in Fish. If this is not the case try adding
-        <programlisting language="nix">
+        ```nix
           environment.pathsToLink = [ "/share/fish" ];
-        </programlisting>
+        ```
         to the system configuration.
       '';
     };
@@ -90,9 +87,8 @@ in {
 
     nix-direnv = {
       enable = mkEnableOption ''
-        <link
-            xlink:href="https://github.com/nix-community/nix-direnv">nix-direnv</link>,
-            a fast, persistent use_nix implementation for direnv'';
+        [nix-direnv](https://github.com/nix-community/nix-direnv),
+        a fast, persistent use_nix implementation for direnv'';
     };
 
   };
diff --git a/modules/programs/emacs.nix b/modules/programs/emacs.nix
index a9a77949..dfab66cf 100644
--- a/modules/programs/emacs.nix
+++ b/modules/programs/emacs.nix
@@ -50,10 +50,10 @@ in {
         '';
         description = ''
           Configuration to include in the Emacs default init file. See
-          <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Init-File.html"/>
+          <https://www.gnu.org/software/emacs/manual/html_node/elisp/Init-File.html>
           for more.
-          </para><para>
-          Note, the <literal>inhibit-startup-message</literal> Emacs option
+
+          Note, the `inhibit-startup-message` Emacs option
           cannot be set here since Emacs disallows setting it from the default
           initialization file.
         '';
@@ -67,7 +67,7 @@ in {
         description = ''
           Extra packages available to Emacs. To get a list of
           available packages run:
-          <command>nix-env -f '&lt;nixpkgs&gt;' -qaP -A emacsPackages</command>.
+          {command}`nix-env -f '<nixpkgs>' -qaP -A emacsPackages`.
         '';
       };
 
diff --git a/modules/programs/eww.nix b/modules/programs/eww.nix
index 9200986d..3d178f94 100644
--- a/modules/programs/eww.nix
+++ b/modules/programs/eww.nix
@@ -27,7 +27,7 @@ in {
       example = literalExpression "./eww-config-dir";
       description = ''
         The directory that gets symlinked to
-        <filename>$XDG_CONFIG_HOME/eww</filename>.
+        {file}`$XDG_CONFIG_HOME/eww`.
       '';
     };
   };
diff --git a/modules/programs/exa.nix b/modules/programs/exa.nix
index 44a1fb58..afe83e73 100644
--- a/modules/programs/exa.nix
+++ b/modules/programs/exa.nix
@@ -6,8 +6,7 @@ with lib;
   meta.maintainers = [ hm.maintainers.kalhauge ];
 
   options.programs.exa = {
-    enable =
-      mkEnableOption "exa, a modern replacement for <command>ls</command>";
+    enable = mkEnableOption "exa, a modern replacement for {command}`ls`";
 
     enableAliases = mkEnableOption "recommended exa aliases (ls, ll…)";
 
@@ -24,7 +23,7 @@ with lib;
       type = types.bool;
       default = false;
       description = ''
-        Display icons next to file names (<option>--icons</option> argument).
+        Display icons next to file names ({option}`--icons` argument).
       '';
     };
 
@@ -32,7 +31,7 @@ with lib;
       type = types.bool;
       default = false;
       description = ''
-        List each file's Git status if tracked or ignored (<option>--git</option> argument).
+        List each file's Git status if tracked or ignored ({option}`--git` argument).
       '';
     };
 
diff --git a/modules/programs/feh.nix b/modules/programs/feh.nix
index 15aac175..f44f184a 100644
--- a/modules/programs/feh.nix
+++ b/modules/programs/feh.nix
@@ -41,7 +41,7 @@ in {
         Override feh's default mouse button mapping. If you want to disable an
         action, set its value to null. If you want to bind multiple buttons to
         an action, set its value to a list.
-        See <link xlink:href="https://man.finalrewind.org/1/feh/#x425554544f4e53"/> for
+        See <https://man.finalrewind.org/1/feh/#x425554544f4e53> for
         default bindings and available commands.
       '';
     };
@@ -58,7 +58,7 @@ in {
         Override feh's default keybindings. If you want to disable a keybinding
         set its value to null. If you want to bind multiple keys to an action,
         set its value to a list.
-        See <link xlink:href="https://man.finalrewind.org/1/feh/#x4b455953"/> for
+        See <https://man.finalrewind.org/1/feh/#x4b455953> for
         default bindings and available commands.
       '';
     };
diff --git a/modules/programs/firefox.nix b/modules/programs/firefox.nix
index 91ce2c30..fc80c226 100644
--- a/modules/programs/firefox.nix
+++ b/modules/programs/firefox.nix
@@ -211,7 +211,7 @@ in {
               type = types.lines;
               default = "";
               description = ''
-                Extra preferences to add to <filename>user.js</filename>.
+                Extra preferences to add to {file}`user.js`.
               '';
             };
 
@@ -417,17 +417,16 @@ in {
                 '';
                 description = ''
                   Attribute set of search engine configurations. Engines
-                  that only have <varname>metaData</varname> specified will
+                  that only have {var}`metaData` specified will
                   be treated as builtin to Firefox.
-                  </para><para>
-                  See <link xlink:href=
-                  "https://searchfox.org/mozilla-central/rev/669329e284f8e8e2bb28090617192ca9b4ef3380/toolkit/components/search/SearchEngine.jsm#1138-1177">SearchEngine.jsm</link>
+
+                  See [SearchEngine.jsm](https://searchfox.org/mozilla-central/rev/669329e284f8e8e2bb28090617192ca9b4ef3380/toolkit/components/search/SearchEngine.jsm#1138-1177)
                   in Firefox's source for available options. We maintain a
                   mapping to let you specify all options in the referenced
                   link without underscores, but it may fall out of date with
                   future options.
-                  </para><para>
-                  Note, <varname>icon</varname> is also a special option
+
+                  Note, {var}`icon` is also a special option
                   added by Home Manager to make it convenient to specify
                   absolute icon paths.
                 '';
@@ -444,18 +443,16 @@ in {
               '';
               description = ''
                 List of Firefox add-on packages to install for this profile.
-                Some pre-packaged add-ons are accessible from NUR,
-                <link xlink:href="https://github.com/nix-community/NUR"/>.
+                Some pre-packaged add-ons are accessible from the
+                [Nix User Repository](https://github.com/nix-community/NUR).
                 Once you have NUR installed run
 
-                <screen language="console">
-                  <prompt>$</prompt> <userinput>nix-env -f '&lt;nixpkgs&gt;' -qaP -A nur.repos.rycee.firefox-addons</userinput>
-                </screen>
+                ```console
+                $ nix-env -f '<nixpkgs>' -qaP -A nur.repos.rycee.firefox-addons
+                ```
 
                 to list the available Firefox add-ons.
 
-                </para><para>
-
                 Note that it is necessary to manually enable these extensions
                 inside Firefox after the first installation.
               '';
@@ -473,8 +470,8 @@ in {
         description = ''
           Whether to enable the GNOME Shell native host connector. Note, you
           also need to set the NixOS option
-          <literal>services.gnome.gnome-browser-connector.enable</literal> to
-          <literal>true</literal>.
+          `services.gnome.gnome-browser-connector.enable` to
+          `true`.
         '';
       };
     };
diff --git a/modules/programs/fish.nix b/modules/programs/fish.nix
index e9bc76e8..109fb529 100644
--- a/modules/programs/fish.nix
+++ b/modules/programs/fish.nix
@@ -12,10 +12,10 @@ let
         type = types.path;
         description = ''
           Path to the plugin folder.
-          </para><para>
+
           Relevant pieces will be added to the fish function path and
-          the completion path. The <filename>init.fish</filename> and
-          <filename>key_binding.fish</filename> files are sourced if
+          the completion path. The {file}`init.fish` and
+          {file}`key_binding.fish` files are sourced if
           they exist.
         '';
       };
@@ -89,7 +89,7 @@ let
         default = null;
         description = ''
           Tells fish to run this function when the job with the specified group
-          ID exits. Instead of a PID, the stringer <literal>caller</literal> can
+          ID exits. Instead of a PID, the stringer `caller` can
           be specified. This is only legal when in a command substitution, and
           will result in the handler being triggered by the exit of the job
           which created this command substitution.
@@ -103,8 +103,8 @@ let
         description = ''
           Tells fish to run this function when the fish child process with the
           specified process ID exits. Instead of a PID, for backwards
-          compatibility, <literal>%self</literal> can be specified as an alias
-          for <literal>$fish_pid</literal>, and the function will be run when
+          compatibility, `%self` can be specified as an alias
+          for `$fish_pid`, and the function will be run when
           the current fish instance exits.
         '';
       };
@@ -270,7 +270,7 @@ in {
       '';
       description = ''
         The plugins to source in
-        <filename>conf.d/99plugins.fish</filename>.
+        {file}`conf.d/99plugins.fish`.
       '';
     };
 
@@ -289,7 +289,7 @@ in {
       '';
       description = ''
         Basic functions to add to fish. For more information see
-        <link xlink:href="https://fishshell.com/docs/current/cmds/function.html"/>.
+        <https://fishshell.com/docs/current/cmds/function.html>.
       '';
     };
   };
diff --git a/modules/programs/foot.nix b/modules/programs/foot.nix
index 2b08f3ac..79832dce 100644
--- a/modules/programs/foot.nix
+++ b/modules/programs/foot.nix
@@ -27,8 +27,7 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/foot/foot.ini</filename>. See <link
-        xlink:href="https://codeberg.org/dnkl/foot/src/branch/master/foot.ini"/>
+        {file}`$XDG_CONFIG_HOME/foot/foot.ini`. See <https://codeberg.org/dnkl/foot/src/branch/master/foot.ini>
         for a list of available options.
       '';
       example = literalExpression ''
diff --git a/modules/programs/fuzzel.nix b/modules/programs/fuzzel.nix
index aff97cf1..5057c36d 100644
--- a/modules/programs/fuzzel.nix
+++ b/modules/programs/fuzzel.nix
@@ -30,9 +30,8 @@ in {
       '';
       description = ''
         Configuration for fuzzel written to
-        <filename>$XDG_CONFIG_HOME/fuzzel/fuzzel.ini</filename>. See
-        <citerefentry><refentrytitle>fuzzel.ini</refentrytitle>
-        <manvolnum>5</manvolnum></citerefentry> for a list of available options.
+        {file}`$XDG_CONFIG_HOME/fuzzel/fuzzel.ini`. See
+        {manpage}`fuzzel.ini(5)` for a list of available options.
       '';
     };
   };
diff --git a/modules/programs/fzf.nix b/modules/programs/fzf.nix
index fe1e720d..7544c1ef 100644
--- a/modules/programs/fzf.nix
+++ b/modules/programs/fzf.nix
@@ -23,7 +23,7 @@ in {
       type = types.package;
       default = pkgs.fzf;
       defaultText = literalExpression "pkgs.fzf";
-      description = "Package providing the <command>fzf</command> tool.";
+      description = "Package providing the {command}`fzf` tool.";
     };
 
     defaultCommand = mkOption {
@@ -104,15 +104,15 @@ in {
         }
       '';
       description = ''
-        Color scheme options added to <code>FZF_DEFAULT_OPTS</code>. See
-        <link xlink:href="https://github.com/junegunn/fzf/wiki/Color-schemes"/>
+        Color scheme options added to `FZF_DEFAULT_OPTS`. See
+        <https://github.com/junegunn/fzf/wiki/Color-schemes>
         for documentation.
       '';
     };
 
     tmux = {
       enableShellIntegration = mkEnableOption ''
-        setting <literal>FZF_TMUX=1</literal> which causes shell integration to use fzf-tmux
+        setting `FZF_TMUX=1` which causes shell integration to use fzf-tmux
       '';
 
       shellIntegrationOptions = mkOption {
@@ -120,9 +120,9 @@ in {
         default = [ ];
         example = literalExpression ''[ "-d 40%" ]'';
         description = ''
-          If <option>programs.fzf.tmux.enableShellIntegration</option> is set to <literal>true</literal>,
+          If {option}`programs.fzf.tmux.enableShellIntegration` is set to `true`,
           shell integration will use these options for fzf-tmux.
-          See <command>fzf-tmux --help</command> for available options.
+          See {command}`fzf-tmux --help` for available options.
         '';
       };
     };
diff --git a/modules/programs/gallery-dl.nix b/modules/programs/gallery-dl.nix
index 560ec8e9..accad55f 100644
--- a/modules/programs/gallery-dl.nix
+++ b/modules/programs/gallery-dl.nix
@@ -24,8 +24,8 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/gallery-dl/config.json</filename>. See
-        <link xlink:href="https://github.com/mikf/gallery-dl#configuration"/>
+        {file}`$XDG_CONFIG_HOME/gallery-dl/config.json`. See
+        <https://github.com/mikf/gallery-dl#configuration>
         for supported values.
       '';
     };
diff --git a/modules/programs/getmail-accounts.nix b/modules/programs/getmail-accounts.nix
index 24eb4fb5..e2ff9405 100644
--- a/modules/programs/getmail-accounts.nix
+++ b/modules/programs/getmail-accounts.nix
@@ -21,7 +21,7 @@ with lib;
       example = [ "INBOX" "INBOX.spam" ];
       description = ''
         A non-empty list of mailboxes. To download all mail you can
-        use the <literal>ALL</literal> mailbox.
+        use the `ALL` mailbox.
       '';
     };
 
@@ -30,8 +30,8 @@ with lib;
       default = false;
       description = ''
         Enable if you want to delete read messages from the server. Most
-        users should either enable <literal>delete</literal> or disable
-        <literal>readAll</literal>.
+        users should either enable `delete` or disable
+        `readAll`.
       '';
     };
 
@@ -40,8 +40,8 @@ with lib;
       default = true;
       description = ''
         Enable if you want to fetch all, even the read messages from the
-        server. Most users should either enable <literal>delete</literal> or
-        disable <literal>readAll</literal>.
+        server. Most users should either enable `delete` or
+        disable `readAll`.
       '';
     };
 
diff --git a/modules/programs/gh.nix b/modules/programs/gh.nix
index 920dd643..fcf0f8f3 100644
--- a/modules/programs/gh.nix
+++ b/modules/programs/gh.nix
@@ -69,14 +69,14 @@ in {
       type = types.package;
       default = pkgs.gh;
       defaultText = literalExpression "pkgs.gh";
-      description = "Package providing <command>gh</command>.";
+      description = "Package providing {command}`gh`.";
     };
 
     settings = mkOption {
       type = settingsType;
       default = { };
       description =
-        "Configuration written to <filename>$XDG_CONFIG_HOME/gh/config.yml</filename>.";
+        "Configuration written to {file}`$XDG_CONFIG_HOME/gh/config.yml`.";
       example = literalExpression ''
         {
           git_protocol = "ssh";
@@ -100,7 +100,7 @@ in {
       type = types.listOf types.package;
       default = [ ];
       description = ''
-        gh extensions, see <link xlink:href="https://cli.github.com/manual/gh_extension"/>.
+        gh extensions, see <https://cli.github.com/manual/gh_extension>.
       '';
       example = literalExpression "[ pkgs.gh-eco ]";
     };
diff --git a/modules/programs/git-cliff.nix b/modules/programs/git-cliff.nix
index 7894ec6c..cd7fb529 100644
--- a/modules/programs/git-cliff.nix
+++ b/modules/programs/git-cliff.nix
@@ -26,8 +26,8 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/git-cliff/cliff.toml</filename>. See
-        <link xlink:href="https://git-cliff.org/docs/configuration" />
+        {file}`$XDG_CONFIG_HOME/git-cliff/cliff.toml`. See
+        <https://git-cliff.org/docs/configuration>
         for the documentation.
       '';
     };
diff --git a/modules/programs/git.nix b/modules/programs/git.nix
index 415f046d..b9aca2db 100644
--- a/modules/programs/git.nix
+++ b/modules/programs/git.nix
@@ -64,8 +64,8 @@ let
         type = types.nullOr types.str;
         description = ''
           The default GPG signing key fingerprint.
-          </para><para>
-          Set to <literal>null</literal> to let GnuPG decide what signing key
+
+          Set to `null` to let GnuPG decide what signing key
           to use depending on commit’s author.
         '';
       };
@@ -91,12 +91,9 @@ let
         type = types.nullOr types.str;
         default = null;
         description = ''
-          Include this configuration only when <varname>condition</varname>
+          Include this configuration only when {var}`condition`
           matches. Allowed conditions are described in
-          <citerefentry>
-            <refentrytitle>git-config</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>.
+          {manpage}`git-config(1)`.
         '';
       };
 
@@ -124,10 +121,7 @@ let
           Configuration to include. If empty then a path must be given.
 
           This follows the configuration structure as described in
-          <citerefentry>
-            <refentrytitle>git-config</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>.
+          {manpage}`git-config(1)`.
         '';
       };
 
@@ -158,8 +152,8 @@ in {
         default = pkgs.git;
         defaultText = literalExpression "pkgs.git";
         description = ''
-          Git package to install. Use <varname>pkgs.gitAndTools.gitFull</varname>
-          to gain access to <command>git send-email</command> for instance.
+          Git package to install. Use {var}`pkgs.gitAndTools.gitFull`
+          to gain access to {command}`git send-email` for instance.
         '';
       };
 
@@ -211,7 +205,7 @@ in {
         '';
         description = ''
           Configuration helper for Git hooks.
-          See <link xlink:href="https://git-scm.com/docs/githooks" />
+          See <https://git-scm.com/docs/githooks>
           for reference.
         '';
       };
@@ -258,7 +252,7 @@ in {
           default = false;
           description = ''
             Skip automatic downloading of objects on clone or pull.
-            This requires a manual <command>git lfs pull</command>
+            This requires a manual {command}`git lfs pull`
             every time a new commit is checked out on your repository.
           '';
         };
@@ -267,8 +261,8 @@ in {
       difftastic = {
         enable = mkEnableOption "" // {
           description = ''
-            Enable the <command>difftastic</command> syntax highlighter.
-            See <link xlink:href="https://github.com/Wilfred/difftastic" />.
+            Enable the {command}`difftastic` syntax highlighter.
+            See <https://github.com/Wilfred/difftastic>.
           '';
         };
 
@@ -305,8 +299,8 @@ in {
       delta = {
         enable = mkEnableOption "" // {
           description = ''
-            Whether to enable the <command>delta</command> syntax highlighter.
-            See <link xlink:href="https://github.com/dandavison/delta" />.
+            Whether to enable the {command}`delta` syntax highlighter.
+            See <https://github.com/dandavison/delta>.
           '';
         };
 
@@ -337,8 +331,8 @@ in {
       diff-so-fancy = {
         enable = mkEnableOption "" // {
           description = ''
-            Enable the <command>diff-so-fancy</command> diff colorizer.
-            See <link xlink:href="https://github.com/so-fancy/diff-so-fancy" />.
+            Enable the {command}`diff-so-fancy` diff colorizer.
+            See <https://github.com/so-fancy/diff-so-fancy>.
           '';
         };
 
@@ -346,7 +340,7 @@ in {
           type = types.listOf types.str;
           default = [ "--tabs=4" "-RFX" ];
           description = ''
-            Arguments to be passed to <command>less</command>.
+            Arguments to be passed to {command}`less`.
           '';
         };
 
@@ -373,7 +367,7 @@ in {
           default = true;
           example = false;
           description = ''
-            Whether the <literal>+</literal> or <literal>-</literal> at
+            Whether the `+` or `-` at
             line-start should be removed.
           '';
         };
diff --git a/modules/programs/gitui.nix b/modules/programs/gitui.nix
index 710e3fd9..029986b9 100644
--- a/modules/programs/gitui.nix
+++ b/modules/programs/gitui.nix
@@ -30,7 +30,7 @@ in {
       '';
       description = ''
         Key config in Ron file format. This is written to
-        <filename>$XDG_CONFIG_HOME/gitui/key_config.ron</filename>.
+        {file}`$XDG_CONFIG_HOME/gitui/key_config.ron`.
       '';
     };
 
@@ -63,7 +63,7 @@ in {
       '';
       description = ''
         Theme in Ron file format. This is written to
-        <filename>$XDG_CONFIG_HOME/gitui/theme.ron</filename>.
+        {file}`$XDG_CONFIG_HOME/gitui/theme.ron`.
       '';
     };
   };
diff --git a/modules/programs/gnome-terminal.nix b/modules/programs/gnome-terminal.nix
index a9e3b5a7..e1922cd0 100644
--- a/modules/programs/gnome-terminal.nix
+++ b/modules/programs/gnome-terminal.nix
@@ -106,7 +106,7 @@ let
         default = null;
         type = types.nullOr types.bool;
         description = ''
-          If <literal>true</literal>, allow applications in the
+          If `true`, allow applications in the
           terminal to make text boldface.
         '';
       };
@@ -150,40 +150,22 @@ let
         type = eraseBinding;
         description = ''
           Which string the terminal should send to an application when the user
-          presses the <emphasis>Backspace</emphasis> key.
+          presses the *Backspace* key.
 
-          <variablelist>
-            <varlistentry>
-              <term><literal>auto</literal></term>
-              <listitem><para>
-                Attempt to determine the right value from the terminal's IO settings.
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>ascii-backspace</literal></term>
-              <listitem><para>
-                Send an ASCII backspace character (0x08).
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>ascii-delete</literal></term>
-              <listitem><para>
-                Send an ASCII delete character (0x7F).
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>delete-sequence</literal></term>
-              <listitem><para>
-                Send the <quote>@7</quote> control sequence.
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>tty</literal></term>
-              <listitem><para>
-                Send terminal’s <quote>erase</quote> setting.
-              </para></listitem>
-            </varlistentry>
-          </variablelist>
+          `auto`
+          : Attempt to determine the right value from the terminal's IO settings.
+
+          `ascii-backspace`
+          : Send an ASCII backspace character (`0x08`).
+
+          `ascii-delete`
+          : Send an ASCII delete character (`0x7F`).
+
+          `delete-sequence`
+          : Send the `@7` control sequence.
+
+          `tty`
+          : Send terminal's "erase" setting.
         '';
       };
 
@@ -198,40 +180,22 @@ let
         type = eraseBinding;
         description = ''
           Which string the terminal should send to an application when the user
-          presses the <emphasis>Delete</emphasis> key.
+          presses the *Delete* key.
 
-          <variablelist>
-            <varlistentry>
-              <term><literal>auto</literal></term>
-              <listitem><para>
-                Send the <quote>@7</quote> control sequence.
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>ascii-backspace</literal></term>
-              <listitem><para>
-                Send an ASCII backspace character (0x08).
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>ascii-delete</literal></term>
-              <listitem><para>
-                Send an ASCII delete character (0x7F).
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>delete-sequence</literal></term>
-              <listitem><para>
-                Send the <quote>@7</quote> control sequence.
-              </para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>tty</literal></term>
-              <listitem><para>
-                Send terminal’s <quote>erase</quote> setting.
-              </para></listitem>
-            </varlistentry>
-          </variablelist>
+          `auto`
+          : Send the `@7` control sequence.
+
+          `ascii-backspace`
+          : Send an ASCII backspace character (`0x08`).
+
+          `ascii-delete`
+          : Send an ASCII delete character (`0x7F`).
+
+          `delete-sequence`
+          : Send the `@7` control sequence.
+
+          `tty`
+          : Send terminal's "erase" setting.
         '';
       };
 
diff --git a/modules/programs/go.nix b/modules/programs/go.nix
index 70a5c9b6..5d150036 100644
--- a/modules/programs/go.nix
+++ b/modules/programs/go.nix
@@ -37,8 +37,8 @@ in {
         default = null;
         example = "go";
         description = ''
-          Primary <envar>GOPATH</envar> relative to
-          <envar>HOME</envar>. It will be exported first and therefore
+          Primary {env}`GOPATH` relative to
+          {env}`HOME`. It will be exported first and therefore
           used by default by the Go tooling.
         '';
       };
@@ -48,8 +48,8 @@ in {
         default = [ ];
         example = [ "extraGoPath1" "extraGoPath2" ];
         description = ''
-          Extra <envar>GOPATH</envar>s relative to <envar>HOME</envar> appended
-          after <xref linkend="opt-programs.go.goPath"/>, if that option is set.
+          Extra {env}`GOPATH`s relative to {env}`HOME` appended
+          after [](#opt-programs.go.goPath), if that option is set.
         '';
       };
 
@@ -65,7 +65,7 @@ in {
         default = [ ];
         example = [ "*.corp.example.com" "rsc.io/private" ];
         description = ''
-          The <envar>GOPRIVATE</envar> environment variable controls
+          The {env}`GOPRIVATE` environment variable controls
           which modules the go command considers to be private (not
           available publicly) and should therefore not use the proxy
           or checksum database.
diff --git a/modules/programs/gpg.nix b/modules/programs/gpg.nix
index 0b75931d..ca1d15f8 100644
--- a/modules/programs/gpg.nix
+++ b/modules/programs/gpg.nix
@@ -65,31 +65,24 @@ let
         description = ''
           The amount of trust you have in the key ownership and the care the
           owner puts into signing other keys. The available levels are
-          <variablelist>
-            <varlistentry>
-              <term><literal>unknown</literal> or <literal>1</literal></term>
-              <listitem><para>I don't know or won't say.</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>never</literal> or <literal>2</literal></term>
-              <listitem><para>I do NOT trust.</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>marginal</literal> or <literal>3</literal></term>
-              <listitem><para>I trust marginally.</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>full</literal> or <literal>4</literal></term>
-              <listitem><para>I trust fully.</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>ultimate</literal> or <literal>5</literal></term>
-              <listitem><para>I trust ultimately.</para></listitem>
-            </varlistentry>
-          </variablelist>
-          </para><para>
-          See <link xlink:href="https://www.gnupg.org/gph/en/manual/x334.html"/>
-          for more.
+
+          `unknown` or `1`
+          : I don't know or won't say.
+
+          `never` or `2`
+          : I do **not** trust.
+
+          `marginal` or `3`
+          : I trust marginally.
+
+          `full` or `4`
+          : I trust fully.
+
+          `ultimate` or `5`
+          : I trust ultimately.
+
+          See the [Key Management chapter](https://www.gnupg.org/gph/en/manual/x334.html)
+          of the GNU Privacy Handbook for more.
         '';
       };
     };
@@ -169,14 +162,10 @@ in {
       description = ''
         GnuPG configuration options. Available options are described
         in
-        <link xlink:href="https://gnupg.org/documentation/manpage.html">
-          <citerefentry>
-              <refentrytitle>gpg</refentrytitle>
-              <manvolnum>1</manvolnum>
-          </citerefentry>
-        </link>.
-        </para>
-        <para>
+        [
+          {manpage}`gpg(1)`
+        ](https://gnupg.org/documentation/manpage.html).
+
         Note that lists are converted to duplicate keys.
       '';
     };
@@ -192,12 +181,9 @@ in {
       description = ''
         SCdaemon configuration options. Available options are described
         in
-        <link xlink:href="https://www.gnupg.org/documentation/manuals/gnupg/Scdaemon-Options.html">
-          <citerefentry>
-              <refentrytitle>scdaemon</refentrytitle>
-              <manvolnum>1</manvolnum>
-          </citerefentry>
-        </link>.
+        [
+          {manpage}`scdaemon(1)`
+        ](https://www.gnupg.org/documentation/manuals/gnupg/Scdaemon-Options.html).
       '';
     };
 
@@ -214,12 +200,12 @@ in {
       type = types.bool;
       default = true;
       description = ''
-        If set to <literal>true</literal>, you may manage your keyring as a user
-        using the <literal>gpg</literal> command. Upon activation, the keyring
+        If set to `true`, you may manage your keyring as a user
+        using the `gpg` command. Upon activation, the keyring
         will have managed keys added without overwriting unmanaged keys.
-        </para><para>
-        If set to <literal>false</literal>, the path
-        <filename>$GNUPGHOME/pubring.kbx</filename> will become an immutable
+
+        If set to `false`, the path
+        {file}`$GNUPGHOME/pubring.kbx` will become an immutable
         link to the Nix store, denying modifications.
       '';
     };
@@ -228,15 +214,15 @@ in {
       type = types.bool;
       default = true;
       description = ''
-        If set to <literal>true</literal>, you may manage trust as a user using
-        the <command>gpg</command> command. Upon activation, trusted keys have
+        If set to `true`, you may manage trust as a user using
+        the {command}`gpg` command. Upon activation, trusted keys have
         their trust set without overwriting unmanaged keys.
-        </para><para>
-        If set to <literal>false</literal>, the path
-        <filename>$GNUPGHOME/trustdb.gpg</filename> will be
-        <emphasis>overwritten</emphasis> on each activation, removing trust for
+
+        If set to `false`, the path
+        {file}`$GNUPGHOME/trustdb.gpg` will be
+        *overwritten* on each activation, removing trust for
         any unmanaged keys. Be careful to make a backup of your old
-        <filename>trustdb.gpg</filename> before switching to immutable trust!
+        {file}`trustdb.gpg` before switching to immutable trust!
       '';
     };
 
diff --git a/modules/programs/havoc.nix b/modules/programs/havoc.nix
index 6ae89c1d..c83a1c39 100644
--- a/modules/programs/havoc.nix
+++ b/modules/programs/havoc.nix
@@ -20,8 +20,7 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/havoc.cfg</filename>. See <link
-        xlink:href="https://raw.githubusercontent.com/ii8/havoc/master/havoc.cfg"/>
+        {file}`$XDG_CONFIG_HOME/havoc.cfg`. See <https://raw.githubusercontent.com/ii8/havoc/master/havoc.cfg>
         for a list of available options.
       '';
       example = literalExpression ''
diff --git a/modules/programs/helix.nix b/modules/programs/helix.nix
index 1f3e6249..e8390ffd 100644
--- a/modules/programs/helix.nix
+++ b/modules/programs/helix.nix
@@ -22,8 +22,8 @@ in {
       type = types.bool;
       default = false;
       description = ''
-        Whether to configure <command>hx</command> as the default
-        editor using the <envar>EDITOR</envar> environment variable.
+        Whether to configure {command}`hx` as the default
+        editor using the {env}`EDITOR` environment variable.
       '';
     };
 
@@ -47,9 +47,9 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/helix/config.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://docs.helix-editor.com/configuration.html" />
+        {file}`$XDG_CONFIG_HOME/helix/config.toml`.
+
+        See <https://docs.helix-editor.com/configuration.html>
         for the full list of options.
       '';
     };
@@ -82,9 +82,9 @@ in {
       '';
       description = ''
         Language specific configuration at
-        <filename>$XDG_CONFIG_HOME/helix/languages.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://docs.helix-editor.com/languages.html" />
+        {file}`$XDG_CONFIG_HOME/helix/languages.toml`.
+
+        See <https://docs.helix-editor.com/languages.html>
         for more information.
       '';
     };
@@ -151,10 +151,10 @@ in {
       '';
       description = ''
         Each theme is written to
-        <filename>$XDG_CONFIG_HOME/helix/themes/theme-name.toml</filename>.
+        {file}`$XDG_CONFIG_HOME/helix/themes/theme-name.toml`.
         Where the name of each attribute is the theme-name (in the example "base16").
-        </para><para>
-        See <link xlink:href="https://docs.helix-editor.com/themes.html" />
+
+        See <https://docs.helix-editor.com/themes.html>
         for the full list of options.
       '';
     };
diff --git a/modules/programs/hexchat.nix b/modules/programs/hexchat.nix
index 4eda0755..01ece4bd 100644
--- a/modules/programs/hexchat.nix
+++ b/modules/programs/hexchat.nix
@@ -75,46 +75,33 @@ let
           default = null;
           description = ''
             The login method. The allowed options are:
-            <variablelist>
-              <varlistentry>
-                <term><literal>null</literal></term>
-                <listitem><para>Default</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>"nickServMsg"</literal></term>
-                <listitem><para>NickServ (/MSG NickServ + password)</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>"nickServ"</literal></term>
-                <listitem><para>NickServ (/NICKSERV + password)</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>"challengeAuth"</literal></term>
-                <listitem><para>Challenge Auth (username + password)</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>"sasl"</literal></term>
-                <listitem><para>SASL (username + password)</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>"serverPassword"</literal></term>
-                <listitem><para>Server password (/PASS password)</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>"saslExternal"</literal></term>
-                <listitem><para>SASL EXTERNAL (cert)</para></listitem>
-              </varlistentry>
-              <varlistentry>
-                <term><literal>"customCommands"</literal></term>
-                <listitem>
-                  <para>Use "commands" field for auth. For example
-                  <programlisting language="nix">
-            commands = [ "/msg NickServ IDENTIFY my_password" ]
-            </programlisting>
-                  </para>
-                </listitem>
-              </varlistentry>
-            </variablelist>
+
+            `null`
+            :  Default
+
+            `"nickServMsg"`
+            :  NickServ (`/MSG NickServ` + password)
+
+            `"nickServ"`
+            :  NickServ (`/NICKSERV` + password)
+
+            `"challengeAuth"`
+            :  Challenge Auth (username + password)
+
+            `"sasl"`
+            :  SASL (username + password)
+
+            `"serverPassword"`
+            :  Server password (`/PASS` password)
+
+            `"saslExternal"`
+            :  SASL EXTERNAL (cert)
+
+            `"customCommands"`
+            : Use "commands" field for auth. For example
+              ```nix
+              commands = [ "/msg NickServ IDENTIFY my_password" ]
+              ```
           '';
         };
 
@@ -154,7 +141,7 @@ let
           default = null;
           description = ''
             Real name. Is used to populate the real name field that appears when
-            someone uses the <literal>WHOIS</literal> command on your nick.
+            someone uses the `WHOIS` command on your nick.
           '';
         };
 
@@ -162,7 +149,7 @@ let
           type = nullOr str;
           default = null;
           description = ''
-            User name. Part of your <literal>user@host</literal> hostmask that
+            User name. Part of your `user@host` hostmask that
             appears to other on IRC.
           '';
         };
@@ -268,7 +255,7 @@ in {
           };
         }'';
       description = ''
-        Configures <filename>$XDG_CONFIG_HOME/hexchat/servlist.conf</filename>.
+        Configures {file}`$XDG_CONFIG_HOME/hexchat/servlist.conf`.
       '';
     };
 
@@ -284,8 +271,8 @@ in {
         };
       '';
       description = ''
-        Configuration for <filename>$XDG_CONFIG_HOME/hexchat/hexchat.conf</filename>, see
-        <link xlink:href="https://hexchat.readthedocs.io/en/latest/settings.html#list-of-settings"/>
+        Configuration for {file}`$XDG_CONFIG_HOME/hexchat/hexchat.conf`, see
+        <https://hexchat.readthedocs.io/en/latest/settings.html#list-of-settings>
         for supported values.
       '';
     };
@@ -295,23 +282,18 @@ in {
       default = false;
       description = ''
         Enables overwriting HexChat configuration files
-        (<filename>hexchat.conf</filename>, <filename>servlist.conf</filename>).
-        Any existing HexChat configuration will be lost. Certify to back-up any
-        previous configuration before enabling this.
-        </para><para>
+        ({file}`hexchat.conf`, {file}`servlist.conf`).
+        Any existing HexChat configuration will be lost. Make sure to back up
+        any previous configuration before enabling this.
+
         Enabling this setting is recommended, because everytime HexChat
         application is closed it overwrites Nix/Home Manager provided
         configuration files, causing:
-        <orderedlist numeration="arabic">
-          <listitem><para>
-            Nix/Home Manager provided configuration to be out of sync with
-            actual active HexChat configuration.
-          </para></listitem>
-          <listitem><para>
-            Blocking Nix/Home Manager updates until configuration files are
-            manually removed.
-          </para></listitem>
-        </orderedlist>
+
+        1. Nix/Home Manager provided configuration to be out of sync with
+           actual active HexChat configuration.
+        2. Nix/Home Manager updates to be blocked until configuration files are
+           manually removed.
       '';
     };
 
@@ -327,7 +309,7 @@ in {
       '';
       description = ''
         Theme package for HexChat. Expects a derivation containing decompressed
-        theme files. Note, <literal>.hct</literal> files are actually ZIP files,
+        theme files. Note, `.hct` files are actually ZIP files,
         as seen in example.
       '';
     };
diff --git a/modules/programs/himalaya.nix b/modules/programs/himalaya.nix
index 673bd7de..26e56312 100644
--- a/modules/programs/himalaya.nix
+++ b/modules/programs/himalaya.nix
@@ -118,22 +118,21 @@ in {
 
   options = {
     programs.himalaya = {
-      enable = lib.mkEnableOption "Enable the Himalaya email client.";
+      enable = lib.mkEnableOption "the Himalaya email client";
       package = lib.mkPackageOption pkgs "himalaya" { };
       settings = lib.mkOption {
         type = lib.types.submodule { freeformType = tomlFormat.type; };
         default = { };
         description = ''
           Himalaya global configuration.
-          See <link xlink:href="https://pimalaya.org/himalaya/cli/configuration/global.html"/> for supported values.
+          See <https://pimalaya.org/himalaya/cli/configuration/global.html> for supported values.
         '';
       };
     };
 
     services = {
       himalaya-notify = {
-        enable =
-          lib.mkEnableOption "Enable the Himalaya new emails notifier service.";
+        enable = lib.mkEnableOption "the Himalaya new emails notifier service";
 
         environment = lib.mkOption {
           type = with lib.types; attrsOf str;
@@ -171,8 +170,8 @@ in {
       };
 
       himalaya-watch = {
-        enable = lib.mkEnableOption
-          "Enable the Himalaya folder changes watcher service.";
+        enable =
+          lib.mkEnableOption "the Himalaya folder changes watcher service";
 
         environment = lib.mkOption {
           type = with lib.types; attrsOf str;
@@ -213,15 +212,15 @@ in {
     accounts.email.accounts = lib.mkOption {
       type = lib.types.attrsOf (lib.types.submodule {
         options.himalaya = {
-          enable = lib.mkEnableOption "Enable Himalaya for this email account.";
+          enable = lib.mkEnableOption "Himalaya for this email account";
 
           # TODO: remove me for the next release
           backend = lib.mkOption {
             type = with lib.types; nullOr str;
             default = null;
             description = ''
-              Specifying 'accounts.email.accounts.*.himalaya.backend' is deprecated,
-              set 'accounts.email.accounts.*.himalaya.settings.backend' instead.
+              Specifying {option}`accounts.email.accounts.*.himalaya.backend` is deprecated,
+              set {option}`accounts.email.accounts.*.himalaya.settings.backend` instead.
             '';
           };
 
@@ -229,8 +228,8 @@ in {
           sender = lib.mkOption {
             type = with lib.types; nullOr str;
             description = ''
-              Specifying 'accounts.email.accounts.*.himalaya.sender' is deprecated,
-              set 'accounts.email.accounts.*.himalaya.settings.sender' instead.
+              Specifying {option}`accounts.email.accounts.*.himalaya.sender` is deprecated,
+              set {option}'accounts.email.accounts.*.himalaya.settings.sender' instead.
             '';
           };
 
@@ -239,7 +238,7 @@ in {
             default = { };
             description = ''
               Himalaya configuration for this email account.
-              See <link xlink:href="https://pimalaya.org/himalaya/cli/configuration/account.html"/> for supported values.
+              See <https://pimalaya.org/himalaya/cli/configuration/account.html> for supported values.
             '';
           };
         };
diff --git a/modules/programs/home-manager.nix b/modules/programs/home-manager.nix
index b5a73298..8ea37017 100644
--- a/modules/programs/home-manager.nix
+++ b/modules/programs/home-manager.nix
@@ -19,9 +19,9 @@ in {
         example = "$HOME/devel/home-manager";
         description = ''
           The default path to use for Home Manager. When
-          <literal>null</literal>, then the <filename>home-manager</filename>
-          channel, <filename>$HOME/.config/nixpkgs/home-manager</filename>, and
-          <filename>$HOME/.nixpkgs/home-manager</filename> will be attempted.
+          `null`, then the {file}`home-manager`
+          channel, {file}`$HOME/.config/nixpkgs/home-manager`, and
+          {file}`$HOME/.nixpkgs/home-manager` will be attempted.
         '';
       };
     };
diff --git a/modules/programs/htop.nix b/modules/programs/htop.nix
index 27368602..1c569c40 100644
--- a/modules/programs/htop.nix
+++ b/modules/programs/htop.nix
@@ -151,7 +151,7 @@ in {
       '';
       description = ''
         Configuration options to add to
-        <filename>$XDG_CONFIG_HOME/htop/htoprc</filename>.
+        {file}`$XDG_CONFIG_HOME/htop/htoprc`.
       '';
     };
 
@@ -159,7 +159,7 @@ in {
       type = types.package;
       default = pkgs.htop;
       defaultText = literalExpression "pkgs.htop";
-      description = "Package containing the <command>htop</command> program.";
+      description = "Package containing the {command}`htop` program.";
     };
   };
 
diff --git a/modules/programs/i3status-rust.nix b/modules/programs/i3status-rust.nix
index 237afd81..c5c020cb 100644
--- a/modules/programs/i3status-rust.nix
+++ b/modules/programs/i3status-rust.nix
@@ -51,8 +51,8 @@ in {
             ];
             description = ''
               Configuration blocks to add to i3status-rust
-              <filename>config</filename>. See
-              <link xlink:href="https://github.com/greshake/i3status-rust/blob/master/blocks.md"/>
+              {file}`config`. See
+              <https://github.com/greshake/i3status-rust/blob/master/blocks.md>
               for block options.
             '';
             example = literalExpression ''
@@ -88,7 +88,7 @@ in {
             default = { };
             description = ''
               Any extra options to add to i3status-rust
-              <filename>config</filename>.
+              {file}`config`.
             '';
             example = literalExpression ''
               {
@@ -108,7 +108,7 @@ in {
             default = "none";
             description = ''
               The icons set to use. See
-              <link xlink:href="https://github.com/greshake/i3status-rust/blob/master/doc/themes.md"/>
+              <https://github.com/greshake/i3status-rust/blob/master/doc/themes.md>
               for a list of available icon sets.
             '';
             example = "awesome6";
@@ -119,7 +119,7 @@ in {
             default = "plain";
             description = ''
               The theme to use. See
-              <link xlink:href="https://github.com/greshake/i3status-rust/blob/master/doc/themes.md"/>
+              <https://github.com/greshake/i3status-rust/blob/master/doc/themes.md>
               for a list of available themes.
             '';
             example = "gruvbox-dark";
@@ -163,18 +163,15 @@ in {
       };
       description = ''
         Attribute set of i3status-rust bars, each with their own configuration.
-        Each bar <varname>name</varname> generates a config file suffixed with
-        the bar's <varname>name</varname> from the attribute set, like so:
-        <filename>config-<replaceable>name</replaceable>.toml</filename>.
-        </para><para>
+        Each bar {var}`name` generates a config file suffixed with
+        the bar's {var}`name` from the attribute set, like so:
+        {file}`config-''${name}.toml`.
+
         This way, multiple config files can be generated, such as for having a
         top and a bottom bar.
-        </para><para>
+
         See
-        <citerefentry>
-         <refentrytitle>i3status-rust</refentrytitle>
-         <manvolnum>1</manvolnum>
-        </citerefentry>
+        {manpage}`i3status-rust(1)`
         for options.
       '';
       example = literalExpression ''
diff --git a/modules/programs/i3status.nix b/modules/programs/i3status.nix
index 5fd4f741..17b1162e 100644
--- a/modules/programs/i3status.nix
+++ b/modules/programs/i3status.nix
@@ -51,13 +51,10 @@ in {
       type = settingsType;
       default = { };
       description = ''
-        Configuration to add to i3status <filename>config</filename>
-        <code>general</code> section.
+        Configuration to add to i3status {file}`config`
+        `general` section.
         See
-        <citerefentry>
-         <refentrytitle>i3status</refentrytitle>
-         <manvolnum>1</manvolnum>
-        </citerefentry>
+        {manpage}`i3status(1)`
         for options.
       '';
       example = literalExpression ''
@@ -84,7 +81,7 @@ in {
           position = mkOption {
             type = with types; either int float;
             description = ''
-              Position of this module in i3status <code>order</code>.
+              Position of this module in i3status `order`.
             '';
           };
           settings = mkOption {
@@ -93,10 +90,7 @@ in {
             description = ''
               Configuration to add to this i3status module.
               See
-              <citerefentry>
-               <refentrytitle>i3status</refentrytitle>
-               <manvolnum>1</manvolnum>
-              </citerefentry>
+              {manpage}`i3status(1)`
               for options.
             '';
             example = literalExpression ''
@@ -111,12 +105,9 @@ in {
       });
       default = { };
       description = ''
-        Modules to add to i3status <filename>config</filename> file.
+        Modules to add to i3status {file}`config` file.
         See
-        <citerefentry>
-         <refentrytitle>i3status</refentrytitle>
-         <manvolnum>1</manvolnum>
-        </citerefentry>
+        {manpage}`i3status(1)`
         for options.
       '';
       example = literalExpression ''
diff --git a/modules/programs/imv.nix b/modules/programs/imv.nix
index 2841b5a2..583c2c57 100644
--- a/modules/programs/imv.nix
+++ b/modules/programs/imv.nix
@@ -23,10 +23,7 @@ in {
       type = with types; attrsOf (attrsOf (oneOf [ bool int str ]));
       description = ''
         Configuration options for imv. See
-        <citerefentry>
-          <refentrytitle>imv</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>.
+        {manpage}`imv(5)`.
       '';
       example = literalExpression ''
         {
diff --git a/modules/programs/irssi.nix b/modules/programs/irssi.nix
index d0953ed7..bcce6cfa 100644
--- a/modules/programs/irssi.nix
+++ b/modules/programs/irssi.nix
@@ -153,7 +153,7 @@ let
         default = false;
         description = ''
           Enable SASL external authentication. This requires setting a path in
-          <xref linkend="opt-programs.irssi.networks._name_.server.ssl.certificateFile"/>.
+          [](#opt-programs.irssi.networks._name_.server.ssl.certificateFile).
         '';
       };
     };
diff --git a/modules/programs/java.nix b/modules/programs/java.nix
index d10f64c5..115a8a9e 100644
--- a/modules/programs/java.nix
+++ b/modules/programs/java.nix
@@ -16,8 +16,8 @@ in {
     programs.java = {
       enable = mkEnableOption "" // {
         description = ''
-          Install the Java development kit and set the <envar>JAVA_HOME</envar>
-          variable.
+          Install the Java development kit and set the
+          {env}`JAVA_HOME` variable.
         '';
       };
 
@@ -27,7 +27,7 @@ in {
         defaultText = "pkgs.jdk";
         description = ''
           Java package to install. Typical values are
-          <literal>pkgs.jdk</literal> or <literal>pkgs.jre</literal>.
+          `pkgs.jdk` or `pkgs.jre`.
         '';
       };
     };
diff --git a/modules/programs/joshuto.nix b/modules/programs/joshuto.nix
index 63c32523..6f87277d 100644
--- a/modules/programs/joshuto.nix
+++ b/modules/programs/joshuto.nix
@@ -23,9 +23,9 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/joshuto/joshuto.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/joshuto.toml.md" />
+        {file}`$XDG_CONFIG_HOME/joshuto/joshuto.toml`.
+
+        See <https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/joshuto.toml.md>
         for the full list of options.
       '';
     };
@@ -35,9 +35,9 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/joshuto/keymap.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/keymap.toml.md" />
+        {file}`$XDG_CONFIG_HOME/joshuto/keymap.toml`.
+
+        See <https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/keymap.toml.md>
         for the full list of options. Note that this option will overwrite any existing keybinds.
       '';
     };
@@ -47,9 +47,9 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/joshuto/mimetype.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/mimetype.toml.md" />
+        {file}`$XDG_CONFIG_HOME/joshuto/mimetype.toml`.
+
+        See <https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/mimetype.toml.md>
         for the full list of options
       '';
     };
@@ -59,9 +59,9 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/joshuto/theme.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/theme.toml.md" />
+        {file}`$XDG_CONFIG_HOME/joshuto/theme.toml`.
+
+        See <https://github.com/kamiyaa/joshuto/blob/main/docs/configuration/theme.toml.md>
         for the full list of options
       '';
     };
diff --git a/modules/programs/jq.nix b/modules/programs/jq.nix
index e810f884..f4ec5334 100644
--- a/modules/programs/jq.nix
+++ b/modules/programs/jq.nix
@@ -39,9 +39,10 @@ in {
 
       colors = mkOption {
         description = ''
-          The colors used in colored JSON output.</para>
+          The colors used in colored JSON output.
 
-          <para>See <link xlink:href="https://stedolan.github.io/jq/manual/#Colors"/>.
+          See the [Colors section](https://jqlang.github.io/jq/manual/#Colors)
+          of the jq manual.
         '';
 
         example = literalExpression ''
diff --git a/modules/programs/jujutsu.nix b/modules/programs/jujutsu.nix
index 6f40064b..aca23550 100644
--- a/modules/programs/jujutsu.nix
+++ b/modules/programs/jujutsu.nix
@@ -28,8 +28,8 @@ in {
         }
       '';
       description = ''
-        Options to add to the <filename>.jjconfig.toml</filename> file. See
-        <link xlink:href="https://github.com/martinvonz/jj/blob/main/docs/config.md"/>
+        Options to add to the {file}`.jjconfig.toml` file. See
+        <https://github.com/martinvonz/jj/blob/main/docs/config.md>
         for options.
       '';
     };
diff --git a/modules/programs/k9s.nix b/modules/programs/k9s.nix
index 11ac2bfd..b32769cc 100644
--- a/modules/programs/k9s.nix
+++ b/modules/programs/k9s.nix
@@ -21,8 +21,8 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/k9s/config.yml</filename>. See
-        <link xlink:href="https://k9scli.io/topics/config/"/>
+        {file}`$XDG_CONFIG_HOME/k9s/config.yml`. See
+        <https://k9scli.io/topics/config/>
         for supported values.
       '';
       example = literalExpression ''
@@ -37,8 +37,8 @@ in {
       default = { };
       description = ''
         Skin written to
-        <filename>$XDG_CONFIG_HOME/k9s/skin.yml</filename>. See
-        <link xlink:href="https://k9scli.io/topics/skins/"/>
+        {file}`$XDG_CONFIG_HOME/k9s/skin.yml`. See
+        <https://k9scli.io/topics/skins/>
         for supported values.
       '';
       example = literalExpression ''
diff --git a/modules/programs/kakoune.nix b/modules/programs/kakoune.nix
index 55db23bd..da0af0c0 100644
--- a/modules/programs/kakoune.nix
+++ b/modules/programs/kakoune.nix
@@ -53,7 +53,7 @@ let
         example = "SetOption";
         description = ''
           The name of the hook. For a description, see
-          <link xlink:href="https://github.com/mawww/kakoune/blob/master/doc/pages/hooks.asciidoc#default-hooks"/>.
+          <https://github.com/mawww/kakoune/blob/master/doc/pages/hooks.asciidoc#default-hooks>.
         '';
       };
 
@@ -116,7 +116,7 @@ let
         example = "<a-x>";
         description = ''
           The key to be mapped. See
-          <link xlink:href="https://github.com/mawww/kakoune/blob/master/doc/pages/mapping.asciidoc#mappable-keys"/>
+          <https://github.com/mawww/kakoune/blob/master/doc/pages/mapping.asciidoc#mappable-keys>
           for possible values.
         '';
       };
@@ -138,7 +138,7 @@ let
         default = null;
         description = ''
           Set the color scheme. To see available schemes, enter
-          <command>colorscheme</command> at the kakoune prompt.
+          {command}`colorscheme` at the kakoune prompt.
         '';
       };
 
@@ -147,7 +147,7 @@ let
         default = null;
         description = ''
           The width of a tab in spaces. The kakoune default is
-          <literal>6</literal>.
+          `6`.
         '';
       };
 
@@ -156,8 +156,8 @@ let
         default = null;
         description = ''
           The width of an indentation in spaces.
-          The kakoune default is <literal>4</literal>.
-          If <literal>0</literal>, a tab will be used instead.
+          The kakoune default is `4`.
+          If `0`, a tab will be used instead.
         '';
       };
 
@@ -184,7 +184,7 @@ let
         example = [ "command" "normal" ];
         description = ''
           Contexts in which to display automatic information box.
-          The kakoune default is <literal>[ "command" "onkey" ]</literal>.
+          The kakoune default is `[ "command" "onkey" ]`.
         '';
       };
 
@@ -193,7 +193,7 @@ let
         default = null;
         description = ''
           Modes in which to display possible completions.
-          The kakoune default is <literal>[ "insert" "prompt" ]</literal>.
+          The kakoune default is `[ "insert" "prompt" ]`.
         '';
       };
 
@@ -202,7 +202,7 @@ let
         default = null;
         description = ''
           Reload buffers when an external modification is detected.
-          The kakoune default is <literal>"ask"</literal>.
+          The kakoune default is `"ask"`.
         '';
       };
 
@@ -297,7 +297,7 @@ let
               description = ''
                 Amount by which shifted function keys are offset. That
                 is, if the terminal sends F13 for Shift-F1, this
-                should be <literal>12</literal>.
+                should be `12`.
               '';
             };
 
@@ -321,7 +321,7 @@ let
         default = false;
         description = ''
           Highlight the matching char of the character under the
-          selections' cursor using the <literal>MatchingChar</literal>
+          selections' cursor using the `MatchingChar`
           face.
         '';
       };
@@ -361,7 +361,7 @@ let
               example = "⏎";
               description = ''
                 Prefix wrapped lines with marker text.
-                If not <literal>null</literal>,
+                If not `null`,
                 the marker text will be displayed in the indentation if possible.
               '';
             };
@@ -400,7 +400,7 @@ let
               description = ''
                 String that separates the line number column from the
                 buffer contents. The kakoune default is
-                <literal>"|"</literal>.
+                `"|"`.
               '';
             };
           };
@@ -421,7 +421,7 @@ let
               default = null;
               description = ''
                 The character to display for line feeds.
-                The kakoune default is <literal>"¬"</literal>.
+                The kakoune default is `"¬"`.
               '';
             };
 
@@ -430,7 +430,7 @@ let
               default = null;
               description = ''
                 The character to display for spaces.
-                The kakoune default is <literal>"·"</literal>.
+                The kakoune default is `"·"`.
               '';
             };
 
@@ -439,7 +439,7 @@ let
               default = null;
               description = ''
                 The character to display for non-breaking spaces.
-                The kakoune default is <literal>"⍽"</literal>.
+                The kakoune default is `"⍽"`.
               '';
             };
 
@@ -448,7 +448,7 @@ let
               default = null;
               description = ''
                 The character to display for tabs.
-                The kakoune default is <literal>"→"</literal>.
+                The kakoune default is `"→"`.
               '';
             };
 
@@ -457,7 +457,7 @@ let
               default = null;
               description = ''
                 The character to append to tabs to reach the width of a tabstop.
-                The kakoune default is <literal>" "</literal>.
+                The kakoune default is `" "`.
               '';
             };
           };
@@ -473,7 +473,7 @@ let
         default = [ ];
         description = ''
           User-defined key mappings. For documentation, see
-          <link xlink:href="https://github.com/mawww/kakoune/blob/master/doc/pages/mapping.asciidoc"/>.
+          <https://github.com/mawww/kakoune/blob/master/doc/pages/mapping.asciidoc>.
         '';
       };
 
@@ -482,7 +482,7 @@ let
         default = [ ];
         description = ''
           Global hooks. For documentation, see
-          <link xlink:href="https://github.com/mawww/kakoune/blob/master/doc/pages/hooks.asciidoc"/>.
+          <https://github.com/mawww/kakoune/blob/master/doc/pages/hooks.asciidoc>.
         '';
       };
     };
@@ -634,8 +634,8 @@ in {
         type = types.bool;
         default = false;
         description = ''
-          Whether to configure <command>kak</command> as the default
-          editor using the <envar>EDITOR</envar> environment variable.
+          Whether to configure {command}`kak` as the default
+          editor using the {env}`EDITOR` environment variable.
         '';
       };
 
@@ -644,7 +644,7 @@ in {
         default = "";
         description = ''
           Extra configuration lines to add to
-          <filename>$XDG_CONFIG_HOME/kak/kakrc</filename>.
+          {file}`$XDG_CONFIG_HOME/kak/kakrc`.
         '';
       };
 
@@ -655,7 +655,7 @@ in {
         description = ''
           List of kakoune plugins to install. To get a list of
           supported plugins run:
-          <command>nix-env -f '&lt;nixpkgs&gt;' -qaP -A kakounePlugins</command>.
+          {command}`nix-env -f '<nixpkgs>' -qaP -A kakounePlugins`.
         '';
       };
     };
diff --git a/modules/programs/keychain.nix b/modules/programs/keychain.nix
index 3eadf72c..d59855f5 100644
--- a/modules/programs/keychain.nix
+++ b/modules/programs/keychain.nix
@@ -100,7 +100,7 @@ in {
       type = types.bool;
       visible = pkgs.stdenv.hostPlatform.isLinux;
       description = ''
-        Whether to run keychain from your <filename>~/.xsession</filename>.
+        Whether to run keychain from your {file}`~/.xsession`.
       '';
     };
   };
diff --git a/modules/programs/khal.nix b/modules/programs/khal.nix
index 209716a1..42720620 100644
--- a/modules/programs/khal.nix
+++ b/modules/programs/khal.nix
@@ -33,104 +33,113 @@ let
       (toKeyValueIfDefined (getAttrs [ "type" "color" "priority" ] value.khal))
     ] ++ [ "\n" ]);
 
-  localeFormatOptions = let T = lib.types;
-  in mapAttrs (n: v:
-    v // {
-      description = v.description + ''
+  localeFormatOptions = let
+    T = lib.types;
+    suffix = ''
+      Format strings are for Python `strftime`, similarly to
+      {manpage}`strftime(3)`.
+    '';
+  in {
+    dateformat = mkOption {
+      type = T.str;
+      default = "%x";
+      description = ''
+        khal will display and understand all dates in this format.
 
-        Format strings are for python 'strftime', similarly to man 3 strftime.
+        ${suffix}
       '';
-    }) {
-      dateformat = {
-        type = T.str;
-        default = "%x";
-        description = ''
-          khal will display and understand all dates in this format.
-        '';
-      };
-
-      timeformat = {
-        type = T.str;
-        default = "%X";
-        description = ''
-          khal will display and understand all times in this format.
-        '';
-      };
-
-      datetimeformat = {
-        type = T.str;
-        default = "%c";
-        description = ''
-          khal will display and understand all datetimes in this format.
-        '';
-      };
-
-      longdateformat = {
-        type = T.str;
-        default = "%x";
-        description = ''
-          khal will display and understand all dates in this format.
-          It should contain a year (e.g. %Y).
-        '';
-      };
-
-      longdatetimeformat = {
-        type = T.str;
-        default = "%c";
-        description = ''
-          khal will display and understand all datetimes in this format.
-          It should contain a year (e.g. %Y).
-        '';
-      };
     };
 
+    timeformat = mkOption {
+      type = T.str;
+      default = "%X";
+      description = ''
+        khal will display and understand all times in this format.
+
+        ${suffix}
+      '';
+    };
+
+    datetimeformat = mkOption {
+      type = T.str;
+      default = "%c";
+      description = ''
+        khal will display and understand all datetimes in this format.
+
+        ${suffix}
+      '';
+    };
+
+    longdateformat = mkOption {
+      type = T.str;
+      default = "%x";
+      description = ''
+        khal will display and understand all dates in this format.
+        It should contain a year (e.g. `%Y`).
+
+        ${suffix}
+      '';
+    };
+
+    longdatetimeformat = mkOption {
+      type = T.str;
+      default = "%c";
+      description = ''
+        khal will display and understand all datetimes in this format.
+        It should contain a year (e.g. `%Y`).
+
+        ${suffix}
+      '';
+    };
+  };
+
   localeOptions = let T = lib.types;
   in localeFormatOptions // {
-    unicode_symbols = {
+    unicode_symbols = mkOption {
       type = T.bool;
       default = true;
       description = ''
-        By default khal uses some unicode symbols (as in ‘non-ascii’) as
+        By default khal uses some Unicode symbols (as in "non-ASCII") as
         indicators for things like repeating events.
         If your font, encoding etc. does not support those symbols, set this
-        to false (this will enable ascii based replacements).
+        to false (this will enable ASCII-based replacements).
       '';
     };
 
-    default_timezone = {
+    default_timezone = mkOption {
       type = T.nullOr T.str;
       default = null;
       description = ''
         Default for new events or if khal does not understand the timezone
         in an ical file.
-        If 'null', the timezone of your computer will be used.
+        If `null`, the timezone of your computer will be used.
       '';
     };
 
-    local_timezone = {
+    local_timezone = mkOption {
       type = T.nullOr T.str;
       default = null;
       description = ''
         khal will show all times in this timezone.
-        If 'null', the timezone of your computer will be used.
+        If `null`, the timezone of your computer will be used.
       '';
     };
 
-    firstweekday = {
+    firstweekday = mkOption {
       type = T.ints.between 0 6;
       default = 0;
       description = ''
-        the first day of the week, where Monday is 0 and Sunday is 6
+        The first day of the week, where Monday is 0 and Sunday is 6.
       '';
     };
 
-    weeknumbers = {
+    weeknumbers = mkOption {
       type = T.enum [ "off" "left" "right" ];
       default = "off";
       description = ''
-        Enable weeknumbers in calendar and interactive (ikhal) mode.
-        As those are iso weeknumbers, they only work properly if firstweekday
-        is set to 0.
+        Enable week numbers in calendar and interactive (ikhal) mode.
+        As those are ISO week numbers, they only work properly if
+        {option}`firstweekday` is set to 0.
       '';
     };
   };
@@ -139,9 +148,7 @@ in {
   options.programs.khal = {
     enable = mkEnableOption "khal, a CLI calendar application";
     locale = mkOption {
-      type = lib.types.submodule {
-        options = mapAttrs (n: v: mkOption v) localeOptions;
-      };
+      type = lib.types.submodule { options = localeOptions; };
       description = ''
         khal locale settings. 
       '';
diff --git a/modules/programs/kitty.nix b/modules/programs/kitty.nix
index 698e8034..e010ba09 100644
--- a/modules/programs/kitty.nix
+++ b/modules/programs/kitty.nix
@@ -91,8 +91,8 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/kitty/kitty.conf</filename>. See
-        <link xlink:href="https://sw.kovidgoyal.net/kitty/conf.html" />
+        {file}`$XDG_CONFIG_HOME/kitty/kitty.conf`. See
+        <https://sw.kovidgoyal.net/kitty/conf.html>
         for the documentation.
       '';
     };
@@ -102,8 +102,8 @@ in {
       default = null;
       description = ''
         Apply a Kitty color theme. This option takes the friendly name of
-        any theme given by the command <command>kitty +kitten themes</command>.
-        See <link xlink:href="https://github.com/kovidgoyal/kitty-themes"/>
+        any theme given by the command {command}`kitty +kitten themes`.
+        See <https://github.com/kovidgoyal/kitty-themes>
         for more details.
       '';
       example = "Space Gray Eighties";
@@ -145,9 +145,9 @@ in {
         example = "no-cursor";
         description = ''
           Set the mode of the shell integration. This accepts the same options
-          as the <literal>shell_integration</literal> option of Kitty. Note that
-          <literal>no-rc</literal> is always implied. See
-          <link xlink:href="https://sw.kovidgoyal.net/kitty/shell-integration"/>
+          as the `shell_integration` option of Kitty. Note that
+          `no-rc` is always implied. See
+          <https://sw.kovidgoyal.net/kitty/shell-integration>
           for more details.
         '';
       };
diff --git a/modules/programs/kodi.nix b/modules/programs/kodi.nix
index bae862ae..f6776b9e 100644
--- a/modules/programs/kodi.nix
+++ b/modules/programs/kodi.nix
@@ -134,7 +134,7 @@ in {
       example = literalExpression
         "pkgs.kodi.withPackages (exts: [ exts.pvr-iptvsimple ])";
       description = ''
-        The <literal>kodi</literal> package to use.
+        The `kodi` package to use.
         Can be used to specify extensions.
       '';
     };
@@ -160,13 +160,13 @@ in {
         { videolibrary.showemptytvshows = "true"; }
       '';
       description = ''
-        Configuration to write to the <literal>advancedsettings.xml</literal>
+        Configuration to write to the `advancedsettings.xml`
         file in kodis userdata directory. Settings specified here will be
         immutable from inside kodi and be hidden from the GUI settings dialog.
-        </para><para>
-        See <link xlink:href="https://kodi.wiki/view/Advancedsettings.xml"/> as
+
+        See <https://kodi.wiki/view/Advancedsettings.xml> as
         reference for how settings need to be specified.
-        </para><para>
+
         The innermost attributes must be of type str.
       '';
     };
@@ -191,16 +191,16 @@ in {
         }
       '';
       description = ''
-        Contents to populate the file <literal>sources.xml</literal> in kodis
+        Contents to populate the file `sources.xml` in kodis
         userdata directory.
-        </para><para>
-        See <link xlink:href="https://kodi.wiki/view/Sources.xml"/> as
+
+        See <https://kodi.wiki/view/Sources.xml> as
         reference for how sources need to be specified.
-        </para><para>
+
         Kodi will still show the dialogs to modify sources in the GUI and they
         appear to be mutable. This however is not the case and the sources will
         stay as specified via Home Manager.
-        </para><para>
+
         The innermost attributes must be of type str.
       '';
     };
@@ -214,7 +214,7 @@ in {
       description = ''
         Attribute set with the plugin namespace as toplevel key and the plugins
         settings as lower level key/value pairs.
-        </para><para>
+
         Kodi will still show the settings of plugins configured via this
         mechanism in the GUI and they appear to be mutable. This however is
         not the case and the settings will stay as specified via Home Manager.
diff --git a/modules/programs/lazygit.nix b/modules/programs/lazygit.nix
index 7e7312be..0102a22c 100644
--- a/modules/programs/lazygit.nix
+++ b/modules/programs/lazygit.nix
@@ -34,11 +34,11 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/lazygit/config.yml</filename>
-        on Linux or on Darwin if <xref linkend="opt-xdg.enable"/> is set, otherwise
-        <filename>~/Library/Application Support/lazygit/config.yml</filename>.
+        {file}`$XDG_CONFIG_HOME/lazygit/config.yml`
+        on Linux or on Darwin if [](#opt-xdg.enable) is set, otherwise
+        {file}`~/Library/Application Support/lazygit/config.yml`.
         See
-        <link xlink:href="https://github.com/jesseduffield/lazygit/blob/master/docs/Config.md"/>
+        <https://github.com/jesseduffield/lazygit/blob/master/docs/Config.md>
         for supported values.
       '';
     };
diff --git a/modules/programs/ledger.nix b/modules/programs/ledger.nix
index f5b591b2..1b9178d1 100644
--- a/modules/programs/ledger.nix
+++ b/modules/programs/ledger.nix
@@ -37,8 +37,8 @@ in {
         ];
       };
       description = ''
-        Configuration written to <filename>$XDG_CONFIG_HOME/ledger/ledgerrc</filename>.
-        See <link xlink:href="https://www.ledger-cli.org/3.0/doc/ledger3.html#Detailed-Option-Description"/>
+        Configuration written to {file}`$XDG_CONFIG_HOME/ledger/ledgerrc`.
+        See <https://www.ledger-cli.org/3.0/doc/ledger3.html#Detailed-Option-Description>
         for explanation about possible values.
       '';
     };
@@ -53,7 +53,7 @@ in {
       '';
       description = ''
         Extra configuration to add to
-        <filename>$XDG_CONFIG_HOME/ledger/ledgerrc</filename>.
+        {file}`$XDG_CONFIG_HOME/ledger/ledgerrc`.
       '';
     };
   };
diff --git a/modules/programs/less.nix b/modules/programs/less.nix
index 9e6e6720..7249f9bb 100644
--- a/modules/programs/less.nix
+++ b/modules/programs/less.nix
@@ -18,8 +18,8 @@ in {
           t        forw-line
         '';
         description = ''
-          Extra configuration for <command>less</command> written to
-          <filename>$XDG_CONFIG_HOME/lesskey</filename>.
+          Extra configuration for {command}`less` written to
+          {file}`$XDG_CONFIG_HOME/lesskey`.
         '';
       };
     };
diff --git a/modules/programs/lf.nix b/modules/programs/lf.nix
index 8f0a07cb..e7ad0274 100644
--- a/modules/programs/lf.nix
+++ b/modules/programs/lf.nix
@@ -79,19 +79,15 @@ in {
           An attribute set of lf settings. The attribute names and corresponding
           values must be among the following supported options.
 
-          <informaltable frame="none"><tgroup cols="1"><tbody>
           ${concatStringsSep "\n" (mapAttrsToList (n: v: ''
-            <row>
-              <entry><varname>${n}</varname></entry>
-              <entry>${v.description}</entry>
-            </row>
+            {var}`${n}`
+            : ${v.description}
           '') knownSettings)}
-          </tbody></tgroup></informaltable>
 
           See the lf documentation for detailed descriptions of these options.
-          Note, use <varname>previewer</varname> to set lf's
-          <varname>previewer</varname> option, and
-          <varname>extraConfig</varname> for any other option not listed above.
+          Use {option}`programs.lf.previewer.*` to set lf's
+          {var}`previewer` option, and
+          [](#opt-programs.lf.extraConfig) for any other option not listed above.
           All string options are quoted with double quotes.
         '';
       };
@@ -152,7 +148,7 @@ in {
         '';
         description = ''
           Script or executable to use to preview files. Sets lf's
-          <varname>previewer</varname> option.
+          {var}`previewer` option.
         '';
       };
 
@@ -161,7 +157,7 @@ in {
         default = null;
         example = "i";
         description = ''
-          Key to bind to the script at <varname>previewer.source</varname> and
+          Key to bind to the script at {var}`previewer.source` and
           pipe through less. Setting to null will not bind any key.
         '';
       };
diff --git a/modules/programs/librewolf.nix b/modules/programs/librewolf.nix
index 99613d46..d8b6dfab 100644
--- a/modules/programs/librewolf.nix
+++ b/modules/programs/librewolf.nix
@@ -39,7 +39,7 @@ in {
       '';
       description = ''
         Attribute set of LibreWolf settings and overrides. Refer to
-        <link xlink:href="https://librewolf.net/docs/settings/"/>
+        <https://librewolf.net/docs/settings/>
         for details on supported values.
       '';
     };
diff --git a/modules/programs/lieer.nix b/modules/programs/lieer.nix
index 15fda1ae..80993f90 100644
--- a/modules/programs/lieer.nix
+++ b/modules/programs/lieer.nix
@@ -56,9 +56,9 @@ let
       description = ''
         Work around a Gmail API quirk where an empty change history
         is sometimes returned.
-        </para><para>
+
         See this
-        <link xlink:href="https://github.com/gauteh/lieer/issues/120">GitHub issue</link>
+        [GitHub issue](https://github.com/gauteh/lieer/issues/120)
         for more details.
       '';
     };
@@ -128,13 +128,10 @@ let
       default = "*:0/5";
       description = ''
         How often to synchronize the account.
-        </para><para>
+
         This value is passed to the systemd timer configuration as the
         onCalendar option. See
-        <citerefentry>
-          <refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>7</manvolnum>
-        </citerefentry>
+        {manpage}`systemd.time(7)`
         for more information about the format.
       '';
     };
@@ -148,8 +145,8 @@ let
       default = true;
       description = ''
         Warn if Notmuch is not also enabled for this account.
-        </para><para>
-        This can safely be disabled if <command>notmuch init</command>
+
+        This can safely be disabled if {command}`notmuch init`
         has been used to configure this account outside of Home
         Manager.
       '';
@@ -162,10 +159,10 @@ let
       };
       default = { };
       description = ''
-        Settings which are applied to <filename>.gmailieer.json</filename>
+        Settings which are applied to {file}`.gmailieer.json`
         for the account.
-        </para><para>
-        See the <link xlink:href="https://github.com/gauteh/lieer/">lieer manual</link>
+
+        See the [lieer manual](https://github.com/gauteh/lieer/)
         for documentation of settings not explicitly covered by this module.
       '';
     };
diff --git a/modules/programs/lsd.nix b/modules/programs/lsd.nix
index a7f81c74..59a51a12 100644
--- a/modules/programs/lsd.nix
+++ b/modules/programs/lsd.nix
@@ -40,8 +40,8 @@ in {
       };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/lsd/config.yaml</filename>. See
-        <link xlink:href="https://github.com/Peltoche/lsd#config-file-content"/>
+        {file}`$XDG_CONFIG_HOME/lsd/config.yaml`. See
+        <https://github.com/Peltoche/lsd#config-file-content>
         for supported values.
       '';
     };
diff --git a/modules/programs/man.nix b/modules/programs/man.nix
index f757fad5..49ea7485 100644
--- a/modules/programs/man.nix
+++ b/modules/programs/man.nix
@@ -10,9 +10,9 @@ in {
         type = types.bool;
         default = true;
         description = ''
-          Whether to enable manual pages and the <command>man</command>
+          Whether to enable manual pages and the {command}`man`
           command. This also includes "man" outputs of all
-          <literal>home.packages</literal>.
+          `home.packages`.
         '';
       };
 
@@ -28,15 +28,9 @@ in {
         default = false;
         description = ''
           Whether to generate the manual page index caches using
-          <citerefentry>
-            <refentrytitle>mandb</refentrytitle>
-            <manvolnum>8</manvolnum>
-          </citerefentry>. This allows searching for a page or
-          keyword using utilities like <citerefentry>
-            <refentrytitle>apropos</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>.
-          </para><para>
+          {manpage}`mandb(8)`. This allows searching for a page or
+          keyword using utilities like {manpage}`apropos(1)`.
+
           This feature is disabled by default because it slows down
           building. If you don't mind waiting a few more seconds when
           Home Manager builds a new generation, you may safely enable
diff --git a/modules/programs/mangohud.nix b/modules/programs/mangohud.nix
index f095e073..f0e35a3a 100644
--- a/modules/programs/mangohud.nix
+++ b/modules/programs/mangohud.nix
@@ -55,8 +55,8 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/MangoHud/MangoHud.conf</filename>. See
-          <link xlink:href="https://github.com/flightlessmango/MangoHud/blob/master/data/MangoHud.conf"/>
+          {file}`$XDG_CONFIG_HOME/MangoHud/MangoHud.conf`. See
+          <https://github.com/flightlessmango/MangoHud/blob/master/data/MangoHud.conf>
           for the default configuration.
         '';
       };
@@ -74,8 +74,8 @@ in {
         description = ''
           Sets MangoHud settings per application.
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/MangoHud/{application_name}.conf</filename>. See
-          <link xlink:href="https://github.com/flightlessmango/MangoHud/blob/master/data/MangoHud.conf"/>
+          {file}`$XDG_CONFIG_HOME/MangoHud/{application_name}.conf`. See
+          <https://github.com/flightlessmango/MangoHud/blob/master/data/MangoHud.conf>
           for the default configuration.
         '';
       };
diff --git a/modules/programs/matplotlib.nix b/modules/programs/matplotlib.nix
index 1edb9b12..cde6f39f 100644
--- a/modules/programs/matplotlib.nix
+++ b/modules/programs/matplotlib.nix
@@ -25,7 +25,7 @@ in {
       default = { };
       type = types.attrsOf types.anything;
       description = ''
-        Add terms to the <filename>matplotlibrc</filename> file to
+        Add terms to the {file}`matplotlibrc` file to
         control the default matplotlib behavior.
       '';
       example = literalExpression ''
@@ -46,7 +46,7 @@ in {
       default = "";
       description = ''
         Additional commands for matplotlib that will be added to the
-        <filename>matplotlibrc</filename> file.
+        {file}`matplotlibrc` file.
       '';
     };
   };
diff --git a/modules/programs/mbsync-accounts.nix b/modules/programs/mbsync-accounts.nix
index af368b9d..abe5a8ca 100644
--- a/modules/programs/mbsync-accounts.nix
+++ b/modules/programs/mbsync-accounts.nix
@@ -27,7 +27,7 @@ let
           List of channels that should be grouped together into this group. When
           performing a synchronization, the groups are synchronized, rather than
           the individual channels.
-          </para><para>
+
           Using these channels and then grouping them together allows for you to
           define the maildir hierarchy as you see fit.
         '';
@@ -45,7 +45,7 @@ let
         description = ''
           The unique name for THIS channel in THIS group. The group will refer to
           this channel by this name.
-          </para><para>
+
           In addition, you can manually sync just this channel by specifying this
           name to mbsync on the command line.
         '';
@@ -57,12 +57,12 @@ let
         example = "[Gmail]/Sent Mail";
         description = ''
           IMAP4 patterns for which mailboxes on the remote mail server to sync.
-          If <literal>Patterns</literal> are specified, <literal>farPattern</literal>
+          If `Patterns` are specified, `farPattern`
           is interpreted as a prefix which is not matched against the patterns,
           and is not affected by mailbox list overrides.
-          </para><para>
+
           If this is left as the default, then mbsync will default to the pattern
-          <literal>INBOX</literal>.
+          `INBOX`.
         '';
       };
 
@@ -74,9 +74,9 @@ let
           Name for where mail coming from the remote (far) mail server will end up
           locally. The mailbox specified by the far pattern will be placed in
           this directory.
-          </para><para>
+
           If this is left as the default, then mbsync will default to the pattern
-          <literal>INBOX</literal>.
+          `INBOX`.
         '';
       };
 
@@ -85,8 +85,8 @@ let
         default = [ ];
         example = [ "INBOX" ];
         description = ''
-          Instead of synchronizing <emphasis>just</emphasis> the mailboxes that
-          match the <literal>farPattern</literal>, use it as a prefix which is
+          Instead of synchronizing *just* the mailboxes that
+          match the `farPattern`, use it as a prefix which is
           not matched against the patterns, and is not affected by mailbox list
           overrides.
         '';
@@ -104,7 +104,7 @@ let
           }
         '';
         description = ''
-          Extra configuration lines to add to <emphasis>THIS</emphasis> channel's
+          Extra configuration lines to add to *THIS* channel's
           configuration.
         '';
       };
@@ -122,7 +122,7 @@ in {
       description = ''
         If set, flattens the hierarchy within the maildir by
         substituting the canonical hierarchy delimiter
-        <literal>/</literal> with this value.
+        `/` with this value.
       '';
     };
 
@@ -132,7 +132,7 @@ in {
       example = "Maildir++";
       description = ''
         The on-disk folder naming style. This option has no
-        effect when <option>flatten</option> is used.
+        effect when {option}`flatten` is used.
       '';
     };
 
@@ -183,8 +183,8 @@ in {
         Some email providers (Gmail) have a different directory hierarchy for
         synchronized email messages. Namely, when using mbsync without specifying
         a set of channels into a group, all synchronized directories end up beneath
-        the <literal>[Gmail]/</literal> directory.
-        </para><para>
+        the `[Gmail]/` directory.
+
         This option allows you to specify a group, and subsequently channels that
         will allow you to sync your mail into an arbitrary hierarchy.
       '';
diff --git a/modules/programs/micro.nix b/modules/programs/micro.nix
index f2f8b6bf..0093e25f 100644
--- a/modules/programs/micro.nix
+++ b/modules/programs/micro.nix
@@ -26,8 +26,8 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/micro/settings.json</filename>. See
-          <link xlink:href="https://github.com/zyedidia/micro/blob/master/runtime/help/options.md"/>
+          {file}`$XDG_CONFIG_HOME/micro/settings.json`. See
+          <https://github.com/zyedidia/micro/blob/master/runtime/help/options.md>
           for supported values.
         '';
       };
diff --git a/modules/programs/mpv.nix b/modules/programs/mpv.nix
index 1d0b24d4..eb9c9c4a 100644
--- a/modules/programs/mpv.nix
+++ b/modules/programs/mpv.nix
@@ -94,11 +94,8 @@ in {
       scriptOpts = mkOption {
         description = ''
           Script options added to
-          <filename>$XDG_CONFIG_HOME/mpv/script-opts/</filename>. See
-          <citerefentry>
-            <refentrytitle>mpv</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>
+          {file}`$XDG_CONFIG_HOME/mpv/script-opts/`. See
+          {manpage}`mpv(1)`
           for the full list of options of builtin scripts.
         '';
         type = types.attrsOf mpvOptions;
@@ -115,11 +112,8 @@ in {
       config = mkOption {
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/mpv/mpv.conf</filename>. See
-          <citerefentry>
-            <refentrytitle>mpv</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>
+          {file}`$XDG_CONFIG_HOME/mpv/mpv.conf`. See
+          {manpage}`mpv(1)`
           for the full list of options.
         '';
         type = mpvOptions;
@@ -137,8 +131,8 @@ in {
       profiles = mkOption {
         description = ''
           Sub-configuration options for specific profiles written to
-          <filename>$XDG_CONFIG_HOME/mpv/mpv.conf</filename>. See
-          <option>programs.mpv.config</option> for more information.
+          {file}`$XDG_CONFIG_HOME/mpv/mpv.conf`. See
+          {option}`programs.mpv.config` for more information.
         '';
         type = mpvProfiles;
         default = { };
@@ -158,7 +152,7 @@ in {
       defaultProfiles = mkOption {
         description = ''
           Profiles to be applied by default. Options set by them are overridden
-          by options set in <xref linkend="opt-programs.mpv.config"/>.
+          by options set in [](#opt-programs.mpv.config).
         '';
         type = mpvDefaultProfiles;
         default = [ ];
@@ -168,11 +162,8 @@ in {
       bindings = mkOption {
         description = ''
           Input configuration written to
-          <filename>$XDG_CONFIG_HOME/mpv/input.conf</filename>. See
-          <citerefentry>
-            <refentrytitle>mpv</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>
+          {file}`$XDG_CONFIG_HOME/mpv/input.conf`. See
+          {manpage}`mpv(1)`
           for the full list of options.
         '';
         type = mpvBindings;
diff --git a/modules/programs/mr.nix b/modules/programs/mr.nix
index 2e02e7c6..50718976 100644
--- a/modules/programs/mr.nix
+++ b/modules/programs/mr.nix
@@ -23,8 +23,8 @@ in {
       type = iniFormat.type;
       default = { };
       description = ''
-        Configuration written to <filename>$HOME/.mrconfig</filename>
-        See <link xlink:href="https://myrepos.branchable.com/"/>
+        Configuration written to {file}`$HOME/.mrconfig`
+        See <https://myrepos.branchable.com/>
         for an example configuration.
       '';
       example = literalExpression ''
diff --git a/modules/programs/msmtp-accounts.nix b/modules/programs/msmtp-accounts.nix
index 894cef51..5e1158bf 100644
--- a/modules/programs/msmtp-accounts.nix
+++ b/modules/programs/msmtp-accounts.nix
@@ -9,15 +9,15 @@ with lib;
       default = false;
       description = ''
         Whether to enable msmtp.
-        </para><para>
+
         If enabled then it is possible to use the
-        <parameter class="command">--account</parameter> command line
+        `--account` command line
         option to send a message for a given account using the
-        <command>msmtp</command> or <command>msmtpq</command> tool.
-        For example, <command>msmtp --account=private</command> would
+        {command}`msmtp` or {command}`msmtpq` tool.
+        For example, {command}`msmtp --account=private` would
         send using the account defined in
-        <option>accounts.email.accounts.private</option>. If the
-        <parameter class="command">--account</parameter> option is not
+        {option}`accounts.email.accounts.private`. If the
+        `--account` option is not
         given then the primary account will be used.
       '';
     };
@@ -30,7 +30,7 @@ with lib;
       description = ''
         Fingerprint of a trusted TLS certificate.
         The fingerprint can be obtained by executing
-        <command>msmtp --serverinfo --tls --tls-certcheck=off</command>.
+        {command}`msmtp --serverinfo --tls --tls-certcheck=off`.
       '';
     };
 
@@ -39,8 +39,8 @@ with lib;
       default = { };
       example = { auth = "login"; };
       description = ''
-        Extra configuration options to add to <filename>~/.msmtprc</filename>.
-        See <link xlink:href="https://marlam.de/msmtp/msmtprc.txt"/> for
+        Extra configuration options to add to {file}`~/.msmtprc`.
+        See <https://marlam.de/msmtp/msmtprc.txt> for
         examples.
       '';
     };
diff --git a/modules/programs/msmtp.nix b/modules/programs/msmtp.nix
index 04e7be8e..2a4d6b78 100644
--- a/modules/programs/msmtp.nix
+++ b/modules/programs/msmtp.nix
@@ -55,13 +55,13 @@ in {
         type = types.lines;
         default = "";
         description = ''
-          Extra configuration lines to add to <filename>~/.msmtprc</filename>.
-          See <link xlink:href="https://marlam.de/msmtp/msmtprc.txt"/> for examples.
-          </para><para>
+          Extra configuration lines to add to {file}`~/.msmtprc`.
+          See <https://marlam.de/msmtp/msmtprc.txt> for examples.
+
           Note, if running msmtp fails with the error message "account default
           was already defined" then you probably have an account command here.
           Account commands should be placed in
-          <xref linkend="opt-accounts.email.accounts._name_.msmtp.extraConfig"/>.
+          [](#opt-accounts.email.accounts._name_.msmtp.extraConfig).
         '';
       };
 
@@ -69,8 +69,8 @@ in {
         type = types.lines;
         default = "";
         description = ''
-          Extra configuration lines to add to the end of <filename>~/.msmtprc</filename>.
-          See <link xlink:href="https://marlam.de/msmtp/msmtprc.txt"/> for examples.
+          Extra configuration lines to add to the end of {file}`~/.msmtprc`.
+          See <https://marlam.de/msmtp/msmtprc.txt> for examples.
         '';
       };
     };
diff --git a/modules/programs/mujmap.nix b/modules/programs/mujmap.nix
index 291b9656..a0e74ab0 100644
--- a/modules/programs/mujmap.nix
+++ b/modules/programs/mujmap.nix
@@ -70,10 +70,10 @@ let
       default = "inbox";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Inbox</code> name attribute.
-        </para><para>
-        If set to an empty string, this mailbox <emphasis>and its child
-        mailboxes</emphasis> are not synchronized with a tag.
+        `Inbox` name attribute.
+
+        If set to an empty string, this mailbox *and its child
+        mailboxes* are not synchronized with a tag.
       '';
     };
 
@@ -82,10 +82,10 @@ let
       default = "deleted";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Trash</code> name attribute.
-        </para><para>
-        If set to an empty string, this mailbox <emphasis>and its child
-        mailboxes</emphasis> are not synchronized with a tag.
+        `Trash` name attribute.
+
+        If set to an empty string, this mailbox *and its child
+        mailboxes* are not synchronized with a tag.
       '';
     };
 
@@ -94,10 +94,10 @@ let
       default = "sent";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Sent</code> name attribute.
-        </para><para>
-        If set to an empty string, this mailbox <emphasis>and its child
-        mailboxes</emphasis> are not synchronized with a tag.
+        `Sent` name attribute.
+
+        If set to an empty string, this mailbox *and its child
+        mailboxes* are not synchronized with a tag.
       '';
     };
 
@@ -106,11 +106,11 @@ let
       default = "spam";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Junk</code> name attribute and/or with the <code>$Junk</code> keyword,
-        <emphasis>except</emphasis> for messages with the <code>$NotJunk</code> keyword.
-        </para><para>
-        If set to an empty string, this mailbox, <emphasis>its child
-        mailboxes</emphasis>, and these keywords are not synchronized with a tag.
+        `Junk` name attribute and/or with the `$Junk` keyword,
+        *except* for messages with the `$NotJunk` keyword.
+
+        If set to an empty string, this mailbox, *its child
+        mailboxes*, and these keywords are not synchronized with a tag.
       '';
     };
 
@@ -119,11 +119,11 @@ let
       default = "important";
       description = ''
         Tag for notmuch to use for messages stored in the mailbox labeled with the
-        <code>Important</code> name attribute and/or with the <code>$Important</code>
+        `Important` name attribute and/or with the `$Important`
         keyword.
-        </para><para>
-        If set to an empty string, this mailbox, <emphasis>its child
-        mailboxes</emphasis>, and these keywords are not synchronized with a tag.
+
+        If set to an empty string, this mailbox, *its child
+        mailboxes*, and these keywords are not synchronized with a tag.
       '';
     };
 
@@ -131,8 +131,8 @@ let
       type = types.str;
       default = "phishing";
       description = ''
-        Tag for notmuch to use for the IANA <code>$Phishing</code> keyword.
-        </para><para>
+        Tag for notmuch to use for the IANA `$Phishing` keyword.
+
         If set to an empty string, this keyword is not synchronized with a tag.
       '';
     };
@@ -145,9 +145,9 @@ let
       example = "alice@example.com";
       description = ''
         Username for basic HTTP authentication.
-        </para><para>
-        If <literal>null</literal>, defaults to
-        <xref linkend="opt-accounts.email.accounts._name_.userName"/>.
+
+        If `null`, defaults to
+        [](#opt-accounts.email.accounts._name_.userName).
       '';
     };
 
@@ -159,9 +159,9 @@ let
       description = ''
         Shell command which will print a password to stdout for basic HTTP
         authentication.
-        </para><para>
-        If <literal>null</literal>, defaults to
-        <xref linkend="opt-accounts.email.accounts._name_.passwordCommand"/>.
+
+        If `null`, defaults to
+        [](#opt-accounts.email.accounts._name_.passwordCommand).
       '';
     };
 
@@ -171,13 +171,13 @@ let
       example = "example.com";
       description = ''
         Fully qualified domain name of the JMAP service.
-        </para><para>
+
         mujmap looks up the JMAP SRV record for this host to determine the JMAP session
         URL. Mutually exclusive with
-        <xref linkend="opt-accounts.email.accounts._name_.mujmap.settings.session_url"/>.
-        </para><para>
-        If <literal>null</literal>, defaults to
-        <xref linkend="opt-accounts.email.accounts._name_.jmap.host"/>.
+        [](#opt-accounts.email.accounts._name_.mujmap.settings.session_url).
+
+        If `null`, defaults to
+        [](#opt-accounts.email.accounts._name_.jmap.host).
       '';
     };
 
@@ -187,12 +187,12 @@ let
       example = "https://jmap.example.com/.well-known/jmap";
       description = ''
         Session URL to connect to.
-        </para><para>
+
         Mutually exclusive with
-        <xref linkend="opt-accounts.email.accounts._name_.mujmap.settings.fqdn"/>.
-        </para><para>
-        If <literal>null</literal>, defaults to
-        <xref linkend="opt-accounts.email.accounts._name_.jmap.sessionUrl"/>.
+        [](#opt-accounts.email.accounts._name_.mujmap.settings.fqdn).
+
+        If `null`, defaults to
+        [](#opt-accounts.email.accounts._name_.jmap.sessionUrl).
       '';
     };
 
@@ -222,10 +222,10 @@ let
       default = { };
       description = ''
         Tag configuration.
-        </para><para>
+
         Beware that there are quirks that require manual consideration if changing the
         values of these files; please see
-        <link xlink:href="https://github.com/elizagamedev/mujmap/blob/main/mujmap.toml.example"/>
+        <https://github.com/elizagamedev/mujmap/blob/main/mujmap.toml.example>
         for more details.
       '';
     };
@@ -239,8 +239,8 @@ let
       default = true;
       description = ''
         Warn if Notmuch is not also enabled for this account.
-        </para><para>
-        This can safely be disabled if <filename>mujmap.toml</filename> is managed
+
+        This can safely be disabled if {file}`mujmap.toml` is managed
         outside of Home Manager.
       '';
     };
@@ -252,10 +252,10 @@ let
       };
       default = { };
       description = ''
-        Settings which are applied to <filename>mujmap.toml</filename>
+        Settings which are applied to {file}`mujmap.toml`
         for the account.
-        </para><para>
-        See the <link xlink:href="https://github.com/elizagamedev/mujmap">mujmap project</link>
+
+        See the [mujmap project](https://github.com/elizagamedev/mujmap)
         for documentation of settings not explicitly covered by this module.
       '';
     };
diff --git a/modules/programs/navi.nix b/modules/programs/navi.nix
index e33a4f38..aff50b5c 100644
--- a/modules/programs/navi.nix
+++ b/modules/programs/navi.nix
@@ -39,10 +39,10 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/navi/config.yaml</filename> on Linux or
-        <filename>$HOME/Library/Application Support/navi/config.yaml</filename>
+        {file}`$XDG_CONFIG_HOME/navi/config.yaml` on Linux or
+        {file}`$HOME/Library/Application Support/navi/config.yaml`
         on Darwin. See
-        <link xlink:href="https://github.com/denisidoro/navi/blob/master/docs/config_file.md"/>
+        <https://github.com/denisidoro/navi/blob/master/docs/config_file.md>
         for more information.
       '';
     };
diff --git a/modules/programs/ncmpcpp.nix b/modules/programs/ncmpcpp.nix
index 5f9bd36e..d0f2c474 100644
--- a/modules/programs/ncmpcpp.nix
+++ b/modules/programs/ncmpcpp.nix
@@ -55,7 +55,7 @@ in {
       default = pkgs.ncmpcpp;
       defaultText = literalExpression "pkgs.ncmpcpp";
       description = ''
-        Package providing the <code>ncmpcpp</code> command.
+        Package providing the `ncmpcpp` command.
       '';
       example =
         literalExpression "pkgs.ncmpcpp.override { visualizerSupport = true; }";
@@ -75,10 +75,10 @@ in {
           null
       '';
       description = ''
-        Value of the <code>mpd_music_dir</code> setting. On Linux platforms the
-        value of <varname>services.mpd.musicDirectory</varname> is used as the
-        default if <varname>services.mpd.enable</varname> is
-        <literal>true</literal>.
+        Value of the `mpd_music_dir` setting. On Linux platforms the
+        value of {var}`services.mpd.musicDirectory` is used as the
+        default if {var}`services.mpd.enable` is
+        `true`.
       '';
       example = "~/music";
     };
@@ -89,10 +89,7 @@ in {
       description = ''
         Attribute set from name of a setting to its value. For available options
         see
-        <citerefentry>
-          <refentrytitle>ncmpcpp</refentrytitle>
-          <manvolnum>1</manvolnum>
-        </citerefentry>.
+        {manpage}`ncmpcpp(1)`.
       '';
       example = { ncmpcpp_directory = "~/.local/share/ncmpcpp"; };
     };
diff --git a/modules/programs/ncspot.nix b/modules/programs/ncspot.nix
index 97d809bd..c3fe37a2 100644
--- a/modules/programs/ncspot.nix
+++ b/modules/programs/ncspot.nix
@@ -32,9 +32,9 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/ncspot/config.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://github.com/hrkfdn/ncspot#configuration" />
+        {file}`$XDG_CONFIG_HOME/ncspot/config.toml`.
+
+        See <https://github.com/hrkfdn/ncspot#configuration>
         for the full list of options.
       '';
     };
diff --git a/modules/programs/ne.nix b/modules/programs/ne.nix
index 1596066b..3b030312 100644
--- a/modules/programs/ne.nix
+++ b/modules/programs/ne.nix
@@ -41,8 +41,8 @@ in {
       default = "";
       description = ''
         Default preferences for ne.
-        </para><para>
-        Equivalent to <literal>programs.ne.automaticPreferences.".default"</literal>.
+
+        Equivalent to `programs.ne.automaticPreferences.".default"`.
       '';
     };
 
diff --git a/modules/programs/neovim.nix b/modules/programs/neovim.nix
index b57cfe06..f5162f82 100644
--- a/modules/programs/neovim.nix
+++ b/modules/programs/neovim.nix
@@ -44,11 +44,11 @@ let
         # passing actual "${xdg.configHome}/nvim" as basePath was a bit tricky
         # due to how fileType.target is implemented
         type = fileType "programs.neovim.plugins._.runtime"
-          "<varname>xdg.configHome/nvim</varname>" "nvim";
+          "{var}`xdg.configHome/nvim`" "nvim";
         example = literalExpression ''
           { "ftplugin/c.vim".text = "setlocal omnifunc=v:lua.vim.lsp.omnifunc"; }
         '';
-        description = lib.mdDoc ''
+        description = ''
           Set of files that have to be linked in nvim config folder.
         '';
       };
@@ -103,7 +103,7 @@ in {
         type = types.bool;
         default = false;
         description = ''
-          Symlink <command>vi</command> to <command>nvim</command> binary.
+          Symlink {command}`vi` to {command}`nvim` binary.
         '';
       };
 
@@ -111,7 +111,7 @@ in {
         type = types.bool;
         default = false;
         description = ''
-          Symlink <command>vim</command> to <command>nvim</command> binary.
+          Symlink {command}`vim` to {command}`nvim` binary.
         '';
       };
 
@@ -119,7 +119,7 @@ in {
         type = types.bool;
         default = false;
         description = ''
-          Alias <command>vimdiff</command> to <command>nvim -d</command>.
+          Alias {command}`vimdiff` to {command}`nvim -d`.
         '';
       };
 
@@ -127,7 +127,7 @@ in {
         type = types.bool;
         default = false;
         description = ''
-          Enable node provider. Set to <literal>true</literal> to
+          Enable node provider. Set to `true` to
           use Node plugins.
         '';
       };
@@ -144,7 +144,7 @@ in {
         type = types.bool;
         default = true;
         description = ''
-          Enable Python 3 provider. Set to <literal>true</literal> to
+          Enable Python 3 provider. Set to `true` to
           use Python 3 plugins.
         '';
       };
@@ -246,8 +246,8 @@ in {
         type = types.bool;
         default = false;
         description = ''
-          Whether to configure <command>nvim</command> as the default
-          editor using the <envar>EDITOR</envar> environment variable.
+          Whether to configure {command}`nvim` as the default
+          editor using the {env}`EDITOR` environment variable.
         '';
       };
 
@@ -296,9 +296,7 @@ in {
           List of vim plugins to install optionally associated with
           configuration to be placed in init.vim.
 
-          </para><para>
-
-          This option is mutually exclusive with <varname>configure</varname>.
+          This option is mutually exclusive with {var}`configure`.
         '';
       };
 
@@ -339,9 +337,9 @@ in {
           '';
           description = ''
             Extra configuration lines to add to
-            <filename>$XDG_CONFIG_HOME/nvim/coc-settings.json</filename>
+            {file}`$XDG_CONFIG_HOME/nvim/coc-settings.json`
             See
-            <link xlink:href="https://github.com/neoclide/coc.nvim/wiki/Using-the-configuration-file" />
+            <https://github.com/neoclide/coc.nvim/wiki/Using-the-configuration-file>
             for options.
           '';
         };
diff --git a/modules/programs/nheko.nix b/modules/programs/nheko.nix
index 53f67011..1bf1ae70 100644
--- a/modules/programs/nheko.nix
+++ b/modules/programs/nheko.nix
@@ -50,16 +50,12 @@ in {
       description = ''
         Attribute set of Nheko preferences (converted to an INI file).
 
-        </para><para>
-
         For now, it is recommended to run nheko and sign-in before filling in
         the configuration settings in this module, as nheko writes the access
-        token to <filename>$XDG_CONFIG_HOME/nheko/nheko.conf</filename> the
+        token to {file}`$XDG_CONFIG_HOME/nheko/nheko.conf` the
         first time we sign in, and we need that data into these settings for the
         correct functionality of the application.
 
-        </para><para>
-
         This a temporary inconvenience, however, as nheko has plans to move the
         authentication stuff into the local database they currently use. Once
         this happens, this will no longer be an issue.
diff --git a/modules/programs/nix-index.nix b/modules/programs/nix-index.nix
index 2593d8b7..49f4b52e 100644
--- a/modules/programs/nix-index.nix
+++ b/modules/programs/nix-index.nix
@@ -10,7 +10,7 @@ in {
       type = types.package;
       default = pkgs.nix-index;
       defaultText = literalExpression "pkgs.nix-index";
-      description = "Package providing the <command>nix-index</command> tool.";
+      description = "Package providing the {command}`nix-index` tool.";
     };
 
     enableBashIntegration = mkEnableOption "Bash integration" // {
diff --git a/modules/programs/nnn.nix b/modules/programs/nnn.nix
index a32ac723..4a81486f 100644
--- a/modules/programs/nnn.nix
+++ b/modules/programs/nnn.nix
@@ -58,7 +58,7 @@ in {
         example =
           literalExpression "pkgs.nnn.override ({ withNerdIcons = true; });";
         description = ''
-          Package containing the <command>nnn</command> program.
+          Package containing the {command}`nnn` program.
         '';
       };
 
diff --git a/modules/programs/noti.nix b/modules/programs/noti.nix
index e7dc982e..491d73b0 100644
--- a/modules/programs/noti.nix
+++ b/modules/programs/noti.nix
@@ -17,13 +17,10 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/noti/noti.yaml</filename>.
-        </para><para>
+        {file}`$XDG_CONFIG_HOME/noti/noti.yaml`.
+
         See
-        <citerefentry>
-          <refentrytitle>noti.yaml</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>.
+        {manpage}`noti.yaml(5)`.
         for the full list of options.
       '';
       example = literalExpression ''
diff --git a/modules/programs/notmuch.nix b/modules/programs/notmuch.nix
index 9c1c9f5c..a3d679b2 100644
--- a/modules/programs/notmuch.nix
+++ b/modules/programs/notmuch.nix
@@ -57,7 +57,7 @@ in {
               default = [ ];
               description = ''
                 A list to specify files and directories that will not be
-                searched for messages by <command>notmuch new</command>.
+                searched for messages by {command}`notmuch new`.
               '';
             };
 
@@ -67,7 +67,7 @@ in {
               example = [ "new" ];
               description = ''
                 A list of tags that will be added to all messages
-                incorporated by <command>notmuch new</command>.
+                incorporated by {command}`notmuch new`.
               '';
             };
           };
@@ -75,7 +75,7 @@ in {
         default = { };
         description = ''
           Options related to email processing performed by
-          <command>notmuch new</command>.
+          {command}`notmuch new`.
         '';
       };
 
diff --git a/modules/programs/nushell.nix b/modules/programs/nushell.nix
index b72cbb69..58b549a5 100644
--- a/modules/programs/nushell.nix
+++ b/modules/programs/nushell.nix
@@ -23,7 +23,7 @@ let
           defaultText = literalExpression
             "if source is defined, the content of source, otherwise empty";
           description = ''
-            Text of the nushell <filename>${name}</filename> file.
+            Text of the nushell {file}`${name}` file.
             If unset then the source option will be preferred.
           '';
         };
@@ -32,7 +32,7 @@ let
           type = types.nullOr types.path;
           default = null;
           description = ''
-            Path of the nushell <filename>${name}</filename> file to use.
+            Path of the nushell {file}`${name}` file to use.
             If the text option is set, it will be preferred.
           '';
         };
@@ -76,9 +76,8 @@ in {
       '';
       description = ''
         The configuration file to be used for nushell.
-        </para>
-        <para>
-        See <link xlink:href="https://www.nushell.sh/book/configuration.html#configuration" /> for more information.
+
+        See <https://www.nushell.sh/book/configuration.html#configuration> for more information.
       '';
     };
 
@@ -90,9 +89,8 @@ in {
       '';
       description = ''
         The environment variables file to be used for nushell.
-        </para>
-        <para>
-        See <link xlink:href="https://www.nushell.sh/book/configuration.html#configuration" /> for more information.
+
+        See <https://www.nushell.sh/book/configuration.html#configuration> for more information.
       '';
     };
 
@@ -107,9 +105,8 @@ in {
       '';
       description = ''
         The login file to be used for nushell upon logging in.
-        </para>
-        <para>
-        See <link xlink:href="https://www.nushell.sh/book/configuration.html#configuring-nu-as-a-login-shell" /> for more information.
+
+        See <https://www.nushell.sh/book/configuration.html#configuring-nu-as-a-login-shell> for more information.
       '';
     };
 
diff --git a/modules/programs/offlineimap.nix b/modules/programs/offlineimap.nix
index 0cddb4f9..e3a47817 100644
--- a/modules/programs/offlineimap.nix
+++ b/modules/programs/offlineimap.nix
@@ -123,7 +123,7 @@ in {
         };
         description = ''
           Extra configuration options added to the
-          <option>general</option> section.
+          {option}`general` section.
         '';
       };
 
@@ -133,7 +133,7 @@ in {
         example = { gmailtrashfolder = "[Gmail]/Papierkorb"; };
         description = ''
           Extra configuration options added to the
-          <option>DEFAULT</option> section.
+          {option}`DEFAULT` section.
         '';
       };
 
@@ -151,7 +151,7 @@ in {
         '';
         description = ''
           Extra configuration options added to the
-          <code>mbnames</code> section.
+          `mbnames` section.
         '';
       };
     };
diff --git a/modules/programs/oh-my-posh.nix b/modules/programs/oh-my-posh.nix
index d1dfda97..1c6941ca 100644
--- a/modules/programs/oh-my-posh.nix
+++ b/modules/programs/oh-my-posh.nix
@@ -29,9 +29,9 @@ in {
         builtins.fromJSON (builtins.unsafeDiscardStringContext (builtins.readFile "''${pkgs.oh-my-posh}/share/oh-my-posh/themes/space.omp.json"))'';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/oh-my-posh/config.json</filename>. See
-        <link xlink:href="https://ohmyposh.dev/docs/configuration/overview"/>
-        for details. The <literal>useTheme</literal> option is ignored when this
+        {file}`$XDG_CONFIG_HOME/oh-my-posh/config.json`. See
+        <https://ohmyposh.dev/docs/configuration/overview>
+        for details. The `useTheme` option is ignored when this
         option is used.
       '';
     };
@@ -41,9 +41,9 @@ in {
       default = null;
       description = ''
         Use one of the official themes. This should be a name from this list:
-        <link xlink:href="https://ohmyposh.dev/docs/themes"/>. Because a theme
+        <https://ohmyposh.dev/docs/themes>. Because a theme
         is essentially a configuration file, this option is not used when a
-        <literal>configFile</literal> is set.
+        `configFile` is set.
       '';
     };
 
diff --git a/modules/programs/papis.nix b/modules/programs/papis.nix
index 9a43f15f..b110172d 100644
--- a/modules/programs/papis.nix
+++ b/modules/programs/papis.nix
@@ -31,8 +31,8 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/papis/config</filename>. See
-        <link xlink:href="https://papis.readthedocs.io/en/latest/configuration.html"/>
+        {file}`$XDG_CONFIG_HOME/papis/config`. See
+        <https://papis.readthedocs.io/en/latest/configuration.html>
         for supported values.
       '';
     };
@@ -71,6 +71,7 @@ in {
           };
         };
       }));
+      description = "Attribute set of papis libraries.";
     };
   };
 
diff --git a/modules/programs/password-store.nix b/modules/programs/password-store.nix
index 076db93e..203eaa34 100644
--- a/modules/programs/password-store.nix
+++ b/modules/programs/password-store.nix
@@ -20,7 +20,7 @@ in {
         pkgs.pass.withExtensions (exts: [ exts.pass-otp ])
       '';
       description = ''
-        The <literal>pass</literal> package to use.
+        The `pass` package to use.
         Can be used to specify extensions.
       '';
     };
@@ -42,13 +42,10 @@ in {
         }
       '';
       description = ''
-        The <literal>pass</literal> environment variables dictionary.
-        </para><para>
+        The `pass` environment variables dictionary.
+
         See the "Environment variables" section of
-        <citerefentry>
-          <refentrytitle>pass</refentrytitle>
-          <manvolnum>1</manvolnum>
-        </citerefentry>
+        {manpage}`pass(1)`
         and the extension man pages for more information about the
         available keys.
       '';
diff --git a/modules/programs/pet.nix b/modules/programs/pet.nix
index 48e972ae..ee7c107d 100644
--- a/modules/programs/pet.nix
+++ b/modules/programs/pet.nix
@@ -56,7 +56,7 @@ in {
       type = format.type;
       default = { };
       description = ''
-        Settings written to <filename>config.toml</filename>. See the pet
+        Settings written to {file}`config.toml`. See the pet
         documentation for details.
       '';
     };
@@ -66,7 +66,7 @@ in {
       default = pkgs.fzf;
       defaultText = literalExpression "pkgs.fzf";
       description = ''
-        The package needed for the <varname>settings.selectcmd</varname>.
+        The package needed for the {var}`settings.selectcmd`.
       '';
     };
 
diff --git a/modules/programs/pistol.nix b/modules/programs/pistol.nix
index 4d6a1d29..28f7ea97 100644
--- a/modules/programs/pistol.nix
+++ b/modules/programs/pistol.nix
@@ -52,7 +52,7 @@ in {
       '';
       description = ''
         Associations written to the Pistol configuration at
-        <filename>$XDG_CONFIG_HOME/pistol/pistol.conf</filename>.
+        {file}`$XDG_CONFIG_HOME/pistol/pistol.conf`.
       '';
     };
 
diff --git a/modules/programs/piston-cli.nix b/modules/programs/piston-cli.nix
index 6315cb5c..c554c596 100644
--- a/modules/programs/piston-cli.nix
+++ b/modules/programs/piston-cli.nix
@@ -31,7 +31,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/piston-cli/config.yml</filename>.
+        {file}`$XDG_CONFIG_HOME/piston-cli/config.yml`.
       '';
     };
   };
diff --git a/modules/programs/pls.nix b/modules/programs/pls.nix
index 5f4ab9da..c56c4b01 100644
--- a/modules/programs/pls.nix
+++ b/modules/programs/pls.nix
@@ -16,8 +16,7 @@ in {
   meta.maintainers = [ maintainers.arjan-s ];
 
   options.programs.pls = {
-    enable =
-      mkEnableOption "pls, a modern replacement for <command>ls</command>";
+    enable = mkEnableOption "pls, a modern replacement for {command}`ls`";
 
     package = mkPackageOption pkgs "pls" { };
 
diff --git a/modules/programs/powerline-go.nix b/modules/programs/powerline-go.nix
index ec4e45c2..9bc9491b 100644
--- a/modules/programs/powerline-go.nix
+++ b/modules/programs/powerline-go.nix
@@ -58,7 +58,7 @@ in {
         description = ''
           List of module names to load. The list of all available
           modules as well as the choice of default ones are at
-          <link xlink:href="https://github.com/justjanne/powerline-go"/>.
+          <https://github.com/justjanne/powerline-go>.
         '';
         example = [ "host" "ssh" "cwd" "gitlite" "jobs" "exit" ];
       };
@@ -102,7 +102,7 @@ in {
         type = with types; attrsOf (oneOf [ bool int str (listOf str) ]);
         description = ''
           This can be any key/value pair as described in
-          <link xlink:href="https://github.com/justjanne/powerline-go"/>.
+          <https://github.com/justjanne/powerline-go>.
         '';
         example = literalExpression ''
           {
diff --git a/modules/programs/pubs.nix b/modules/programs/pubs.nix
index 5a597dea..1d7f0c0d 100644
--- a/modules/programs/pubs.nix
+++ b/modules/programs/pubs.nix
@@ -46,7 +46,7 @@ in {
         ''''';
       description = ''
         Configuration using syntax written to
-        <filename>$HOME/.pubsrc</filename>.
+        {file}`$HOME/.pubsrc`.
       '';
     };
   };
diff --git a/modules/programs/pyenv.nix b/modules/programs/pyenv.nix
index a83713bb..c2273c67 100644
--- a/modules/programs/pyenv.nix
+++ b/modules/programs/pyenv.nix
@@ -49,10 +49,13 @@ in {
       default = "${config.xdg.dataHome}/pyenv";
       defaultText = "\${config.xdg.dataHome}/pyenv";
       description = ''
-        The pyenv root directory (PYENV_ROOT).
-        </para><para>
-        Note: Deviating from upstream which uses `$HOME/.pyenv`,
-        the default path is set according to the XDG base directory specification.
+        The pyenv root directory ({env}`PYENV_ROOT`).
+
+        ::: {.note}
+        This deviates from upstream, which uses {file}`$HOME/.pyenv`.
+        The default path in Home Manager is set according to the XDG
+        base directory specification.
+        :::
       '';
     };
   };
diff --git a/modules/programs/qutebrowser.nix b/modules/programs/qutebrowser.nix
index 4c391f94..4de6f3e0 100644
--- a/modules/programs/qutebrowser.nix
+++ b/modules/programs/qutebrowser.nix
@@ -66,16 +66,16 @@ in {
       default = { };
       description = ''
         Search engines that can be used via the address bar. Maps a search
-        engine name (such as <literal>DEFAULT</literal>, or
-        <literal>ddg</literal>) to a URL with a <literal>{}</literal>
+        engine name (such as `DEFAULT`, or
+        `ddg`) to a URL with a `{}`
         placeholder. The placeholder will be replaced by the search term, use
-        <literal>{{</literal> and <literal>}}</literal> for literal
-        <literal>{/}</literal> signs. The search engine named
-        <literal>DEFAULT</literal> is used when
-        <literal>url.auto_search</literal> is turned on and something else than
+        `{{` and `}}` for literal
+        `{/}` signs. The search engine named
+        `DEFAULT` is used when
+        `url.auto_search` is turned on and something else than
         a URL was entered to be opened. Other search engines can be used by
         prepending the search engine name to the search term, for example
-        <literal>:open google qutebrowser</literal>.
+        `:open google qutebrowser`.
       '';
       example = literalExpression ''
         {
@@ -91,8 +91,8 @@ in {
       type = types.attrsOf types.anything;
       default = { };
       description = ''
-        Options to add to qutebrowser <filename>config.py</filename> file.
-        See <link xlink:href="https://qutebrowser.org/doc/help/settings.html"/>
+        Options to add to qutebrowser {file}`config.py` file.
+        See <https://qutebrowser.org/doc/help/settings.html>
         for options.
       '';
       example = literalExpression ''
@@ -117,8 +117,8 @@ in {
         as dictionary-key is pressed, the binding for the key used as
         dictionary-value is invoked instead. This is useful for global
         remappings of keys, for example to map Ctrl-[ to Escape. Note that when
-        a key is bound (via <literal>bindings.default</literal> or
-        <literal>bindings.commands</literal>), the mapping is ignored.
+        a key is bound (via `bindings.default` or
+        `bindings.commands`), the mapping is ignored.
       '';
     };
 
@@ -136,108 +136,74 @@ in {
       description = ''
         Key bindings mapping keys to commands in different modes. This setting
         is a dictionary containing mode names and dictionaries mapping keys to
-        commands: <literal>{mode: {key: command}}</literal> If you want to map
-        a key to another key, check the <literal>keyMappings</literal> setting
-        instead. For modifiers, you can use either <literal>-</literal> or
-        <literal>+</literal> as delimiters, and these names:
+        commands: `{mode: {key: command}}` If you want to map
+        a key to another key, check the `keyMappings` setting
+        instead. For modifiers, you can use either `-` or
+        `+` as delimiters, and these names:
 
-        <itemizedlist>
-          <listitem><para>
-            Control: <literal>Control</literal>, <literal>Ctrl</literal>
-          </para></listitem>
-          <listitem><para>
-            Meta: <literal>Meta</literal>, <literal>Windows</literal>,
-            <literal>Mod4</literal>
-          </para></listitem>
-          <listitem><para>
-            Alt: <literal>Alt</literal>, <literal>Mod1</literal>
-          </para></listitem>
-          <listitem><para>
-            Shift: <literal>Shift</literal>
-          </para></listitem>
-        </itemizedlist>
+        Control
+        : `Control`, `Ctrl`
 
-        For simple keys (no <literal>&lt;&gt;</literal>-signs), a capital
+        Meta
+        : `Meta`, `Windows`, `Mod4`
+
+        Alt
+        : `Alt`, `Mod1`
+
+        Shift
+        : `Shift`
+
+        For simple keys (no `<>`-signs), a capital
         letter means the key is pressed with Shift. For special keys (with
-        <literal>&lt;&gt;</literal>-signs), you need to explicitly add
-        <literal>Shift-</literal> to match a key pressed with shift. If you
-        want a binding to do nothing, bind it to the <literal>nop</literal>
+        `<>`-signs), you need to explicitly add
+        `Shift-` to match a key pressed with shift. If you
+        want a binding to do nothing, bind it to the `nop`
         command. If you want a default binding to be passed through to the
         website, bind it to null. Note that some commands which are only useful
         for bindings (but not used interactively) are hidden from the command
-        completion. See <literal>:</literal>help for a full list of available
+        completion. See `:help` for a full list of available
         commands. The following modes are available:
 
-        <variablelist>
-          <varlistentry>
-            <term><literal>normal</literal></term>
-            <listitem><para>
-              Default mode, where most commands are invoked.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>insert</literal></term>
-            <listitem><para>
-              Entered when an input field is focused on a website, or by
-              pressing i in normal mode. Passes through almost all keypresses
-              to the website, but has some bindings like
-              <literal>&lt;Ctrl-e&gt;</literal> to open an external editor.
-              Note that single keys can’t be bound in this mode.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>hint</literal></term>
-            <listitem><para>
-              Entered when f is pressed to select links with the keyboard. Note
-              that single keys can’t be bound in this mode.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>passthrough</literal></term>
-            <listitem><para>
-              Similar to insert mode, but passes through all keypresses except
-              <literal>&lt;Escape&gt;</literal> to leave the mode. It might be
-              useful to bind <literal>&lt;Escape&gt;</literal> to some other
-              key in this mode if you want to be able to send an Escape key to
-              the website as well. Note that single keys can’t be bound in this
-              mode.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>command</literal></term>
-            <listitem><para>
-              Entered when pressing the : key in order to enter a command. Note
-              that single keys can’t be bound in this mode.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>prompt</literal></term>
-            <listitem><para>
-              Entered when there’s a prompt to display, like for download
-              locations or when invoked from JavaScript.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>yesno</literal></term>
-            <listitem><para>
-              Entered when there’s a yes/no prompt displayed.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>caret</literal></term>
-            <listitem><para>
-              Entered when pressing the v mode, used to select text using the
-              keyboard.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>register</literal></term>
-            <listitem><para>
-              Entered when qutebrowser is waiting for a register name/key for
-              commands like <literal>:set-mark</literal>.
-            </para></listitem>
-          </varlistentry>
-        </variablelist>
+        `normal`
+        : Default mode, where most commands are invoked.
+
+        `insert`
+        : Entered when an input field is focused on a website, or by
+          pressing `i` in normal mode. Passes through almost all keypresses
+          to the website, but has some bindings like
+          `<Ctrl-e>` to open an external editor.
+          Note that single keys can't be bound in this mode.
+
+        `hint`
+        : Entered when `f` is pressed to select links with the keyboard. Note
+          that single keys can't be bound in this mode.
+
+        `passthrough`
+        : Similar to insert mode, but passes through all keypresses except
+          `<Escape>` to leave the mode. It might be
+          useful to bind `<Escape>` to some other
+          key in this mode if you want to be able to send an Escape key to
+          the website as well. Note that single keys can't be bound in this
+          mode.
+
+        `command`
+        : Entered when pressing the `:` key in order to enter a command. Note
+          that single keys can't be bound in this mode.
+
+        `prompt`
+        : Entered when there's a prompt to display, like for download
+          locations or when invoked from JavaScript.
+
+        `yesno`
+        : Entered when there's a yes/no prompt displayed.
+
+        `caret`
+        : Entered when pressing the `v` mode, used to select text using the
+          keyboard.
+
+        `register`
+        : Entered when qutebrowser is waiting for a register name/key for
+          commands like `:set-mark`.
       '';
       example = literalExpression ''
         {
@@ -262,7 +228,7 @@ in {
       type = types.attrsOf types.str;
       default = { };
       description = ''
-        Quickmarks to add to qutebrowser's <filename>quickmarks</filename> file.
+        Quickmarks to add to qutebrowser's {file}`quickmarks` file.
         Note that when Home Manager manages your quickmarks, you cannot edit them at runtime.
       '';
       example = literalExpression ''
@@ -277,7 +243,7 @@ in {
       type = types.lines;
       default = "";
       description = ''
-        Extra lines added to qutebrowser <filename>config.py</filename> file.
+        Extra lines added to qutebrowser {file}`config.py` file.
       '';
     };
   };
diff --git a/modules/programs/rbenv.nix b/modules/programs/rbenv.nix
index e491cb81..e740c560 100644
--- a/modules/programs/rbenv.nix
+++ b/modules/programs/rbenv.nix
@@ -48,9 +48,9 @@ in {
         ]
       '';
       description = ''
-        rbenv plugins to install in <filename>$HOME/.rbenv/plugins/</filename>.
-        </para><para>
-        See <link xlink:href="https://github.com/rbenv/rbenv/wiki/Plugins" />
+        rbenv plugins to install in {file}`$HOME/.rbenv/plugins/`.
+
+        See <https://github.com/rbenv/rbenv/wiki/Plugins>
         for the full list of plugins.
       '';
     };
diff --git a/modules/programs/rbw.nix b/modules/programs/rbw.nix
index 204aaa6b..b6369dbc 100644
--- a/modules/programs/rbw.nix
+++ b/modules/programs/rbw.nix
@@ -46,13 +46,13 @@ let
           default = "gtk2";
           description = ''
             Which pinentry interface to use. Beware that
-            <literal>pinentry-gnome3</literal> may not work on non-Gnome
+            `pinentry-gnome3` may not work on non-Gnome
             systems. You can fix it by adding the following to your
             system configuration:
-            <programlisting language="nix">
+            ```nix
             services.dbus.packages = [ pkgs.gcr ];
-            </programlisting>
-            For this reason, the default is <literal>gtk2</literal> for
+            ```
+            For this reason, the default is `gtk2` for
             now.
           '';
           # we want the program in the config
@@ -75,8 +75,8 @@ in {
       default = pkgs.rbw;
       defaultText = literalExpression "pkgs.rbw";
       description = ''
-        Package providing the <command>rbw</command> tool and its
-        <command>rbw-agent</command> daemon.
+        Package providing the {command}`rbw` tool and its
+        {command}`rbw-agent` daemon.
       '';
     };
 
diff --git a/modules/programs/readline.nix b/modules/programs/readline.nix
index fecb4572..b8739e37 100644
--- a/modules/programs/readline.nix
+++ b/modules/programs/readline.nix
@@ -63,7 +63,7 @@ in {
       default = "";
       description = ''
         Configuration lines appended unchanged to the end of the
-        <filename>~/.inputrc</filename> file.
+        {file}`~/.inputrc` file.
       '';
     };
   };
diff --git a/modules/programs/ripgrep.nix b/modules/programs/ripgrep.nix
index 10bc1596..39b31824 100644
--- a/modules/programs/ripgrep.nix
+++ b/modules/programs/ripgrep.nix
@@ -21,8 +21,8 @@ in {
         description = ''
           List of arguments to pass to ripgrep. Each item is given to ripgrep as
           a single command line argument verbatim.
-          </para><para>
-          See <link xlink:href="https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md#configuration-file"/>
+
+          See <https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md#configuration-file>
           for an example configuration.
         '';
       };
diff --git a/modules/programs/rofi-pass.nix b/modules/programs/rofi-pass.nix
index da75299e..9d3ed738 100644
--- a/modules/programs/rofi-pass.nix
+++ b/modules/programs/rofi-pass.nix
@@ -31,7 +31,7 @@ in {
       description = ''
         Extra configuration to be added at to the rofi-pass config file.
         Additional examples can be found at
-        <link xlink:href="https://github.com/carnager/rofi-pass/blob/master/config.example"/>.
+        <https://github.com/carnager/rofi-pass/blob/master/config.example>.
       '';
     };
   };
diff --git a/modules/programs/rofi.nix b/modules/programs/rofi.nix
index 8b1fc991..bf11201b 100644
--- a/modules/programs/rofi.nix
+++ b/modules/programs/rofi.nix
@@ -108,7 +108,7 @@ in {
       default = pkgs.rofi;
       type = types.package;
       description = ''
-        Package providing the <command>rofi</command> binary.
+        Package providing the {command}`rofi` binary.
       '';
       example = literalExpression ''
         pkgs.rofi.override { plugins = [ pkgs.rofi-emoji ]; };
@@ -211,7 +211,7 @@ in {
       description = ''
         Name of theme or path to theme file in rasi format or attribute set with
         theme configuration. Available named themes can be viewed using the
-        <command>rofi-theme-selector</command> tool.
+        {command}`rofi-theme-selector` tool.
       '';
     };
 
diff --git a/modules/programs/rtorrent.nix b/modules/programs/rtorrent.nix
index 7736596e..35c245a2 100644
--- a/modules/programs/rtorrent.nix
+++ b/modules/programs/rtorrent.nix
@@ -23,8 +23,8 @@ in {
       default = "";
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/rtorrent/rtorrent.rc</filename>. See
-        <link xlink:href="https://github.com/rakshasa/rtorrent/wiki/Config-Guide" />
+        {file}`$XDG_CONFIG_HOME/rtorrent/rtorrent.rc`. See
+        <https://github.com/rakshasa/rtorrent/wiki/Config-Guide>
         for explanation about possible values.
       '';
     };
diff --git a/modules/programs/rtx.nix b/modules/programs/rtx.nix
index bb105333..5fa9b563 100644
--- a/modules/programs/rtx.nix
+++ b/modules/programs/rtx.nix
@@ -41,17 +41,15 @@ in {
           };
         '';
         description = ''
-          Settings written to <filename>$XDG_CONFIG_HOME/rtx/config.toml</filename>.
-          </para><para>
-          See <link xlink:href="https://github.com/jdxcode/rtx#global-config-configrtxconfigtoml"/>
+          Settings written to {file}`$XDG_CONFIG_HOME/rtx/config.toml`.
+
+          See <https://github.com/jdxcode/rtx#global-config-configrtxconfigtoml>
           for details on supported values.
 
-          <warning>
-            <para>
-              Modifying the <literal>tools</literal> section doesn't make RTX install them. 
-              You have to manually run <literal>rtx install</literal> to install the tools.
-            </para>
-          </warning>
+          ::: {.warning}
+          Modifying the `tools` section doesn't make RTX install them.
+          You have to manually run `rtx install` to install the tools.
+          :::
         '';
       };
     };
diff --git a/modules/programs/sagemath.nix b/modules/programs/sagemath.nix
index b07cec10..70efaca5 100644
--- a/modules/programs/sagemath.nix
+++ b/modules/programs/sagemath.nix
@@ -24,8 +24,8 @@ in {
       default = "${config.xdg.configHome}/sage";
       defaultText = literalExpression "\${config.xdg.configHome}/sage";
       description = ''
-        Directory where the <filename>sage.init</filename> file will be stored.
-        Note that the upstream default is <filename>~/.sage</filename>,
+        Directory where the {file}`sage.init` file will be stored.
+        Note that the upstream default is {file}`~/.sage`,
         but our default is to follow XDG.
       '';
     };
@@ -35,8 +35,8 @@ in {
       default = "${config.xdg.dataHome}/sage";
       defaultText = literalExpression "\${config.xdg.dataHome}/sage";
       description = ''
-        Location for <envar>DOT_SAGE</envar>.
-        Note that the upstream default is <filename>~/.sage</filename>,
+        Location for {env}`DOT_SAGE`.
+        Note that the upstream default is {file}`~/.sage`,
         but our default is to follow XDG.
       '';
     };
@@ -46,7 +46,7 @@ in {
       default = "";
       example = "%colors linux";
       description = ''
-        Contents of the <filename>init.sage</filename> file that is loaded on startup.
+        Contents of the {file}`init.sage` file that is loaded on startup.
       '';
     };
   };
diff --git a/modules/programs/sbt.nix b/modules/programs/sbt.nix
index 3e8dbc10..de14bc6f 100644
--- a/modules/programs/sbt.nix
+++ b/modules/programs/sbt.nix
@@ -104,7 +104,7 @@ in {
       default = ".sbt";
       description = ''
         Where the sbt configuration files should be located, relative
-        <envar>HOME</envar>.
+        {env}`HOME`.
       '';
     };
 
@@ -162,25 +162,19 @@ in {
       description = ''
         A list of repositories to use when resolving dependencies. Defined as a
         list of pre-defined repository or custom repository as a set of name to
-        URL. The list will be used populate the <code>~/.sbt/repositories</code>
+        URL. The list will be used populate the `~/.sbt/repositories`
         file in the order specified.
 
-        </para><para>
-
-        Pre-defined repositories must be one of <code>local</code>,
-        <code>maven-local</code>, <code>maven-central</code>.
-
-        </para><para>
+        Pre-defined repositories must be one of `local`,
+        `maven-local`, `maven-central`.
 
         Custom repositories are defined as
-        <code language="nix">{ name-of-repo = "https://url.to.repo.com"}</code>.
-
-        </para><para>
+        `{ name-of-repo = "https://url.to.repo.com"}`.
 
         See
-        <link xlink:href="https://www.scala-sbt.org/1.x/docs/Launcher-Configuration.html#3.+Repositories+Section"/>
+        <https://www.scala-sbt.org/1.x/docs/Launcher-Configuration.html#3.+Repositories+Section>
         about this configuration section and
-        <link xlink:href="https://www.scala-sbt.org/1.x/docs/Proxy-Repositories.html"/>
+        <https://www.scala-sbt.org/1.x/docs/Proxy-Repositories.html>
         to read about proxy repositories.
       '';
     };
diff --git a/modules/programs/scmpuff.nix b/modules/programs/scmpuff.nix
index 0a573af0..5f2fba53 100644
--- a/modules/programs/scmpuff.nix
+++ b/modules/programs/scmpuff.nix
@@ -13,7 +13,7 @@ in {
       type = types.package;
       default = pkgs.scmpuff;
       defaultText = literalExpression "pkgs.scmpuff";
-      description = "Package providing the <command>scmpuff</command> tool.";
+      description = "Package providing the {command}`scmpuff` tool.";
     };
 
     enableBashIntegration = mkOption {
diff --git a/modules/programs/script-directory.nix b/modules/programs/script-directory.nix
index 2f19a32f..9b0bcab2 100644
--- a/modules/programs/script-directory.nix
+++ b/modules/programs/script-directory.nix
@@ -6,7 +6,7 @@ in {
   options.programs.script-directory = {
     enable = lib.mkEnableOption "script-directory";
 
-    package = lib.mkPackageOptionMD pkgs "script-directory" { };
+    package = lib.mkPackageOption pkgs "script-directory" { };
 
     settings = lib.mkOption {
       default = { };
@@ -18,7 +18,7 @@ in {
           SD_CAT = "lolcat";
         }
       '';
-      description = lib.mdDoc
+      description =
         "script-directory config, for options take a look at the [documentation](github.com/ianthehenry/sd#options)";
     };
   };
diff --git a/modules/programs/senpai.nix b/modules/programs/senpai.nix
index 63208071..24256e76 100644
--- a/modules/programs/senpai.nix
+++ b/modules/programs/senpai.nix
@@ -12,7 +12,7 @@ in {
       type = types.package;
       default = pkgs.senpai;
       defaultText = literalExpression "pkgs.senpai";
-      description = "The <literal>senpai</literal> package to use.";
+      description = "The `senpai` package to use.";
     };
     config = mkOption {
       type = types.submodule {
@@ -57,8 +57,7 @@ in {
       '';
       description = ''
         Configuration for senpai. For a complete list of options, see
-        <citerefentry><refentrytitle>senpai</refentrytitle>
-        <manvolnum>5</manvolnum></citerefentry>.
+        {manpage}`senpai(5)`.
       '';
     };
   };
diff --git a/modules/programs/sioyek.nix b/modules/programs/sioyek.nix
index 63bf5b6f..04a30973 100644
--- a/modules/programs/sioyek.nix
+++ b/modules/programs/sioyek.nix
@@ -15,7 +15,7 @@ in {
   options = {
     programs.sioyek = {
       enable = mkEnableOption
-        "Sioyek is a PDF viewer designed for reading research papers and technical books.";
+        "Sioyek, a PDF viewer designed for reading research papers and technical books";
 
       package = mkOption {
         default = pkgs.sioyek;
@@ -27,9 +27,9 @@ in {
       bindings = mkOption {
         description = ''
           Input configuration written to
-          <filename>$XDG_CONFIG_HOME/sioyek/keys_user.config</filename>.
-          See <link xlink:href="https://github.com/ahrm/sioyek/blob/main/pdf_viewer/keys.config"/>.
-          </para><para>
+          {file}`$XDG_CONFIG_HOME/sioyek/keys_user.config`.
+          See <https://github.com/ahrm/sioyek/blob/main/pdf_viewer/keys.config>.
+
           Each attribute could also accept a list of strings to set multiple
           bindings of the same command.
         '';
@@ -50,8 +50,8 @@ in {
       config = mkOption {
         description = ''
           Input configuration written to
-          <filename>$XDG_CONFIG_HOME/sioyek/prefs_user.config</filename>.
-          See <link xlink:href="https://github.com/ahrm/sioyek/blob/main/pdf_viewer/prefs.config"/>.
+          {file}`$XDG_CONFIG_HOME/sioyek/prefs_user.config`.
+          See <https://github.com/ahrm/sioyek/blob/main/pdf_viewer/prefs.config>.
         '';
         type = types.attrsOf types.str;
         default = { };
diff --git a/modules/programs/skim.nix b/modules/programs/skim.nix
index 3d4da74d..2bb17d1b 100644
--- a/modules/programs/skim.nix
+++ b/modules/programs/skim.nix
@@ -14,7 +14,7 @@ in {
       type = types.package;
       default = pkgs.skim;
       defaultText = literalExpression "pkgs.skim";
-      description = "Package providing the <command>skim</command> tool.";
+      description = "Package providing the {command}`skim` tool.";
     };
 
     defaultCommand = mkOption {
diff --git a/modules/programs/sm64ex.nix b/modules/programs/sm64ex.nix
index 48c1cb9b..35d608ba 100644
--- a/modules/programs/sm64ex.nix
+++ b/modules/programs/sm64ex.nix
@@ -64,7 +64,7 @@ in {
       default = null;
       description = ''
         Extra flags to pass to the compiler. See
-        <link xlink:href="https://github.com/sm64pc/sm64ex/wiki/Build-options"/>
+        <https://github.com/sm64pc/sm64ex/wiki/Build-options>
         for more information.
       '';
       example = literalExpression ''
@@ -80,7 +80,7 @@ in {
         nullOr (attrsOf (either str (either int (either bool (listOf str)))));
       default = null;
       description =
-        "Settings for sm64ex's <filename>$XDG_DATA_HOME/sm64pc/sm64config.txt</filename> file.";
+        "Settings for sm64ex's {file}`$XDG_DATA_HOME/sm64pc/sm64config.txt` file.";
       example = literalExpression ''
         {
           fullscreen = false;
diff --git a/modules/programs/sqls.nix b/modules/programs/sqls.nix
index 2436c020..aaa161a7 100644
--- a/modules/programs/sqls.nix
+++ b/modules/programs/sqls.nix
@@ -30,8 +30,8 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/sqls/config.yml</filename>. See
-        <link xlink:href="https://github.com/lighttiger2505/sqls#db-configuration"/>
+        {file}`$XDG_CONFIG_HOME/sqls/config.yml`. See
+        <https://github.com/lighttiger2505/sqls#db-configuration>
         for supported values.
       '';
     };
diff --git a/modules/programs/ssh.nix b/modules/programs/ssh.nix
index 2e29a03d..e510fe8a 100644
--- a/modules/programs/ssh.nix
+++ b/modules/programs/ssh.nix
@@ -70,15 +70,12 @@ let
         default = null;
         example = "*.example.org";
         description = ''
-          <literal>Host</literal> pattern used by this conditional block.
+          `Host` pattern used by this conditional block.
           See
-          <citerefentry>
-          <refentrytitle>ssh_config</refentrytitle>
-          <manvolnum>5</manvolnum>
-          </citerefentry>
-          for <literal>Host</literal> block details.
+          {manpage}`ssh_config(5)`
+          for `Host` block details.
           This option is ignored if
-          <option>ssh.matchBlocks.*.match</option>
+          {option}`ssh.matchBlocks.*.match`
           if defined.
         '';
       };
@@ -88,14 +85,11 @@ let
         default = null;
         example = "host <hostname> canonical\nhost <hostname> exec \"ping -c1 -q 192.168.17.1\"";
         description = ''
-          <literal>Match</literal> block conditions used by this block. See
-          <citerefentry>
-          <refentrytitle>ssh_config</refentrytitle>
-          <manvolnum>5</manvolnum>
-          </citerefentry>
-          for <literal>Match</literal> block details.
+          `Match` block conditions used by this block. See
+          {manpage}`ssh_config(5)`
+          for `Match` block details.
           This option takes precedence over
-          <option>ssh.matchBlocks.*.host</option>
+          {option}`ssh.matchBlocks.*.host`
           if defined.
         '';
       };
@@ -120,7 +114,7 @@ let
         default = false;
         description = ''
           Specifies whether X11 connections will be automatically redirected
-          over the secure channel and <envar>DISPLAY</envar> set.
+          over the secure channel and {env}`DISPLAY` set.
         '';
       };
 
@@ -139,8 +133,8 @@ let
         description = ''
           Specifies that ssh should only use the authentication
           identity explicitly configured in the
-          <filename>~/.ssh/config</filename> files or passed on the
-          ssh command-line, even if <command>ssh-agent</command>
+          {file}`~/.ssh/config` files or passed on the
+          ssh command-line, even if {command}`ssh-agent`
           offers more identities.
         '';
       };
@@ -208,7 +202,7 @@ let
         default = null;
         description = ''
           Specifies whether to use compression. Omitted from the host
-          block when <literal>null</literal>.
+          block when `null`.
         '';
       };
 
@@ -217,7 +211,7 @@ let
         default = true;
         description = ''
           Check the host IP address in the
-          <filename>known_hosts</filename> file.
+          {file}`known_hosts` file.
         '';
       };
 
@@ -267,10 +261,7 @@ let
         '';
         description = ''
           Specify local port forwardings. See
-          <citerefentry>
-            <refentrytitle>ssh_config</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry> for <literal>LocalForward</literal>.
+          {manpage}`ssh_config(5)` for `LocalForward`.
         '';
       };
 
@@ -288,10 +279,7 @@ let
         '';
         description = ''
           Specify remote port forwardings. See
-          <citerefentry>
-            <refentrytitle>ssh_config</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry> for <literal>RemoteForward</literal>.
+          {manpage}`ssh_config(5)` for `RemoteForward`.
         '';
       };
 
@@ -303,10 +291,7 @@ let
         '';
         description = ''
           Specify dynamic port forwardings. See
-          <citerefentry>
-            <refentrytitle>ssh_config</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry> for <literal>DynamicForward</literal>.
+          {manpage}`ssh_config(5)` for `DynamicForward`.
         '';
       };
 
@@ -404,10 +389,7 @@ in
       type = types.bool;
       description = ''
         Indicates that
-        <citerefentry>
-          <refentrytitle>ssh</refentrytitle>
-          <manvolnum>1</manvolnum>
-        </citerefentry>
+        {manpage}`ssh(1)`
         should hash host names and addresses when they are added to
         the known hosts file.
       '';
@@ -419,7 +401,7 @@ in
       description = ''
         Specifies one or more files to use for the user host key
         database, separated by whitespace. The default is
-        <filename>~/.ssh/known_hosts</filename>.
+        {file}`~/.ssh/known_hosts`.
       '';
     };
 
@@ -470,13 +452,10 @@ in
       default = [];
       description = ''
         File globs of ssh config files that should be included via the
-        <literal>Include</literal> directive.
-        </para><para>
+        `Include` directive.
+
         See
-        <citerefentry>
-          <refentrytitle>ssh_config</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>
+        {manpage}`ssh_config(5)`
         for more information.
       '';
     };
@@ -500,12 +479,9 @@ in
         Specify per-host settings. Note, if the order of rules matter
         then use the DAG functions to express the dependencies as
         shown in the example.
-        </para><para>
+
         See
-        <citerefentry>
-          <refentrytitle>ssh_config</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>
+        {manpage}`ssh_config(5)`
         for more information.
       '';
     };
diff --git a/modules/programs/starship.nix b/modules/programs/starship.nix
index 5c90af39..8a97b53a 100644
--- a/modules/programs/starship.nix
+++ b/modules/programs/starship.nix
@@ -51,9 +51,9 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/starship.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://starship.rs/config/" /> for the full list
+        {file}`$XDG_CONFIG_HOME/starship.toml`.
+
+        See <https://starship.rs/config/> for the full list
         of options.
       '';
     };
diff --git a/modules/programs/swaylock.nix b/modules/programs/swaylock.nix
index 9299e645..774ecf70 100644
--- a/modules/programs/swaylock.nix
+++ b/modules/programs/swaylock.nix
@@ -25,7 +25,7 @@ in {
       type = with types; attrsOf (oneOf [ bool float int str ]);
       default = { };
       description = ''
-        Default arguments to <command>swaylock</command>. An empty set
+        Default arguments to {command}`swaylock`. An empty set
         disables configuration generation.
       '';
       example = {
diff --git a/modules/programs/taskwarrior.nix b/modules/programs/taskwarrior.nix
index 985b6285..5c4f0bf8 100644
--- a/modules/programs/taskwarrior.nix
+++ b/modules/programs/taskwarrior.nix
@@ -51,7 +51,7 @@ in {
         '';
         description = ''
           Key-value configuration written to
-          <filename>$XDG_CONFIG_HOME/task/taskrc</filename>.
+          {file}`$XDG_CONFIG_HOME/task/taskrc`.
         '';
       };
 
@@ -61,7 +61,7 @@ in {
         defaultText = "$XDG_DATA_HOME/task";
         description = ''
           Location where Task Warrior will store its data.
-          </para><para>
+
           Home Manager will attempt to create this directory.
         '';
       };
@@ -81,7 +81,7 @@ in {
         default = "";
         description = ''
           Additional content written at the end of
-          <filename>$XDG_CONFIG_HOME/task/taskrc</filename>.
+          {file}`$XDG_CONFIG_HOME/task/taskrc`.
         '';
       };
 
diff --git a/modules/programs/tealdeer.nix b/modules/programs/tealdeer.nix
index ecb8919c..f0e610c2 100644
--- a/modules/programs/tealdeer.nix
+++ b/modules/programs/tealdeer.nix
@@ -34,10 +34,10 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/tealdeer/config.toml</filename> on Linux or
-        <filename>$HOME/Library/Application Support/tealdeer/config.toml</filename>
+        {file}`$XDG_CONFIG_HOME/tealdeer/config.toml` on Linux or
+        {file}`$HOME/Library/Application Support/tealdeer/config.toml`
         on Darwin. See
-        <link xlink:href="https://dbrgn.github.io/tealdeer/config.html"/>
+        <https://dbrgn.github.io/tealdeer/config.html>
         for more information.
       '';
     };
diff --git a/modules/programs/terminator.nix b/modules/programs/terminator.nix
index 4a5e367b..283f4ad9 100644
--- a/modules/programs/terminator.nix
+++ b/modules/programs/terminator.nix
@@ -44,12 +44,9 @@ in {
       default = { };
       description = ''
         configuration for terminator.
-        </para><para>
+
         For a list of all possible options refer to the
-        <citerefentry>
-          <refentrytitle>terminator_config</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>
+        {manpage}`terminator_config(5)`
         man page.
       '';
       type = types.attrsOf types.anything;
diff --git a/modules/programs/termite.nix b/modules/programs/termite.nix
index ccf3cabb..c0015dcb 100644
--- a/modules/programs/termite.nix
+++ b/modules/programs/termite.nix
@@ -160,10 +160,7 @@ in {
         description = ''
           Emit escape sequences for extra keys,
           like the modifyOtherKeys resource for
-          <citerefentry>
-            <refentrytitle>xterm</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>.
+          {manpage}`xterm(1)`.
         '';
       };
 
diff --git a/modules/programs/thunderbird.nix b/modules/programs/thunderbird.nix
index c072c984..8b14628a 100644
--- a/modules/programs/thunderbird.nix
+++ b/modules/programs/thunderbird.nix
@@ -165,7 +165,7 @@ in {
                 '';
                 description = ''
                   Preferences to add to this profile's
-                  <filename>user.js</filename>.
+                  {file}`user.js`.
                 '';
               };
 
@@ -202,11 +202,12 @@ in {
                 type = types.lines;
                 default = "";
                 description = ''
-                  Extra preferences to add to <filename>user.js</filename>.
+                  Extra preferences to add to {file}`user.js`.
                 '';
               };
             };
           }));
+        description = "Attribute set of Thunderbird profiles.";
       };
 
       settings = mkOption {
@@ -268,7 +269,7 @@ in {
               '';
               description = ''
                 Extra settings to add to this Thunderbird account configuration.
-                The <varname>id</varname> given as argument is an automatically
+                The {var}`id` given as argument is an automatically
                 generated account identifier.
               '';
             };
@@ -285,7 +286,7 @@ in {
               '';
               description = ''
                 Extra settings to add to each identity of this Thunderbird
-                account configuration. The <varname>id</varname> given as
+                account configuration. The {var}`id` given as
                 argument is an automatically generated identifier.
               '';
             };
diff --git a/modules/programs/tint2.nix b/modules/programs/tint2.nix
index 4579f619..70930197 100644
--- a/modules/programs/tint2.nix
+++ b/modules/programs/tint2.nix
@@ -24,7 +24,7 @@ in {
       type = types.lines;
       default = "";
       description = ''
-        Commands for tint2 that will be add to the <filename>tint2rc</filename>
+        Commands for tint2 that will be add to the {file}`tint2rc`
         file.
       '';
     };
diff --git a/modules/programs/tiny.nix b/modules/programs/tiny.nix
index eba0c9c4..7c510535 100644
--- a/modules/programs/tiny.nix
+++ b/modules/programs/tiny.nix
@@ -19,7 +19,7 @@ in {
         type = types.package;
         default = pkgs.tiny;
         defaultText = literalExpression "pkgs.tiny";
-        description = "The <command>tiny</command> package to install.";
+        description = "The {command}`tiny` package to install.";
       };
 
       settings = mkOption {
@@ -47,8 +47,8 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/tiny/config.yml</filename>. See
-          <link xlink:href="https://github.com/osa1/tiny/blob/master/crates/tiny/config.yml"/>
+          {file}`$XDG_CONFIG_HOME/tiny/config.yml`. See
+          <https://github.com/osa1/tiny/blob/master/crates/tiny/config.yml>
           for the default configuration.
         '';
       };
diff --git a/modules/programs/tmate.nix b/modules/programs/tmate.nix
index 6681baf6..e895647f 100644
--- a/modules/programs/tmate.nix
+++ b/modules/programs/tmate.nix
@@ -56,7 +56,7 @@ in {
         default = "";
         description = ''
           Additional content written at the end of
-          <filename>~/.tmate.conf</filename>.
+          {file}`~/.tmate.conf`.
         '';
       };
     };
diff --git a/modules/programs/tmux.nix b/modules/programs/tmux.nix
index df3ed11d..b68fd8d5 100644
--- a/modules/programs/tmux.nix
+++ b/modules/programs/tmux.nix
@@ -187,7 +187,7 @@ in {
         default = "";
         description = ''
           Additional configuration to add to
-          <filename>tmux.conf</filename>.
+          {file}`tmux.conf`.
         '';
       };
 
@@ -243,7 +243,7 @@ in {
         description = ''
           Run the sensible plugin at the top of the configuration. It
           is possible to override the sensible settings using the
-          <option>programs.tmux.extraConfig</option> option.
+          {option}`programs.tmux.extraConfig` option.
         '';
       };
 
@@ -283,8 +283,8 @@ in {
         default = pkgs.stdenv.isLinux;
         type = types.bool;
         description = ''
-          Store tmux socket under <filename>/run</filename>, which is more
-          secure than <filename>/tmp</filename>, but as a downside it doesn't
+          Store tmux socket under {file}`/run`, which is more
+          secure than {file}`/tmp`, but as a downside it doesn't
           survive user logout.
         '';
       };
diff --git a/modules/programs/topgrade.nix b/modules/programs/topgrade.nix
index ac88643d..a49f897b 100644
--- a/modules/programs/topgrade.nix
+++ b/modules/programs/topgrade.nix
@@ -42,9 +42,9 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/topgrade.toml</filename>.
-        </para><para>
-        See <link xlink:href="https://github.com/r-darwish/topgrade/wiki/Step-list" /> for the full list
+        {file}`$XDG_CONFIG_HOME/topgrade.toml`.
+
+        See <https://github.com/r-darwish/topgrade/wiki/Step-list> for the full list
         of options.
       '';
     };
diff --git a/modules/programs/translate-shell.nix b/modules/programs/translate-shell.nix
index 360d28f0..1eb3e125 100644
--- a/modules/programs/translate-shell.nix
+++ b/modules/programs/translate-shell.nix
@@ -36,8 +36,8 @@ in {
         tl = [ "es" "fr" ];
       };
       description = ''
-        Options to add to <filename>$XDG_CONFIG_HOME/translate-shell/init.trans</filename> file.
-        See <link xlink:href="https://github.com/soimort/translate-shell/wiki/Configuration"/>
+        Options to add to {file}`$XDG_CONFIG_HOME/translate-shell/init.trans` file.
+        See <https://github.com/soimort/translate-shell/wiki/Configuration>
         for options.
       '';
     };
diff --git a/modules/programs/urxvt.nix b/modules/programs/urxvt.nix
index 545a1e7f..059666c3 100644
--- a/modules/programs/urxvt.nix
+++ b/modules/programs/urxvt.nix
@@ -119,7 +119,7 @@ in {
       type = types.ints.between 0 200;
       default = 100;
       description =
-        "Darken (0 .. 99) or lighten (101 .. 200) the transparent background.";
+        "Darken (0 to 99) or lighten (101 to 200) the transparent background.";
     };
 
     extraConfig = mkOption {
diff --git a/modules/programs/vdirsyncer-accounts.nix b/modules/programs/vdirsyncer-accounts.nix
index 564a0948..35badb92 100644
--- a/modules/programs/vdirsyncer-accounts.nix
+++ b/modules/programs/vdirsyncer-accounts.nix
@@ -25,8 +25,8 @@ in {
       default = null;
       description = ''
         What to do in case of a conflict between the storages. Either
-        <literal>remote wins</literal> or
-        <literal>local wins</literal> or
+        `remote wins` or
+        `local wins` or
         a list that contains a command to run. By default, an error
         message is printed.
       '';
@@ -38,10 +38,10 @@ in {
       description = ''
         What should happen if synchronization in one direction
         is impossible due to one storage being read-only.
-        Defaults to <literal>revert</literal>.
-        </para><para>
+        Defaults to `revert`.
+
         See
-        <link xlink:href="https://vdirsyncer.pimutils.org/en/stable/config.html#pair-section"/>
+        <https://vdirsyncer.pimutils.org/en/stable/config.html#pair-section>
         for more information.
       '';
     };
@@ -73,7 +73,7 @@ in {
       default = null;
       description = ''
         A time range to synchronize. start and end can be any Python
-        expression that returns a <literal>datetime.datetime</literal>
+        expression that returns a `datetime.datetime`
         object.
       '';
       example = {
@@ -103,9 +103,9 @@ in {
       default = null;
       description = ''
         Optional. SHA1 or MD5 fingerprint of the expected server certificate.
-        </para><para>
+
         See
-        <link xlink:href="https://vdirsyncer.pimutils.org/en/stable/ssl-tutorial.html#ssl-tutorial"/>
+        <https://vdirsyncer.pimutils.org/en/stable/ssl-tutorial.html#ssl-tutorial>
         for more information.
       '';
     };
@@ -114,7 +114,7 @@ in {
       type = types.nullOr (types.enum [ "basic" "digest" "guess" ]);
       default = null;
       description = ''
-        Authentication settings. The default is <literal>basic</literal>.
+        Authentication settings. The default is `basic`.
       '';
     };
 
@@ -132,7 +132,7 @@ in {
       default = null;
       description = ''
         The user agent to report to the server. Defaults to
-        <literal>vdirsyncer</literal>.
+        `vdirsyncer`.
       '';
     };
 
@@ -163,9 +163,9 @@ in {
       description = ''
         A command that prints the OAuth credentials to standard
         output.
-        </para><para>
+
         See
-        <link xlink:href="https://vdirsyncer.pimutils.org/en/stable/config.html#google"/>
+        <https://vdirsyncer.pimutils.org/en/stable/config.html#google>
         for more information.
       '';
     };
@@ -177,9 +177,9 @@ in {
       description = ''
         A command that prints the OAuth credentials to standard
         output.
-        </para><para>
+
         See
-        <link xlink:href="https://vdirsyncer.pimutils.org/en/stable/config.html#google"/>
+        <https://vdirsyncer.pimutils.org/en/stable/config.html#google>
         for more information.
       '';
     };
diff --git a/modules/programs/vdirsyncer.nix b/modules/programs/vdirsyncer.nix
index 258692df..ec1b3879 100644
--- a/modules/programs/vdirsyncer.nix
+++ b/modules/programs/vdirsyncer.nix
@@ -184,10 +184,9 @@ in {
         defaultText = "$XDG_DATA_HOME/vdirsyncer/status";
         description = ''
           A directory where vdirsyncer will store some additional data for the next sync.
-          </para>
 
-          <para>For more information, see
-          <link xlink:href="https://vdirsyncer.pimutils.org/en/stable/config.html#general-section"/>
+          For more information, see the
+          [vdirsyncer manual](https://vdirsyncer.pimutils.org/en/stable/config.html#general-section).
         '';
       };
     };
diff --git a/modules/programs/vim-vint.nix b/modules/programs/vim-vint.nix
index e44d96e4..9565a8cb 100644
--- a/modules/programs/vim-vint.nix
+++ b/modules/programs/vim-vint.nix
@@ -21,7 +21,7 @@ in {
         default = { };
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/.vintrc.yaml</filename>
+          {file}`$XDG_CONFIG_HOME/.vintrc.yaml`
         '';
       };
     };
diff --git a/modules/programs/vim.nix b/modules/programs/vim.nix
index e4d993a6..2f13caee 100644
--- a/modules/programs/vim.nix
+++ b/modules/programs/vim.nix
@@ -71,9 +71,7 @@ in {
         example = literalExpression "[ pkgs.vimPlugins.YankRing ]";
         description = ''
           List of vim plugins to install. To get a list of supported plugins run:
-          <command>nix-env -f '&lt;nixpkgs&gt;' -qaP -A vimPlugins</command>.
-
-          </para><para>
+          {command}`nix-env -f '<nixpkgs>' -qaP -A vimPlugins`.
 
           Note: String values are deprecated, please use actual packages.
         '';
@@ -94,18 +92,14 @@ in {
           corresponding values must be among the following supported
           options.
 
-          <informaltable frame="none"><tgroup cols="1"><tbody>
           ${concatStringsSep "\n" (mapAttrsToList (n: v: ''
-            <row>
-              <entry><varname>${n}</varname></entry>
-              <entry>${v.description}</entry>
-            </row>
+            {var}`${n}`
+            : ${v.description}
           '') knownSettings)}
-          </tbody></tgroup></informaltable>
 
           See the Vim documentation for detailed descriptions of these
-          options. Note, use <varname>extraConfig</varname> to
-          manually set any options not listed above.
+          options. Use [](#opt-programs.vim.extraConfig) to manually
+          set any options not listed above.
         '';
       };
 
@@ -137,8 +131,8 @@ in {
         type = types.bool;
         default = false;
         description = ''
-          Whether to configure <command>vim</command> as the default
-          editor using the <envar>EDITOR</envar> environment variable.
+          Whether to configure {command}`vim` as the default
+          editor using the {env}`EDITOR` environment variable.
         '';
       };
     };
diff --git a/modules/programs/vscode.nix b/modules/programs/vscode.nix
index 779565d2..5ea6be8b 100644
--- a/modules/programs/vscode.nix
+++ b/modules/programs/vscode.nix
@@ -99,7 +99,7 @@ in {
         '';
         description = ''
           Configuration written to Visual Studio Code's
-          <filename>settings.json</filename>.
+          {file}`settings.json`.
         '';
       };
 
@@ -120,7 +120,7 @@ in {
         '';
         description = ''
           Configuration written to Visual Studio Code's
-          <filename>tasks.json</filename>.
+          {file}`tasks.json`.
         '';
       };
 
@@ -167,7 +167,7 @@ in {
         '';
         description = ''
           Keybindings written to Visual Studio Code's
-          <filename>keybindings.json</filename>.
+          {file}`keybindings.json`.
         '';
       };
 
diff --git a/modules/programs/vscode/haskell.nix b/modules/programs/vscode/haskell.nix
index 7fe3235d..63ecd18e 100644
--- a/modules/programs/vscode/haskell.nix
+++ b/modules/programs/vscode/haskell.nix
@@ -37,10 +37,13 @@ in {
       defaultText = defaultHieNixExeText;
       description = ''
         The path to the Haskell IDE Engine executable.
-        </para><para>
+
         Because hie-nix is not packaged in Nixpkgs, you need to add it as an
         overlay or set this option. Example overlay configuration:
-        <programlisting language="nix">${exampleOverlay}</programlisting>
+
+        ```nix
+        ${exampleOverlay}
+        ```
       '';
       example = literalExpression ''
         (import ~/src/haskell-ide-engine {}).hies + "/bin/hie-wrapper";
diff --git a/modules/programs/watson.nix b/modules/programs/watson.nix
index 54cfbc13..b30dec09 100644
--- a/modules/programs/watson.nix
+++ b/modules/programs/watson.nix
@@ -23,7 +23,7 @@ in {
       type = types.package;
       default = pkgs.watson;
       defaultText = literalExpression "pkgs.watson";
-      description = "Package providing the <command>watson</command>.";
+      description = "Package providing the {command}`watson`.";
     };
 
     enableBashIntegration = mkEnableOption "watson's bash integration" // {
@@ -43,10 +43,10 @@ in {
       default = { };
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/watson/config</filename> on Linux or
-        <filename>$HOME/Library/Application Support/watson/config</filename> on Darwin.
-        </para><para>
-        See <link xlink:href="https://github.com/TailorDev/Watson/blob/master/docs/user-guide/configuration.md"/>
+        {file}`$XDG_CONFIG_HOME/watson/config` on Linux or
+        {file}`$HOME/Library/Application Support/watson/config` on Darwin.
+
+        See <https://github.com/TailorDev/Watson/blob/master/docs/user-guide/configuration.md>
         for an example configuration.
       '';
       example = literalExpression ''
diff --git a/modules/programs/waybar.nix b/modules/programs/waybar.nix
index d82b673d..efc34a30 100644
--- a/modules/programs/waybar.nix
+++ b/modules/programs/waybar.nix
@@ -27,8 +27,8 @@ let
           type = nullOr (enum [ "top" "bottom" ]);
           default = null;
           description = ''
-            Decide if the bar is displayed in front (<code>"top"</code>)
-            of the windows or behind (<code>"bottom"</code>).
+            Decide if the bar is displayed in front (`"top"`)
+            of the windows or behind (`"bottom"`).
           '';
           example = "top";
         };
@@ -152,7 +152,7 @@ in {
       default = pkgs.waybar;
       defaultText = literalExpression "pkgs.waybar";
       description = ''
-        Waybar package to use. Set to <code>null</code> to use the default package.
+        Waybar package to use. Set to `null` to use the default package.
       '';
     };
 
@@ -160,8 +160,7 @@ in {
       type = either (listOf waybarBarConfig) (attrsOf waybarBarConfig);
       default = [ ];
       description = ''
-        Configuration for Waybar, see <link
-          xlink:href="https://github.com/Alexays/Waybar/wiki/Configuration"/>
+        Configuration for Waybar, see <https://github.com/Alexays/Waybar/wiki/Configuration>
         for supported values.
       '';
       example = literalExpression ''
@@ -203,10 +202,9 @@ in {
       example = "sway-session.target";
       description = ''
         The systemd target that will automatically start the Waybar service.
-        </para>
-        <para>
-        When setting this value to <literal>"sway-session.target"</literal>,
-        make sure to also enable <option>wayland.windowManager.sway.systemd.enable</option>,
+
+        When setting this value to `"sway-session.target"`,
+        make sure to also enable {option}`wayland.windowManager.sway.systemd.enable`,
         otherwise the service may never be started.
       '';
     };
@@ -216,12 +214,10 @@ in {
       default = null;
       description = ''
         CSS style of the bar.
-        </para>
-        <para>
-        See <link xlink:href="https://github.com/Alexays/Waybar/wiki/Configuration"/>
+
+        See <https://github.com/Alexays/Waybar/wiki/Configuration>
         for the documentation.
-        </para>
-        <para>
+
         If the value is set to a path literal, then the path will be used as the css file.
       '';
       example = ''
diff --git a/modules/programs/wezterm.nix b/modules/programs/wezterm.nix
index 08f7dbfc..b66028d6 100644
--- a/modules/programs/wezterm.nix
+++ b/modules/programs/wezterm.nix
@@ -46,8 +46,8 @@ in {
       '';
       description = ''
         Extra configuration written to
-        <filename>$XDG_CONFIG_HOME/wezterm/wezterm.lua</filename>. See
-        <link xlink:href="https://wezfurlong.org/wezterm/config/files.html"/>
+        {file}`$XDG_CONFIG_HOME/wezterm/wezterm.lua`. See
+        <https://wezfurlong.org/wezterm/config/files.html>
         how to configure.
       '';
     };
@@ -76,18 +76,18 @@ in {
       '';
       description = ''
         Attribute set of additional color schemes to be written to
-        <filename>$XDG_CONFIG_HOME/wezterm/colors</filename>, where each key is
+        {file}`$XDG_CONFIG_HOME/wezterm/colors`, where each key is
         taken as the name of the corresponding color scheme. See
-        <link xlink:href="https://wezfurlong.org/wezterm/config/appearance.html#defining-a-color-scheme-in-a-separate-file"/>
+        <https://wezfurlong.org/wezterm/config/appearance.html#defining-a-color-scheme-in-a-separate-file>
         for more details of the TOML color scheme format.
       '';
     };
 
-    enableBashIntegration = mkEnableOption "WezTerm's Bash integration." // {
+    enableBashIntegration = mkEnableOption "WezTerm's Bash integration" // {
       default = true;
     };
 
-    enableZshIntegration = mkEnableOption "WezTerm's Zsh integration." // {
+    enableZshIntegration = mkEnableOption "WezTerm's Zsh integration" // {
       default = true;
     };
   };
diff --git a/modules/programs/wlogout.nix b/modules/programs/wlogout.nix
index 49e59b07..b01f8a0a 100644
--- a/modules/programs/wlogout.nix
+++ b/modules/programs/wlogout.nix
@@ -78,8 +78,7 @@ in {
       type = listOf wlogoutLayoutConfig;
       default = [ ];
       description = ''
-        Layout configuration for wlogout, see <link
-          xlink:href="https://github.com/ArtsyMacaw/wlogout#config"/>
+        Layout configuration for wlogout, see <https://github.com/ArtsyMacaw/wlogout#config>
         for supported values.
       '';
       example = literalExpression ''
@@ -99,12 +98,10 @@ in {
       default = null;
       description = ''
         CSS style of the bar.
-        </para>
-        <para>
-        See <link xlink:href="https://github.com/ArtsyMacaw/wlogout#style"/>
+
+        See <https://github.com/ArtsyMacaw/wlogout#style>
         for the documentation.
-        </para>
-        <para>
+
         If the value is set to a path literal, then the path will be used as the css file.
       '';
       example = ''
diff --git a/modules/programs/wofi.nix b/modules/programs/wofi.nix
index e1e84ba2..1317716e 100644
--- a/modules/programs/wofi.nix
+++ b/modules/programs/wofi.nix
@@ -24,10 +24,7 @@ in {
       type = types.attrs;
       description = ''
         Configuration options for wofi. See
-        <citerefentry>
-          <refentrytitle>wofi</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>.
+        {manpage}`wofi(5)`.
       '';
       example = literalExpression ''
         {
@@ -43,10 +40,7 @@ in {
       type = types.nullOr types.str;
       description = ''
         CSS style for wofi to use as a stylesheet. See
-        <citerefentry>
-          <refentrytitle>wofi</refentrytitle>
-          <manvolnum>7</manvolnum>
-        </citerefentry>.
+        {manpage}`wofi(7)`.
       '';
       example = ''
         * {
diff --git a/modules/programs/xmobar.nix b/modules/programs/xmobar.nix
index a29bea84..267b3080 100644
--- a/modules/programs/xmobar.nix
+++ b/modules/programs/xmobar.nix
@@ -12,7 +12,7 @@ in {
       defaultText = literalExpression "pkgs.haskellPackages.xmobar";
       type = types.package;
       description = ''
-        Package providing the <command>xmobar</command> binary.
+        Package providing the {command}`xmobar` binary.
       '';
     };
 
@@ -42,9 +42,9 @@ in {
       type = types.lines;
       description = ''
         Extra configuration lines to add to
-        <filename>$XDG_CONFIG_HOME/xmobar/.xmobarrc</filename>.
+        {file}`$XDG_CONFIG_HOME/xmobar/.xmobarrc`.
         See
-        <link xlink:href="https://xmobar.org/#configuration" />
+        <https://xmobar.org/#configuration>
         for options.
       '';
     };
diff --git a/modules/programs/yt-dlp.nix b/modules/programs/yt-dlp.nix
index 11398bd9..3b8e9c70 100644
--- a/modules/programs/yt-dlp.nix
+++ b/modules/programs/yt-dlp.nix
@@ -22,7 +22,7 @@ in {
       type = types.package;
       default = pkgs.yt-dlp;
       defaultText = literalExpression "pkgs.yt-dlp";
-      description = "Package providing the <command>yt-dlp</command> tool.";
+      description = "Package providing the {command}`yt-dlp` tool.";
     };
 
     settings = mkOption {
@@ -39,12 +39,12 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/yt-dlp/config</filename>.
-        </para><para>
-        Options must be specified in their <quote>long form</quote>, for
-        example, <code>update = true;</code> instead of <code>U = true;</code>.
-        Short options can be specified in the <code>extraConfig</code> option.
-        See <link xlink:href="https://github.com/yt-dlp/yt-dlp#configuration"/>
+        {file}`$XDG_CONFIG_HOME/yt-dlp/config`.
+
+        Options must be specified in their "long form", for
+        example, `update = true;` instead of `U = true;`.
+        Short options can be specified in the `extraConfig` option.
+        See <https://github.com/yt-dlp/yt-dlp#configuration>
         for explanation about possible values.
       '';
     };
@@ -58,7 +58,7 @@ in {
       '';
       description = ''
         Extra configuration to add to
-        <filename>$XDG_CONFIG_HOME/yt-dlp/config</filename>.
+        {file}`$XDG_CONFIG_HOME/yt-dlp/config`.
       '';
     };
   };
diff --git a/modules/programs/zathura.nix b/modules/programs/zathura.nix
index b043fa23..ba34af59 100644
--- a/modules/programs/zathura.nix
+++ b/modules/programs/zathura.nix
@@ -33,12 +33,9 @@ in {
       default = { };
       type = with types; attrsOf (either str (either bool int));
       description = ''
-        Add <option>:set</option> command options to zathura and make
+        Add {option}`:set` command options to zathura and make
         them permanent. See
-        <citerefentry>
-          <refentrytitle>zathurarc</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>
+        {manpage}`zathurarc(5)`
         for the full list of options.
       '';
       example = {
@@ -51,16 +48,13 @@ in {
       default = { };
       type = with types; attrsOf str;
       description = ''
-        Add <option>:map</option> mappings to zathura and make
+        Add {option}`:map` mappings to zathura and make
         them permanent. See
-        <citerefentry>
-          <refentrytitle>zathurarc</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry>
+        {manpage}`zathurarc(5)`
         for the full list of possible mappings.
 
         You can create a mode-specific mapping by specifying the mode before the key:
-        <literal>"[normal] &lt;C-b&gt;" = "scroll left";</literal>
+        `"[normal] <C-b>" = "scroll left";`
       '';
       example = {
         D = "toggle_page_mode";
@@ -74,7 +68,7 @@ in {
       default = "";
       description = ''
         Additional commands for zathura that will be added to the
-        <filename>zathurarc</filename> file.
+        {file}`zathurarc` file.
       '';
     };
   };
diff --git a/modules/programs/zellij.nix b/modules/programs/zellij.nix
index e1973025..44a3d69f 100644
--- a/modules/programs/zellij.nix
+++ b/modules/programs/zellij.nix
@@ -33,9 +33,9 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/zellij/config.yaml</filename>.
-        </para><para>
-        See <link xlink:href="https://zellij.dev/documentation" /> for the full
+        {file}`$XDG_CONFIG_HOME/zellij/config.yaml`.
+
+        See <https://zellij.dev/documentation> for the full
         list of options.
       '';
     };
diff --git a/modules/programs/zsh.nix b/modules/programs/zsh.nix
index d69ea7c3..94f2a392 100644
--- a/modules/programs/zsh.nix
+++ b/modules/programs/zsh.nix
@@ -115,7 +115,7 @@ let
         description = ''
           Path to the plugin folder.
 
-          Will be added to <envar>fpath</envar> and <envar>PATH</envar>.
+          Will be added to {env}`fpath` and {env}`PATH`.
         '';
       };
 
@@ -124,7 +124,7 @@ let
         description = ''
           The name of the plugin.
 
-          Don't forget to add <option>file</option>
+          Don't forget to add {option}`file`
           if the script name does not follow convention.
         '';
       };
@@ -159,7 +159,7 @@ let
         example = "$HOME/my_customizations";
         description = ''
           Path to a custom oh-my-zsh package to override config of
-          oh-my-zsh. See <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization"/>
+          oh-my-zsh. See <https://github.com/robbyrussell/oh-my-zsh/wiki/Customization>
           for more information.
         '';
       };
@@ -194,7 +194,7 @@ let
         default = [ "^[[A" ];
         description = ''
           The key codes to be used when searching up.
-          The default of <literal>^[[A</literal> corresponds to the UP key.
+          The default of `^[[A` corresponds to the UP key.
         '';
       };
       searchDownKey = mkOption {
@@ -202,7 +202,7 @@ let
         default = [ "^[[B" ];
         description = ''
           The key codes to be used when searching down.
-          The default of <literal>^[[B</literal> corresponds to the DOWN key.
+          The default of `^[[B` corresponds to the DOWN key.
         '';
       };
     };
@@ -219,7 +219,7 @@ let
         default = {};
         description = ''
           Custom styles for syntax highlighting.
-          See each highlighter's options: <link xlink:href="https://github.com/zsh-users/zsh-syntax-highlighting/blob/master/docs/highlighters.md"/>
+          See each highlighter's options: <https://github.com/zsh-users/zsh-syntax-highlighting/blob/master/docs/highlighters.md>
         '';
       };
     };
@@ -249,7 +249,7 @@ in
       cdpath = mkOption {
         default = [];
         description = ''
-          List of paths to autocomplete calls to `cd`.
+          List of paths to autocomplete calls to {command}`cd`.
         '';
         type = types.listOf types.str;
       };
@@ -289,7 +289,7 @@ in
           }
         '';
         description = ''
-          Similar to <xref linkend="opt-programs.zsh.shellAliases"/>,
+          Similar to [](#opt-programs.zsh.shellAliases),
           but are substituted anywhere on a line.
         '';
         type = types.attrsOf types.str;
@@ -314,9 +314,9 @@ in
         default = true;
         description = ''
           Enable zsh completion. Don't forget to add
-          <programlisting language="nix">
+          ```nix
             environment.pathsToLink = [ "/share/zsh" ];
-          </programlisting>
+          ```
           to your system configuration to get completion for system packages (e.g. systemd).
         '';
         type = types.bool;
@@ -368,43 +368,43 @@ in
       initExtraBeforeCompInit = mkOption {
         default = "";
         type = types.lines;
-        description = "Extra commands that should be added to <filename>.zshrc</filename> before compinit.";
+        description = "Extra commands that should be added to {file}`.zshrc` before compinit.";
       };
 
       initExtra = mkOption {
         default = "";
         type = types.lines;
-        description = "Extra commands that should be added to <filename>.zshrc</filename>.";
+        description = "Extra commands that should be added to {file}`.zshrc`.";
       };
 
       initExtraFirst = mkOption {
         default = "";
         type = types.lines;
-        description = "Commands that should be added to top of <filename>.zshrc</filename>.";
+        description = "Commands that should be added to top of {file}`.zshrc`.";
       };
 
       envExtra = mkOption {
         default = "";
         type = types.lines;
-        description = "Extra commands that should be added to <filename>.zshenv</filename>.";
+        description = "Extra commands that should be added to {file}`.zshenv`.";
       };
 
       profileExtra = mkOption {
         default = "";
         type = types.lines;
-        description = "Extra commands that should be added to <filename>.zprofile</filename>.";
+        description = "Extra commands that should be added to {file}`.zprofile`.";
       };
 
       loginExtra = mkOption {
         default = "";
         type = types.lines;
-        description = "Extra commands that should be added to <filename>.zlogin</filename>.";
+        description = "Extra commands that should be added to {file}`.zlogin`.";
       };
 
       logoutExtra = mkOption {
         default = "";
         type = types.lines;
-        description = "Extra commands that should be added to <filename>.zlogout</filename>.";
+        description = "Extra commands that should be added to {file}`.zlogout`.";
       };
 
       plugins = mkOption {
@@ -434,7 +434,7 @@ in
             }
           ]
         '';
-        description = "Plugins to source in <filename>.zshrc</filename>.";
+        description = "Plugins to source in {file}`.zshrc`.";
       };
 
       oh-my-zsh = mkOption {
@@ -448,7 +448,7 @@ in
         default = {};
         example = { POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=["dir" "vcs"]; };
         description = ''
-          Extra local variables defined at the top of <filename>.zshrc</filename>.
+          Extra local variables defined at the top of {file}`.zshrc`.
         '';
       };
     };
diff --git a/modules/programs/zsh/prezto.nix b/modules/programs/zsh/prezto.nix
index 5aaf205f..ddf862f9 100644
--- a/modules/programs/zsh/prezto.nix
+++ b/modules/programs/zsh/prezto.nix
@@ -26,21 +26,23 @@ let
         type = types.nullOr types.bool;
         default = true;
         example = false;
-        description = "Color output (auto set to 'no' on dumb terminals)";
+        description = ''
+          Color output (automatically set to `false` on dumb terminals).
+        '';
       };
 
       pmoduleDirs = mkOption {
         type = types.listOf types.path;
         default = [ ];
         example = [ "$HOME/.zprezto-contrib" ];
-        description = "Add additional directories to load prezto modules from";
+        description = "Add additional directories to load prezto modules from.";
       };
 
       extraConfig = mkOption {
         type = types.lines;
         default = "";
         description = ''
-          Additional configuration to add to <filename>.zpreztorc</filename>.
+          Additional configuration to add to {file}`.zpreztorc`.
         '';
       };
 
@@ -48,14 +50,18 @@ let
         type = types.listOf types.str;
         default = [ ];
         example = [ "attr" "stat" ];
-        description = "Set the Zsh modules to load (man zshmodules).";
+        description = ''
+          Set the Zsh modules to load ({manpage}`zshmodules(1)`).
+        '';
       };
 
       extraFunctions = mkOption {
         type = types.listOf types.str;
         default = [ ];
         example = [ "zargs" "zmv" ];
-        description = "Set the Zsh functions to load (man zshcontrib).";
+        description = ''
+          Set the Zsh functions to load ({manpage}`zshcontrib(1)`).
+        '';
       };
 
       pmodules = mkOption {
@@ -86,8 +92,10 @@ let
         type = types.listOf types.str;
         default = [ ];
         example = [ "0.0.0.0" "127.0.0.1" ];
-        description =
-          "Set the entries to ignore in static */etc/hosts* for host completion.";
+        description = ''
+          Set the entries to ignore in static {file}`/etc/hosts` for
+          host completion.
+        '';
       };
 
       editor = {
@@ -95,21 +103,25 @@ let
           type = types.nullOr (types.enum [ "emacs" "vi" ]);
           default = "emacs";
           example = "vi";
-          description = "Set the key mapping style to 'emacs' or 'vi'.";
+          description = ''
+            Set the key mapping style to `emacs` or `vi`.
+          '';
         };
 
         dotExpansion = mkOption {
           type = types.nullOr types.bool;
           default = null;
           example = true;
-          description = "Auto convert .... to ../..";
+          description = ''
+            Automatically convert `....` to `../..`
+          '';
         };
 
         promptContext = mkOption {
           type = types.nullOr types.bool;
           default = null;
           example = true;
-          description = "Allow the zsh prompt context to be shown.";
+          description = "Allow the Zsh prompt context to be shown.";
         };
       };
 
@@ -117,8 +129,10 @@ let
         type = types.nullOr (types.enum [ "dirty" "untracked" "all" "none" ]);
         default = null;
         example = "all";
-        description =
-          "Ignore submodules when they are 'dirty', 'untracked', 'all', or 'none'.";
+        description = ''
+          Ignore submodules when they are `dirty`, `untracked`, `all`,
+          or `none`.
+        '';
       };
 
       gnuUtility.prefix = mkOption {
@@ -154,8 +168,10 @@ let
         type = types.nullOr types.str;
         default = null;
         example = "manpages";
-        description =
-          "Set the keyword used by `mand` to open man pages in Dash.app";
+        description = ''
+          Set the keyword used by {command}`mand` to open man pages
+          in Dash.app.
+        '';
       };
 
       prompt = {
@@ -164,8 +180,10 @@ let
           default = "sorin";
           example = "pure";
           description = ''
-            Set the prompt theme to load. Setting it to 'random'
-                      loads a random theme. Auto set to 'off' on dumb terminals.'';
+            Set the prompt theme to load. Setting it to `random`
+            loads a random theme. Automatically set to `off` on dumb
+            terminals.
+          '';
         };
 
         pwdLength = mkOption {
@@ -174,8 +192,10 @@ let
           example = "short";
           description = ''
             Set the working directory prompt display length. By
-                      default, it is set to 'short'. Set it to 'long' (without '~' expansion) for
-                      longer or 'full' (with '~' expansion) for even longer prompt display.'';
+            default, it is set to `short`. Set it to `long` (without `~`
+            expansion) for longer or `full` (with `~` expansion) for
+            even longer prompt display.
+          '';
         };
 
         showReturnVal = mkOption {
@@ -184,7 +204,8 @@ let
           example = true;
           description = ''
             Set the prompt to display the return code along with an
-                      indicator for non-zero return codes. This is not supported by all prompts.'';
+            indicator for non-zero return codes. This is not supported by all prompts.
+          '';
         };
       };
 
@@ -244,7 +265,8 @@ let
           example = [ "main" "brackets" "pattern" "line" "cursor" "root" ];
           description = ''
             Set syntax highlighters. By default, only the main
-                      highlighter is enabled.'';
+            highlighter is enabled.
+          '';
         };
 
         styles = mkOption {
@@ -333,9 +355,11 @@ let
         default = null;
         example = true;
         description = ''
-          Enabled safe options. This aliases cp, ln, mv and rm so
-                  that they prompt before deleting or overwriting files. Set to 'no' to disable
-                  this safer behavior.'';
+          Enabled safe options. This aliases {command}`cp`,
+          {command}`ln`, {command}`mv` and {command}`rm` so that they
+          prompt before deleting or overwriting files. Set to `no` to
+          disable this safer behavior.
+        '';
       };
     };
   };
diff --git a/modules/services/autorandr.nix b/modules/services/autorandr.nix
index 84791a66..64e6008e 100644
--- a/modules/services/autorandr.nix
+++ b/modules/services/autorandr.nix
@@ -13,8 +13,8 @@ in {
       enable = mkEnableOption "" // {
         description = ''
           Whether to enable the Autorandr systemd service.
-          This module is complementary to <code>programs.autorandr</code> which handles the
-          configuration (profiles).
+          This module is complementary to {option}`programs.autorandr`
+          which handles the configuration (profiles).
         '';
       };
 
diff --git a/modules/services/avizo.nix b/modules/services/avizo.nix
index 70a0e0b6..1bf1c1e6 100644
--- a/modules/services/avizo.nix
+++ b/modules/services/avizo.nix
@@ -39,7 +39,7 @@ in {
           patchPhase = "cp ''${./images}/*.png data/images/";
         })
       '';
-      description = "The <literal>avizo</literal> package to use.";
+      description = "The `avizo` package to use.";
     };
   };
 
diff --git a/modules/services/barrier.nix b/modules/services/barrier.nix
index b619cb28..513a7e74 100644
--- a/modules/services/barrier.nix
+++ b/modules/services/barrier.nix
@@ -30,8 +30,8 @@ in {
         type = types.str;
         description = ''
           Server to connect to formatted as
-          <literal>&lt;host&gt;[:&lt;port&gt;]</literal>.
-          Port defaults to <literal>24800</literal>.
+          `<host>[:<port>]`.
+          Port defaults to `24800`.
         '';
       };
 
@@ -46,8 +46,8 @@ in {
         default = [ "-f" ];
         defaultText = literalExpression ''[ "-f" ]'';
         description = ''
-          Additional flags to pass to <command>barrierc</command>.
-          See <command>barrierc --help</command>.
+          Additional flags to pass to {command}`barrierc`.
+          See {command}`barrierc --help`.
         '';
       };
 
diff --git a/modules/services/betterlockscreen.nix b/modules/services/betterlockscreen.nix
index b4b28b5f..c64ca08a 100644
--- a/modules/services/betterlockscreen.nix
+++ b/modules/services/betterlockscreen.nix
@@ -15,21 +15,21 @@ in {
         type = types.package;
         default = pkgs.betterlockscreen;
         defaultText = literalExpression "pkgs.betterlockscreen";
-        description = "Package providing <command>betterlockscreen</command>.";
+        description = "Package providing {command}`betterlockscreen`.";
       };
 
       arguments = mkOption {
         type = types.listOf types.str;
         default = [ ];
         description =
-          "List of arguments appended to <literal>./betterlockscreen --lock [args]</literal>";
+          "List of arguments appended to `./betterlockscreen --lock [args]`";
       };
 
       inactiveInterval = mkOption {
         type = types.int;
         default = 10;
         description = ''
-          Value used for <option>services.screen-locker.inactiveInterval</option>.
+          Value used for {option}`services.screen-locker.inactiveInterval`.
         '';
       };
 
diff --git a/modules/services/blueman-applet.nix b/modules/services/blueman-applet.nix
index d81db1db..5211534c 100644
--- a/modules/services/blueman-applet.nix
+++ b/modules/services/blueman-applet.nix
@@ -8,13 +8,13 @@ with lib;
       enable = mkEnableOption "" // {
         description = ''
           Whether to enable the Blueman applet.
-          </para><para>
-          Note, for the applet to work, the 'blueman' service should
+
+          Note that for the applet to work, the `blueman` service should
           be enabled system-wide. You can enable it in the system
           configuration using
-          <programlisting language="nix">
-            services.blueman.enable = true;
-          </programlisting>
+          ```nix
+          services.blueman.enable = true;
+          ```
         '';
       };
     };
diff --git a/modules/services/borgmatic.nix b/modules/services/borgmatic.nix
index c2f2963a..1e181394 100644
--- a/modules/services/borgmatic.nix
+++ b/modules/services/borgmatic.nix
@@ -17,13 +17,10 @@ in {
         default = "hourly";
         description = ''
           How often to run borgmatic when
-          <code language="nix">services.borgmatic.enable = true</code>.
+          `services.borgmatic.enable = true`.
           This value is passed to the systemd timer configuration as
           the onCalendar option. See
-          <citerefentry>
-            <refentrytitle>systemd.time</refentrytitle>
-            <manvolnum>7</manvolnum>
-          </citerefentry>
+          {manpage}`systemd.time(7)`
           for more information about the format.
         '';
       };
diff --git a/modules/services/cachix-agent.nix b/modules/services/cachix-agent.nix
index 01eca05b..7b29b3c4 100644
--- a/modules/services/cachix-agent.nix
+++ b/modules/services/cachix-agent.nix
@@ -10,8 +10,8 @@ in {
   meta.maintainers = [ maintainers.rycee ];
 
   options.services.cachix-agent = {
-    enable = mkEnableOption ''
-      Cachix Deploy Agent: <link xlink:href="https://docs.cachix.org/deploy/"/>'';
+    enable =
+      mkEnableOption "Cachix Deploy Agent: <https://docs.cachix.org/deploy/>";
 
     name = mkOption {
       type = types.str;
@@ -43,7 +43,7 @@ in {
         literalExpression ''"''${config.xdg.configHome}/cachix-agent.token"'';
       description = ''
         Required file that needs to contain
-        <literal>CACHIX_AGENT_TOKEN=...</literal>.
+        `CACHIX_AGENT_TOKEN=...`.
       '';
     };
   };
diff --git a/modules/services/clipman.nix b/modules/services/clipman.nix
index 6a177670..4616c298 100644
--- a/modules/services/clipman.nix
+++ b/modules/services/clipman.nix
@@ -15,10 +15,9 @@ in {
       example = "sway-session.target";
       description = ''
         The systemd target that will automatically start the clipman service.
-        </para>
-        <para>
-        When setting this value to <literal>"sway-session.target"</literal>,
-        make sure to also enable <option>wayland.windowManager.sway.systemd.enable</option>,
+
+        When setting this value to `"sway-session.target"`,
+        make sure to also enable {option}`wayland.windowManager.sway.systemd.enable`,
         otherwise the service may never be started.
       '';
     };
diff --git a/modules/services/clipmenu.nix b/modules/services/clipmenu.nix
index 4bb8916f..c55166b3 100644
--- a/modules/services/clipmenu.nix
+++ b/modules/services/clipmenu.nix
@@ -24,7 +24,7 @@ in {
       default = null;
       example = "rofi";
       description = ''
-        Launcher command, if not set, <command>dmenu</command>
+        Launcher command, if not set, {command}`dmenu`
         will be used by default.
       '';
     };
diff --git a/modules/services/copyq.nix b/modules/services/copyq.nix
index 358185c0..32e83978 100644
--- a/modules/services/copyq.nix
+++ b/modules/services/copyq.nix
@@ -19,10 +19,9 @@ in {
       example = "sway-session.target";
       description = ''
         The systemd target that will automatically start the CopyQ service.
-        </para>
-        <para>
-        When setting this value to <literal>"sway-session.target"</literal>,
-        make sure to also enable <option>wayland.windowManager.sway.systemd.enable</option>,
+
+        When setting this value to `"sway-session.target"`,
+        make sure to also enable {option}`wayland.windowManager.sway.systemd.enable`,
         otherwise the service may never be started.
       '';
     };
diff --git a/modules/services/dunst.nix b/modules/services/dunst.nix
index 8606e248..daa800cf 100644
--- a/modules/services/dunst.nix
+++ b/modules/services/dunst.nix
@@ -61,7 +61,7 @@ in {
         type = types.package;
         default = pkgs.dunst;
         defaultText = literalExpression "pkgs.dunst";
-        description = "Package providing <command>dunst</command>.";
+        description = "Package providing {command}`dunst`.";
       };
 
       configFile = mkOption {
@@ -70,9 +70,9 @@ in {
         defaultText = "$XDG_CONFIG_HOME/dunst/dunstrc";
         description = ''
           Path to the configuration file read by dunst.
-          </para><para>
+
           Note that the configuration generated by Home Manager will be
-          written to <filename>$XDG_CONFIG_HOME/dunst/dunstrc</filename>
+          written to {file}`$XDG_CONFIG_HOME/dunst/dunstrc`
           regardless. This allows using a mutable configuration file generated
           from the immutable one, useful in scenarios where live reloading is
           desired.
@@ -89,7 +89,7 @@ in {
         type = types.str;
         default = "";
         description =
-          "Set the service's <envar>WAYLAND_DISPLAY</envar> environment variable.";
+          "Set the service's {env}`WAYLAND_DISPLAY` environment variable.";
       };
 
       settings = mkOption {
@@ -104,7 +104,7 @@ in {
         };
         default = { };
         description =
-          "Configuration written to <filename>$XDG_CONFIG_HOME/dunst/dunstrc</filename>.";
+          "Configuration written to {file}`$XDG_CONFIG_HOME/dunst/dunstrc`.";
         example = literalExpression ''
           {
             global = {
diff --git a/modules/services/easyeffects.nix b/modules/services/easyeffects.nix
index 9dd01b94..fd5e4b40 100644
--- a/modules/services/easyeffects.nix
+++ b/modules/services/easyeffects.nix
@@ -15,16 +15,16 @@ in {
     enable = mkEnableOption ''
       Easyeffects daemon.
       Note, it is necessary to add
-      <programlisting language="nix">
+      ```nix
       programs.dconf.enable = true;
-      </programlisting>
+      ```
       to your system configuration for the daemon to work correctly'';
 
     package = mkOption {
       type = types.package;
       default = pkgs.easyeffects;
       defaultText = literalExpression "pkgs.easyeffects";
-      description = "The <literal>easyeffects</literal> package to use.";
+      description = "The `easyeffects` package to use.";
     };
 
     preset = mkOption {
diff --git a/modules/services/emacs.nix b/modules/services/emacs.nix
index 2d5a24b9..64c6c6ee 100644
--- a/modules/services/emacs.nix
+++ b/modules/services/emacs.nix
@@ -59,7 +59,7 @@ in {
       default = [ ];
       example = [ "-f" "exwm-enable" ];
       description = ''
-        Extra command-line arguments to pass to <command>emacs</command>.
+        Extra command-line arguments to pass to {command}`emacs`.
       '';
     };
 
@@ -69,7 +69,7 @@ in {
         type = with types; listOf str;
         default = [ "-c" ];
         description = ''
-          Command-line arguments to pass to <command>emacsclient</command>.
+          Command-line arguments to pass to {command}`emacsclient`.
         '';
       };
     };
@@ -89,10 +89,10 @@ in {
       example = "graphical";
       description = ''
         Whether to launch Emacs service with the systemd user session. If it is
-        <literal>true</literal>, Emacs service is started by
-        <literal>default.target</literal>. If it is
-        <literal>"graphical"</literal>, Emacs service is started by
-        <literal>graphical-session.target</literal>.
+        `true`, Emacs service is started by
+        `default.target`. If it is
+        `"graphical"`, Emacs service is started by
+        `graphical-session.target`.
       '';
     };
 
@@ -101,8 +101,8 @@ in {
       default = false;
       example = !default;
       description = ''
-        Whether to configure <command>emacsclient</command> as the default
-        editor using the <envar>EDITOR</envar> environment variable.
+        Whether to configure {command}`emacsclient` as the default
+        editor using the {env}`EDITOR` environment variable.
       '';
     };
   };
diff --git a/modules/services/espanso.nix b/modules/services/espanso.nix
index ec8ace5e..404dfecd 100644
--- a/modules/services/espanso.nix
+++ b/modules/services/espanso.nix
@@ -47,7 +47,7 @@ in {
         '';
         description = ''
           The Espanso configuration to use. See
-          <link xlink:href="https://espanso.org/docs/configuration/basics/"/>
+          <https://espanso.org/docs/configuration/basics/>
           for a description of available options.
         '';
       };
@@ -91,7 +91,7 @@ in {
         '';
         description = ''
           The Espanso matches to use. See
-          <link xlink:href="https://espanso.org/docs/matches/basics/"/>
+          <https://espanso.org/docs/matches/basics/>
           for a description of available options.
         '';
       };
diff --git a/modules/services/flameshot.nix b/modules/services/flameshot.nix
index 2de0d547..0c2435ae 100644
--- a/modules/services/flameshot.nix
+++ b/modules/services/flameshot.nix
@@ -20,7 +20,7 @@ in {
       type = types.package;
       default = pkgs.flameshot;
       defaultText = literalExpression "pkgs.flameshot";
-      description = "Package providing <command>flameshot</command>.";
+      description = "Package providing {command}`flameshot`.";
     };
 
     settings = mkOption {
@@ -34,7 +34,7 @@ in {
       };
       description = ''
         Configuration to use for Flameshot. See
-        <link xlink:href="https://github.com/flameshot-org/flameshot/blob/master/flameshot.example.ini"/>
+        <https://github.com/flameshot-org/flameshot/blob/master/flameshot.example.ini>
         for available options.
       '';
     };
diff --git a/modules/services/fluidsynth.nix b/modules/services/fluidsynth.nix
index bf1b76a0..dbeb8df7 100644
--- a/modules/services/fluidsynth.nix
+++ b/modules/services/fluidsynth.nix
@@ -36,10 +36,7 @@ in {
         example = [ "--sample-rate 96000" ];
         description = ''
           Extra arguments, added verbatim to the fluidsynth command. See
-          <citerefentry>
-            <refentrytitle>fluidsynth.conf</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>.
+          {manpage}`fluidsynth.conf(1)`.
         '';
       };
     };
diff --git a/modules/services/fnott.nix b/modules/services/fnott.nix
index 43be5d71..3d2d1dd8 100644
--- a/modules/services/fnott.nix
+++ b/modules/services/fnott.nix
@@ -21,7 +21,7 @@ in {
         type = types.package;
         default = pkgs.fnott;
         defaultText = literalExpression "pkgs.fnott";
-        description = "Package providing <command>fnott</command>.";
+        description = "Package providing {command}`fnott`.";
       };
 
       extraFlags = mkOption {
@@ -39,12 +39,12 @@ in {
         defaultText = "$XDG_CONFIG_HOME/fnott/fnott.ini";
         description = ''
           Path to the configuration file read by fnott.
-          </para><para>
+
           Note that environment variables in the path won't be properly expanded.
-          </para><para>
+
           The configuration specified under
-          <option>services.fnott.settings</option> will be generated and
-          written to <filename>$XDG_CONFIG_HOME/fnott/fnott.ini</filename>
+          {option}`services.fnott.settings` will be generated and
+          written to {file}`$XDG_CONFIG_HOME/fnott/fnott.ini`
           regardless of this option. This allows using a mutable configuration file
           generated from the immutable one, useful in scenarios where live reloading is desired.
         '';
@@ -55,14 +55,10 @@ in {
         default = { };
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/fnott/fnott.ini</filename>.
-          </para><para>
+          {file}`$XDG_CONFIG_HOME/fnott/fnott.ini`.
+
           See
-          <citerefentry>
-            <refentrytitle>fnott.ini</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry> for a list of available options and <link
-          xlink:href="https://codeberg.org/dnkl/fnott/src/branch/master/fnott.ini"/>
+          {manpage}`fnott.ini(5)` for a list of available options and <https://codeberg.org/dnkl/fnott/src/branch/master/fnott.ini>
           for an example configuration.
         '';
         example = literalExpression ''
diff --git a/modules/services/fusuma.nix b/modules/services/fusuma.nix
index c48cf5a9..e0ced976 100644
--- a/modules/services/fusuma.nix
+++ b/modules/services/fusuma.nix
@@ -66,7 +66,7 @@ in {
       type = types.package;
       default = pkgs.fusuma;
       defaultText = literalExpression "pkgs.fusuma";
-      description = "Package providing <command>fusuma</command>.";
+      description = "Package providing {command}`fusuma`.";
     };
 
     settings = mkOption {
diff --git a/modules/services/getmail.nix b/modules/services/getmail.nix
index 05950e62..7357987e 100644
--- a/modules/services/getmail.nix
+++ b/modules/services/getmail.nix
@@ -25,11 +25,11 @@ in {
         default = "*:0/5";
         example = "hourly";
         description = ''
-          The refresh frequency. Check <literal>man systemd.time</literal> for
+          The refresh frequency. Check `man systemd.time` for
           more information on the syntax. If you use a gpg-agent in
           combination with the passwordCommand, keep the poll
           frequency below the cache-ttl value (as set by the
-          <literal>default</literal>) to avoid pinentry asking
+          `default`) to avoid pinentry asking
           permanently for a password.
         '';
       };
diff --git a/modules/services/git-sync.nix b/modules/services/git-sync.nix
index 42f8c4cc..770cec0f 100644
--- a/modules/services/git-sync.nix
+++ b/modules/services/git-sync.nix
@@ -49,7 +49,7 @@ let
         description = ''
           The URI of the remote to be synchronized. This is only used in the
           event that the directory does not already exist. See
-          <link xlink:href="https://git-scm.com/docs/git-clone#_git_urls"/>
+          <https://git-scm.com/docs/git-clone#_git_urls>
           for the supported URIs.
         '';
       };
@@ -77,7 +77,7 @@ in {
         default = pkgs.git-sync;
         defaultText = literalExpression "pkgs.git-sync";
         description = ''
-          Package containing the <command>git-sync</command> program.
+          Package containing the {command}`git-sync` program.
         '';
       };
 
diff --git a/modules/services/gpg-agent.nix b/modules/services/gpg-agent.nix
index 39e93669..63ba11c7 100644
--- a/modules/services/gpg-agent.nix
+++ b/modules/services/gpg-agent.nix
@@ -157,7 +157,7 @@ in {
           Tell the pinentry to grab the keyboard and mouse. This
           option should in general be used to avoid X-sniffing
           attacks. When disabled, this option passes
-          <option>no-grab</option> setting to gpg-agent.
+          {option}`no-grab` setting to gpg-agent.
         '';
       };
 
@@ -168,7 +168,7 @@ in {
           Make use of the scdaemon tool. This option has the effect of
           enabling the ability to do smartcard operations. When
           disabled, this option passes
-          <option>disable-scdaemon</option> setting to gpg-agent.
+          {option}`disable-scdaemon` setting to gpg-agent.
         '';
       };
 
@@ -191,16 +191,16 @@ in {
         default = "gtk2";
         description = ''
           Which pinentry interface to use. If not
-          <literal>null</literal>, it sets
-          <option>pinentry-program</option> in
-          <filename>gpg-agent.conf</filename>. Beware that
-          <literal>pinentry-gnome3</literal> may not work on non-Gnome
+          `null`, it sets
+          {option}`pinentry-program` in
+          {file}`gpg-agent.conf`. Beware that
+          `pinentry-gnome3` may not work on non-Gnome
           systems. You can fix it by adding the following to your
           system configuration:
-          <programlisting language="nix">
+          ```nix
           services.dbus.packages = [ pkgs.gcr ];
-          </programlisting>
-          For this reason, the default is <literal>gtk2</literal> for
+          ```
+          For this reason, the default is `gtk2` for
           now.
         '';
       };
diff --git a/modules/services/grobi.nix b/modules/services/grobi.nix
index d90b7244..e656a763 100644
--- a/modules/services/grobi.nix
+++ b/modules/services/grobi.nix
@@ -23,8 +23,8 @@ in {
         description = ''
           Commands to be run after an output configuration was
           changed. The Nix value declared here will be translated to
-          JSON and written to the <option>execute_after</option> key
-          in <filename>$XDG_CONFIG_HOME/grobi.conf</filename>.
+          JSON and written to the {option}`execute_after` key
+          in {file}`$XDG_CONFIG_HOME/grobi.conf`.
         '';
       };
 
@@ -61,10 +61,10 @@ in {
           These are the rules grobi tries to match to the current
           output configuration. The rules are evaluated top to bottom,
           the first matching rule is applied and processing stops. See
-          <link xlink:href="https://github.com/fd0/grobi/blob/master/doc/grobi.conf"/>
+          <https://github.com/fd0/grobi/blob/master/doc/grobi.conf>
           for more information. The Nix value declared here will be
-          translated to JSON and written to the <option>rules</option>
-          key in <filename>$XDG_CONFIG_HOME/grobi.conf</filename>.
+          translated to JSON and written to the {option}`rules`
+          key in {file}`$XDG_CONFIG_HOME/grobi.conf`.
         '';
       };
     };
diff --git a/modules/services/gromit-mpx.nix b/modules/services/gromit-mpx.nix
index 7a85cf76..f46eddb3 100644
--- a/modules/services/gromit-mpx.nix
+++ b/modules/services/gromit-mpx.nix
@@ -95,7 +95,7 @@ let
         default = null;
         example = 2;
         description = ''
-          If not <literal>null</literal>, automatically draw an arrow
+          If not `null`, automatically draw an arrow
           at the end of a stroke with the given size.
         '';
       };
@@ -130,7 +130,7 @@ in {
       example = "Insert";
       description = ''
         A keysym or raw keycode that toggles the activation state of
-        gromit-mpx.  Set to <literal>null</literal> to disable the
+        gromit-mpx.  Set to `null` to disable the
         hotkey in which case you'll have to activate gromit-mpx
         manually using the command line.
       '';
@@ -142,7 +142,7 @@ in {
       description = ''
         A keysym or raw keycode that causes gromit-mpx to undo the
         last stroke.  Use this key along with the shift key to redo an
-        undone stoke.  Set to <literal>null</literal> to disable the
+        undone stoke.  Set to `null` to disable the
         undo hotkey.
       '';
     };
diff --git a/modules/services/home-manager-auto-upgrade.nix b/modules/services/home-manager-auto-upgrade.nix
index 2f975ef1..659f9118 100644
--- a/modules/services/home-manager-auto-upgrade.nix
+++ b/modules/services/home-manager-auto-upgrade.nix
@@ -15,7 +15,7 @@ in {
     services.home-manager.autoUpgrade = {
       enable = lib.mkEnableOption ''
         the Home Manager upgrade service that periodically updates your Nix
-        channels before running <code>home-manager switch</code>'';
+        channels before running `home-manager switch`'';
 
       frequency = lib.mkOption {
         type = lib.types.str;
@@ -23,12 +23,9 @@ in {
         description = ''
           The interval at which the Home Manager auto upgrade is run.
           This value is passed to the systemd timer configuration
-          as the <code>OnCalendar</code> option.
+          as the `OnCalendar` option.
           The format is described in
-          <citerefentry>
-            <refentrytitle>systemd.time</refentrytitle>
-            <manvolnum>7</manvolnum>
-          </citerefentry>.
+          {manpage}`systemd.time(7)`.
         '';
       };
     };
diff --git a/modules/services/kanshi.nix b/modules/services/kanshi.nix
index cdef4c72..3297d5fb 100644
--- a/modules/services/kanshi.nix
+++ b/modules/services/kanshi.nix
@@ -16,12 +16,9 @@ let
           The latter can be used to match any output.
 
           On
-          <citerefentry>
-            <refentrytitle>sway</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>,
+          {manpage}`sway(1)`,
           output names and descriptions can be obtained via
-          <literal>swaymsg -t get_outputs</literal>.
+          `swaymsg -t get_outputs`.
         '';
       };
 
@@ -39,7 +36,7 @@ let
         example = "1920x1080@60Hz";
         description = ''
           &lt;width&gt;x&lt;height&gt;[@&lt;rate&gt;[Hz]]
-          </para><para>
+
           Configures the specified output to use the specified mode.
           Modes are a combination of width and height (in pixels) and
           a refresh rate (in Hz) that your display can be configured to use.
@@ -52,7 +49,7 @@ let
         example = "1600,0";
         description = ''
           &lt;x&gt;,&lt;y&gt;
-          </para><para>
+
           Places the output at the specified position in the global coordinates
           space.
         '';
diff --git a/modules/services/kbfs.nix b/modules/services/kbfs.nix
index 4f1bfd8b..a541a32c 100644
--- a/modules/services/kbfs.nix
+++ b/modules/services/kbfs.nix
@@ -16,7 +16,7 @@ in {
         default = "keybase";
         description = ''
           Mount point for the Keybase filesystem, relative to
-          <envar>HOME</envar>.
+          {env}`HOME`.
         '';
       };
 
diff --git a/modules/services/listenbrainz-mpd.nix b/modules/services/listenbrainz-mpd.nix
index 5a6d2082..0a55a9e4 100644
--- a/modules/services/listenbrainz-mpd.nix
+++ b/modules/services/listenbrainz-mpd.nix
@@ -22,7 +22,7 @@ in {
       default = { };
       description = ''
         Configuration for listenbrainz-mpd written to
-        <filename>$XDG_CONFIG_HOME/listenbrainz-mpd/config.toml</filename>.
+        {file}`$XDG_CONFIG_HOME/listenbrainz-mpd/config.toml`.
       '';
       example = { submission.tokenFile = "/run/secrets/listenbrainz-mpd"; };
     };
diff --git a/modules/services/mako.nix b/modules/services/mako.nix
index be36c435..7ca01178 100644
--- a/modules/services/mako.nix
+++ b/modules/services/mako.nix
@@ -185,8 +185,8 @@ in {
           Set popup progress indicator color to a specific color,
           represented in hex color code. To draw the progress
           indicator on top of the background color, use the
-          <literal>over</literal> attribute. To replace the background
-          color, use the <literal>source</literal> attribute (this can
+          `over` attribute. To replace the background
+          color, use the `source` attribute (this can
           be useful when the notification is semi-transparent).
         '';
       };
@@ -216,9 +216,9 @@ in {
           algorithm used by the XDG Icon Theme Specification, but does not
           support any of the theme metadata. Therefore, if you want to search
           parent themes, you'll need to add them to the path manually.
-          </para><para>
-          The <filename>/usr/share/icons/hicolor</filename> and
-          <filename>/usr/share/pixmaps</filename> directories are
+
+          The {file}`/usr/share/icons/hicolor` and
+          {file}`/usr/share/pixmaps` directories are
           always searched.
         '';
       };
diff --git a/modules/services/mbsync.nix b/modules/services/mbsync.nix
index bdeda0ec..7f0f2d30 100644
--- a/modules/services/mbsync.nix
+++ b/modules/services/mbsync.nix
@@ -29,10 +29,7 @@ in {
       description = ''
         How often to run mbsync.  This value is passed to the systemd
         timer configuration as the onCalendar option.  See
-        <citerefentry>
-          <refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>7</manvolnum>
-        </citerefentry>
+        {manpage}`systemd.time(7)`
         for more information about the format.
       '';
     };
@@ -50,7 +47,7 @@ in {
       default = null;
       description = ''
         Optional configuration file to link to use instead of
-        the default file (<filename>~/.mbsyncrc</filename>).
+        the default file ({file}`~/.mbsyncrc`).
       '';
     };
 
diff --git a/modules/services/mopidy.nix b/modules/services/mopidy.nix
index f5064c51..37642a29 100644
--- a/modules/services/mopidy.nix
+++ b/modules/services/mopidy.nix
@@ -94,9 +94,9 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/mopidy/mopidy.conf</filename>.
-        </para><para>
-        See <link xlink:href="https://docs.mopidy.com/en/latest/config/"/> for
+        {file}`$XDG_CONFIG_HOME/mopidy/mopidy.conf`.
+
+        See <https://docs.mopidy.com/en/latest/config/> for
         more details.
       '';
     };
diff --git a/modules/services/mpd-discord-rpc.nix b/modules/services/mpd-discord-rpc.nix
index 50bc824b..8996051a 100644
--- a/modules/services/mpd-discord-rpc.nix
+++ b/modules/services/mpd-discord-rpc.nix
@@ -25,8 +25,8 @@ in {
         }
       '';
       description = ''
-        Configuration included in <literal>config.toml</literal>.
-        For available options see <link xlink:href="https://github.com/JakeStanger/mpd-discord-rpc#configuration"/>
+        Configuration included in `config.toml`.
+        For available options see <https://github.com/JakeStanger/mpd-discord-rpc#configuration>
       '';
     };
 
diff --git a/modules/services/mpd-mpris.nix b/modules/services/mpd-mpris.nix
index 681137f7..924036c8 100644
--- a/modules/services/mpd-mpris.nix
+++ b/modules/services/mpd-mpris.nix
@@ -36,8 +36,8 @@ in {
         defaultText = lib.literalExpression "config.services.mpd.enable";
         description = ''
           Whether to configure for the local MPD daemon. If
-          <literal>true</literal> the <literal>network</literal>,
-          <literal>host</literal>, and <literal>port</literal>
+          `true` the `network`,
+          `host`, and `port`
           settings are ignored.
         '';
       };
@@ -47,7 +47,7 @@ in {
         default = null;
         description = ''
           The network used to dial to the MPD server. Check
-          <link xlink:href="https://golang.org/pkg/net/#Dial" />
+          <https://golang.org/pkg/net/#Dial>
           for available values (most common are "tcp" and "unix")
         '';
       };
diff --git a/modules/services/mpd.nix b/modules/services/mpd.nix
index 3d3ce1b9..a0011b02 100644
--- a/modules/services/mpd.nix
+++ b/modules/services/mpd.nix
@@ -60,9 +60,9 @@ in {
         apply = toString; # Prevent copies to Nix store.
         description = ''
           The directory where mpd reads music from.
-          </para><para>
-          If <xref linkend="opt-xdg.userDirs.enable"/> is
-          <literal>true</literal> then the defined XDG music directory is used.
+
+          If [](#opt-xdg.userDirs.enable) is
+          `true` then the defined XDG music directory is used.
           Otherwise, you must explicitly specify a value.
         '';
       };
@@ -82,13 +82,10 @@ in {
         default = "";
         description = ''
           Extra directives added to to the end of MPD's configuration
-          file, <filename>mpd.conf</filename>. Basic configuration
+          file, {file}`mpd.conf`. Basic configuration
           like file location and uid/gid is added automatically to the
           beginning of the file. For available options see
-          <citerefentry>
-            <refentrytitle>mpd.conf</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry>.
+          {manpage}`mpd.conf(5)`.
         '';
       };
 
@@ -127,7 +124,7 @@ in {
           example = "any";
           description = ''
             The address for the daemon to listen on.
-            Use <literal>any</literal> to listen on all addresses.
+            Use `any` to listen on all addresses.
           '';
         };
 
@@ -147,7 +144,7 @@ in {
         defaultText = "\${dataDir}/tag_cache";
         description = ''
           The path to MPD's database. If set to
-          <literal>null</literal> the parameter is omitted from the
+          `null` the parameter is omitted from the
           configuration.
         '';
       };
diff --git a/modules/services/muchsync.nix b/modules/services/muchsync.nix
index 8c9e2701..d4fcd864 100644
--- a/modules/services/muchsync.nix
+++ b/modules/services/muchsync.nix
@@ -13,13 +13,10 @@ let
         type = types.str;
         default = "*:0/5";
         description = ''
-          How often to run <command>muchsync</command>. This
+          How often to run {command}`muchsync`. This
           value is passed to the systemd timer configuration as the
-          <literal>OnCalendar</literal> option. See
-          <citerefentry>
-            <refentrytitle>systemd.time</refentrytitle>
-            <manvolnum>7</manvolnum>
-          </citerefentry>
+          `OnCalendar` option. See
+          {manpage}`systemd.time(7)`
           for more information about the format.
         '';
       };
@@ -29,9 +26,9 @@ let
         default = "${pkgs.openssh}/bin/ssh -CTaxq";
         defaultText = "ssh -CTaxq";
         description = ''
-          Specifies a command line to pass to <command>/bin/sh</command>
+          Specifies a command line to pass to {command}`/bin/sh`
           to execute a command on another machine.
-          </para><para>
+
           Note that because this string is passed to the shell,
           special characters including spaces may need to be escaped.
         '';
@@ -53,12 +50,12 @@ let
             Check for locally modified files.
             Without this option, muchsync assumes that files in a maildir are
             never edited.
-            </para><para>
-            <option>checkForModifiedFiles</option> disables certain
+
+            {option}`checkForModifiedFiles` disables certain
             optimizations so as to make muchsync at least check the timestamp on
             every file, which will detect modified files at the cost of a longer
             startup time.
-            </para><para>
+
             This option is useful if your software regularly modifies the
             contents of mail files (e.g., because you are running offlineimap
             with "synclabels = yes").
@@ -70,7 +67,7 @@ let
           default = true;
           description = ''
             Whether to begin the synchronisation by running
-            <command>notmuch new</command> locally.
+            {command}`notmuch new` locally.
           '';
         };
       };
@@ -104,12 +101,12 @@ let
             Check for modified files on the remote side.
             Without this option, muchsync assumes that files in a maildir are
             never edited.
-            </para><para>
-            <option>checkForModifiedFiles</option> disables certain
+
+            {option}`checkForModifiedFiles` disables certain
             optimizations so as to make muchsync at least check the timestamp on
             every file, which will detect modified files at the cost of a longer
             startup time.
-            </para><para>
+
             This option is useful if your software regularly modifies the
             contents of mail files (e.g., because you are running offlineimap
             with "synclabels = yes").
@@ -121,7 +118,7 @@ let
           default = true;
           description = ''
             Whether to begin the synchronisation by running
-            <command>notmuch new</command> on the remote side.
+            {command}`notmuch new` on the remote side.
           '';
         };
       };
diff --git a/modules/services/notify-osd.nix b/modules/services/notify-osd.nix
index 6a75ce6e..4faf8364 100644
--- a/modules/services/notify-osd.nix
+++ b/modules/services/notify-osd.nix
@@ -18,7 +18,7 @@ in {
         default = pkgs.notify-osd;
         defaultText = literalExpression "pkgs.notify-osd";
         description = ''
-          Package containing the <command>notify-osd</command> program.
+          Package containing the {command}`notify-osd` program.
         '';
       };
     };
diff --git a/modules/services/pantalaimon.nix b/modules/services/pantalaimon.nix
index d833d453..67fe76cd 100644
--- a/modules/services/pantalaimon.nix
+++ b/modules/services/pantalaimon.nix
@@ -19,7 +19,7 @@ in {
         default = pkgs.pantalaimon;
         defaultText = literalExpression "pkgs.pantalaimon";
         description =
-          "Package providing the <command>pantalaimon</command> executable to use.";
+          "Package providing the {command}`pantalaimon` executable to use.";
       };
 
       settings = mkOption {
@@ -41,13 +41,10 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/pantalaimon/pantalaimon.conf</filename>.
-          </para><para>
-          See <link xlink:href="https://github.com/matrix-org/pantalaimon/blob/master/docs/manpantalaimon.5.md" /> or
-          <citerefentry>
-            <refentrytitle>pantalaimon</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry>
+          {file}`$XDG_CONFIG_HOME/pantalaimon/pantalaimon.conf`.
+
+          See <https://github.com/matrix-org/pantalaimon/blob/master/docs/manpantalaimon.5.md> or
+          {manpage}`pantalaimon(5)`
           for options.
         '';
       };
diff --git a/modules/services/pass-secret-service.nix b/modules/services/pass-secret-service.nix
index 91e5cd01..db494337 100644
--- a/modules/services/pass-secret-service.nix
+++ b/modules/services/pass-secret-service.nix
@@ -21,9 +21,9 @@ in {
       example = "/home/user/.local/share/password-store";
       description = ''
         Absolute path to password store. Defaults to
-        <filename>$HOME/.password-store</filename> if the
-        <option>programs.password-store</option> module is not enabled, and
-        <option>programs.password-store.settings.PASSWORD_STORE_DIR</option> if it is.
+        {file}`$HOME/.password-store` if the
+        {option}`programs.password-store` module is not enabled, and
+        {option}`programs.password-store.settings.PASSWORD_STORE_DIR` if it is.
       '';
     };
   };
diff --git a/modules/services/password-store-sync.nix b/modules/services/password-store-sync.nix
index c8dbe808..dfff410f 100644
--- a/modules/services/password-store-sync.nix
+++ b/modules/services/password-store-sync.nix
@@ -19,14 +19,11 @@ in {
       description = ''
         How often to synchronise the password store git repository with its
         default upstream.
-        </para><para>
+
         This value is passed to the systemd timer configuration as the
-        <literal>onCalendar</literal> option.
+        `onCalendar` option.
         See
-        <citerefentry>
-          <refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>7</manvolnum>
-        </citerefentry>
+        {manpage}`systemd.time(7)`
         for more information about the format.
       '';
     };
diff --git a/modules/services/pbgopy.nix b/modules/services/pbgopy.nix
index 487aa4f3..fecc64ca 100644
--- a/modules/services/pbgopy.nix
+++ b/modules/services/pbgopy.nix
@@ -34,7 +34,7 @@ in {
       default = "24h";
       example = "10m";
       description = ''
-        The TTL for the cache. Use <literal>"0s"</literal> to disable it.
+        The TTL for the cache. Use `"0s"` to disable it.
       '';
     };
 
diff --git a/modules/services/picom.nix b/modules/services/picom.nix
index 66f707c0..e1368809 100644
--- a/modules/services/picom.nix
+++ b/modules/services/picom.nix
@@ -100,7 +100,7 @@ in {
       example = [ "window_type *= 'menu'" "name ~= 'Firefox$'" "focused = 1" ];
       description = ''
         List of conditions of windows that should not be faded.
-        See <literal>picom(1)</literal> man page for more examples.
+        See `picom(1)` man page for more examples.
       '';
     };
 
@@ -136,7 +136,7 @@ in {
       example = [ "window_type *= 'menu'" "name ~= 'Firefox$'" "focused = 1" ];
       description = ''
         List of conditions of windows that should have no shadow.
-        See <literal>picom(1)</literal> man page for more examples.
+        See `picom(1)` man page for more examples.
       '';
     };
 
@@ -201,7 +201,7 @@ in {
       type = types.enum [ "egl" "glx" "xrender" "xr_glx_hybrid" ];
       default = "xrender";
       description = ''
-        Backend to use: <literal>egl</literal>, <literal>glx</literal>, <literal>xrender</literal> or <literal>xr_glx_hybrid</literal>.
+        Backend to use: `egl`, `glx`, `xrender` or `xr_glx_hybrid`.
       '';
     };
 
@@ -264,7 +264,7 @@ in {
         description = ''
           Picom settings. Use this option to configure Picom settings not exposed
           in a NixOS option or to bypass one. For the available options see the
-          CONFIGURATION FILES section at <literal>picom(1)</literal>.
+          CONFIGURATION FILES section at `picom(1)`.
         '';
       };
   };
diff --git a/modules/services/plex-mpv-shim.nix b/modules/services/plex-mpv-shim.nix
index b5fb6218..940e5718 100644
--- a/modules/services/plex-mpv-shim.nix
+++ b/modules/services/plex-mpv-shim.nix
@@ -37,8 +37,8 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/plex-mpv-shim/config.json</filename>. See
-          <link xlink:href="https://github.com/iwalton3/plex-mpv-shim/blob/master/README.md"/>
+          {file}`$XDG_CONFIG_HOME/plex-mpv-shim/config.json`. See
+          <https://github.com/iwalton3/plex-mpv-shim/blob/master/README.md>
           for the configuration documentation.
         '';
       };
diff --git a/modules/services/polybar.nix b/modules/services/polybar.nix
index d3ac68de..fbcecc5a 100644
--- a/modules/services/polybar.nix
+++ b/modules/services/polybar.nix
@@ -94,7 +94,7 @@ in {
         description = ''
           Polybar configuration. Can be either path to a file, or set of attributes
           that will be used to create the final configuration.
-          See also <option>services.polybar.settings</option> for a more nix-friendly format.
+          See also {option}`services.polybar.settings` for a more nix-friendly format.
         '';
         default = { };
         example = literalExpression ''
@@ -127,33 +127,33 @@ in {
           strange data format that polybar uses.
           Each entry will be converted to a section in the output file.
           Several things are treated specially: nested keys are converted
-          to dash-separated keys; the special <literal>text</literal> key is ignored as a nested key,
+          to dash-separated keys; the special `text` key is ignored as a nested key,
           to allow mixing different levels of nesting; and lists are converted to
-          polybar's <literal>foo-0, foo-1, ...</literal> format.
-          </para><para>
+          polybar's `foo-0, foo-1, ...` format.
+
           For example:
-          <programlisting language="nix">
+          ```nix
           "module/volume" = {
             type = "internal/pulseaudio";
-            format.volume = "&lt;ramp-volume&gt; &lt;label-volume&gt;";
+            format.volume = "<ramp-volume> <label-volume>";
             label.muted.text = "🔇";
             label.muted.foreground = "#666";
             ramp.volume = ["🔈" "🔉" "🔊"];
-            click.right = "pavucontrol &amp;";
+            click.right = "pavucontrol &";
           }
-          </programlisting>
+          ```
           becomes:
-          <programlisting language="ini">
+          ```ini
           [module/volume]
           type=internal/pulseaudio
-          format-volume=&lt;ramp-volume&gt; &lt;label-volume&gt;
+          format-volume=<ramp-volume> <label-volume>
           label-muted=🔇
           label-muted-foreground=#666
           ramp-volume-0=🔈
           ramp-volume-1=🔉
           ramp-volume-2=🔊
-          click-right=pavucontrol &amp;
-          </programlisting>
+          click-right=pavucontrol &
+          ```
         '';
         default = { };
         example = literalExpression ''
@@ -190,7 +190,7 @@ in {
         description = ''
           This script will be used to start the polybars.
           Set all necessary environment variables here and start all bars.
-          It can be assumed that <command>polybar</command> executable is in the <envar>PATH</envar>.
+          It can be assumed that {command}`polybar` executable is in the {env}`PATH`.
 
           Note, this script must start all bars in the background and then terminate.
         '';
diff --git a/modules/services/pueue.nix b/modules/services/pueue.nix
index 3375f49d..1431c1cd 100644
--- a/modules/services/pueue.nix
+++ b/modules/services/pueue.nix
@@ -28,7 +28,7 @@ in {
       '';
       description = ''
         Configuration written to
-        <filename>$XDG_CONFIG_HOME/pueue/pueue.yml</filename>.
+        {file}`$XDG_CONFIG_HOME/pueue/pueue.yml`.
       '';
     };
   };
diff --git a/modules/services/pulseeffects.nix b/modules/services/pulseeffects.nix
index 0181e39b..434adf85 100644
--- a/modules/services/pulseeffects.nix
+++ b/modules/services/pulseeffects.nix
@@ -15,9 +15,9 @@ in {
     enable = mkEnableOption ''
       Pulseeffects daemon
       Note, it is necessary to add
-      <programlisting language="nix">
+      ```nix
       programs.dconf.enable = true;
-      </programlisting>
+      ```
       to your system configuration for the daemon to work correctly'';
 
     package = mkOption {
diff --git a/modules/services/random-background.nix b/modules/services/random-background.nix
index 16c869a9..7e887f32 100644
--- a/modules/services/random-background.nix
+++ b/modules/services/random-background.nix
@@ -18,11 +18,11 @@ in {
       enable = mkEnableOption "" // {
         description = ''
           Whether to enable random desktop background.
-          </para><para>
+
           Note, if you are using NixOS and have set up a custom
           desktop manager session for Home Manager, then the session
-          configuration must have the <option>bgSupport</option>
-          option set to <literal>true</literal> or the background
+          configuration must have the `bgSupport`
+          option set to `true` or the background
           image set by this module may be overwritten.
         '';
       };
diff --git a/modules/services/recoll.nix b/modules/services/recoll.nix
index 794a5de8..e4159d28 100644
--- a/modules/services/recoll.nix
+++ b/modules/services/recoll.nix
@@ -85,7 +85,7 @@ in {
       default = pkgs.recoll;
       defaultText = literalExpression "pkgs.recoll";
       description = ''
-        Package providing the <literal>recoll</literal> binary.
+        Package providing the `recoll` binary.
       '';
       example = literalExpression "(pkgs.recoll.override { withGui = false; })";
     };
@@ -97,10 +97,7 @@ in {
       description = ''
         When or how often the periodic update should run. Must be the format
         described from
-        <citerefentry>
-          <refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>7</manvolnum>
-        </citerefentry>.
+        {manpage}`systemd.time(7)`.
       '';
     };
 
@@ -109,13 +106,10 @@ in {
       default = { };
       description = ''
         The configuration to be written at
-        <filename>''${config.services.recoll.configDir}/recoll.conf</filename>.
+        {file}`''${config.services.recoll.configDir}/recoll.conf`.
 
         See
-        <citerefentry>
-          <refentrytitle>recoll</refentrytitle>
-          <manvolnum>5</manvolnum>
-        </citerefentry> for more details about the configuration.
+        {manpage}`recoll(5)` for more details about the configuration.
       '';
       example = literalExpression ''
         {
@@ -141,7 +135,7 @@ in {
       example = literalExpression "\${config.xdg.configHome}/recoll";
       description = ''
         The directory to contain Recoll configuration files. This will be set
-        as <literal>RECOLL_CONFDIR</literal>.
+        as `RECOLL_CONFDIR`.
       '';
     };
   };
diff --git a/modules/services/redshift-gammastep/lib/options.nix b/modules/services/redshift-gammastep/lib/options.nix
index 7b02150e..81347e64 100644
--- a/modules/services/redshift-gammastep/lib/options.nix
+++ b/modules/services/redshift-gammastep/lib/options.nix
@@ -55,8 +55,8 @@ in {
       type = with types; nullOr (either str float);
       default = null;
       description = ''
-        Your current latitude, between <literal>-90.0</literal> and
-        <literal>90.0</literal>. Must be provided along with
+        Your current latitude, between `-90.0` and
+        `90.0`. Must be provided along with
         longitude.
       '';
     };
@@ -65,8 +65,8 @@ in {
       type = with types; nullOr (either str float);
       default = null;
       description = ''
-        Your current longitude, between <literal>-180.0</literal> and
-        <literal>180.0</literal>. Must be provided along with
+        Your current longitude, between `-180.0` and
+        `180.0`. Must be provided along with
         latitude.
       '';
     };
@@ -76,8 +76,8 @@ in {
       default = "manual";
       description = ''
         The location provider to use for determining your location. If set to
-        <literal>manual</literal> you must also provide latitude/longitude.
-        If set to <literal>geoclue2</literal>, you must also enable the global
+        `manual` you must also provide latitude/longitude.
+        If set to `geoclue2`, you must also enable the global
         geoclue2 service.
       '';
     };
@@ -88,7 +88,7 @@ in {
         default = 5500;
         description = ''
           Colour temperature to use during the day, between
-          <literal>1000</literal> and <literal>25000</literal> K.
+          `1000` and `25000` K.
         '';
       };
       night = mkOption {
@@ -96,7 +96,7 @@ in {
         default = 3700;
         description = ''
           Colour temperature to use at night, between
-          <literal>1000</literal> and <literal>25000</literal> K.
+          `1000` and `25000` K.
         '';
       };
     };
@@ -137,10 +137,7 @@ in {
       description = ''
         The configuration to pass to ${programName}.
         Available options for ${programName} described in
-        <citerefentry>
-          <refentrytitle>${moduleName}</refentrytitle>
-          <manvolnum>1</manvolnum>
-        </citerefentry>.
+        {manpage}`${moduleName}(1)`.
       '';
     };
   };
diff --git a/modules/services/screen-locker.nix b/modules/services/screen-locker.nix
index 4fa98008..085573f8 100644
--- a/modules/services/screen-locker.nix
+++ b/modules/services/screen-locker.nix
@@ -37,9 +37,9 @@ in {
       description = ''
         Inactive time interval in minutes after which session will be locked.
         The minimum is 1 minute, and the maximum is 1 hour.
-        If <option>xautolock.enable</option> is true, it will use this setting.
-        See <link xlink:href="https://linux.die.net/man/1/xautolock"/>.
-        Otherwise, this will be used with <command>xset</command> to configure
+        If {option}`xautolock.enable` is true, it will use this setting.
+        See <https://linux.die.net/man/1/xautolock>.
+        Otherwise, this will be used with {command}`xset` to configure
         the X server's screensaver timeout.
       '';
     };
@@ -55,7 +55,7 @@ in {
         type = types.package;
         default = pkgs.xautolock;
         description = ''
-          Package providing the <command>xautolock</command> binary.
+          Package providing the {command}`xautolock` binary.
         '';
       };
 
@@ -64,7 +64,7 @@ in {
         default = true;
         description = ''
           Whether to reset xautolock timers when awaking from sleep.
-          No effect if <option>xautolock.enable</option> is false.
+          No effect if {option}`xautolock.enable` is false.
         '';
       };
 
@@ -72,8 +72,8 @@ in {
         type = types.listOf types.str;
         default = [ ];
         description = ''
-          Extra command-line arguments to pass to <command>xautolock</command>.
-          No effect if <option>xautolock.enable</option> is false.
+          Extra command-line arguments to pass to {command}`xautolock`.
+          No effect if {option}`xautolock.enable` is false.
         '';
       };
     };
@@ -83,7 +83,7 @@ in {
         type = types.package;
         default = pkgs.xss-lock;
         description = ''
-          Package providing the <command>xss-lock</command> binary.
+          Package providing the {command}`xss-lock` binary.
         '';
       };
 
@@ -91,7 +91,7 @@ in {
         type = types.listOf types.str;
         default = [ ];
         description = ''
-          Extra command-line arguments to pass to <command>xss-lock</command>.
+          Extra command-line arguments to pass to {command}`xss-lock`.
         '';
       };
 
@@ -100,7 +100,7 @@ in {
         default = 600;
         description = ''
           The X server's screensaver cycle value expressed as seconds.
-          This will be used with <command>xset</command> to configure
+          This will be used with {command}`xset` to configure
           the cycle along with timeout.
         '';
       };
diff --git a/modules/services/sctd.nix b/modules/services/sctd.nix
index 54cf53e4..44c77026 100644
--- a/modules/services/sctd.nix
+++ b/modules/services/sctd.nix
@@ -15,10 +15,7 @@ with lib;
         description = ''
           The base color temperature used by sctd, which should be between 2500 and 9000.
           See
-          <citerefentry>
-            <refentrytitle>sctd</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>
+          {manpage}`sctd(1)`
           for more details.
         '';
       };
diff --git a/modules/services/spotifyd.nix b/modules/services/spotifyd.nix
index b06749a3..dfe611fd 100644
--- a/modules/services/spotifyd.nix
+++ b/modules/services/spotifyd.nix
@@ -21,7 +21,7 @@ in {
       example =
         literalExpression "(pkgs.spotifyd.override { withKeyring = true; })";
       description = ''
-        The <literal>spotifyd</literal> package to use.
+        The `spotifyd` package to use.
         Can be used to specify extensions.
       '';
     };
diff --git a/modules/services/sxhkd.nix b/modules/services/sxhkd.nix
index d308c95b..e955d00b 100644
--- a/modules/services/sxhkd.nix
+++ b/modules/services/sxhkd.nix
@@ -25,15 +25,13 @@ in {
       type = types.package;
       default = pkgs.sxhkd;
       defaultText = "pkgs.sxhkd";
-      description =
-        "Package containing the <command>sxhkd</command> executable.";
+      description = "Package containing the {command}`sxhkd` executable.";
     };
 
     extraOptions = mkOption {
       type = types.listOf types.str;
       default = [ ];
-      description =
-        "Command line arguments to invoke <command>sxhkd</command> with.";
+      description = "Command line arguments to invoke {command}`sxhkd` with.";
       example = literalExpression ''[ "-m 1" ]'';
     };
 
diff --git a/modules/services/syncthing.nix b/modules/services/syncthing.nix
index c847985f..b6cebfa5 100644
--- a/modules/services/syncthing.nix
+++ b/modules/services/syncthing.nix
@@ -27,7 +27,7 @@ in {
         default = [ ];
         example = [ "--gui-apikey=apiKey" ];
         description = ''
-          Extra command-line arguments to pass to <command>syncthing</command>.
+          Extra command-line arguments to pass to {command}`syncthing`.
         '';
       };
 
diff --git a/modules/services/taskwarrior-sync.nix b/modules/services/taskwarrior-sync.nix
index ddce6d6f..9c01f414 100644
--- a/modules/services/taskwarrior-sync.nix
+++ b/modules/services/taskwarrior-sync.nix
@@ -16,13 +16,10 @@ in {
       type = types.str;
       default = "*:0/5";
       description = ''
-        How often to run <literal>taskwarrior sync</literal>. This
+        How often to run `taskwarrior sync`. This
         value is passed to the systemd timer configuration as the
-        <literal>OnCalendar</literal> option. See
-        <citerefentry>
-          <refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>7</manvolnum>
-        </citerefentry>
+        `OnCalendar` option. See
+        {manpage}`systemd.time(7)`
         for more information about the format.
       '';
     };
diff --git a/modules/services/trayer.nix b/modules/services/trayer.nix
index 0621c55e..48cef7a8 100644
--- a/modules/services/trayer.nix
+++ b/modules/services/trayer.nix
@@ -6,52 +6,44 @@ let
 
   boolTrue = {
     type = types.bool;
-    values = "true|false";
-    default = "true";
+    default = true;
   };
 
   number0 = {
     type = types.int;
-    values = "number";
-    default = "0";
+    default = 0;
   };
 
   knownSettings = {
     edge = {
-      type = types.str;
-      values = "left|right|top|bottom|none";
+      type = types.enum [ "left" "right" "top" "bottom" "none" ];
       default = "bottom";
     };
 
     align = {
-      type = types.str;
-      values = "left|right|center";
+      type = types.enum [ "left" "right" "center" ];
       default = "center";
     };
 
     margin = number0;
     widthtype = {
-      type = types.str;
-      values = "request|pixel|percent";
+      type = types.enum [ "request" "pixel" "percent" ];
       default = "percent";
     };
 
     width = {
       type = types.int;
-      values = "number";
-      default = "100";
+      default = 100;
     };
 
     heighttype = {
-      type = types.str;
-      values = "request|pixel";
+      type = types.enum [ "request" "pixel" ];
       default = "pixel";
     };
 
     height = {
       type = types.int;
-      values = "number";
-      default = "26";
+      default = 26;
     };
 
     SetDockType = boolTrue;
@@ -60,27 +52,23 @@ let
 
     transparent = {
       type = types.bool;
-      values = "true|false";
-      default = "false";
+      default = false;
     };
 
     alpha = {
       type = types.int;
-      values = "number";
-      default = "127";
+      default = 127;
     };
 
     tint = {
       type = types.str;
-      values = "int";
       default = "0xFFFFFFFF";
     };
 
     distance = number0;
 
     distancefrom = {
-      type = types.str;
-      values = "left|right|top|bottom";
+      type = types.enum [ "left" "right" "top" "bottom" ];
       default = "top";
     };
 
@@ -89,9 +77,8 @@ let
     padding = number0;
 
     monitor = {
-      values = "number|primary";
-      type = types.str;
-      default = "0";
+      type = types.either types.ints.unsigned (types.enum [ "primary" ]);
+      default = 0;
     };
 
     iconspacing = number0;
@@ -119,26 +106,12 @@ in {
         type = with types; attrsOf (nullOr (either str (either bool int)));
         description = ''
           Trayer configuration as a set of attributes. Further details can be
-          found at <link xlink:href="https://github.com/sargon/trayer-srg"/>.
+          found in [trayer's README](https://github.com/sargon/trayer-srg/blob/master/README).
 
-          <informaltable frame="none"><tgroup cols="4">
-          <thead>
-          <row>
-          <entry>Property Name</entry>
-          <entry>Type</entry>
-          <entry>Values</entry>
-          <entry>Default</entry>
-          </row>
-          </thead><tbody>
           ${concatStringsSep "\n" (mapAttrsToList (n: v: ''
-            <row>
-              <entry><varname>${n}</varname></entry>
-              <entry>${v.type.description}</entry>
-              <entry>${v.values}</entry>
-              <entry>${v.default}</entry>
-            </row>
+            {var}`${n}`
+            : ${v.type.description} (default: `${builtins.toJSON v.default}`)
           '') knownSettings)}
-          </tbody></tgroup></informaltable>
         '';
         default = { };
         example = literalExpression ''
diff --git a/modules/services/twmn.nix b/modules/services/twmn.nix
index d4c12682..c29ff621 100644
--- a/modules/services/twmn.nix
+++ b/modules/services/twmn.nix
@@ -13,8 +13,8 @@ let
       example = 19;
       description = ''
         The qt easing-curve animation to use for the animation. See
-        <link xlink:href="https://doc.qt.io/qt-5/qeasingcurve.html#Type-enum">
-        QEasingCurve documentation</link>.
+        [
+        QEasingCurve documentation](https://doc.qt.io/qt-5/qeasingcurve.html#Type-enum).
       '';
     };
 
@@ -48,7 +48,7 @@ in {
         ''{ main.activation_command = "\${pkgs.hello}/bin/hello"; }'';
       description = ''
         Extra configuration options to add to the twmnd config file. See
-        <link xlink:href="https://github.com/sboli/twmn/blob/master/README.md"/>
+        <https://github.com/sboli/twmn/blob/master/README.md>
         for details.
       '';
     };
@@ -108,7 +108,7 @@ in {
         default = "#999999";
         example = "lightgray";
         description = ''
-          Notification's text color. RGB hex and keywords (e.g. <literal>lightgray</literal>)
+          Notification's text color. RGB hex and keywords (e.g. `lightgray`)
           are supported.
         '';
       };
@@ -119,7 +119,7 @@ in {
           default = null;
           example = literalExpression "pkgs.dejavu_fonts";
           description = ''
-            Notification text's font package. If <literal>null</literal> then
+            Notification text's font package. If `null` then
             the font is assumed to already be available in your profile.
           '';
         };
@@ -172,7 +172,7 @@ in {
         example = 80;
         description = ''
           Maximum length of the text before it is cut and suffixed with "...".
-          Never cuts if <literal>null</literal>.
+          Never cuts if `null`.
         '';
       };
     };
@@ -209,7 +209,7 @@ in {
 
         bounce = {
           enable = mkEnableOption
-            "notification bounce when displaying next notification directly.";
+            "notification bounce when displaying next notification directly";
 
           duration = mkOption {
             type = types.ints.unsigned;
@@ -226,7 +226,7 @@ in {
         example = "lightgray";
         description = ''
           Notification's background color. RGB hex and keywords (e.g.
-          <literal>lightgray</literal>) are supported.
+          `lightgray`) are supported.
         '';
       };
 
@@ -291,7 +291,7 @@ in {
         description = ''
           Position of the notification slide. The notification will slide
           in vertically from the border if placed in
-          <literal>top_center</literal> or <literal>bottom_center</literal>,
+          `top_center` or `bottom_center`,
           horizontally otherwise.
         '';
       };
diff --git a/modules/services/udiskie.nix b/modules/services/udiskie.nix
index 56229796..2572b359 100644
--- a/modules/services/udiskie.nix
+++ b/modules/services/udiskie.nix
@@ -25,12 +25,12 @@ in {
 
   options = {
     services.udiskie = {
-      enable = mkEnableOption "udiskie mount daemon" // {
+      enable = mkEnableOption "" // {
         description = ''
           Whether to enable the udiskie mount daemon.
-          </para><para>
+
           Note, if you use NixOS then you must add
-          <code>services.udisks2.enable = true</code>
+          `services.udisks2.enable = true`
           to your system configuration. Otherwise mounting will fail because
           the Udisk2 DBus service is not found.
         '';
@@ -50,9 +50,9 @@ in {
         '';
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/udiskie/config.yml</filename>.
-          </para><para>
-          See <link xlink:href="https://github.com/coldfix/udiskie/blob/master/doc/udiskie.8.txt#configuration" />
+          {file}`$XDG_CONFIG_HOME/udiskie/config.yml`.
+
+          See <https://github.com/coldfix/udiskie/blob/master/doc/udiskie.8.txt#configuration>
           for the full list of options.
         '';
       };
@@ -74,24 +74,17 @@ in {
         default = "auto";
         description = ''
           Whether to display tray icon.
-          </para><para>
+
           The options are
-          <variablelist>
-          <varlistentry>
-            <term><literal>always</literal></term>
-            <listitem><para>Always show tray icon.</para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>auto</literal></term>
-            <listitem><para>
-              Show tray icon only when there is a device available.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>never</literal></term>
-            <listitem><para>Never show tray icon.</para></listitem>
-          </varlistentry>
-          </variablelist>
+
+          `always`
+          : Always show tray icon.
+
+          `auto`
+          : Show tray icon only when there is a device available.
+
+          `never`
+          : Never show tray icon.
         '';
       };
     };
diff --git a/modules/services/unison.nix b/modules/services/unison.nix
index e32f7052..7f8a47a6 100644
--- a/modules/services/unison.nix
+++ b/modules/services/unison.nix
@@ -34,15 +34,12 @@ let
         };
         description = ''
           Additional command line options as a dictionary to pass to the
-          <literal>unison</literal> program.
-          </para><para>
+          `unison` program.
+
           Use a list of strings to declare the same option multiple times.
-          </para><para>
+
           See
-          <citerefentry>
-            <refentrytitle>unison</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>
+          {manpage}`unison(1)`
           for a list of available options.
         '';
       };
diff --git a/modules/services/vdirsyncer.nix b/modules/services/vdirsyncer.nix
index ab9230d0..4eb376f9 100644
--- a/modules/services/vdirsyncer.nix
+++ b/modules/services/vdirsyncer.nix
@@ -30,10 +30,7 @@ in {
       description = ''
         How often to run vdirsyncer.  This value is passed to the systemd
         timer configuration as the onCalendar option.  See
-        <citerefentry>
-          <refentrytitle>systemd.time</refentrytitle>
-          <manvolnum>7</manvolnum>
-        </citerefentry>
+        {manpage}`systemd.time(7)`
         for more information about the format.
       '';
     };
@@ -52,7 +49,7 @@ in {
       default = null;
       description = ''
         Optional configuration file to link to use instead of
-        the default file (<filename>$XDG_CONFIG_HOME/vdirsyncer/config</filename>).
+        the default file ({file}`$XDG_CONFIG_HOME/vdirsyncer/config`).
       '';
     };
   };
diff --git a/modules/services/volnoti.nix b/modules/services/volnoti.nix
index 016fe7ab..e90db2c2 100644
--- a/modules/services/volnoti.nix
+++ b/modules/services/volnoti.nix
@@ -18,7 +18,7 @@ in {
         default = pkgs.volnoti;
         defaultText = literalExpression "pkgs.volnoti";
         description = ''
-          Package containing the <command>volnoti</command> program.
+          Package containing the {command}`volnoti` program.
         '';
       };
     };
diff --git a/modules/services/window-managers/bspwm/options.nix b/modules/services/window-managers/bspwm/options.nix
index 848e991b..fab95f88 100644
--- a/modules/services/window-managers/bspwm/options.nix
+++ b/modules/services/window-managers/bspwm/options.nix
@@ -90,7 +90,7 @@ let
         type = types.nullOr types.bool;
         default = null;
         description = ''
-          Whether the node should ignore <command>node --close</command>
+          Whether the node should ignore {command}`node --close`
           messages.
         '';
         example = true;
@@ -147,8 +147,7 @@ let
       rectangle = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description =
-          "The node's geometry, in the format <literal>WxH+X+Y</literal>.";
+        description = "The node's geometry, in the format `WxH+X+Y`.";
         example = "800x600+32+32";
       };
     };
@@ -169,7 +168,7 @@ in {
     settings = mkOption {
       type = with types; attrsOf (either primitive (listOf primitive));
       default = { };
-      description = "General settings given to <literal>bspc config</literal>.";
+      description = "General settings given to `bspc config`.";
       example = {
         "border_width" = 2;
         "split_ratio" = 0.52;
@@ -206,12 +205,12 @@ in {
       type = types.bool;
       default = true;
       description = ''
-        If set to <literal>true</literal>, desktops configured in <option>monitors</option> will be reset
+        If set to `true`, desktops configured in {option}`monitors` will be reset
         every time the config is run.
 
-        If set to <literal>false</literal>, desktops will only be configured the first time the config is run.
+        If set to `false`, desktops will only be configured the first time the config is run.
         This is useful if you want to dynamically add desktops and you don't want them to be destroyed if you
-        re-run <literal>bspwmrc</literal>.
+        re-run `bspwmrc`.
       '';
     };
 
diff --git a/modules/services/window-managers/fluxbox.nix b/modules/services/window-managers/fluxbox.nix
index 6b05d295..99dfa50e 100644
--- a/modules/services/window-managers/fluxbox.nix
+++ b/modules/services/window-managers/fluxbox.nix
@@ -20,10 +20,8 @@ in {
         default = "";
         description = ''
           Init configuration for Fluxbox, written to
-          <filename>~/.fluxbox/init</filename>. Look at the
-          <citerefentry>
-          <refentrytitle>fluxbox</refentrytitle>
-          <manvolnum>1</manvolnum></citerefentry> manpage for details.
+          {file}`~/.fluxbox/init`. Look at the
+          {manpage}`fluxbox(1)` manpage for details.
         '';
       };
 
@@ -32,9 +30,8 @@ in {
         default = "";
         description = ''
           Apps configuration for Fluxbox, written to
-          <filename>~/.fluxbox/apps</filename>. Look at the
-          <citerefentry><refentrytitle>fluxbox</refentrytitle>
-          <manvolnum>1</manvolnum></citerefentry> manpage for details.
+          {file}`~/.fluxbox/apps`. Look at the
+          {manpage}`fluxbox(1)` manpage for details.
         '';
       };
 
@@ -43,9 +40,8 @@ in {
         default = "";
         description = ''
           Keyboard shortcuts configuration for Fluxbox, written to
-          <filename>~/.fluxbox/keys</filename>. Look at the
-          <citerefentry><refentrytitle>fluxbox-keys</refentrytitle>
-          <manvolnum>1</manvolnum></citerefentry> manpage for details.
+          {file}`~/.fluxbox/keys`. Look at the
+          {manpage}`fluxbox-keys(1)` manpage for details.
         '';
       };
 
@@ -54,9 +50,8 @@ in {
         default = "";
         description = ''
           Menu configuration for Fluxbox, written to
-          <filename>~/.fluxbox/menu</filename>. Look at the
-          <citerefentry><refentrytitle>fluxbox-menu</refentrytitle>
-          <manvolnum>1</manvolnum></citerefentry> manpage for details.
+          {file}`~/.fluxbox/menu`. Look at the
+          {manpage}`fluxbox-menu(1)` manpage for details.
         '';
       };
 
@@ -65,9 +60,8 @@ in {
         default = "";
         description = ''
           Slitlist configuration for Fluxbox, written to
-          <filename>~/.fluxbox/slitlist</filename>. Look at the
-          <citerefentry><refentrytitle>fluxbox</refentrytitle>
-          <manvolnum>1</manvolnum></citerefentry> manpage for details.
+          {file}`~/.fluxbox/slitlist`. Look at the
+          {manpage}`fluxbox(1)` manpage for details.
         '';
       };
 
@@ -76,9 +70,8 @@ in {
         default = "";
         description = ''
           Window menu configuration for Fluxbox, written to
-          <filename>~/.fluxbox/windowmenu</filename>. Look at the
-          <citerefentry><refentrytitle>fluxbox-menu</refentrytitle>
-          <manvolnum>1</manvolnum></citerefentry>
+          {file}`~/.fluxbox/windowmenu`. Look at the
+          {manpage}`fluxbox-menu(1)`
           manpage for details.
         '';
       };
@@ -88,10 +81,9 @@ in {
         default = [ ];
         example = [ "-log" "/tmp/fluxbox.log" ];
         description = ''
-          Extra command line arguments to pass to <command>fluxbox</command>.
+          Extra command line arguments to pass to {command}`fluxbox`.
           Look at the
-          <citerefentry><refentrytitle>fluxbox</refentrytitle>
-          <manvolnum>1</manvolnum></citerefentry> manpage for details.
+          {manpage}`fluxbox(1)` manpage for details.
         '';
       };
     };
diff --git a/modules/services/window-managers/herbstluftwm.nix b/modules/services/window-managers/herbstluftwm.nix
index 51fe22bd..a407da6c 100644
--- a/modules/services/window-managers/herbstluftwm.nix
+++ b/modules/services/window-managers/herbstluftwm.nix
@@ -42,8 +42,8 @@ in {
       default = pkgs.herbstluftwm;
       defaultText = lib.literalExpression "pkgs.herbstluftwm";
       description = ''
-        Package providing the <command>herbstluftwm</command> and
-        <command>herbstclient</command> commands.
+        Package providing the {command}`herbstluftwm` and
+        {command}`herbstclient` commands.
       '';
     };
 
@@ -114,7 +114,7 @@ in {
       '';
       description = ''
         Extra configuration lines to add verbatim to
-        <filename>$XDG_CONFIG_HOME/herbstluftwm/autostart</filename>.
+        {file}`$XDG_CONFIG_HOME/herbstluftwm/autostart`.
       '';
     };
   };
diff --git a/modules/services/window-managers/i3-sway/i3.nix b/modules/services/window-managers/i3-sway/i3.nix
index b4742c78..183463d3 100644
--- a/modules/services/window-managers/i3-sway/i3.nix
+++ b/modules/services/window-managers/i3-sway/i3.nix
@@ -93,9 +93,9 @@ let
         defaultText = "Default i3 keybindings.";
         description = ''
           An attribute set that assigns a key press to an action using a key symbol.
-          See <link xlink:href="https://i3wm.org/docs/userguide.html#keybindings"/>.
-          </para><para>
-          Consider to use <code>lib.mkOptionDefault</code> function to extend or override
+          See <https://i3wm.org/docs/userguide.html#keybindings>.
+
+          Consider to use `lib.mkOptionDefault` function to extend or override
           default keybindings instead of specifying all of them from scratch.
         '';
         example = literalExpression ''
diff --git a/modules/services/window-managers/i3-sway/lib/options.nix b/modules/services/window-managers/i3-sway/lib/options.nix
index d669f766..b9182439 100644
--- a/modules/services/window-managers/i3-sway/lib/options.nix
+++ b/modules/services/window-managers/i3-sway/lib/options.nix
@@ -59,7 +59,7 @@ let
         default = true;
         description = ''
           Whether to enable startup-notification support for the command.
-          See <option>--no-startup-id</option> option description in the i3 user guide.
+          See {option}`--no-startup-id` option description in the i3 user guide.
         '';
       };
 
@@ -68,8 +68,8 @@ let
         default = null;
         description = ''
           Launch application on a particular workspace. DEPRECATED:
-          Use <xref linkend="opt-xsession.windowManager.i3.config.assigns"/>
-          instead. See <link xlink:href="https://github.com/nix-community/home-manager/issues/265"/>.
+          Use [](#opt-xsession.windowManager.i3.config.assigns)
+          instead. See <https://github.com/nix-community/home-manager/issues/265>.
         '';
       };
     };
@@ -284,7 +284,7 @@ let
           See default values for the reference.
           Note that 'background', 'status', and 'separator' parameters take a single RGB value.
 
-          See <link xlink:href="https://i3wm.org/docs/userguide.html#_colors"/>.
+          See <https://i3wm.org/docs/userguide.html#_colors>.
         '';
       };
 
@@ -365,8 +365,8 @@ let
         type = criteriaModule;
         description = ''
           Criteria of the windows on which command should be executed.
-          </para><para>
-          A value of <literal>true</literal> is equivalent to using an empty
+
+          A value of `true` is equivalent to using an empty
           criteria (which is different from an empty string criteria).
         '';
         example = literalExpression ''
@@ -430,7 +430,7 @@ in {
           default = [ ];
           description = ''
             List of commands that should be executed on specific windows.
-            See <option>for_window</option> ${moduleName}wm option documentation.
+            See {option}`for_window` ${moduleName}wm option documentation.
           '';
           example = [{
             command = "border pixel 1";
@@ -502,7 +502,7 @@ in {
           description = ''
             This option modifies focus behavior on new window activation.
 
-            See <link xlink:href="https://i3wm.org/docs/userguide.html#focus_on_window_activation"/>
+            See <https://i3wm.org/docs/userguide.html#focus_on_window_activation>
           '';
           example = "none";
         };
@@ -529,7 +529,7 @@ in {
           description = ''
             Whether the window focus commands automatically wrap around the edge of containers.
 
-            See <link xlink:href="https://i3wm.org/docs/userguide.html#_focus_wrapping"/>
+            See <https://i3wm.org/docs/userguide.html#_focus_wrapping>
           '';
         };
 
@@ -539,7 +539,7 @@ in {
           description = ''
             Whether to force focus wrapping in tabbed or stacked containers.
 
-            This option is deprecated, use <option>focus.wrapping</option> instead.
+            This option is deprecated, use {option}`focus.wrapping` instead.
           '';
         };
 
@@ -609,7 +609,7 @@ in {
     default = { };
     description = ''
       An attribute set that assigns keypress to an action using key code.
-      See <link xlink:href="https://i3wm.org/docs/userguide.html#keybindings"/>.
+      See <https://i3wm.org/docs/userguide.html#keybindings>.
     '';
     example = { "214" = "exec /bin/script.sh"; };
   };
@@ -700,7 +700,7 @@ in {
       and RGB color hex-codes as values. See default values for the reference.
       Note that '${moduleName}.config.colors.background' parameter takes a single RGB value.
 
-      See <link xlink:href="https://i3wm.org/docs/userguide.html#_changing_colors"/>.
+      See <https://i3wm.org/docs/userguide.html#_changing_colors>.
     '';
   };
 
@@ -762,7 +762,7 @@ in {
     description = ''
       Commands that should be executed at startup.
 
-      See <link xlink:href="https://i3wm.org/docs/userguide.html#_automatically_starting_applications_on_i3_startup"/>.
+      See <https://i3wm.org/docs/userguide.html#_automatically_starting_applications_on_i3_startup>.
     '';
     example = if isI3 then
       literalExpression ''
@@ -916,9 +916,9 @@ in {
               apply = lists.toList;
               example = "eDP";
               description = ''
-                Name(s) of the output(s) from <command>
+                Name(s) of the output(s) from {command}`
                   ${if isSway then "swaymsg" else "i3-msg"} -t get_outputs
-                </command>.
+                `.
               '';
             };
           };
diff --git a/modules/services/window-managers/i3-sway/sway.nix b/modules/services/window-managers/i3-sway/sway.nix
index 5568d6ab..9031a0a7 100644
--- a/modules/services/window-managers/i3-sway/sway.nix
+++ b/modules/services/window-managers/i3-sway/sway.nix
@@ -123,9 +123,9 @@ let
         defaultText = "Default sway keybindings.";
         description = ''
           An attribute set that assigns a key press to an action using a key symbol.
-          See <link xlink:href="https://i3wm.org/docs/userguide.html#keybindings"/>.
-          </para><para>
-          Consider to use <code>lib.mkOptionDefault</code> function to extend or override
+          See <https://i3wm.org/docs/userguide.html#keybindings>.
+
+          Consider to use `lib.mkOptionDefault` function to extend or override
           default keybindings instead of specifying all of them from scratch.
         '';
         example = literalExpression ''
@@ -144,7 +144,7 @@ let
         default = false;
         example = true;
         description = ''
-          Whether to make use of <option>--to-code</option> in keybindings.
+          Whether to make use of {option}`--to-code` in keybindings.
         '';
       };
 
@@ -154,10 +154,7 @@ let
         example = { "*" = { xkb_variant = "dvorak"; }; };
         description = ''
           An attribute set that defines input modules. See
-          <citerefentry>
-            <refentrytitle>sway-input</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry>
+          {manpage}`sway-input(5)`
           for options.
         '';
       };
@@ -168,10 +165,7 @@ let
         example = { "HDMI-A-2" = { bg = "~/path/to/background.png fill"; }; };
         description = ''
           An attribute set that defines output modules. See
-          <citerefentry>
-            <refentrytitle>sway-output</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry>
+          {manpage}`sway-output(5)`
           for options.
         '';
       };
@@ -182,10 +176,7 @@ let
         example = { "*" = { hide_cursor = "when-typing enable"; }; };
         description = ''
           An attribute set that defines seat modules. See
-          <citerefentry>
-            <refentrytitle>sway-input</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry>
+          {manpage}`sway-input(5)`
           for options.
         '';
       };
@@ -352,7 +343,7 @@ in {
       description = ''
         Sway package to use. Will override the options
         'wrapperFeatures', 'extraSessionCommands', and 'extraOptions'.
-        Set to <code>null</code> to not add any Sway package to your
+        Set to `null` to not add any Sway package to your
         path. This should be done if you want to use the NixOS Sway
         module to install Sway.
       '';
@@ -364,26 +355,21 @@ in {
         default = pkgs.stdenv.isLinux;
         example = false;
         description = ''
-          Whether to enable <filename>sway-session.target</filename> on
+          Whether to enable {file}`sway-session.target` on
           sway startup. This links to
-          <filename>graphical-session.target</filename>.
+          {file}`graphical-session.target`.
           Some important environment variables will be imported to systemd
           and dbus user environment before reaching the target, including
-          <itemizedlist>
-            <listitem><para><literal>DISPLAY</literal></para></listitem>
-            <listitem><para><literal>WAYLAND_DISPLAY</literal></para></listitem>
-            <listitem><para><literal>SWAYSOCK</literal></para></listitem>
-            <listitem><para><literal>XDG_CURRENT_DESKTOP</literal></para></listitem>
-          </itemizedlist>
+          * {env}`DISPLAY`
+          * {env}`WAYLAND_DISPLAY`
+          * {env}`SWAYSOCK`
+          * {env}`XDG_CURRENT_DESKTOP`
         '';
       };
 
       xdgAutostart = mkEnableOption ''
         autostart of applications using
-        <citerefentry>
-          <refentrytitle>systemd-xdg-autostart-generator</refentrytitle>
-          <manvolnum>8</manvolnum>
-        </citerefentry>
+        {manpage}`systemd-xdg-autostart-generator(8)`
       '';
     };
 
diff --git a/modules/services/window-managers/i3-sway/swaynag.nix b/modules/services/window-managers/i3-sway/swaynag.nix
index 8b77b55f..fcdedd3d 100644
--- a/modules/services/window-managers/i3-sway/swaynag.nix
+++ b/modules/services/window-managers/i3-sway/swaynag.nix
@@ -26,15 +26,12 @@ in {
         default = { };
         description = ''
           Configuration written to
-          <filename>$XDG_CONFIG_HOME/swaynag/config</filename>.
-          </para><para>
+          {file}`$XDG_CONFIG_HOME/swaynag/config`.
+
           See
-          <citerefentry>
-            <refentrytitle>swaynag</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry>
+          {manpage}`swaynag(5)`
           for a list of available options and an example configuration.
-          Note, configurations declared under <literal>&lt;config&gt;</literal>
+          Note, configurations declared under `<config>`
           will override the default type values of swaynag.
         '';
         example = literalExpression ''
diff --git a/modules/services/window-managers/spectrwm.nix b/modules/services/window-managers/spectrwm.nix
index f2d7af4c..5561759b 100644
--- a/modules/services/window-managers/spectrwm.nix
+++ b/modules/services/window-managers/spectrwm.nix
@@ -37,7 +37,7 @@ in {
         default = pkgs.spectrwm;
         defaultText = literalExpression "pkgs.spectrwm";
         description = ''
-          Package providing the <command>spectrwm</command> command.
+          Package providing the {command}`spectrwm` command.
         '';
       };
 
diff --git a/modules/services/window-managers/xmonad.nix b/modules/services/window-managers/xmonad.nix
index 8066bae2..59b403d3 100644
--- a/modules/services/window-managers/xmonad.nix
+++ b/modules/services/window-managers/xmonad.nix
@@ -25,10 +25,10 @@ in {
         defaultText = literalExpression "pkgs.haskellPackages";
         example = literalExpression "pkgs.haskell.packages.ghc784";
         description = ''
-          The <varname>haskellPackages</varname> used to build xmonad
+          The {var}`haskellPackages` used to build xmonad
           and other packages. This can be used to change the GHC
           version used to build xmonad and the packages listed in
-          <varname>extraPackages</varname>.
+          {var}`extraPackages`.
         '';
       };
 
@@ -44,7 +44,7 @@ in {
         description = ''
           Extra packages available to GHC when rebuilding xmonad. The
           value must be a function which receives the attribute set
-          defined in <varname>haskellPackages</varname> as the sole
+          defined in {var}`haskellPackages` as the sole
           argument.
         '';
       };
@@ -70,14 +70,13 @@ in {
         '';
         description = ''
           The configuration file to be used for xmonad. This must be
-          an absolute path or <literal>null</literal> in which case
-          <filename>~/.xmonad/xmonad.hs</filename> will not be managed
+          an absolute path or `null` in which case
+          {file}`~/.xmonad/xmonad.hs` will not be managed
           by Home Manager.
-          </para>
-          <para>
-          If this option is set to a non-<literal>null</literal> value,
+
+          If this option is set to a non-`null` value,
           recompilation of xmonad outside of Home Manager (e.g. via
-          <command>xmonad --recompile</command>) will fail.
+          {command}`xmonad --recompile`) will fail.
         '';
       };
 
@@ -94,7 +93,7 @@ in {
         '';
         description = ''
           Additional files that will be saved in
-          <filename>~/.xmonad/lib/</filename> and included in the configuration
+          {file}`~/.xmonad/lib/` and included in the configuration
           build. The keys are the file names while the values are paths to the
           contents of the files.
         '';
diff --git a/modules/services/wlsunset.nix b/modules/services/wlsunset.nix
index 6cd45ed5..3bc3f2f7 100644
--- a/modules/services/wlsunset.nix
+++ b/modules/services/wlsunset.nix
@@ -22,16 +22,16 @@ in {
     latitude = mkOption {
       type = types.str;
       description = ''
-        Your current latitude, between <literal>-90.0</literal> and
-        <literal>90.0</literal>.
+        Your current latitude, between `-90.0` and
+        `90.0`.
       '';
     };
 
     longitude = mkOption {
       type = types.str;
       description = ''
-        Your current longitude, between <literal>-180.0</literal> and
-        <literal>180.0</literal>.
+        Your current longitude, between `-180.0` and
+        `180.0`.
       '';
     };
 
@@ -41,7 +41,7 @@ in {
         default = 6500;
         description = ''
           Colour temperature to use during the day, in Kelvin (K).
-          This value must be greater than <literal>temperature.night</literal>.
+          This value must be greater than `temperature.night`.
         '';
       };
 
@@ -50,7 +50,7 @@ in {
         default = 4000;
         description = ''
           Colour temperature to use during the night, in Kelvin (K).
-          This value must be smaller than <literal>temperature.day</literal>.
+          This value must be smaller than `temperature.day`.
         '';
       };
     };
diff --git a/modules/services/xcape.nix b/modules/services/xcape.nix
index 72b8303b..130db65b 100644
--- a/modules/services/xcape.nix
+++ b/modules/services/xcape.nix
@@ -31,19 +31,17 @@ in {
           Control_L = "Control_L|O";
         };
         description = ''
-          The value has the grammar <literal>Key[|OtherKey]</literal>.
-          </para>
-          <para>
+          The value has the grammar `Key[|OtherKey]`.
+
           The list of key names is found in the header file
-          <filename>X11/keysymdef.h</filename> (remove the
-          <literal>XK_</literal> prefix). Note that due to limitations
+          {file}`X11/keysymdef.h` (remove the
+          `XK_` prefix). Note that due to limitations
           of X11 shifted keys must be specified as a shift key
           followed by the key to be pressed rather than the actual
           name of the character. For example to generate "{" the
-          expression <literal>Shift_L|bracketleft</literal> could be
+          expression `Shift_L|bracketleft` could be
           used (assuming that you have a key with "{" above "[").
-          </para>
-          <para>
+
           You can also specify keys in decimal (prefix #), octal (#0),
           or hexadecimal (#0x). They will be interpreted as keycodes
           unless no corresponding key name is found.
diff --git a/modules/services/xembed-sni-proxy.nix b/modules/services/xembed-sni-proxy.nix
index 54ea0599..e0b1f846 100644
--- a/modules/services/xembed-sni-proxy.nix
+++ b/modules/services/xembed-sni-proxy.nix
@@ -18,7 +18,7 @@ in {
         default = pkgs.plasma-workspace;
         defaultText = literalExpression "pkgs.plasma-workspace";
         description = ''
-          Package containing the <command>xembedsniproxy</command>
+          Package containing the {command}`xembedsniproxy`
           program.
         '';
       };
diff --git a/modules/services/xidlehook.nix b/modules/services/xidlehook.nix
index d769ccaf..2ce64e69 100644
--- a/modules/services/xidlehook.nix
+++ b/modules/services/xidlehook.nix
@@ -52,7 +52,7 @@ in {
       '';
       description = ''
         Extra environment variables to be exported in the script.
-        These options are passed unescaped as <code>export name=value</code>.
+        These options are passed unescaped as `export name=value`.
       '';
     };
 
@@ -127,10 +127,10 @@ in {
       '';
       description = ''
         A set of commands to be executed after a specific idle timeout.
-        The commands specified in <literal>command</literal> and <literal>canceller</literal>
+        The commands specified in `command` and `canceller`
         are passed escaped to the script.
         To use or re-use environment variables that are script-dependent, specify them
-        in the <literal>environment</literal> section.
+        in the `environment` section.
       '';
     };
   };
diff --git a/modules/services/xsettingsd.nix b/modules/services/xsettingsd.nix
index 58eb2665..c949676f 100644
--- a/modules/services/xsettingsd.nix
+++ b/modules/services/xsettingsd.nix
@@ -32,7 +32,7 @@ in {
         default = pkgs.xsettingsd;
         defaultText = literalExpression "pkgs.xsettingsd";
         description = ''
-          Package containing the <command>xsettingsd</command> program.
+          Package containing the {command}`xsettingsd` program.
         '';
       };
 
@@ -49,7 +49,7 @@ in {
         '';
         description = ''
           Xsettingsd options for configuration file. See
-          <link xlink:href="https://github.com/derat/xsettingsd/wiki/Settings"/>
+          <https://github.com/derat/xsettingsd/wiki/Settings>
           for documentation on these values.
         '';
       };
diff --git a/modules/systemd.nix b/modules/systemd.nix
index 68929ed1..22490218 100644
--- a/modules/systemd.nix
+++ b/modules/systemd.nix
@@ -59,13 +59,10 @@ let
   unitDescription = type: ''
     Definition of systemd per-user ${type} units. Attributes are
     merged recursively.
-    </para><para>
+
     Note that the attributes follow the capitalization and naming used
     by systemd. More details can be found in
-    <citerefentry>
-      <refentrytitle>systemd.${type}</refentrytitle>
-      <manvolnum>5</manvolnum>
-    </citerefentry>.
+    {manpage}`systemd.${type}(5)`.
   '';
 
   unitExample = type:
@@ -100,7 +97,7 @@ in {
         defaultText = literalExpression ''"''${pkgs.systemd}/bin/systemctl"'';
         type = types.str;
         description = ''
-          Absolute path to the <command>systemctl</command> tool. This
+          Absolute path to the {command}`systemctl` tool. This
           option may need to be set if running Home Manager on a
           non-NixOS distribution.
         '';
@@ -109,56 +106,56 @@ in {
       services = mkOption {
         default = { };
         type = unitType "service";
-        description = unitDescription "service";
+        description = (unitDescription "service");
         example = unitExample "Service";
       };
 
       slices = mkOption {
         default = { };
         type = unitType "slice";
-        description = unitDescription "slice";
+        description = (unitDescription "slice");
         example = unitExample "Slice";
       };
 
       sockets = mkOption {
         default = { };
         type = unitType "socket";
-        description = unitDescription "socket";
+        description = (unitDescription "socket");
         example = unitExample "Socket";
       };
 
       targets = mkOption {
         default = { };
         type = unitType "target";
-        description = unitDescription "target";
+        description = (unitDescription "target");
         example = unitExample "Target";
       };
 
       timers = mkOption {
         default = { };
         type = unitType "timer";
-        description = unitDescription "timer";
+        description = (unitDescription "timer");
         example = unitExample "Timer";
       };
 
       paths = mkOption {
         default = { };
         type = unitType "path";
-        description = unitDescription "path";
+        description = (unitDescription "path");
         example = unitExample "Path";
       };
 
       mounts = mkOption {
         default = { };
         type = unitType "mount";
-        description = unitDescription "mount";
+        description = (unitDescription "mount");
         example = unitExample "Mount";
       };
 
       automounts = mkOption {
         default = { };
         type = unitType "automount";
-        description = unitDescription "automount";
+        description = (unitDescription "automount");
         example = unitExample "Automount";
       };
 
@@ -171,36 +168,25 @@ in {
           Whether new or changed services that are wanted by active targets
           should be started. Additionally, stop obsolete services from the
           previous generation.
-          </para><para>
+
           The alternatives are
-          <variablelist>
-          <varlistentry>
-            <term><literal>suggest</literal> (or <literal>false</literal>)</term>
-            <listitem><para>
-              Use a very simple shell script to print suggested
-              <command>systemctl</command> commands to run. You will have to
-              manually run those commands after the switch.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>legacy</literal> (or <literal>true</literal>)</term>
-            <listitem><para>
-              Use a Ruby script to, in a more robust fashion, determine the
-              necessary changes and automatically run the
-              <command>systemctl</command> commands.
-            </para></listitem>
-          </varlistentry>
-          <varlistentry>
-            <term><literal>sd-switch</literal></term>
-            <listitem><para>
-              Use sd-switch, a third party application, to perform the service
-              updates. This tool offers more features while having a small
-              closure size. Note, it requires a fully functional user D-Bus
-              session. Once tested and deemed sufficiently robust, this will
-              become the default.
-            </para></listitem>
-          </varlistentry>
-          </variablelist>
+
+          `suggest` (or `false`)
+          : Use a very simple shell script to print suggested
+            {command}`systemctl` commands to run. You will have to
+            manually run those commands after the switch.
+
+          `legacy` (or `true`)
+          : Use a Ruby script to, in a more robust fashion, determine the
+            necessary changes and automatically run the
+            {command}`systemctl` commands.
+
+          `sd-switch`
+          : Use sd-switch, a third party application, to perform the service
+            updates. This tool offers more features while having a small
+            closure size. Note, it requires a fully functional user D-Bus
+            session. Once tested and deemed sufficiently robust, this will
+            become the default.
         '';
       };
 
@@ -220,10 +206,7 @@ in {
         description = ''
           Environment variables that will be set for the user session.
           The variable values must be as described in
-          <citerefentry>
-            <refentrytitle>environment.d</refentrytitle>
-            <manvolnum>5</manvolnum>
-          </citerefentry>.
+          {manpage}`environment.d(5)`.
         '';
       };
     };
diff --git a/modules/targets/darwin/keybindings.nix b/modules/targets/darwin/keybindings.nix
index 824daa57..c4348333 100644
--- a/modules/targets/darwin/keybindings.nix
+++ b/modules/targets/darwin/keybindings.nix
@@ -18,15 +18,13 @@ in {
     description = ''
       This will configure the default keybindings for text fields in macOS
       applications. See
-      <link xlink:href="https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/TextDefaultsBindings.html">Apple's documentation</link>
+      [Apple's documentation](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/EventOverview/TextDefaultsBindings/TextDefaultsBindings.html)
       for more details.
 
-      <warning>
-        <para>
-          Existing keybinding configuration will be wiped when using this
-          option.
-        </para>
-      </warning>
+      ::: {.warning}
+      Existing keybinding configuration will be wiped when using this
+      option.
+      :::
     '';
   };
 
diff --git a/modules/targets/darwin/user-defaults/default.nix b/modules/targets/darwin/user-defaults/default.nix
index c44d4f9c..8d4e17a2 100644
--- a/modules/targets/darwin/user-defaults/default.nix
+++ b/modules/targets/darwin/user-defaults/default.nix
@@ -42,20 +42,17 @@ in {
       };
     };
     description = ''
-      Set macOS user defaults. Values set to <literal>null</literal> are
+      Set macOS user defaults. Values set to `null` are
       ignored.
 
-      <warning>
-        <para>
-          Some settings might require a re-login to take effect.
-        </para>
-      </warning>
-      <warning>
-        <para>
-          Some settings are only read from
-          <option>targets.darwin.currentHostDefaults</option>.
-        </para>
-      </warning>
+      ::: {.warning}
+      Some settings might require a re-login to take effect.
+      :::
+
+      ::: {.warning}
+      Some settings are only read from
+      {option}`targets.darwin.currentHostDefaults`.
+      :::
     '';
   };
 
@@ -66,17 +63,15 @@ in {
       "com.apple.controlcenter" = { BatteryShowPercentage = true; };
     };
     description = ''
-      Set macOS user defaults. Unlike <option>targets.darwin.defaults</option>,
+      Set macOS user defaults. Unlike {option}`targets.darwin.defaults`,
       the preferences will only be applied to the currently logged-in host. This
       distinction is important for networked accounts.
 
-      Values set to <literal>null</literal> are ignored.
+      Values set to `null` are ignored.
 
-      <warning>
-        <para>
-          Some settings might require a re-login to take effect.
-        </para>
-      </warning>
+      ::: {.warning}
+      Some settings might require a re-login to take effect.
+      :::
     '';
   };
 
diff --git a/modules/targets/darwin/user-defaults/opts-allhosts.nix b/modules/targets/darwin/user-defaults/opts-allhosts.nix
index 832318a9..820f05b3 100644
--- a/modules/targets/darwin/user-defaults/opts-allhosts.nix
+++ b/modules/targets/darwin/user-defaults/opts-allhosts.nix
@@ -70,16 +70,16 @@ in {
         type = types.bool;
         example = false;
         description = ''
-          Disable use of <filename>.DS_Store</filename> files on network shares.
-          See <link xlink:href="https://support.apple.com/en-us/HT208209">the
-          official article</link> for more info.
+          Disable use of {file}`.DS_Store` files on network shares.
+          See [the
+          official article](https://support.apple.com/en-us/HT208209) for more info.
         '';
       };
       DSDontWriteUSBStores = mkNullableOption {
         type = types.bool;
         example = false;
         description = ''
-          Disable use of <filename>.DS_Store</filename> files on thumb drives.
+          Disable use of {file}`.DS_Store` files on thumb drives.
         '';
       };
     };
@@ -100,7 +100,7 @@ in {
       example = "NO";
       description = ''
         This option no longer works on macOS 11 and later. Instead, use
-        <option>targets.darwin.currentHostDefaults.\"com.apple.controlcenter\".BatteryShowPercentage</option>.
+        {option}`targets.darwin.currentHostDefaults.\"com.apple.controlcenter\".BatteryShowPercentage`.
 
         Whether to show battery percentage in the menu bar.
       '';
@@ -122,12 +122,10 @@ in {
         description = ''
           Configures the web inspector.
 
-          <warning>
-            <para>
-              Instead of setting this option directly, set
-              <option>IncludeDevelopMenu</option> instead.
-            </para>
-          </warning>
+          ::: {.warning}
+          Instead of setting this option directly, set
+          {option}`IncludeDevelopMenu` instead.
+          :::
         '';
       };
       "WebKitPreferences.developerExtrasEnabled" = mkNullableOption {
@@ -135,12 +133,10 @@ in {
         description = ''
           Configures the web inspector.
 
-          <warning>
-            <para>
-              Instead of setting this option directly, set
-              <option>IncludeDevelopMenu</option> instead.
-            </para>
-          </warning>
+          ::: {.warning}
+          Instead of setting this option directly, set
+          {option}`IncludeDevelopMenu` instead.
+          :::
         '';
       };
     };
@@ -151,12 +147,10 @@ in {
         description = ''
           Show the "Develop" menu in Safari's menubar.
 
-          <warning>
-            <para>
-              Instead of setting this option directly, set
-              <option>"com.apple.Safari".IncludeDevelopMenu</option> instead.
-            </para>
-          </warning>
+          ::: {.warning}
+          Instead of setting this option directly, set
+          {option}`"com.apple.Safari".IncludeDevelopMenu` instead.
+          :::
         '';
       };
     };
@@ -177,20 +171,16 @@ in {
         description = ''
           Configures how to restore tmux windows when attaching to a session.
 
-          <variablelist><title>Possible Values</title>
-            <varlistentry>
-              <term><literal>0</literal></term>
-              <listitem><para>Native windows</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>1</literal></term>
-              <listitem><para>Native tabs in a new window</para></listitem>
-            </varlistentry>
-            <varlistentry>
-              <term><literal>2</literal></term>
-              <listitem><para>Tabs in the attaching window</para></listitem>
-            </varlistentry>
-          </variablelist>
+          **Possible Values**
+
+          `0`
+          : Native windows
+
+          `1`
+          : Native tabs in a new window
+
+          `2`
+          : Tabs in the attaching window
         '';
       };
 
diff --git a/modules/xresources.nix b/modules/xresources.nix
index 31eb6eaa..e4ba0e47 100644
--- a/modules/xresources.nix
+++ b/modules/xresources.nix
@@ -50,8 +50,8 @@ in {
         All other values are directly formatted using builtins.toString.
         Note, that 2-dimensional lists are not supported and specifying one will throw an exception.
         If this and all other xresources options are
-        <code>null</code>, then this feature is disabled and no
-        <filename>~/.Xresources</filename> link is produced.
+        `null`, then this feature is disabled and no
+        {file}`~/.Xresources` link is produced.
       '';
     };
 
@@ -71,8 +71,8 @@ in {
       description = ''
         Additional X server resources contents.
         If this and all other xresources options are
-        <code>null</code>, then this feature is disabled and no
-        <filename>~/.Xresources</filename> link is produced.
+        `null`, then this feature is disabled and no
+        {file}`~/.Xresources` link is produced.
       '';
     };
 
@@ -81,7 +81,7 @@ in {
       default = "${config.home.homeDirectory}/.Xresources";
       defaultText = "$HOME/.Xresources";
       description =
-        "Path where Home Manager should link the <filename>.Xresources</filename> file.";
+        "Path where Home Manager should link the {file}`.Xresources` file.";
     };
   };
 
diff --git a/modules/xsession.nix b/modules/xsession.nix
index 6d05d432..d8e2a71c 100644
--- a/modules/xsession.nix
+++ b/modules/xsession.nix
@@ -18,7 +18,7 @@ in {
         default = ".xsession";
         example = ".xsession-hm";
         description = ''
-          Path, relative to <envar>HOME</envar>, where Home Manager
+          Path, relative to {env}`HOME`, where Home Manager
           should write the X session script.
         '';
       };
@@ -28,7 +28,7 @@ in {
         default = ".xprofile";
         example = ".xprofile-hm";
         description = ''
-          Path, relative to <envar>HOME</envar>, where Home Manager
+          Path, relative to {env}`HOME`, where Home Manager
           should write the X profile script.
         '';
       };
@@ -46,10 +46,10 @@ in {
         default = ''test -n "$1" && eval "$@"'';
         description = ''
           Command to use to start the window manager.
-          </para><para>
+
           The default value allows integration with NixOS' generated xserver configuration.
-          </para><para>
-          Extra actions and commands can be specified in <option>xsession.initExtra</option>.
+
+          Extra actions and commands can be specified in {option}`xsession.initExtra`.
         '';
       };
 
diff --git a/nixos/common.nix b/nixos/common.nix
index a897799d..38c5aabb 100644
--- a/nixos/common.nix
+++ b/nixos/common.nix
@@ -45,14 +45,12 @@ in {
   options.home-manager = {
     useUserPackages = mkEnableOption ''
       installation of user packages through the
-      <option>users.users.&lt;name&gt;.packages</option> option
-    '';
+      {option}`users.users.<name>.packages` option'';
 
     useGlobalPkgs = mkEnableOption ''
-      using the system configuration's <literal>pkgs</literal>
+      using the system configuration's `pkgs`
       argument in Home Manager. This disables the Home Manager
-      options <option>nixpkgs.*</option>
-    '';
+      options {option}`nixpkgs.*`'';
 
     backupFileExtension = mkOption {
       type = types.nullOr types.str;
@@ -69,7 +67,7 @@ in {
       default = { };
       example = literalExpression "{ inherit emacs-overlay; }";
       description = ''
-        Extra <literal>specialArgs</literal> passed to Home Manager. This
+        Extra `specialArgs` passed to Home Manager. This
         option can be used to pass additional arguments to all modules.
       '';
     };
diff --git a/release.json b/release.json
new file mode 100644
index 00000000..5675c269
--- /dev/null
+++ b/release.json
@@ -0,0 +1,4 @@
+{
+  "release": "23.11",
+  "isReleaseBranch": false
+}
diff --git a/tests/big-test.nix b/tests/big-test.nix
index 421eaebb..5396f170 100644
--- a/tests/big-test.nix
+++ b/tests/big-test.nix
@@ -5,7 +5,7 @@
     type = lib.types.bool;
     default = true;
     description = ''
-      Whether to enable <quote>big</quote> tests. These are tests that require
+      Whether to enable "big" tests. These are tests that require
       more resources than typical tests. For example, tests that depend on large
       packages or tests that take long to run.
     '';
diff --git a/tests/default.nix b/tests/default.nix
index 89026403..5b6cbcb2 100644
--- a/tests/default.nix
+++ b/tests/default.nix
@@ -30,7 +30,7 @@ let
 
       # Avoid including documentation since this will cause
       # unnecessary rebuilds of the tests.
-      manual.manpages.enable = false;
+      manual.manpages.enable = lib.mkDefault false;
 
       imports = [ ./asserts.nix ./big-test.nix ./stubs.nix ];
 
@@ -52,6 +52,7 @@ import nmt {
     ./modules/files
     ./modules/home-environment
     ./modules/misc/fontconfig
+    ./modules/misc/manual
     ./modules/misc/nix
     ./modules/misc/specialisation
     ./modules/programs/aerc
diff --git a/tests/modules/misc/manual/default.nix b/tests/modules/misc/manual/default.nix
new file mode 100644
index 00000000..095809c9
--- /dev/null
+++ b/tests/modules/misc/manual/default.nix
@@ -0,0 +1 @@
+{ manual = ./manual.nix; }
diff --git a/tests/modules/misc/manual/manual.nix b/tests/modules/misc/manual/manual.nix
new file mode 100644
index 00000000..eb70374a
--- /dev/null
+++ b/tests/modules/misc/manual/manual.nix
@@ -0,0 +1,19 @@
+{ ... }:
+
+{
+  config = {
+    manual = {
+      html.enable = true;
+      manpages.enable = true;
+      json.enable = true;
+    };
+
+    nmt.script = ''
+      assertFileExists home-path/share/doc/home-manager/index.html
+      assertFileExists home-path/share/doc/home-manager/options.html
+      assertFileExists home-path/share/doc/home-manager/options.json
+      assertFileExists home-path/share/man/man1/home-manager.1.gz
+      assertFileExists home-path/share/man/man5/home-configuration.nix.5.gz
+    '';
+  };
+}