Mellifluous

A colorscheme for Neovim. Pleasant and productive, with stronger highlights on important keywords.

Highlighted features

• Multiple color sets: Each color set presents a unique visual theme while adhering to the same set of productive highlight rules. Every color set can be customised.

• Layered backgrounds: Most UI elements have backgrounds with different shades of the background color and have no borders. This allows for easy differentiation between the relative importance of the elements and keeps the colorscheme looking minimal.

• Oklab color space: To truly achieve perceptually uniform variations of colors, all color modifications are done in this color space; thanks to mini.colors project for the code and idea.

• Small number of colors: Color sets use a small number of colors to provide distraction-free coding experience.

• Stronger highlights on important keywords: Keywords related to control flow have stronger highlights, making it easier to quickly understand the code.

Styled plugins

• Treesitter
• Native LSP
• Telescope
• NvimTree
• Neo-Tree
• Nvim-cmp
• Indent Blankline
• Startify
• Gitsigns
• Neorg

Installation and usage

Example with packer.nvim:

use({
    'ramojus/mellifluous.nvim',
    -- version = "v0.*", -- uncomment for stable config (some features might be missed if/when v1 comes out)
    config = function()
        require'mellifluous'.setup({}) -- optional, see configuration section.
        vim.cmd('colorscheme mellifluous')
    end,
})

Configuration

Here is an example with the default config. This is optional, and only relevant parts of the config can be included.

require 'mellifluous'.setup({
    dim_inactive = false,
    color_set = 'mellifluous',
    styles = { -- see :h attr-list for options. set {} for NONE, { option = true } for option
        comments = { italic = true },
        conditionals = {},
        folds = {},
        loops = {},
        functions = {},
        keywords = {},
        strings = {},
        variables = {},
        numbers = {},
        booleans = {},
        properties = {},
        types = {},
        operators = {},
        markup = {
            headings = { bold = true },
        },
    },
    transparent_background = {
        enabled = false,
        floating_windows = true,
        telescope = true,
        file_tree = true,
        cursor_line = true,
        status_line = false,
    },
    flat_background = {
        line_numbers = false,
        floating_windows = false,
        file_tree = false,
        cursor_line_number = false,
    },
    plugins = {
        cmp = true,
        gitsigns = true,
        indent_blankline = true,
        nvim_tree = {
            enabled = true,
            show_root = false,
        },
        neo_tree = {
            enabled = true,
        },
        telescope = {
            enabled = true,
            nvchad_like = true,
        },
        startify = true,
    },
})

Setting light theme

Set vim.opt.background to 'light'. This will only work on color sets that have light theme.

Color sets

Non-original color sets are made to match their original version as closely as possible with the same highlight rules as mellifluous.

These color sets don't get loaded, unless you specify them in a color_set option, so there is no performance impact.

Available color sets:

• mellifluous. Dark and light, original.
• alduin. Dark, link to original.
• mountain. Dark, link to original.
• tender. Dark, link to original.
• kanagawa_dragon. Dark, link to original.

Mellifluous color set configuration

Default config:

require 'mellifluous'.setup({
    mellifluous = {
        neutral = true, -- set this to false and bg_contrast to 'medium' for original mellifluous (then it was called meliora theme)
        bg_contrast = 'medium' -- options: 'soft', 'medium', 'hard'
    }
})

Overriding colors of a color set

The following snippet shows where and which colors can be overridden:

require 'mellifluous'.setup({
    <color_set_name> = { -- name any of the defined color sets
        color_overrides = {
            dark = { -- dark variant of the color set
                bg = nil, -- used for shades, on some color sets fg will be derived from this
                fg = nil, -- used for shades if shades_fg is undefined
                shades_fg = nil, -- used for shades (dimmed foregrounds)

                main_keywords = nil,
                other_keywords = nil,
                types = nil,
                operators = nil,
                strings = nil,
                functions = nil,
                constants = nil,
                comments = nil,

                red = nil, -- errors, deletes, bad spellings
                orange = nil, -- warnings, changes, unusual spellings
                green = nil, -- staged, additions
                blue = nil, -- information, new files
                purple = nil, -- hints, merge

                -- for better terminal highlights
                yellow = nil,
                cyan = nil,
            },
            light = { -- light variant of the color set
                -- same keys as in dark variant
            },
        }
    }
})

