document how to extend and create own colorscheme

colors/neovim.lua

@@ -10,4 +10,5 @@ package.loaded["zenbones.neovim"] = nil
 
 require("zenbones.neovim.terminal").setup()
 
+-- include our theme file and pass it to lush to apply
 require "lush"(require "zenbones.neovim")

doc/zenbones.md

@@ -43,7 +43,8 @@ Change background colors darkness. Options: `'stark'`, `'warm'`.
 
 #### g:zenflesh_solid_vert_split
 
-Default: `v:false`. Make vertical split more distinguishable background highlight.
+Default: `v:false`. Make vertical split more distinguishable background
+highlight.
 
 #### g:zenbones_dim_noncurrent_window
 
@@ -75,3 +76,89 @@ print(palette.blossom.darken(20).hex)
 See also
 [Lush's documentation](https://github.com/rktjmp/lush.nvim#advanced-usage) for
 more options.
+
+### Create your own colorscheme
+
+You can ultimately create your own colorscheme that is based on Zenbones by
+modifying the base palette and extending the specs. Best way to demonstrate this
+is through an example. Let's make a zenbones-flavored Gruvbox colorscheme called
+`gruvbones`.
+
+Let's define our
+[colorscheme](https://neovim.io/doc/user/syntax.html#:colorscheme) in
+`nvim/colors/gruvbones.lua`. And it contains the following:
+
+```lua
+vim.g.colors_name = "gruvbones"
+
+-- let's base bg=dark, bg=light on zenflesh, zenbones specs respectively
+local base_name = vim.opt.background:get() == "dark" and "zenflesh" or "zenbones"
+
+-- reset base palette and specs
+package.loaded[base_name .. ".palette"] = nil
+package.loaded[base_name] = nil
+
+local lush = require "lush"
+local hsl = lush.hsl
+
+-- modify base palette (before requiring specs)
+-- and we can also define our own
+-- note: non-exhaustive copy of gruvbox palette. Ref: https://github.com/gruvbox-community/gruvbox#palette
+local base = require(base_name .. ".palette")
+local gruv
+if base_name == "zenbones" then
+	base.bg = hsl "#fbf1c7"
+	base.fg = hsl "#3c3836"
+	gruv = {
+		gray = hsl "#7c6f64",
+		fg0 = hsl "#282828",
+		fg1 = hsl "#3c3836",
+		fg2 = hsl "#504945",
+		fg3 = hsl "#665c54",
+		fg4 = hsl "#7c6f64",
+	}
+else
+	base.bg = hsl "#282828"
+	base.fg = hsl "#ebdbb2"
+	gruv = {
+		gray = hsl "#a89984",
+		fg0 = hsl "#fbf1c7",
+		fg1 = hsl "#ebdbb2",
+		fg2 = hsl "#d5c4a1",
+		fg3 = hsl "#d5c4a1",
+		fg4 = hsl "#a89984",
+	}
+end
+
+base.rose = hsl "#cc241d"
+base.leaf = hsl "#98971a"
+base.wood = hsl "#d79921"
+base.water = hsl "#458588"
+base.blossom = hsl "#b16286"
+base.sky = hsl "#689d6a"
+
+-- extend specs using Lush
+local theme = require(base_name)
+local specs = lush.extends({ theme }).with(function()
+	return {
+		Constant { fg = gruv.fg4, gui = "italic" },
+		Identifier { fg = gruv.fg2, gui = "italic" },
+		Special { fg = gruv.fg3, gui = "bold" },
+		Delimiter { fg = gruv.gray },
+		Comment { fg = gruv.gray, gui = "italic" },
+		LineNr { fg = Comment.fg },
+	}
+end)
+
+-- apply terminal colors
+require(base_name .. ".terminal").setup()
+
+-- include our theme file and pass it to lush to apply
+lush(specs)
+```
+
+And there you have it. Just call `colorscheme gruvbones` to use your new
+colorscheme. It respects `&background` and other configurations too.
+
+Also checkout the [neovim](colors/neovim.lua) colorscheme for a similarly
+complete example.

lua/zenbones/neovim/palette.lua

@@ -5,6 +5,7 @@ local base_name = require("zenbones.util").bg_to_base_name()
 local palette = require(base_name .. ".palette")
 
 if base_name == "zenbones" then
+	-- palette.bg = hsl "#d3e4db" -- --accent-bg-color
 	palette.bg = hsl "#e7eee8" -- --bg-color
 	palette.fg = hsl "#202e18" -- --accent-color
 	palette.leaf = palette.leaf.sa(24).li(8) -- need to make green more prominent