diff --git a/README.md b/README.md
index fb04ca6..61f95da 100644
--- a/README.md
+++ b/README.md
@@ -436,7 +436,7 @@ return {
   -- when the readme opens with :help it will be correctly displayed as markdown
   readme = {
     root = vim.fn.stdpath("state") .. "/lazy/readme",
-    files = { "README.md" },
+    files = { "README.md", "lua/**/README.md" },
     -- only generate markdown helptags for plugins that dont have docs
     skip_if_doc_exists = true,
   },
diff --git a/lua/lazy/core/config.lua b/lua/lazy/core/config.lua
index 87e9c98..563e809 100644
--- a/lua/lazy/core/config.lua
+++ b/lua/lazy/core/config.lua
@@ -135,7 +135,7 @@ M.defaults = {
   -- when the readme opens with :help it will be correctly displayed as markdown
   readme = {
     root = vim.fn.stdpath("state") .. "/lazy/readme",
-    files = { "README.md" },
+    files = { "README.md", "lua/**/README.md" },
     -- only generate markdown helptags for plugins that dont have docs
     skip_if_doc_exists = true,
   },
diff --git a/lua/lazy/help.lua b/lua/lazy/help.lua
index a41602f..f9e6637 100644
--- a/lua/lazy/help.lua
+++ b/lua/lazy/help.lua
@@ -7,23 +7,28 @@ function M.index(plugin)
   if Config.options.readme.skip_if_doc_exists and vim.loop.fs_stat(plugin.dir .. "/doc") then
     return {}
   end
+  local files = vim.tbl_flatten(vim.tbl_map(function(file)
+    return vim.fn.expand(plugin.dir .. "/" .. file, false, true)
+  end, Config.options.readme.files))
   ---@type table<string,{file:string, tag:string, line:string}>
   local tags = {}
-  for _, file in ipairs(Config.options.readme.files) do
-    file = plugin.dir .. "/" .. file
+  for _, file in ipairs(files) do
+    file = Util.norm(file)
     if vim.loop.fs_stat(file) then
+      local rel_file = file:sub(#plugin.dir + 1)
+      local tag_filename = string.gsub(plugin.name .. vim.fn.fnamemodify(rel_file, ":h:gs?/?-?"), "-$", "")
       local lines = vim.split(Util.read_file(file), "\n")
       for _, line in ipairs(lines) do
         local title = line:match("^#+%s*(.*)")
         if title then
-          local tag = plugin.name .. "-" .. title:lower():gsub("%W+", "-")
+          local tag = tag_filename .. "-" .. title:lower():gsub("%W+", "-")
           tag = tag:gsub("%-+", "-"):gsub("%-$", "")
           line = line:gsub("([%[%]/])", "\\%1")
-          tags[tag] = { tag = tag, line = line, file = plugin.name .. ".md" }
+          tags[tag] = { tag = tag, line = line, file = tag_filename .. ".md" }
         end
       end
       table.insert(lines, [[<!-- vim: set ft=markdown: -->]])
-      Util.write_file(Config.options.readme.root .. "/doc/" .. plugin.name .. ".md", table.concat(lines, "\n"))
+      Util.write_file(Config.options.readme.root .. "/doc/" .. tag_filename .. ".md", table.concat(lines, "\n"))
     end
   end
   return tags