Skip to content

Latest commit

 

History

History
247 lines (180 loc) · 10.2 KB

contributing.md

File metadata and controls

247 lines (180 loc) · 10.2 KB
Raw

Contributing

This document contains information about nvim-highlite which is relevant for contributors.

Warning

This document assumes that you have read the usage guide.

Code Style

This repository has an editorconfig. Neovim 0.9 supports editorconfigs out of the box, but if you are using an earlier version, you may have to install a plugin.

Project Layout

Module Description
highlite Construct & configure colorschemes
highlite.color Color manipulation functions
highlite.color.palette Palette deriving
highlite.color.palette.types Shared type definitions for built-in palettes
highlite.color.palette.<foo> Built-in color palettes
highlite.export Boilerplate for exporting various formats
highlite.export.<format> Formats that can be exported to from a colorscheme
highlite.fmt String formatting
highlite.fs Operations on the filesystem
highlite.groups Utilities for working with highlight groups
highlite.groups.options User configuration resolvers
highlite.groups.types Shared type definitions for highlight group templates
highlite.groups.<foo> Highlight group generation templates
highlite.import Boilerplate for importing from various formats to nvim-highlite
highlite.import.<format> Formats that can be imported to nvim-highlite
highlite.nvim Nvim API utilities
highlite.table Utilities for working with tables

Features

This section is about contributing new features to nvim-highlite.

Export Format

Export formats go in the export module.

The Fs module will be of use for writing the end result.

highlite.Fmt

There has an internal string formatting library that allows you to easily write a template for whatever you need, and all the logic will be handled behind the scenes:

function Fmt.string(format: string, opts?: highlite.Fmt.string.opts)
  -> formatted: string, count: integer

The opts are as follows:

--- @class highlite.Fmt.string.opts
--- @field convert_int_attributes? false|'hex_literal'|'hex_string' if `Foo.bar` is an integer (e.g. when `Normal.fg == 16777215`), convert it to a hex string (e.g. `'#FFFFFF'`) or a hex literal (e.g. `0xFFFFFF`)
--- @field default? true|{[string]: highlite.Fmt.string.substitution} if `true`, use default values when formatting returns `nil` for a highlight group
--- @field loadstring_compat? boolean if `true`, enable compatability for `loadstring`ing the returned value
--- @field map? {[string]: nil|fun(value: boolean|integer|string): highlite.Fmt.string.substitution}
local FMT_STRING_DEFUALT_OPTS = {
  convert_int_attributes = 'hex_string',
  default = true,
  map = {},
}

For example, you can do this:

local Fmt = require 'highlite.fmt' --- @type highlite.Fmt
local formatted = Fmt.string [[
normal_bg = ${Normal.bg}
fallback_bg = ${undefined_group.bg | defined_group.underline}
terminal_idx_1 = ${1}
]]

Import Format

Import formats go in the import module.

Some useful tools for writing support for new import formats are:

  • loadstring
  • vim.api.nvim_parse_expression
  • vim.json.decode
  • vim.treesitter + a parser for the language in question

The Fs module will be of use for file reading.

Palettes

Note

If you are looking to correct how a built-in colorscheme looks with regards to its original, it might be necessary to create palette-specific highlight groups:

  • If an entire category of highlights is wrong, adjusting the palette is correct.
  • If only one group is wrong, adjusting the groups is correct.

If you would like to add a new palette to nvim-highlite:

  1. First create a file with the same name as your palette in the palette directory.
    • e.g. a palette named "example" would be lua/highlite/color/palette/example.lua.
  2. Paste this template into the file: 
    --- @type highlite.color.palette.get
local function get(bg, get_terminal)
	local palette, terminal_palette
	if bg ~= 'light' then
		if get_terminal then
			terminal_palette = {…}
		end

		palette = {…}
	else
		if get_terminal then
			terminal_palette = {…}
		end

		palette = {…}
	end

	return palette, terminal_palette
end

return get
  3. Fill in the information (i.e. dark and light palettes / terminal palettes).
  4. Update the highlite.color.palette.shortname alias in highlite.color.palette.types to include the new palette.

Highlight Groups

