From 15451e8cb439308630b6f95d9758ffb0e60fd226 Mon Sep 17 00:00:00 2001
From: Joshua Tye <21010072+catgoose@users.noreply.github.com>
Date: Sun, 19 Apr 2026 07:40:13 -0500
Subject: [PATCH] docs: updates readme around legacy config key support

---
 README.md                  | 59 ++++++++++++++++++++++++++++++++++++--
 tests/test_new_options.lua | 24 ++++++++++++++++
 2 files changed, 80 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 233f0bd..4210b2f 100644
--- a/README.md
+++ b/README.md
@@ -90,15 +90,68 @@ require("colorizer").setup({
 
 -- Per-filetype overrides
 require("colorizer").setup({
+  options = {
+    -- base options applied to every filetype unless overridden below
+    parsers = {
+      hex = { default = false },
+      names = { enable = false },
+      tailwind = { enable = false },
+    },
+  },
   filetypes = {
     "*",
-    "!markdown",
-    html = { mode = "foreground" },
-    cmp_docs = { always_update = true },
+    "!markdown",                          -- exclude markdown entirely
+    html = { mode = "foreground" },       -- legacy flat key
+    cmp_docs = { always_update = true },  -- legacy flat key
+    -- Each entry can also use the same nested format as `options`,
+    -- deep-merged on top of the base options:
+    css = {
+      parsers = {
+        hex = { default = true },
+        oklch = { enable = true },
+      },
+    },
+    javascriptreact = {
+      parsers = { tailwind = { enable = true, lsp = true } },
+    },
+  },
+  buftypes = {
+    -- Same override format works for buftypes
+    terminal = { parsers = { hex = { default = true } } },
+  },
+})
+
+-- Enabling a parser per-filetype: both shapes below are valid
+require("colorizer").setup({
+  options = {
+    parsers = { names = { enable = false } }, -- disabled by default
+  },
+  filetypes = {
+    html = { names = true },                                               -- legacy flat shorthand
+    css  = { parsers = { names = { enable = true, lowercase = false } } }, -- nested new-format
   },
 })
 ```
 
+> Each value in `filetypes` / `buftypes` accepts **either** the nested
+> format (`parsers = {...}`, `display = {...}`, `hooks = {...}`,
+> `always_update`) **or** legacy flat keys (`mode`, `names`, `RGB`,
+> `rgb_fn`, …). Both shapes are translated and deep-merged onto the base
+> `options`, so you only need to specify what changes for that filetype.
+>
+> This mixed-format compatibility is intentional for `filetypes` /
+> `buftypes` overrides even though the top-level recommended shape is
+> `options = { ... }` — it lets short per-filetype tweaks stay terse.
+>
+> In summary
+>
+> - flat legacy parser keys (`names`, `RGB`, `rgb_fn`, …) go **directly**
+>   on the filetype table, e.g. `html = { names = true }`
+> - structured parser config goes **under `parsers`**, e.g.
+>   `html = { parsers = { names = { enable = true } } }`
+> - to tweak sub-options (`lowercase`, `camelcase`, …) use the nested
+>   form — the flat shorthand only toggles `enable`
+
 ## Parser options
 
 ### Hex `default` key
diff --git a/tests/test_new_options.lua b/tests/test_new_options.lua
index 287e978..5bc423d 100644
--- a/tests/test_new_options.lua
+++ b/tests/test_new_options.lua
@@ -911,6 +911,30 @@ T["translate_filetypes"]["override translates legacy options"] = function()
   eq(true, new.overrides.html.parsers.hsl.enable)
 end
 
+T["translate_filetypes"]["override translates legacy names shorthand"] = function()
+  local new = config.translate_filetypes({
+    html = { names = true },
+  })
+  eq(true, new.overrides.html.parsers.names.enable)
+end
+
+T["translate_filetypes"]["override translates legacy names_opts"] = function()
+  local new = config.translate_filetypes({
+    html = { names = true, names_opts = { lowercase = false, camelcase = true } },
+  })
+  eq(true, new.overrides.html.parsers.names.enable)
+  eq(false, new.overrides.html.parsers.names.lowercase)
+  eq(true, new.overrides.html.parsers.names.camelcase)
+end
+
+T["translate_filetypes"]["override accepts nested new-format parser key"] = function()
+  local new = config.translate_filetypes({
+    html = { parsers = { names = { enable = true, lowercase = false } } },
+  })
+  eq(true, new.overrides.html.parsers.names.enable)
+  eq(false, new.overrides.html.parsers.names.lowercase)
+end
+
 T["translate_filetypes"]["new format fills missing keys"] = function()
   local new = config.translate_filetypes({ enable = { "*" } })
   eq("*", new.enable[1])