{"id":50872338,"url":"https://github.com/0antinomia/hlcraft.nvim","last_synced_at":"2026-06-15T06:07:31.878Z","repository":{"id":349224623,"uuid":"1198541968","full_name":"0antinomia/hlcraft.nvim","owner":"0antinomia","description":"Interactive highlight explorer, override manager, and customizable theme layer for Neovim.","archived":false,"fork":false,"pushed_at":"2026-04-26T10:58:49.000Z","size":82,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T12:27:13.177Z","etag":null,"topics":["colorscheme","customization","highlight","lua","neovim","neovim-plugin","theme","toml","ui"],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0antinomia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T14:19:18.000Z","updated_at":"2026-04-26T10:58:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0antinomia/hlcraft.nvim","commit_stats":null,"previous_names":["0antinomia/hlcraft.nvim"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/0antinomia/hlcraft.nvim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0antinomia%2Fhlcraft.nvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0antinomia%2Fhlcraft.nvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0antinomia%2Fhlcraft.nvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0antinomia%2Fhlcraft.nvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0antinomia","download_url":"https://codeload.github.com/0antinomia/hlcraft.nvim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0antinomia%2Fhlcraft.nvim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34350005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["colorscheme","customization","highlight","lua","neovim","neovim-plugin","theme","toml","ui"],"created_at":"2026-06-15T06:07:31.154Z","updated_at":"2026-06-15T06:07:31.869Z","avatar_url":"https://github.com/0antinomia.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hlcraft.nvim\n\n[中文文档](./README.zh.md)\n\n`hlcraft.nvim` is an interactive highlight explorer and override manager for Neovim.\n\nIt gives you one place to inspect highlight groups, search by name or color, edit overrides, and persist the result as TOML files.\n\nIt also works well as a unified control surface for your Neovim highlights. And if you want, you can absolutely use it like a \"theme\" plugin: one whose final look is shaped entirely by you.\n\nA practical workflow is to ask AI to turn a colorscheme you already like into hlcraft persistence files, then keep refining it from there. Or skip that and build your own style from scratch. Either way, the end result stays in your hands.\n\n## Features\n\n- Search highlight groups by name\n- Search highlight groups by color similarity\n- Inspect resolved `fg`, `bg`, `sp`, links, source and attributes\n- Edit overrides in a detail editor\n- Persist overrides across sessions\n- Reapply persisted overrides after colorscheme changes\n- Zero external dependencies\n\n## Requirements\n\n- Neovim `\u003e= 0.10.0`\n\n## Installation\n\n### lazy.nvim\n\n```lua\n{\n  '0antinomia/hlcraft.nvim',\n  config = function()\n    require('hlcraft').setup()\n  end,\n}\n```\n\n### Minimal setup\n\n```lua\nrequire('hlcraft').setup()\n```\n\nThe plugin also registers the `:Hlcraft` command automatically.\n\n## Configuration\n\nDefault configuration:\n\n```lua\nrequire('hlcraft').setup({\n  from_none = {\n    enabled = false,\n    scope = 'extended',\n  },\n  threshold = 100,\n  include_sp_in_color_search = false,\n  persist_dir = vim.fn.stdpath('config') .. '/hlcraft',\n  reapply_events = {\n    enabled = true,\n    events = {\n      'ColorScheme',\n    },\n  },\n  dynamic = {\n    enabled = false,\n    interval_ms = 80,\n  },\n  debounce_ms = 100,\n  preview_key = 'z',\n})\n```\n\n### Options\n\n#### `from_none`\n\nControls whether hlcraft applies a transparent baseline preset before your own runtime and persisted overrides.\n\n```lua\nfrom_none = {\n  enabled = false,\n  scope = 'extended',\n}\n```\n\n- `enabled`: whether the preset is active\n- `scope = 'core'`: only clears a smaller set of foundational groups such as `Normal`, `NormalFloat`, `SignColumn`\n- `scope = 'extended'`: also clears more UI groups such as popup menu and winbar related highlights\n\nUse this when you want hlcraft to maintain a transparent background setup for you.\n\nIf you want the quickest path to a transparent Neovim look, this is probably the setting you want.\n\n#### `threshold`\n\nDefault distance threshold used by color search.\n\n```lua\nthreshold = 100\n```\n\nColor search uses RGB Euclidean distance. Lower values are stricter. Higher values return broader matches.\n\n#### `include_sp_in_color_search`\n\nControls whether the `sp` field participates in color matching.\n\n```lua\ninclude_sp_in_color_search = false\n```\n\nWhen enabled, highlight groups whose special color matches the query can also appear in the results. This is mainly useful for underline- and undercurl-heavy colorschemes.\n\n#### `persist_dir`\n\nDirectory used to store persisted override files.\n\n```lua\npersist_dir = vim.fn.stdpath('config') .. '/hlcraft'\n```\n\nBy default, hlcraft stores persistence data in a visible `hlcraft` directory under your Neovim config directory. It may create multiple TOML files there. Set `persist_dir` explicitly if you want to keep using a different location.\n\n#### `reapply_events`\n\nEvents that trigger automatic replay of persisted overrides.\n\n```lua\nreapply_events = {\n  enabled = true,\n  events = {\n    'ColorScheme',\n  },\n}\n```\n\nYou can provide either plain event names or structured entries inside `events`:\n\n```lua\nreapply_events = {\n  enabled = true,\n  events = {\n    'ColorScheme',\n    { event = 'SessionLoadPost', once = false },\n  },\n}\n```\n\nStructured entries support:\n\n- `event`: autocmd event name\n- `pattern`: optional autocmd pattern\n- `once`: whether the autocmd should run only once\n\nSet `enabled = false` to disable automatic replay entirely.\n\n#### `dynamic`\n\nControls whether saved dynamic color overrides are animated at runtime. Dynamic colors are an early experimental feature in hlcraft: they let a color channel keep changing after the override has been applied, instead of staying on one static `fg`, `bg`, or `sp` value.\n\n```lua\ndynamic = {\n  enabled = false,\n  interval_ms = 80,\n}\n```\n\n- `enabled`: when `false`, dynamic configuration is loaded and saved but does not animate.\n- `interval_ms`: animation tick interval in milliseconds. Lower values feel smoother but write highlights more often.\n\nDynamic color configuration is edited from the existing `FG`, `BG`, and `SP` editors:\n\n- Press `d` in a color editor to toggle dynamic mode for the current `FG`, `BG`, or `SP` channel.\n- Press `m` to switch between the current modes: `rgb` and `breath`.\n- Press `+` / `-` to change the effect speed, or the selected dynamic parameter when a parameter row is selected.\n- In `rgb` mode, palette rows can be selected and edited to change the animated color stops.\n- In `breath` mode, parameter rows expose editable `min` and `max` brightness values.\n- Press `s` in the detail view to persist the override, just like static color changes.\n\nDynamic rows use animated color swatches as the primary preview. Compact text such as `rgb 2000ms` remains visible as metadata and as a fallback for environments where the preview cannot animate.\n\nThe current implementation is still early-stage and intentionally small. It exposes dynamic `fg`, `bg`, and `sp` channels, two built-in modes, speed control, editable `rgb` palette stops, and editable `breath` brightness bounds, but broader configurability is deliberately limited while the feature settles.\n\n#### `debounce_ms`\n\nDebounce delay for search input updates.\n\n```lua\ndebounce_ms = 100\n```\n\n- `0`: disable debounce and update immediately\n- `\u003e 0`: wait the given milliseconds before recomputing results during typing\n\n#### `preview_key`\n\nTemporary flash key used to identify the currently selected highlight group.\n\n```lua\npreview_key = 'z'\n```\n\nThis key is installed as a temporary global normal-mode mapping while the hlcraft workspace is open, so it still works after switching to another window. Once the workspace closes, the mapping is removed.\n\nSet it to `false` to disable the feature entirely.\n\n## Usage\n\nOpen the workspace:\n\n```vim\n:Hlcraft\n```\n\n### Search\n\nThe top area contains two inputs:\n\n- `name`: filters by case-insensitive substring match on highlight group names\n- `color`: filters by color similarity\n\nThe two filters can be combined.\n\nColor queries accept:\n\n- `#RRGGBB`\n- `NONE`\n\n`NONE` matches groups whose resolved color is unset. By default this checks `fg` and `bg`. If `include_sp_in_color_search` is enabled, it also checks `sp`.\n\n## Persistence\n\nPersisted overrides are written under:\n\n```lua\nvim.fn.stdpath('config') .. '/hlcraft'\n```\n\nEach file stores one top-level TOML section. Section names come from groups you explicitly select or create in the detail view. If an override has no group, hlcraft asks you to choose or create one before saving.\n\nDynamic color settings are stored as hlcraft-specific flat keys such as `dyn_fg_mode` and `dyn_fg_speed`. Palette stops and mode parameters are serialized as JSON strings in optional flat keys such as `dyn_fg_palette` and `dyn_fg_params`; the same pattern applies to each dynamic channel, for example `dyn_bg_palette`, `dyn_bg_params`, `dyn_sp_palette`, and `dyn_sp_params`. Depending on mode and defaults, absent palette or params keys can still be valid.\n\nPersisted overrides are loaded during `setup()` and replayed again on configured `reapply_events`.\n\n## Health Check\n\nRun:\n\n```vim\n:checkhealth hlcraft\n```\n\nThis checks:\n\n- Neovim version compatibility\n- persistence directory availability\n- persistence directory writability\n- TOML parse integrity\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0antinomia%2Fhlcraft.nvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0antinomia%2Fhlcraft.nvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0antinomia%2Fhlcraft.nvim/lists"}