docs: document highlight groups

README.md

@@ -659,6 +659,39 @@ To uninstall **lazy.nvim**, you need to remove the following files and directori
 
 > paths can differ if you changed `XDG` environment variables.
 
+## 🌈 Highlight Groups
+
+<details>
+<summary>Click to see all highlight groups</summary>
+
+<!-- colors:start -->
+
+| Highlight Group        | Default Group              | Description       |
+| ---------------------- | -------------------------- | ----------------- |
+| **LazyButton**         | **_CursorLine_**           |                   |
+| **LazyButtonActive**   | **_Visual_**               |                   |
+| **LazyCommit**         | **_@variable.builtin_**    |                   |
+| **LazyError**          | **_ErrorMsg_**             | task errors       |
+| **LazyH1**             | **_IncSearch_**            |                   |
+| **LazyH2**             | **_Bold_**                 |                   |
+| **LazyHandlerCmd**     | **_Operator_**             |                   |
+| **LazyHandlerEvent**   | **_Constant_**             |                   |
+| **LazyHandlerFt**      | **_Character_**            |                   |
+| **LazyHandlerKeys**    | **_Statement_**            |                   |
+| **LazyHandlerPlugin**  | **_Special_**              |                   |
+| **LazyHandlerRuntime** | **_@macro_**               |                   |
+| **LazyHandlerSource**  | **_Character_**            |                   |
+| **LazyHandlerStart**   | **_@field_**               |                   |
+| **LazyKey**            | **_Conceal_**              |                   |
+| **LazyMuted**          | **_Comment_**              |                   |
+| **LazyNormal**         | **_NormalFloat_**          |                   |
+| **LazyProgressDone**   | **_Constant_**             | progress bar done |
+| **LazyProgressTodo**   | **_LineNr_**               | progress bar todo |
+| **LazySpecial**        | **_@punctuation.special_** |                   |
+| **LazyValue**          | **_@string_**              |                   |
+
+<!-- colors:end -->
+
 ## 📦 Other Neovim Plugin Managers in Lua
 
 - [packer.nvim](https://github.com/wbthomason/packer.nvim)

lua/lazy/docs.lua

@@ -10,26 +10,6 @@ function M.indent(str, indent)
   return table.concat(lines, "\n")
 end
 
-function M.toc(md)
-  local toc = {}
-  local lines = vim.split(md, "\n")
-  local toc_found = false
-  for _, line in ipairs(lines) do
-    local hash, title = line:match("^(#+)%s*(.*)")
-    if hash then
-      if toc_found then
-        local anchor = string.gsub(title:lower(), "[^\32-\126]", "")
-        anchor = string.gsub(anchor, " ", "-")
-        toc[#toc + 1] = string.rep("  ", #hash - 1) .. "- [" .. title .. "](#" .. anchor .. ")"
-      end
-      if title:find("Table of Contents") then
-        toc_found = true
-      end
-    end
-  end
-  return M.fix_indent(table.concat(toc, "\n"))
-end
-
 ---@param str string
 function M.fix_indent(str)
   local lines = vim.split(str, "\n")
@@ -48,7 +28,6 @@ end
 ---@param contents table<string, string>
 function M.save(contents)
   local readme = Util.read_file("README.md")
-  -- contents.toc = M.toc(readme)
   for tag, content in pairs(contents) do
     content = M.fix_indent(content)
     content = content:gsub("%%", "%%%%")
@@ -57,7 +36,7 @@ function M.save(contents)
     if not readme:find(pattern) then
       error("tag " .. tag .. " not found")
     end
-    if tag == "toc" or tag == "commands" then
+    if tag == "commands" or tag == "colors" then
       readme = readme:gsub(pattern, "%1\n\n" .. content .. "\n\n%2")
     else
       readme = readme:gsub(pattern, "%1\n\n```lua\n" .. content .. "\n```\n\n%2")
@@ -104,6 +83,12 @@ function M.commands()
       end
     end
   end)
+  return M.table(lines)
+end
+
+---@param lines string[][]
+function M.table(lines)
+  ---@type string[]
   local ret = {}
   for _, line in ipairs(lines) do
     ret[#ret + 1] = "| " .. table.concat(line, " | ") .. " |"
@@ -111,6 +96,26 @@ function M.commands()
   return table.concat(ret, "\n")
 end
 
+function M.colors()
+  local str = M.extract("lua/lazy/view/colors.lua", "\nM%.colors = ({.-\n})")
+  ---@type table<string,string>
+  local comments = {}
+  for _, line in ipairs(vim.split(str, "\n")) do
+    local group, desc = line:match("^  (%w+) = .* -- (.*)")
+    if group then
+      comments[group] = desc
+    end
+  end
+  local lines = {
+    { "Highlight Group", "Default Group", "Description" },
+    { "---", "---", "---" },
+  }
+  Util.foreach(require("lazy.view.colors").colors, function(group, link)
+    lines[#lines + 1] = { "**Lazy" .. group .. "**", "***" .. link .. "***", comments[group] or "" }
+  end)
+  return M.table(lines)
+end
+
 function M.update()
   local cache_config = M.extract("lua/lazy/core/cache.lua", "\nM%.config = ({.-\n})")
   local config = M.extract("lua/lazy/core/config.lua", "\nM%.defaults = ({.-\n})")
@@ -124,6 +129,7 @@ function M.update()
     config = config,
     spec = Util.read_file("lua/lazy/example.lua"),
     commands = M.commands(),
+    colors = M.colors(),
   })
   vim.cmd.checktime()
 end

lua/lazy/view/colors.lua

@@ -1,7 +1,7 @@
 local M = {}
 
 M.colors = {
-  Error = "ErrorMsg",
+  Error = "ErrorMsg", -- task errors
   H1 = "IncSearch",
   H2 = "Bold",
   Muted = "Comment",
@@ -9,13 +9,9 @@ M.colors = {
   Commit = "@variable.builtin",
   Key = "Conceal",
   Value = "@string",
-  ProgressDone = {
-    bold = true,
-    default = true,
-    fg = "#ff007c",
-  },
-  ProgressTodo = "LineNr",
   NoCond = "DiagnosticError",
+  ProgressDone = "Constant", -- progress bar done
+  ProgressTodo = "LineNr", -- progress bar todo
   Special = "@punctuation.special",
   HandlerRuntime = "@macro",
   HandlerPlugin = "Special",
@@ -32,12 +28,11 @@ M.colors = {
 M.did_setup = false
 
 function M.set_hl()
-  for hl_group, opts in pairs(M.colors) do
+  for hl_group, link in pairs(M.colors) do
-    if type(opts) == "string" then
+    vim.api.nvim_set_hl(0, "Lazy" .. hl_group, {
-      opts = { link = opts }
+      link = link,
-    end
+      default = true,
-    opts.default = true
+    })
-    vim.api.nvim_set_hl(0, "Lazy" .. hl_group, opts)
   end
 end