For example, to override a color for the main keywords group in the dark version of the mellifluous color set, one could do the following:

require 'mellifluous'.setup({
    mellifluous = {
        color_overrides = {
            dark = {
                main_keywords = '#e0e066'
            }
        }
    }
})

Overriding highlights of a color set

The following snippet shows how highlight overrides can be defined for a specific color set:

require 'mellifluous'.setup({
    <color_set_name> = { -- name any of the defined color sets
        -- config structure from here is the same as for global highlight overrides
    }
})

For further instructions, refer to overriding highlights section

Extra colors

In addition to the colors listed in available colors section, some color sets may have more colors available (cyan). To check your color set, refer to the source code for color sets and see if get_colors_* functions return any extra (optional) colors.

Overriding highlights

The following snippet shows how global (for any color set) highlight overrides can be defined:

require 'mellifluous'.setup({
    highlight_overrides = {
        dark = function(highlighter, colors) -- dark variant of the color set
            -- set highlights here (using highlighter)
        end,
        light = function(highlighter, colors) -- light variant of the color set
            -- set highlights here (using highlighter)
        end,
    }
})

For an example on how to set the highlights, check the source code for general highlights, where M.set function has the same signature as dark or light functions seen above. A detailed documentation is provided below.

Highlighter usage

This is the signature to set a highlight:

highlighter.set(name, definition_map)

Parameters:

• name: highlight group name in string format
• definition_map: highlight definition map in table format, the supported keys can be found in :h nvim_set_hl. Keys fg, bg and sp can also be set to any of the available colors (see available colors).

To get an existing highlight, use this function:

highlighter.get(name)

This function returns highlight definition map for highlight group with the requested name.

Available colors

To use one of the available colors from a color set, in highlight definition map, set the value of fg, bg or sp key to colors.available_color

Available colors:

• Syntax element colors.
  • main_keywords: used to indicate keywords related to control flow.
  • other_keywords
  • types
  • operators
  • strings
  • functions
  • constants
  • comments
  • fg: in code -- identifiers.
  • bg
• Named colors. Used for terminal colors, but most of these colors will match some syntax element color.
  • red
  • orange
  • green
  • blue
  • purple
  • yellow
• UI colors. Same as named colors, but all are of the same brightness (lightness).
  • ui_red: used to indicate errors, deletes, bad spellings.
  • ui_orange: used to indicate warnings, changes, other (strange) spellings.
  • ui_green: used to indicate staged, additions.
  • ui_blue: used to indicate information, new files.
  • ui_purple: used to indicate hints, merge.
  • ui_yellow

NOTE: some color sets may have more colors available. See extra colors section.

Color functions

Every color from available colors has the following meta functions (accessed with : operator):

• lightened(val): returns color with val added current to lightness.
• darkened(val): returns color with val subtracted from current lightness.
• with_lightness(val): returns color with specified lightness, where val can be from 0 to 100.
• saturated(val): returns color with val added to current saturation.
• desaturated(val): returns color with val subtracted from current saturation.
• with_saturation(val): returns color with specified saturation, where val can be from 0 to 100.

To create your own color that has the same functions available, use require('mellifluous.color').new(hex_value) function.

CLI options

Type :Mellifluous <TAB> and see the available options.

Options include:

• Toggling transparency.
• Changing color set.

TODO

• Support more plugins (contributions are welcome).

Ports

• Helix (with slightly outdated color palette)

Inspiration

• Mountain and Mountaineer
• Alduin
• Melange
• Sema

License

MIT