Skip to content

Latest commit

 

History

History
182 lines (142 loc) · 5.9 KB

CREATE.md

File metadata and controls

182 lines (142 loc) · 5.9 KB
Raw

Creating Your New Colorscheme With Lush

To create a Vim colorscheme in Lush you will:

  1. Copy the lush-template
  2. Create your colorscheme
    1. Import an existing non-lush colorscheme
  3. Add your colorscheme to nvim
  4. (optional) Export your colorscheme for distribution to non-Neovim clients.

See also, Advanced Usage and :h lush for more detailed documentation.

1. Copy the lush-template repo

Lush provides a starter structure that contains some boilerplate files and (most) of the default highlight groups that you may wish to edit.

First, clone down a copy of the template from rktjmp/lush-template while also picking a name for your colorscheme; don't worry, it's easy to change this later.

git clone https://github.com/rktjmp/lush-template.git <your_colorscheme_name>
cd <your_colorscheme_name>

Next we have to update some of the boilerplate files to match your new colorschemes name. You can copy and paste the script below into a zsh/bash prompt or perform the steps manually.

macOS users you might have to perform the sed lines manually. They're just updating some place holders in colors/<name.lua> and LICENSE. See also.

sh << "EOF"
  LUSH_NAME=$(basename $(pwd))
  GIT_NAME=$(git config user.name)
  YEAR=$(date +"%Y")
  mv colors/lush_template.lua colors/$LUSH_NAME.lua
  mv lua/lush_theme/lush_template.lua lua/lush_theme/$LUSH_NAME.lua
  if command -v sed &> /dev/null; then
    sed -i "s/lush_template/$LUSH_NAME/g" colors/$LUSH_NAME.lua
    sed -i "s/COPYRIGHT_NAME/$GIT_NAME/g" LICENSE
    sed -i "s/COPYRIGHT_YEAR/$YEAR/g" LICENSE
    git add .
  else
    echo "Could not find sed, please manually replace 'lush_template' with '$LUSH_NAME' in colors/$LUSH_NAME.vim, and update the LICENCE file."
  fi
EOF

Lets examine the provided structure:

cool_name/
  |-lua/
    |-lush_theme/
      |-cool_name.lua # contains your lush spec, this is what we'll edit next
  |-colors/
    |-cool_name.vim   # used to load your colorscheme into neovim

2. Create your colorscheme

Open your lua/lush_theme/*.lua file and run :Lushify.

Be sure to check out the the tutorial if you haven't yet (:LushRunTutorial) or see the docs (:h lush) more details. Also see the examples folder in the main repository.

You may prefer to disable LSP/Linters while editing your lush spec, as they can have trouble parsing the meta programming, or disable undefined global warninngs if your LSP supports annotations. For example, sumneko's lua-language-server accepts:

---@diagnostic disable: undefined-global
local colorscheme = lush(function()
-- your colorscheme here...

A simple lush-spec would look like this, though lush-template comes with a more comprehesive list of groups.

-- In cool_name/lua/lush_theme/cool_name.lua

-- require lush
local lush = require('lush')
local hsl = lush.hsl

-- lush() will parse the spec and
-- return a table containing all color information.
-- We return it for use in other files.
return lush(function()
  return {
    -- Define Vim's Normal highlight group.
    -- You can provide values with hsl/hsluv or anything that responds to `tostring`
    -- but be aware if you don't "wrap" your color in a hsl/hsluv call you
    -- wont have chainable access to the color "operators" (darken, etc).
    Normal { bg = hsl(208, 90, 30), fg = hsl("#A3CFF5") },

    -- Make whitespace slightly darker than normal.
    -- you must define Normal before deriving from it.
    Whitespace { fg = Normal.fg.darken(40) },

    -- Make comments look the same as whitespace, but with italic text
    Comment { Whitespace, gui="italic" },

    -- Clear all highlighting for CursorLine
    CursorLine { },
  }
end)

2.1 Import an existing non-lush colorscheme

Lush includes a built in command to extract the currently loaded colorscheme, and generate a lush_spec for it. This generated spec will be "greedy", it will contain all currently applied highlight groups which will make it somewhat disorganised and loud, but it may be useful as a starting point.

To import the currently applied highlights, simply open a new file and run :LushImport. The generated spec will be placed in the z register which you can paste with "zp.

3. Add your colorscheme to nvim

Lush colorschemes (like most vim colorschemes) act as plugins, so we have to add our colorscheme to neovim's runtime before we can load it. Most people will do this via a package manager.

Assuming your colorscheme is in ~/projects/cool_name:

-- when using packer-nvim
use '~/projects/cool_name'
-- example when using lazy.nvim
require("lazy").setup({
    { dir = '/home/your_username_here/projects/cool_name', lazy = true },
}

Alternatively, if you organize your plugins by having a separate file for each one in a dedicated plugins directory (e.g. ~/.config/nvim/lua/plugins), you should instead call setup in init.lua as you would normally:

-- ~/.config/nvim/init.lua
require("lazy").setup("plugins")

And treat Lush and your colorscheme directory as you would any other plugin, for example in lush.lua:

-- ~/.config/nvim/lua/plugins/lush.lua
return {
    "rktjmp/lush.nvim",
    { dir = '/home/your_username_here/projects/cool_name', lazy = true },
}

Note that it may not show up in the menu if you enter, for example, :colorscheme <tab>. However, the following should work:

colorscheme cool_name

4. (optional) Export your colorscheme for distribution to non-Neovim clients.

Lush uses Shipwright as its build system. See the build guide for more details.

Lush provides tools for use with Shipwright to export your colorscheme as:

  • Vim Script (for use with Vim, or Neovim)
  • Lua, with extension hooks to provide end-user configuration