Gondolin

A beautifully dark and calm Neovim color scheme, named after the hidden Elven city in Tolkien's legendarium.

"Great was the fall of Gondolin, greatest of the cities of the Elves."

Requirements

• Neovim >= 0.8.0
• truecolor terminal support
• undercurl terminal support (optional)

Installation

Install the theme with your preferred package manager, such as lazy.nvim:

{
  "wunki/gondolin.nvim",
  lazy = false,
  priority = 1000,
  opts = {},
}

Usage

Load the colorscheme:

Vim:

colorscheme gondolin

Neovim:

vim.cmd.colorscheme("gondolin")

A full plugin spec example using lazy.nvim:

return {
  "wunki/gondolin.nvim",
  lazy = false,
  priority = 1000,
  init = function()
    vim.cmd.colorscheme("gondolin")
  end,
  opts = {...},
}

Configuration

Important

Set the configuration BEFORE loading the color scheme to ensure the settings are applied, otherwise defaults will be used.

The default configuration can be found here

require("gondolin").setup({
  -- enable undercurls for underlined text
  undercurl = true,
  -- transparent background
  transparent = false,
  -- highlight background for the left gutter
  gutter = false,
  -- background for diagnostic virtual text
  diag_background = true,
  -- dim inactive windows. Disabled when transparent
  dim_inactive = false,
  -- set colors for terminal buffers
  terminal_colors = true,
  -- cache highlights and colors for faster startup.
  -- see Cache section for more details.
  cache = false,

  styles = {
    -- style for comments
    comment = { italic = true },
    -- style for functions
    functions = { italic = false },
    -- style for keywords
    keyword = { italic = false, bold = false },
    -- style for statements
    statement = { italic = false, bold = false },
    -- style for types
    type = { italic = false },
  },
  -- override default palette and theme colors
  colors = {
    palette = {},
    theme = {
      dark = {},
    },
  },
  -- adjust overall color balance [-1, 1]
  color_balance = {
    dark = { brightness = 0, saturation = 0 },
  },
  -- override highlight groups
  overrides = function(colors)
    return {}
  end,

  -- uses lazy.nvim, if installed, to automatically enable needed plugins
  auto_plugins = true,
  -- enable highlights for all plugins (disabled if using lazy.nvim)
  all_plugins = package.loaded.lazy == nil,
  -- manually enable/disable individual plugins.
  -- check the `groups/plugins` directory for the exact names
  plugins = {
    -- examples:
    -- rainbow_delimiters = true
    -- which_key = false
  },

  -- enable integrations with other applications
  integrations = {
    -- automatically set wezterm theme to match the current neovim theme
    wezterm = {
      enabled = false,
      -- neovim will write the theme name to this file
      -- wezterm will read from this file to know which theme to use
      path = (os.getenv("TEMP") or "/tmp") .. "/nvim-theme",
    },
  },
})

Cache

The color scheme comes with a cache option that can be used to speed up startup time.

When you set cache = true in your config, the theme colors and all of your edits/adjustments will be saved to a cache file. This is loaded at startup so colors don't need to be recomputed every time.

Any changes you make to your config (e.g. overriding colors or highlight groups) should automatically invalidate the cache and build a new one.

In rare cases where this doesn't happen and you notice your changes aren't being applied, you can manually rebuild the cache by running :GondolinCache.

Integrations

Lualine

This color scheme comes with a matching Lualine theme.

local gondolin = require("lualine.themes.gondolin-dark")

require("lualine").setup({
  options = {
    theme = gondolin,
    -- ... your lualine config
  },
})

WezTerm and WezTerm Tabline

If you use WezTerm and/or WezTerm Tabline, you can use the wezterm integration to automatically switch themes based on the current Neovim theme. This feature requires Wezterm automatic reload config to be turned on.

There are a few things to set up for this to work:

1. Enable the integration in your Neovim configuration:

require("gondolin").setup({
  integrations = {
    wezterm = {
      enabled = true,
      path = (os.getenv("TEMP") or "/tmp") .. "/nvim-theme"
    },
  },
})

2. Place the wezterm and wezterm tabline extras in the wezterm color scheme directory. Point wezterms config to that directory:

