Skip to content

Commit e76baf3

Browse files
dasupradyumnadasupradyumna
committed
docs: added README.md
 * Added showcase images to `showcase/sample*.png` folder
1 parent 5c4fd5b commit e76baf3

22 files changed

+196
-27
lines changed

‎README.md

+164
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# :crescent_moon: Midnight
2+
3+
A modern black [neovim](https://github.com/neovim/neovim) theme written in Lua, with a strong focus
4+
on maintaining a comfortable level of color contrast for a pleasant visual experience while coding.
5+
6+
## Showcase
7+
8+
![Sample 1](showcase/sample1.png "Sample 1")
9+
10+
---
11+
12+
![Sample 2](showcase/sample2.png "Sample 2")
13+
14+
## Vision
15+
16+
As a lover of dark themes and all things black, I searched far and wide for black background
17+
colorschemes when I first started using **neovim**. Although I have used many well-crafted themes so
18+
far, it would always come down to choosing between one of these two: *healthy color contrast* and
19+
*focused semantic clarity*. It is quite difficult to nail the balance between both, especially when
20+
working with ***black*** backgrounds. Focusing too much on the former would result in a tame and
21+
uniform looking theme, whereas too much emphasis on the latter would cause the screen content to
22+
have sharp changes in color straining the eyes. I created this colorscheme to find the perfect
23+
balance between both, to provide focus and clarity while ensuring a healthy contrast level.
24+
25+
**midnight.nvim** leans towards mostly using shades of gray, followed by blue-green shades for a
26+
cooler UI color experience, while using warmer colors only for syntax and status. Most colors have
27+
sufficiently low saturation so they do not stand out against the jet black background to avoid eye
28+
strain when working for a longer duration (particularly beneficial in low-light conditions).
29+
30+
***NOTE: This plugin is a WIP. There are still a few color choices that I am not satisfied with and
31+
will be changed in the future. Other than these select few, most colors are stable and the theme's
32+
appearance will not change as a whole.***
33+
34+
## Features
35+
36+
- Support for treesitter and LSP syntax groups for multiple filetypes
37+
- Appropriate color contrast between content and UI to reduce eye strain while maintaining focus
38+
- Darker shades of gray for non-critical UI elements such as separators to reduce distraction
39+
- Consistent usage of the palette across plugins and neovim builtins to provide a unified IDE-like
40+
appearance
41+
- Warmer colors for multiple language syntax groups to attract attention intuitively in dense code
42+
files
43+
44+
#### Integrations
45+
46+
The following plugins have fully customized highlight groups -
47+
48+
- [lazy.nvim](https://github.com/folke/lazy.nvim)
49+
- [nvim-tree.lua](https://github.com/nvim-tree/nvim-tree.lua)
50+
- [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim)
51+
- [diffview.nvim](https://github.com/sindrets/diffview.nvim)
52+
- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
53+
- [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)
54+
- [todo-comments.nvim](https://github.com/folke/todo-comments.nvim)
55+
- [mason.nvim](https://github.com/williamboman/mason.nvim)
56+
- [nvim-dap-ui](https://github.com/rcarriga/nvim-dap-ui)
57+
- [nvim-cmp](https://github.com/hrsh7th/nvim-cmp)
58+
- [neorg](https://github.com/nvim-neorg/neorg)
59+
60+
## Installation
61+
62+
Install the colorscheme using the package manager that you love!
63+
64+
[lazy.nvim](https://github.com/folke/lazy.nvim)
65+
66+
```lua
67+
-- LazySpec (plugin specification)
68+
-- return {
69+
{ 'dasupradyumna/midnight.nvim', lazy = false, priority = 1000 }
70+
-- }
71+
```
72+
73+
[packer.nvim](https://github.com/wbthomason/packer.nvim)
74+
75+
```lua
76+
-- inside setup function
77+
-- packer.startup(function(use)
78+
use { 'dasupradyumna/midnight.nvim' }
79+
-- end)
80+
```
81+
82+
### Requirements
83+
84+
***midnight.nvim*** is a *GUI-only* colorscheme. It requires GUI client or a modern terminal version
85+
of **neovim** installed in a
86+
[true-color supported](https://github.com/termstandard/colors#truecolor-support-in-output-devices)
87+
terminal emulator.
88+
89+
**Neovim** version should be newer than 0.8.0.
90+
91+
## Usage
92+
93+
Add the following code snippet to load the colorscheme.
94+
95+
```lua
96+
-- Lua
97+
vim.cmd.colorscheme 'midnight'
98+
```
99+
100+
```vim
101+
" VimScript
102+
colorscheme midnight
103+
```
104+
105+
### Configuration
106+
107+
Configuration can be skipped if the user does not wish to change any of the default higlight groups.
108+
The plugin runs setup automatically when it is loaded using the `colorscheme` command.
109+
110+
For now, users can directly add overriding higlight groups as arguments to the `setup()` method.
111+
Better options will be added in the future to make the colorscheme customization simpler.
112+
113+
```lua
114+
require('midnight').setup {
115+
HighlightGroup = {
116+
fg = ForegroundColor, -- :h guifg
117+
bg = BackgroundColor, -- :h guibg
118+
sp = SpecialColor, -- :h guisp
119+
style = RenderStyle, -- :h attr-list
120+
-- OR
121+
link = TargetHiglightGroup -- :h :hi-link (link to "TargetHiglightGroup")
122+
-- OR
123+
clear = true -- :h :hi-clear (clear "HighlightGroup"; `false` ignores this option)
124+
},
125+
...
126+
}
127+
```
128+
129+
The evaluation priority of options within a highlight specification (*like above*) is:
130+
131+
1. When `clear = true` is specified, all other attributes are ignored
132+
2. When a `link` group name is specified, all attributes except `clear` are ignored
133+
3. Highlight specification using `fg`, `bg`, `sp` and `style` is evaluated only if above attributes
134+
are not specified
135+
136+
### Color Palette
137+
138+
Although quite limited in variety, **midnight.nvim** color palette can be used from
139+
[palette.lua](lua/midnight/palette.lua), if the user so wishes.
140+
141+
```lua
142+
local colors = require('midnight.colors')
143+
local p = colors.palette -- raw color palette
144+
local c = colors.components -- component color palette
145+
```
146+
147+
## Contributing
148+
149+
I encourage fellow contributors to submit PRs if they wish to fix a bug or add a feature.
150+
Since I cannot feasibly test out every single possibility, I would love it if contributors can help
151+
in improving the documentation especially for other package managers.
152+
I would also like help with LSP and treesitter groups for languages that have not been covered.
153+
154+
*Since this is my first plugin, all suggestions and advice from the more experienced are welcome.*
155+
156+
## Thanks
157+
158+
This colorscheme's design was inspired by **nyoom-engineering**'s
159+
[oxocarbon.nvim](https://github.com/nyoom-engineering/oxocarbon.nvim) and highlighting logic
160+
was inspired by **folke**'s [tokyonight.nvim](https://github.com/folke/tokyonight.nvim).
161+
162+
## License
163+
164+
**midnight.nvim** is licensed under the *Apache License 2.0*.

‎lua/midnight/palette.lua renamed to ‎lua/midnight/colors.lua

+1
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ local palette = {
7171

7272
local components = {
7373
-- main
74+
none = 'NONE',
7475
bg = '#080c10',
7576
fg = '#b5bdc5',
7677

‎lua/midnight/highlight/builtin.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
----------------------------------------------------------------------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
ColorColumn = { bg = p.black },

‎lua/midnight/highlight/common.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---------------------------------------- COMMON HIGHLIGHTS -----------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
Bold = { style = 'bold' },

‎lua/midnight/highlight/plugin/diffview.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
------------------------------------- DIFFVIEW.NVIM HIGHLIGHTS -------------------------------------
22

3-
local p = require('midnight.palette').palette
3+
local p = require('midnight.colors').palette
44

55
return {
66
DiffviewDim1 = { fg = p.gray[5] },

‎lua/midnight/highlight/plugin/lazy.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
--------------------------------------- LAZY.NVIM HIGHLIGHTS ---------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
LazyH1 = { fg = c.bg, bg = p.cyan[3] },

‎lua/midnight/highlight/plugin/mason.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
-------------------------------------- MASON.NVIM HIGHLIGHTS ---------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
MasonHeader = { fg = c.bg, bg = p.cyan[3], style = 'bold' },

‎lua/midnight/highlight/plugin/nvim-cmp.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
--------------------------------------- NVIM-CMP HIGHLIGHTS ----------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
CmpItemAbbr = { fg = p.gray[4] },

‎lua/midnight/highlight/plugin/nvim-dap-ui.lua

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
-------------------------------------- NVIM-DAP-UI HIGHLIGHTS --------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
DapUINormal = { link = 'Normal' },
@@ -14,10 +14,14 @@ return {
1414
DapUIValue = { link = 'Parameter' },
1515
DapUIModifiedValue = { fg = c.string, bg = p.cyan[5] },
1616
DapUIWatchesEmpty = { fg = c.error },
17+
DapUIWatchesError = { fg = c.error },
1718
DapUIWatchesValue = { link = 'DapUICustomFG' },
1819
DapUIStoppedThread = { link = 'DapUICustomFG' },
1920
DapUIFrameName = { link = 'Function' },
21+
DapUICurrentFrameName = { fg = c.method, style = 'bold,italic' },
2022
DapUISource = { link = 'Identifier' },
2123
DapUIBreakpointsPath = { link = 'DapUICustomFG' },
2224
DapUIBreakpointsInfo = { link = 'Type' },
25+
DapUIBreakpointsLine = { link = 'Operator' },
26+
DapUIBreakpointsCurrentLine = { fg = c.operator, style = 'bold,italic' },
2327
}

‎lua/midnight/highlight/plugin/nvim-lspconfig.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
------------------------------------ NVIM-LSPCONFIG HIGHLIGHTS -------------------------------------
22

3-
local p = require('midnight.palette').palette
3+
local p = require('midnight.colors').palette
44

55
return {
66
LspInfoList = { fg = p.blue[3] },

‎lua/midnight/highlight/plugin/nvim-tree.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
------------------------------------- NVIM-TREE.LUA HIGHLIGHTS -------------------------------------
22

3-
local p = require('midnight.palette').palette
3+
local p = require('midnight.colors').palette
44

55
return {
66
NvimTreeRootFolder = { fg = p.purple[2], style = 'bold' },

‎lua/midnight/highlight/plugin/telescope.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
------------------------------------ TELESCOPE.NVIM HIGHLIGHTS -------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
TelescopeTitle = { fg = c.fg },

‎lua/midnight/highlight/plugin/todo-comments.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---------------------------------- TODO-COMMENTS.NVIM HIGHLIGHTS -----------------------------------
22

3-
local c = require('midnight.palette').components
3+
local c = require('midnight.colors').components
44

55
return {
66
TodoBgFix = { fg = c.bg, bg = c.error, style = 'bold' },

‎lua/midnight/highlight/semantic/neorg.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
----------------------------------------- NEORG HIGHLIGHTS -----------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
['@neorg.anchors.declaration.norg'] = { fg = c.parameter, style = 'bold,underline' },

‎lua/midnight/highlight/standard/checkhealth.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
-------------------------------------- CHECKHEALTH HIGHLIGHTS --------------------------------------
22

3-
local c = require('midnight.palette').components
3+
local c = require('midnight.colors').components
44

55
return {
66
healthError = { fg = c.error, style = 'bold' },

‎lua/midnight/highlight/standard/diagnostics.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
-------------------------------------- DIAGNOSTICS HIGHLIGHTS --------------------------------------
22

3-
local c = require('midnight.palette').components
3+
local c = require('midnight.colors').components
44

55
return {
66
DiagnosticError = { fg = c.error, style = 'italic' },

‎lua/midnight/highlight/standard/diff.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
----------------------------------------- DIFF HIGHLIGHTS ------------------------------------------
22

3-
local p = require('midnight.palette').palette
3+
local p = require('midnight.colors').palette
44

55
return {
66
diffAdded = { link = 'DiffAdd' },

‎lua/midnight/highlight/standard/git.lua

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
------------------------------------------ GIT HIGHLIGHTS ------------------------------------------
22

3-
local p = require('midnight.palette').palette
4-
local c = require('midnight.palette').components
3+
local p = require('midnight.colors').palette
4+
local c = require('midnight.colors').components
55

66
return {
77
gitCommitHeader = { link = 'Title' },

‎lua/midnight/highlight/standard/help.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
----------------------------------------- HELP HIGHLIGHTS ------------------------------------------
22

3-
local c = require('midnight.palette').components
3+
local c = require('midnight.colors').components
44

55
return {
66
helpCommand = { fg = c.help_command },

‎lua/midnight/highlight/standard/syntax.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---------------------------------------- SYNTAX HIGHLIGHTS -----------------------------------------
22

3-
local c = require('midnight.palette').components
3+
local c = require('midnight.colors').components
44

55
return {
66
Comment = { fg = c.comment, style = 'italic' },

‎showcase/sample1.png

290 KB
Loading

‎showcase/sample2.png

358 KB
Loading

0 commit comments

Comments
 (0)