diff --git a/modules/files.nix b/modules/files.nix
index 4f64a9f86..af52b58ca 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 "<envar>HOME</envar>" homeDirectory;
+      type = fileType "home.file" "<envar>HOME</envar>" homeDirectory;
     };
 
     home-files = mkOption {
diff --git a/modules/lib/file-type.nix b/modules/lib/file-type.nix
index b12b3262a..2f0d28463 100644
--- a/modules/lib/file-type.nix
+++ b/modules/lib/file-type.nix
@@ -10,9 +10,10 @@ in
   # absolute path).
   #
   # Arguments:
+  #   - opt            the name of the option, for self-references
   #   - basePathDesc   docbook compatible description of the base path
   #   - basePath       the file base path
-  fileType = basePathDesc: basePath: types.attrsOf (types.submodule (
+  fileType = opt: basePathDesc: basePath: types.attrsOf (types.submodule (
     { name, config, ... }: {
       options = {
         enable = mkOption {
@@ -30,7 +31,7 @@ in
               absPath = if hasPrefix "/" p then p else "${basePath}/${p}";
             in
               removePrefix (homeDirectory + "/") absPath;
-          defaultText = literalExpression "<name>";
+          defaultText = literalExpression "name";
           description = ''
             Path to target file relative to ${basePathDesc}.
           '';
@@ -41,7 +42,7 @@ in
           type = types.nullOr types.lines;
           description = ''
             Text of the file. If this option is null then
-            <xref linkend="opt-home.file._name_.source"/>
+            <xref linkend="opt-${opt}._name_.source"/>
             must be set.
           '';
         };
@@ -50,7 +51,7 @@ in
           type = types.path;
           description = ''
             Path of the source file or directory. If
-            <xref linkend="opt-home.file._name_.text"/>
+            <xref linkend="opt-${opt}._name_.text"/>
             is non-null then this option will automatically point to a file
             containing that text.
           '';
diff --git a/modules/misc/xdg.nix b/modules/misc/xdg.nix
index 247e73192..3d2a72a06 100644
--- a/modules/misc/xdg.nix
+++ b/modules/misc/xdg.nix
@@ -34,7 +34,8 @@ in {
     };
 
     configFile = mkOption {
-      type = fileType "<varname>xdg.configHome</varname>" cfg.configHome;
+      type = fileType "xdg.configFile" "<varname>xdg.configHome</varname>"
+        cfg.configHome;
       default = { };
       description = ''
         Attribute set of files to link into the user's XDG
@@ -52,7 +53,8 @@ in {
     };
 
     dataFile = mkOption {
-      type = fileType "<varname>xdg.dataHome</varname>" cfg.dataHome;
+      type =
+        fileType "xdg.dataFile" "<varname>xdg.dataHome</varname>" cfg.dataHome;
       default = { };
       description = ''
         Attribute set of files to link into the user's XDG
diff --git a/modules/programs/neovim.nix b/modules/programs/neovim.nix
index df4b487d6..b57cfe065 100644
--- a/modules/programs/neovim.nix
+++ b/modules/programs/neovim.nix
@@ -43,7 +43,8 @@ let
         default = { };
         # passing actual "${xdg.configHome}/nvim" as basePath was a bit tricky
         # due to how fileType.target is implemented
-        type = fileType "<varname>xdg.configHome/nvim</varname>" "nvim";
+        type = fileType "programs.neovim.plugins._.runtime"
+          "<varname>xdg.configHome/nvim</varname>" "nvim";
         example = literalExpression ''
           { "ftplugin/c.vim".text = "setlocal omnifunc=v:lua.vim.lsp.omnifunc"; }
         '';