While working on the highlight groups in this plugin, if you add support for a plugin or :syntax filetype, make sure that:

  1. the plugin/filetype has been added highlite.groups.types; and
  2. the default group generator, highlite.groups.default, also gets support for that plugin or filetype.

Note

The usage guide will be helpful.

New Group Generator

If you would like to add a new group generator to nvim-highlite:

  1. Create a file in the groups directory.
    • e.g. for "highlite-example", the groups would be lua/highlite/groups/example.lua.
  2. Paste this template into the file:
    • NOTE: feel free to change default_groups_from_palette to another group generator, if you'd like to base it on something else.
    local default_groups_from_palette = require 'highlite.groups.default' --- @type highlite.groups.from_palette
local Groups = require 'highlite.groups' --- @type highlite.Groups
local Options = require 'highlite.groups.options' --- @type highlite.groups.Options

--- Generate the default highlight groups using the `palette`.
--- @type highlite.groups.from_palette
local function from_palette(palette, opts)
	local all_nvim_plugins, any_nvim_plugins,
		all_syntax, any_syntax,
		all_vim_plugins, any_vim_plugins = Options.parse_from_palette(opts)

	local groups = default_groups_from_palette(palette, opts)

	--[[ override the groups. ]]

	if any_nvim_plugins then
		local nvim_plugins = type(opts.plugins) == 'table' and opts.plugins.nvim or {}

		if all_nvim_plugins or nvim_plugins['PLUGIN NAME HERE'] ~= false then
		end

		--[[ other plgin-specific changes ]]
	end

	if any_vim_plugins then
		local vim_plugins = type(opts.plugins) == 'table' and opts.plugins.vim or {}

		if all_vim_plugins or vim_plugins['PLUGIN NAME HERE'] ~= false then
		end

		--[[ other plugin-specific changes ]]
	end

	if any_syntax then
		local syntax = opts.syntax

		if all_syntax or syntax['FILETYPE NAME HERE'] ~= false then
		end

		--[[ other filetype-specific changes ]]
	end

	return groups
end

return from_palette
  3. Fill in the information necessary.
  4. Remove empty if blocks.

Colorschemes

If you would like to add a new colorscheme to nvim-highlite:

  1. Create a new file named highlite-<colorscheme>.lua in the colors directory.
    • e.g. a colorscheme named "example" should be put in colors/highlite-example.lua.
  2. Paste this template into the file: 
    local Highlite = require 'highlite' --- @type Highlite

local palette, terminal_palette = Highlite.palette 'PALETTE'
Highlite.generate('highlite-COLORSCHEME_NAME', Highlite.groups('GROUPS', palette), terminal_palette)
  3. Replace COLORSCHEME_NAME with the name of your colorscheme, PALETTE with the name of your chosen palette, and GROUPS with the name of your group generator.
    • If the palette or groups do not exist in nvim-highlite, you will have to create those as well.

Porting Colorschemes

Before covering how to port a colorscheme to nvim-highlite, it's important to note which colorschemes this project is looking for:

  • Bad: Modern, maintained, Lua colorschemes
  • Good: VimScript colorschemes, or abandoned/outdated Lua colorschemes

It is better to let colorschemes that are being maintained and updated for Neovim stay in the hands of their maintainers. Otherwise, feel free!

There is a function in the import module designed specifically for the purpose of automatically importing and formatting all of your installed colorschemes:

--- @param ignore? {patterns: nil|string[], raw: nil|string[]} a list of colorschemes to not import. `patterns` are passed to `getcompletion`, `raw` are given literally.
--- @param repo_dir? string the path to the `nvim-highlite` repo on-disk
function Import._all_nvim_to_highlite(ignore, repo_dir)
  • All of the built-in colorschemes (e.g. zellner) and this repo's colorschemes which are ported from another repo (e.g. highlite-ayu) are skipped by default.
  • The path to the repo is inferred, but you can specify it (to be safe, or if you have a second clone of this repo, etc).

For example, here is how to import all of your installed colorschemes except for catppuccin and a custom colorscheme:

:lua require('highlite.import')._all_nvim_to_highlite({patterns = {'catppuccin'}, raw = {'highlite-custom'}})
  • Run git diff just to make sure it worked correctly.