farout.nvim.txt*     For Neovim >= 0.8.0     Last change: 2024 January 31

==============================================================================
Table of Contents                          *farout.nvim-table-of-contents*

1. FarOut                                   |farout.nvim-far-out|
  - Features                            |farout.nvim-far-out-features|
  - Requirements                    |farout.nvim-far-out-requirements|
  - Installation                    |farout.nvim-far-out-installation|
  - Usage                                  |farout.nvim-far-out-usage|
  - Configuration                  |farout.nvim-far-out-configuration|
  - Overriding Colors & Highlight Groups|farout.nvim-far-out-overriding-colors-&-highlight-groups|
  - Extras                                |farout.nvim-far-out-extras|
  - Contributing                    |farout.nvim-far-out-contributing|

==============================================================================
1. FarOut                                   *farout.nvim-far-out*

A dark and light Neovim <https://github.com/neovim/neovim> theme written in Lua
<https://www.lua.org> ported from the Visual Studio Code FarOut
<https://github.com/enkia/far-out-vscode-theme> theme. Includes
|farout.nvim-extra| themes for Kitty
<https://sw.kovidgoyal.net/kitty/conf.html>, Alacritty
<https://github.com/alacritty/alacritty>, iTerm <https://iterm2.com/> and Fish
<https://fishshell.com/docs/current/index.html>.


FEATURES                                *farout.nvim-far-out-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/folke/farout.nvim>
    |farout.nvim-extras| for numerous other applications.


EXTRAS ~

- 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>)
- Fzf <https://github.com/junegunn/fzf> (fzf <extras/fzf>)
- 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>)


REQUIREMENTS                        *farout.nvim-far-out-requirements*

- Neovim <https://github.com/neovim/neovim> >=
    0.7.2 <https://github.com/neovim/neovim/releases/tag/v0.7.2>


INSTALLATION                        *farout.nvim-far-out-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                                      *farout.nvim-far-out-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 ~

>lua
    vim.cmd[[colorscheme farout]]
<


EXTERNAL PLUGINS


BARBECUE

>lua
    -- Lua
    require('barbecue').setup {
      -- ... your barbecue config
      theme = 'farout',
      -- ... your barbecue config
    }
<


LUALINE

>lua
    -- Lua
    require('lualine').setup {
      options = {
        -- ... your lualine config
        theme = 'farout'
        -- ... your lualine config
      }
    }
<


LIGHTLINE

>vim
    " Vim Script
    let g:lightline = {'colorscheme': 'farout'}
<


CONFIGURATION                      *farout.nvim-far-out-configuration*


  Set the configuration **BEFORE** loading the color scheme with `colorscheme
  farout`.
The theme offers four styles: |farout.nvim-storm|, |farout.nvim-moon|,
|farout.nvim-night|, and |farout.nvim-day|.

The |farout.nvim-day| style is used when `{ style = "day" }` is passed to
`setup(options)` or when `vim.o.background = "light"`.

FarOut <https://github.com/folke/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*farout.nvim-far-out-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)`.
2. These `colors` are utilized to generate the highlight groups.
3. `config.on_highlights(highlights, colors)` can be used to override highlight
groups.

For default values of `colors` and `highlights`, please consult the night
<extras/lua/farout_night.lua>, and day <extras/lua/farout_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 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 ~

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                                    *farout.nvim-far-out-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                        *farout.nvim-far-out-contributing*

Pull requests are welcome.

For the |farout.nvim-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 |farout.nvim-extra| 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.



==============================================================================
2. Links                                               *farout.nvim-links*

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl:
