diff --git a/modules/config/home-cursor.nix b/modules/config/home-cursor.nix
index e2d26a5ba..d8cbb5390 100644
--- a/modules/config/home-cursor.nix
+++ b/modules/config/home-cursor.nix
@@ -101,9 +101,9 @@ in {
         options. Options declared under namespaces such as <literal>x11</literal>
         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, <varname>
-        <link linkend="opt-home.pointerCursor.x11.enable">home.pointerCursor.x11.enable</link>
-        </varname> will enable x11 cursor configurations.
+        backends, you can toggle them via the enable option. For example,
+        <xref linkend="opt-home.pointerCursor.x11.enable"/>
+        will enable x11 cursor configurations.
       '';
     };
   };
diff --git a/modules/home-environment.nix b/modules/home-environment.nix
index b83cf1d1e..385762608 100644
--- a/modules/home-environment.nix
+++ b/modules/home-environment.nix
@@ -383,7 +383,7 @@ in
         unexpected state is found. For example, the
         <literal>checkLinkTargets</literal> script block checks for
         collisions between non-managed files and files defined in
-        <varname><link linkend="opt-home.file">home.file</link></varname>.
+        <xref linkend="opt-home.file"/>.
 
         </para><para>
 
diff --git a/modules/lib/file-type.nix b/modules/lib/file-type.nix
index 0b30cb1b6..cc23292ba 100644
--- a/modules/lib/file-type.nix
+++ b/modules/lib/file-type.nix
@@ -33,7 +33,7 @@ in
           type = types.nullOr types.lines;
           description = ''
             Text of the file. If this option is null then
-            <link linkend="opt-home.file._name_.source">home.file.&lt;name?&gt;.source</link>
+            <xref linkend="opt-home.file._name_.source"/>
             must be set.
           '';
         };
@@ -42,7 +42,7 @@ in
           type = types.path;
           description = ''
             Path of the source file or directory. If
-            <link linkend="opt-home.file._name_.text">home.file.&lt;name?&gt;.text</link>
+            <xref linkend="opt-home.file._name_.text"/>
             is non-null then this option will automatically point to a file
             containing that text.
           '';
diff --git a/modules/programs/firefox.nix b/modules/programs/firefox.nix
index 39f1e9802..a5864b815 100644
--- a/modules/programs/firefox.nix
+++ b/modules/programs/firefox.nix
@@ -176,7 +176,7 @@ in {
 
           Extensions listed here will only be available in Firefox
           profiles managed through the
-          <link linkend="opt-programs.firefox.profiles">programs.firefox.profiles</link>
+          <xref linkend="opt-programs.firefox.profiles"/>
           option. This is due to recent changes in the way Firefox
           handles extension side-loading.
         '';
diff --git a/modules/programs/go.nix b/modules/programs/go.nix
index 8ec361b3d..70a5c9b62 100644
--- a/modules/programs/go.nix
+++ b/modules/programs/go.nix
@@ -47,12 +47,9 @@ in {
         type = types.listOf types.str;
         default = [ ];
         example = [ "extraGoPath1" "extraGoPath2" ];
-        description = let goPathOpt = "programs.go.goPath";
-        in ''
+        description = ''
           Extra <envar>GOPATH</envar>s relative to <envar>HOME</envar> appended
-          after
-          <varname><link linkend="opt-${goPathOpt}">${goPathOpt}</link></varname>,
-          if that option is set.
+          after <xref linkend="opt-programs.go.goPath"/>, if that option is set.
         '';
       };
 
diff --git a/modules/programs/zsh.nix b/modules/programs/zsh.nix
index 133b1c320..f06d0d0b9 100644
--- a/modules/programs/zsh.nix
+++ b/modules/programs/zsh.nix
@@ -246,7 +246,7 @@ in
           }
         '';
         description = ''
-          Similar to <varname><link linkend="opt-programs.zsh.shellAliases">opt-programs.zsh.shellAliases</link></varname>,
+          Similar to <xref linkend="opt-programs.zsh.shellAliases"/>,
           but are substituted anywhere on a line.
         '';
         type = types.attrsOf types.str;
diff --git a/modules/services/window-managers/i3-sway/lib/options.nix b/modules/services/window-managers/i3-sway/lib/options.nix
index 27addca29..cae9c3a64 100644
--- a/modules/services/window-managers/i3-sway/lib/options.nix
+++ b/modules/services/window-managers/i3-sway/lib/options.nix
@@ -67,7 +67,7 @@ let
         default = null;
         description = ''
           Launch application on a particular workspace. DEPRECATED:
-          Use <varname><link linkend="opt-xsession.windowManager.i3.config.assigns">xsession.windowManager.i3.config.assigns</link></varname>
+          Use <xref linkend="opt-xsession.windowManager.i3.config.assigns"/>
           instead. See <link xlink:href="https://github.com/nix-community/home-manager/issues/265"/>.
         '';
       };