290 lines
9.6 KiB
Markdown
290 lines
9.6 KiB
Markdown
# FarOut
|
|
|
|
FarOut colorscheme for NeoVim.
|
|
|
|
## ✨ Features
|
|
|
|
- Supports the latest [Neovim](https://github.com/neovim/neovim)
|
|
[0.9.0](https://github.com/neovim/neovim/releases/tag/v0.9.0) features.
|
|
- Enhances terminal colors.
|
|
- Introduces a darker background option for sidebar-like windows.
|
|
- Supports all major plugins.
|
|
- Provides [Farout](https://github.com/thallada/farout.nvim)
|
|
[extras](#-extras) for numerous other applications.
|
|
|
|
### 🍭 Extras
|
|
|
|
<!-- extras:start -->
|
|
- [Alacritty](https://github.com/alacritty/alacritty) ([alacritty](extras/alacritty))
|
|
- [Delta](https://github.com/dandavison/delta) ([delta](extras/delta))
|
|
- [Dunst](https://dunst-project.org/) ([dunst](extras/dunst))
|
|
- [Fish](https://fishshell.com/docs/current/index.html) ([fish](extras/fish))
|
|
- [Fish Themes](https://fishshell.com/docs/current/interactive.html#syntax-highlighting) ([fish_themes](extras/fish_themes))
|
|
- [Foot](https://codeberg.org/dnkl/foot) ([foot](extras/foot))
|
|
- [GitUI](https://github.com/extrawurst/gitui) ([gitui](extras/gitui))
|
|
- [Helix](https://helix-editor.com/) ([helix](extras/helix))
|
|
- [iTerm](https://iterm2.com/) ([iterm](extras/iterm))
|
|
- [Kitty](https://sw.kovidgoyal.net/kitty/conf.html) ([kitty](extras/kitty))
|
|
- [Lua Table for testing](https://www.lua.org) ([lua](extras/lua))
|
|
- [Prism](https://prismjs.com) ([prism](extras/prism))
|
|
- [Sublime Text](https://www.sublimetext.com/docs/themes) ([sublime](extras/sublime))
|
|
- [Terminator](https://gnome-terminator.readthedocs.io/en/latest/config.html) ([terminator](extras/terminator))
|
|
- [Tilix](https://github.com/gnunn1/tilix) ([tilix](extras/tilix))
|
|
- [Tmux](https://github.com/tmux/tmux/wiki) ([tmux](extras/tmux))
|
|
- [WezTerm](https://wezfurlong.org/wezterm/config/files.html) ([wezterm](extras/wezterm))
|
|
- [Windows Terminal](https://aka.ms/terminal-documentation) ([windows_terminal](extras/windows_terminal))
|
|
- [Xfce Terminal](https://docs.xfce.org/apps/terminal/advanced) ([xfceterm](extras/xfceterm))
|
|
- [Xresources](https://wiki.archlinux.org/title/X_resources) ([xresources](extras/xresources))
|
|
- [Zathura](https://pwmt.org/projects/zathura/) ([zathura](extras/zathura))
|
|
<!-- extras:end -->
|
|
|
|
## ⚡️ Requirements
|
|
|
|
- [Neovim](https://github.com/neovim/neovim) >=
|
|
[0.7.2](https://github.com/neovim/neovim/releases/tag/v0.7.2)
|
|
|
|
## 📦 Installation
|
|
|
|
Install the theme with your preferred package manager, such as
|
|
[folke/lazy.nvim](https://github.com/folke/lazy.nvim):
|
|
|
|
```lua
|
|
{
|
|
"thallada/farout.nvim",
|
|
lazy = false,
|
|
priority = 1000,
|
|
opts = {},
|
|
}
|
|
```
|
|
|
|
## 🚀 Usage
|
|
|
|
### Vim Script
|
|
|
|
```vim
|
|
colorscheme farout
|
|
|
|
" There are also colorschemes for the different styles.
|
|
" colorscheme farout-night
|
|
" colorscheme farout-storm
|
|
" colorscheme farout-day
|
|
" colorscheme farout-moon
|
|
```
|
|
|
|
### [Lua](https://www.lua.org)
|
|
|
|
```lua
|
|
vim.cmd[[colorscheme farout]]
|
|
```
|
|
|
|
#### External Plugins
|
|
|
|
##### [Barbecue](https://github.com/utilyre/barbecue.nvim)
|
|
|
|
```lua
|
|
-- Lua
|
|
require('barbecue').setup {
|
|
-- ... your barbecue config
|
|
theme = 'farout',
|
|
-- ... your barbecue config
|
|
}
|
|
```
|
|
|
|
##### [Lualine](https://github.com/nvim-lualine/lualine.nvim)
|
|
|
|
```lua
|
|
-- Lua
|
|
require('lualine').setup {
|
|
options = {
|
|
-- ... your lualine config
|
|
theme = 'farout'
|
|
-- ... your lualine config
|
|
}
|
|
}
|
|
```
|
|
|
|
##### [Lightline](https://github.com/itchyny/lightline.vim)
|
|
|
|
```vim
|
|
" Vim Script
|
|
let g:lightline = {'colorscheme': 'farout'}
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
> ❗️ Set the configuration **BEFORE** loading the color scheme with `colorscheme farout`.
|
|
|
|
The theme offers four styles: [storm](#storm), [moon](#moon), [night](#night),
|
|
and [day](#day).
|
|
|
|
The [day](#day) style is used when `{ style = "day" }` is passed to
|
|
`setup(options)` or when `vim.o.background = "light"`.
|
|
|
|
[FarOut](https://github.com/thallada/farout.nvim) uses the default options,
|
|
unless `setup` is explicitly called.
|
|
|
|
```lua
|
|
require("farout").setup({
|
|
-- your configuration comes here
|
|
-- or leave it empty to use the default settings
|
|
style = "storm", -- The theme comes in three styles, `storm`, `moon`, a darker variant `night` and `day`
|
|
light_style = "day", -- The theme is used when the background is set to light
|
|
transparent = false, -- Enable this to disable setting the background color
|
|
terminal_colors = true, -- Configure the colors used when opening a `:terminal` in [Neovim](https://github.com/neovim/neovim)
|
|
styles = {
|
|
-- Style to be applied to different syntax groups
|
|
-- Value is any valid attr-list value for `:help nvim_set_hl`
|
|
comments = { italic = true },
|
|
keywords = { italic = true },
|
|
functions = {},
|
|
variables = {},
|
|
-- Background styles. Can be "dark", "transparent" or "normal"
|
|
sidebars = "dark", -- style for sidebars, see below
|
|
floats = "dark", -- style for floating windows
|
|
},
|
|
sidebars = { "qf", "help" }, -- Set a darker background on sidebar-like windows. For example: `["qf", "vista_kind", "terminal", "packer"]`
|
|
day_brightness = 0.3, -- Adjusts the brightness of the colors of the **Day** style. Number between 0 and 1, from dull to vibrant colors
|
|
hide_inactive_statusline = false, -- Enabling this option, will hide inactive statuslines and replace them with a thin border instead. Should work with the standard **StatusLine** and **LuaLine**.
|
|
dim_inactive = false, -- dims inactive windows
|
|
lualine_bold = false, -- When `true`, section headers in the lualine theme will be bold
|
|
|
|
--- You can override specific color groups to use other groups or a hex color
|
|
--- function will be called with a ColorScheme table
|
|
---@param colors ColorScheme
|
|
on_colors = function(colors) end,
|
|
|
|
--- You can override specific highlights to use other groups or a hex color
|
|
--- function will be called with a Highlights and ColorScheme table
|
|
---@param highlights Highlights
|
|
---@param colors ColorScheme
|
|
on_highlights = function(highlights, colors) end,
|
|
})
|
|
```
|
|
|
|
## 🪓 Overriding Colors & Highlight Groups
|
|
|
|
How the highlight groups are calculated:
|
|
|
|
1. `colors` are determined based on your configuration, with the ability to
|
|
override them using `config.on_colors(colors)`.
|
|
1. These `colors` are utilized to generate the highlight groups.
|
|
1. `config.on_highlights(highlights, colors)` can be used to override highlight
|
|
groups.
|
|
|
|
For default values of `colors` and `highlights`, please consult the
|
|
[storm](extras/lua/tokyonight_storm.lua),
|
|
[moon](extras/lua/tokyonight_moon.lua),
|
|
[night](extras/lua/tokyonight_night.lua), and
|
|
[day](extras/lua/tokyonight_day.lua) themes.
|
|
|
|
### Settings and color alteration demonstration
|
|
|
|
```lua
|
|
require("farout").setup({
|
|
-- use the night style
|
|
style = "night",
|
|
-- disable italic for functions
|
|
styles = {
|
|
functions = {}
|
|
},
|
|
sidebars = { "qf", "vista_kind", "terminal", "packer" },
|
|
-- Change the "hint" color to the "orange" color, and make the "error" color bright red
|
|
on_colors = function(colors)
|
|
colors.hint = colors.orange
|
|
colors.error = "#ff0000"
|
|
end
|
|
})
|
|
```
|
|
|
|
### [Borderless Telescope](https://github.com/nvim-telescope/telescope.nvim/wiki/Gallery#borderless) example
|
|
|
|
```lua
|
|
require("farout").setup({
|
|
on_highlights = function(hl, c)
|
|
local prompt = "#2d3149"
|
|
hl.TelescopeNormal = {
|
|
bg = c.bg_dark,
|
|
fg = c.fg_dark,
|
|
}
|
|
hl.TelescopeBorder = {
|
|
bg = c.bg_dark,
|
|
fg = c.bg_dark,
|
|
}
|
|
hl.TelescopePromptNormal = {
|
|
bg = prompt,
|
|
}
|
|
hl.TelescopePromptBorder = {
|
|
bg = prompt,
|
|
fg = prompt,
|
|
}
|
|
hl.TelescopePromptTitle = {
|
|
bg = prompt,
|
|
fg = prompt,
|
|
}
|
|
hl.TelescopePreviewTitle = {
|
|
bg = c.bg_dark,
|
|
fg = c.bg_dark,
|
|
}
|
|
hl.TelescopeResultsTitle = {
|
|
bg = c.bg_dark,
|
|
fg = c.bg_dark,
|
|
}
|
|
end,
|
|
})
|
|
```
|
|
|
|
### Fix `undercurls` in [Tmux](https://github.com/tmux/tmux)
|
|
|
|
To have undercurls show up and in color, add the following to your
|
|
[Tmux](https://github.com/tmux/tmux) configuration file:
|
|
|
|
```sh
|
|
# Undercurl
|
|
set -g default-terminal "${TERM}"
|
|
set -as terminal-overrides ',*:Smulx=\E[4::%p1%dm' # undercurl support
|
|
set -as terminal-overrides ',*:Setulc=\E[58::2::%p1%{65536}%/%d::%p1%{256}%/%{255}%&%d::%p1%{255}%&%d%;m' # underscore colours - needs tmux-3.0
|
|
```
|
|
|
|
## 🍭 Extras
|
|
|
|
Extra color configs for [Kitty](https://sw.kovidgoyal.net/kitty/conf.html),
|
|
[Alacritty](https://github.com/alacritty/alacritty),
|
|
[Fish](https://fishshell.com/docs/current/index.html), [WezTerm](https://wezfurlong.org/wezterm/config/files.html),
|
|
[iTerm](https://iterm2.com/) and [foot](https://codeberg.org/dnkl/foot) can be
|
|
found in [extras](extras/). To use them, refer to their respective
|
|
documentation.
|
|
|
|
|
|
|
|
You can easily use the color palette for other plugins inside your
|
|
[Neovim](https://github.com/neovim/neovim) configuration:
|
|
|
|
```lua
|
|
local colors = require("farout.colors").setup() -- pass in any of the config options as explained above
|
|
local util = require("farout.util")
|
|
|
|
aplugin.background = colors.bg_dark
|
|
aplugin.my_error = util.lighten(colors.red1, 0.3) -- number between 0 and 1. 0 results in white, 1 results in red1
|
|
```
|
|
|
|
## 🔥 Contributing
|
|
|
|
Pull requests are welcome.
|
|
|
|
For the [extras](#-extras), we use a simple template system that can be used to
|
|
generate themes for the different styles.
|
|
|
|
How to add a new extra template:
|
|
|
|
1. Create a file like `lua/farout/extra/cool-app.lua`.
|
|
2. Add the name and output file extension to the `extras` table in
|
|
`lua/farout/extra/init.lua`.
|
|
3. Run the following command to generate new [extra](#-extras) themes from the farout plugin directory:
|
|
|
|
```sh
|
|
nvim --headless "+lua require('farout.extra').setup()" +qa
|
|
```
|
|
|
|
4. Check the newly created themes in the `extra/` directory. Please **DO NOT**
|
|
commit them, as they are already automatically built by the CI.
|