config.color_scheme_dirs = { "~/.config/wezterm/colors" } -- or wherever you want to store the themes

3. Copy theme_switcher.lua to where your wezterm config is. Add require("theme_switcher") to your wezterm config to load the theme switcher.

4. Update the theme_switcher.lua file with the correct paths to your files:

-- default colorscheme after neovim exits
local theme_default = "gondolin-dark"

-- this should match the path set in the neovim config
-- it's best to use a temporary directory for this
local theme_file = (os.getenv("TEMP") or "/tmp") .. "/nvim-theme"

-- relative path to the directory containing the tabline themes
-- e.g. if I have placed the tabline extra themes in ./colors/wezterm_tabline then this would be "colors.wezterm_tabline"
-- this is treated as a relative lua module that will be required by the theme switcher
local tabline_theme_dir = "colors.wezterm_tabline"

Customizing Colors

There are two kinds of colors: PaletteColors and ThemeColors.

PaletteColors are defined directly as RGB Hex strings, and have arbitrary names that recall their actual color. Conversely, ThemeColors are named and grouped semantically on the basis of their actual function.

In short, a palette defines all the available colors, while a theme maps the PaletteColors to specific ThemeColors and the same palette color may be assigned to multiple theme colors.

You can change both theme or palette colors using config.colors. All the palette color names can be found here, while their usage by each theme can be found here.

You can see a visual preview of the entire color palette here.

require('gondolin').setup({
  colors = {
    palette = {
      -- change all usages of these color names
      bg1 = "#000000",
      fg1 = "#FFFFFF",
    },
    theme = {
      -- change specific usages for the theme
      dark = {
        ui = {
          float = {
            fg = "#ff0000",
          },
        },
      },
    },
  }
})

You can also conveniently add/modify hlgroups using the config.overrides option. Supported keywords are the same for :h nvim_set_hl {val} parameter.

require("gondolin").setup({
  overrides = function(colors)
    return {
      -- Assign a static color to strings
      String = { fg = colors.palette.string, italic = true },
      -- theme colors will update dynamically when you change theme!
      SomePluginHl = { fg = colors.theme.syn.type, bold = true },
    }
  end,
})

Extracting colors

You can get the palette and theme colors from the colors module like this:

-- Get the colors for the current theme
local colors = require("gondolin.colors")
local palette_colors = colors.palette
local theme_colors = colors.theme

and use them in your opts function. Example:

{
  "wunki/gondolin.nvim",
  lazy = false,
  priority = 1000,
  opts = function()
    local colors = require("gondolin.colors")
    local palette_colors = colors.palette
    return {
      colors = {
        theme = {
          dark = {
            ui = {
              bg_dim = palette_colors.bg2,
            },
          },
        },
      },
    }
  end
}

Extras

• alacritty
• foot
• fzf (guide: fzf color schemes)
• ghostty
• kitty
• lazygit
• nushell
• opencode (guide: OpenCode themes)
• tailwind
• terminator
• termux
• tilix
• tmux
• vivid
• vscode terminal (guide: Visual Studio Code Theme Color)
• wezterm (guide: Defining a Color Scheme in a separate file)
• wezterm tabline (guide: tabline.wez)
• windows terminal (guide: Color schemes in Windows Terminal)
• zellij

Contributing

Pull requests are welcome for theme fixes, new features, and new extras.

Using the Conventional Commits format for commit messages is recommended.

For the extras, we use a simple template system that can be used to generate styles for the different themes.

How to add a new extra template:

1. Create a new template file in lua/gondolin/extras.
2. Add the name and output file extension to the extras table in lua/gondolin/extras/init.lua.
3. To check that your template compiles properly, run ./scripts/build.sh and check the newly compiled styles in the root extras directory.

Important

Please DO NOT commit the compiled files, as they are already automatically built by the CI.

Acknowledgements

• zed-dark by mattermill - The color palette this theme is based on
• kanagawa-paper.nvim by Simon Ho - The plugin structure this project is forked from
• kanagawa.nvim by Tommaso Laurenzi - Original theme architecture
• tokyonight.nvim by folke - Plugin architecture inspiration