From e3298b3e6d1c2b926bd6a7ad1671ddcc36ce3615 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Umut=20Topuzo=C4=9Flu?= Date: Wed, 16 Sep 2026 11:10:00 +0200 Subject: [PATCH 1/3] docs: auto generate help file --- .github/workflows/panvimdoc.yml | 30 +++++ README.md | 206 +++++++++++++++++--------------- doc/.gitkeep | 0 lua/bluloco/init.lua | 10 +- 4 files changed, 148 insertions(+), 98 deletions(-) create mode 100644 .github/workflows/panvimdoc.yml create mode 100644 doc/.gitkeep diff --git a/.github/workflows/panvimdoc.yml b/.github/workflows/panvimdoc.yml new file mode 100644 index 0000000..cdaead7 --- /dev/null +++ b/.github/workflows/panvimdoc.yml @@ -0,0 +1,30 @@ +name: panvimdoc + +on: + push: + branches: [main] + paths: + - README.md + +permissions: + contents: write + +jobs: + docs: + runs-on: ubuntu-latest + name: generate vimdoc + steps: + - uses: actions/checkout@v4 + - name: generate vimdoc + uses: kdheepak/panvimdoc@v5.0.0 + with: + vimdoc: bluloco + description: "A fancy and sophisticated designer neovim theme" + version: "Neovim" + demojify: true + treesitter: true + ignorerawblocks: true + shiftheadinglevelby: -1 + - uses: stefanzweifel/git-auto-commit-action@v5 + with: + commit_message: "chore(docs): auto generate vimdoc" diff --git a/README.md b/README.md index ab018e1..9775254 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,17 @@ + + ![banner-light](./screenshots/banner-light.svg#gh-light-mode-only) ![banner-dark](./screenshots/banner-dark.svg#gh-dark-mode-only) + + # Bluloco.nvim A fancy and sophisticated designer neovim theme built with [lush.nvim](https://github.com/rktjmp/lush.nvim). It features a much more comprehensive usage of syntax scopes and color consistency, with due regards to aesthetics, contrast and readability. There is a light and dark variant. -Most popular plugins are also supported, see [Plugins](#plugins) +Most popular plugins are also supported, see [Plugins](#plugin-support) This theme also works very good with blue light filters like Apple's _Nightshift Mode_ or _f.lux_. @@ -15,7 +19,9 @@ This is a port of the popular Visual Studio Code Themes [Bluloco Light](https://github.com/uloco/theme-bluloco-light) and [Bluloco Dark](https://github.com/uloco/theme-bluloco-dark) -### Support + + +## Support If you like using this, please consider donating a little bit. It takes a lot of time to keep this updated with neovim and plugin updates. I want to keep bluloco a great experience for everybody and your help would be immensely motivating to keep me doing this. :) @@ -30,6 +36,8 @@ I want to keep bluloco a great experience for everybody and your help would be i ![light](./screenshots/light.png) + + ## Features - Auto switching light & dark style @@ -37,58 +45,11 @@ I want to keep bluloco a great experience for everybody and your help would be i - Exhaustive plugin support - Written in lua -## Plugins - -Currently supported (aka. tested) plugins: - -- [treesitter](https://github.com/nvim-treesitter/nvim-treesitter) -- [hlargs](https://github.com/m-demare/hlargs.nvim) -- [alpha-nvim](https://github.com/goolord/alpha-nvim) -- [nvim-notify](https://github.com/rcarriga/nvim-notify) -- [mason.nvim](https://github.com/williamboman/mason.nvim) -- [nvim-cursorword](https://github.com/xiyaowong/nvim-cursorword) -- [vim-illuminate](https://github.com/RRethy/vim-illuminate) -- [nvim-scrollbar](https://github.com/petertriho/nvim-scrollbar) -- [lualine.nvim](https://github.com/hoob3rt/lualine.nvim) -- [barbar.nvim](https://github.com/romgrk/barbar.nvim) -- [nvim-bufferline.lua](https://github.com/akinsho/nvim-bufferline.lua) -- [indent-blankline.nvim](https://github.com/lukas-reineke/indent-blankline.nvim) -- [neogit](https://github.com/TimUntersberger/neogit) -- [diffview.nvim](https://github.com/sindrets/diffview.nvim) -- [codediff.nvim](https://github.com/esmuellert/codediff.nvim) -- [render-markdown.nvim](https://github.com/meanderingprogrammer/render-markdown.nvim) -- [git-conflict.nvim](https://github.com/akinsho/git-conflict.nvim) -- [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim) -- [nvim-cmp](https://github.com/hrsh7th/nvim-cmp) -- [blink.cmp](https://github.com/saghen/blink.cmp) -- [blink.pairs](https://github.com/saghen/blink.pairs) -- [vim-which-key](https://github.com/liuchengxu/vim-which-key) -- [which-key.nvim](https://github.com/folke/which-key.nvim) -- [todo-comments.nvim](https://github.com/folke/todo-comments.nvim) -- [trouble.nvim](https://github.com/folke/trouble.nvim) -- [nvim-tree.lua](https://github.com/kyazdani42/nvim-tree.lua) -- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) -- [telescope-file-browser.nvim](https://github.com/nvim-telescope/telescope-file-browser.nvim) -- [fzf-lua](https://github.com/ibhagwan/fzf-lua) -- [lsp-config](https://github.com/neovim/lsp-config) -- [lspsaga.nvim](https://github.com/glepnir/lspsaga.nvim) -- [leap.nvim](https://github.com/ggandor/leap.nvim) -- [flash.nvim](https://github.com/folke/flash.nvim) -- [snacks.nvim](https://github.com/folke/snacks.nvim) -- [neotest](https://github.com/nvim-neotest/neotest) -- [rainbow-delimiters.nvim](https://github.com/HiPhish/rainbow-delimiters.nvim) -- [copilot.vim](https://github.com/github/copilot.vim) -- [copilot.lua](https://github.com/zbirenbaum/copilot.lua) -- [nvim-ufo](https://github.com/kevinhwang91/nvim-ufo) -- [virt-column.nvim](https://github.com/lukas-reineke/virt-column.nvim) -- [conflict.nvim](https://github.com/is0n/conflict.nvim) - -### Plugin showcase +## Requirements -You can see a lot of screenshots of themed plugins in the [wiki page](https://github.com/uloco/bluloco.nvim/wiki#screenshots). -No config needed, works out of the box. +[lush.nvim](https://github.com/rktjmp/lush.nvim) is required. -## Install +## Installation Install Bluloco with your favorite package manager. @@ -99,9 +60,6 @@ vim.pack.add({ 'https://github.com/uloco/bluloco.nvim', 'https://github.com/rktjmp/lush.nvim', }) - --- If configuring the colorscheme is wanted -require('bluloco').setup({}) ``` ### [lazy.nvim](https://github.com/folke/lazy.nvim) @@ -113,26 +71,15 @@ require('bluloco').setup({}) priority = 1000, dependencies = { 'rktjmp/lush.nvim' }, opts = {}, -}, +} ``` ## Usage -> ⚠️ The `setup()` function is optional but please call it +> The `setup()` function is optional but please call it > **before** you set the colorscheme if you want to adjust the config. -These are the default values: - ```lua -require("bluloco").setup({ - style = "auto", -- "auto" | "dark" | "light" - transparent = false, - italics = false, - terminal = vim.fn.has("gui_running") == 1, -- bluoco colors are enabled in gui terminals per default. - guicursor = true, - float_window = "default" -- "default" | "transparent" -}) - vim.opt.termguicolors = true vim.cmd('colorscheme bluloco') ``` @@ -145,72 +92,130 @@ These are especially helpful when switching in an already running vim session. :colorscheme bluloco-light ``` -#### Lualine +## Configuration -Make sure your lualine settings are set to auto: +These are the default values: ```lua -require('lualine').setup({ - options = { - theme = 'auto' - } +require("bluloco").setup({ + style = "auto", -- "auto" | "dark" | "light" + transparent = false, + italics = false, + terminal = vim.fn.has("gui_running") == 1, -- bluloco colors are enabled in gui terminals per default. + guicursor = true, + float_window = "default" -- "default" | "transparent" }) ``` -## Config - -### style +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `style` | `"auto"` \| `"dark"` \| `"light"` | `"auto"` | Select the variant. `"auto"` follows `vim.o.background`. | +| `transparent` | `boolean` | `false` | Use the terminal background. | +| `italics` | `boolean` | `false` | Use italics for keywords, comments, and markup attributes. | +| `terminal` | `boolean` | GUI: `true`; terminal: `false` | Set builtin terminal colors. | +| `guicursor` | `boolean` | `true` | Set a colored `guicursor`. | +| `float_window` | `"default"` \| `"transparent"` | `"default"` | Control float backgrounds with transparency. | There are three styles you can configure here: `auto`, `dark` and `light`. The `auto` setting is the default and will adjust automatically to your `vim.o.background` value. If you change this value during runtime, it will also adjust accordingly. -> ℹ️ The style value only applies if you set the theme with `vim.cmd('colorscheme bluloco')`. +> The style value only applies if you set the theme with `vim.cmd('colorscheme bluloco')`. > Setting the theme with a variant directly will override this setting. -### transparency (default: false) - This setting will disable the background and use the default background of your terminal. You need to enable this if you want the terminal to be transparent. You would still need to configure your terminal accordingly for light and dark backgrounds when switching often. -### italics (default: false) - This setting will enable italics for _keywords_, _comments_ and _markup attributes_. -### terminal (default: true in gui, otherwise false) - This setting will enable the bluloco colors in your integrated terminal. You most likely want to keep your terminal colors instead of overriding them if you are running neovim in a terminal. When you are running neovim inside a gui application this setting is enabled per default. You can skip the `terminal` setting completely to have it disabled in terminals and enabled in gui neovim. -> ℹ️ Please note that some terminals will display bold text as the bright color variant but enabling this feature will override this behavior in the integrated terminal. This is by design and has nothing to do with this theme. [see](https://github.com/neovim/neovim/issues/11335) - -### guicursor (default: true) +> Please note that some terminals will display bold text as the bright color variant but enabling this feature will override this behavior in the integrated terminal. This is by design and has nothing to do with this theme. [see](https://github.com/neovim/neovim/issues/11335) This setting sets a guicursor to fix your terminal cursor and make it colorful (as intended). It is enabled by default. If you want to override this, make sure to set your `:set guicursor` after loading the theme or disable it completely. -### float_window (default: "default") - Controls how floating windows look when `transparent` is enabled. The default keeps a solid float background for better contrast, while setting it to `"transparent"` will also make floating windows inherit your terminal background (useful if you prefer a fully transparent UI). - +## Plugin support -## Terminal Colors +Currently supported (aka. tested) plugins: -I've added a bunch of terminal themes for your terminal emulators. I've used the great [iTerm-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes) -repository for this, thanks @mbadolato! +- [treesitter](https://github.com/nvim-treesitter/nvim-treesitter) +- [hlargs](https://github.com/m-demare/hlargs.nvim) +- [alpha-nvim](https://github.com/goolord/alpha-nvim) +- [nvim-notify](https://github.com/rcarriga/nvim-notify) +- [mason.nvim](https://github.com/williamboman/mason.nvim) +- [nvim-cursorword](https://github.com/xiyaowong/nvim-cursorword) +- [vim-illuminate](https://github.com/RRethy/vim-illuminate) +- [nvim-scrollbar](https://github.com/petertriho/nvim-scrollbar) +- [lualine.nvim](https://github.com/hoob3rt/lualine.nvim) +- [barbar.nvim](https://github.com/romgrk/barbar.nvim) +- [nvim-bufferline.lua](https://github.com/akinsho/nvim-bufferline.lua) +- [indent-blankline.nvim](https://github.com/lukas-reineke/indent-blankline.nvim) +- [neogit](https://github.com/TimUntersberger/neogit) +- [diffview.nvim](https://github.com/sindrets/diffview.nvim) +- [codediff.nvim](https://github.com/esmuellert/codediff.nvim) +- [render-markdown.nvim](https://github.com/meanderingprogrammer/render-markdown.nvim) +- [git-conflict.nvim](https://github.com/akinsho/git-conflict.nvim) +- [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim) +- [vim-fugitive](https://github.com/tpope/vim-fugitive) +- [nvim-cmp](https://github.com/hrsh7th/nvim-cmp) +- [blink.cmp](https://github.com/saghen/blink.cmp) +- [blink.pairs](https://github.com/saghen/blink.pairs) +- [minuet-ai.nvim](https://github.com/milanglacier/minuet-ai.nvim) +- [vim-which-key](https://github.com/liuchengxu/vim-which-key) +- [which-key.nvim](https://github.com/folke/which-key.nvim) +- [todo-comments.nvim](https://github.com/folke/todo-comments.nvim) +- [trouble.nvim](https://github.com/folke/trouble.nvim) +- [nvim-tree.lua](https://github.com/kyazdani42/nvim-tree.lua) +- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) +- [telescope-file-browser.nvim](https://github.com/nvim-telescope/telescope-file-browser.nvim) +- [fzf-lua](https://github.com/ibhagwan/fzf-lua) +- [lsp-config](https://github.com/neovim/lsp-config) +- [lspsaga.nvim](https://github.com/glepnir/lspsaga.nvim) +- [leap.nvim](https://github.com/ggandor/leap.nvim) +- [flash.nvim](https://github.com/folke/flash.nvim) +- [snacks.nvim](https://github.com/folke/snacks.nvim) +- [neotest](https://github.com/nvim-neotest/neotest) +- [rainbow-delimiters.nvim](https://github.com/HiPhish/rainbow-delimiters.nvim) +- [copilot.vim](https://github.com/github/copilot.vim) +- [copilot.lua](https://github.com/zbirenbaum/copilot.lua) +- [nvim-ufo](https://github.com/kevinhwang91/nvim-ufo) +- [virt-column.nvim](https://github.com/lukas-reineke/virt-column.nvim) +- [conflict.nvim](https://github.com/is0n/conflict.nvim) -They are located at `terminal-themes/`. Please follow your terminals installation guide in how to apply them. + + +### Plugin showcase + +You can see a lot of screenshots of themed plugins in the [wiki page](https://github.com/uloco/bluloco.nvim/wiki#screenshots). +No config needed, works out of the box. + + -## Switching light and dark theme according your OS settings +## Integrations + +### Lualine + +Make sure your lualine settings are set to auto: + +```lua +require('lualine').setup({ + options = { + theme = 'auto' + } +}) +``` + +### Switching light and dark with your OS This themes light and dark variant are meant to be used during day and night. To make this easily possible I am using the [auto-dark-mode.nvim](https://github.com/f-person/auto-dark-mode.nvim) plugin @@ -242,6 +247,13 @@ auto_dark_mode.setup({ If you are also using lazygit as your git client, you might be interested in this [wiki guide](https://github.com/uloco/bluloco.nvim/wiki/Lazygit-%E2%80%90-Delta-%E2%80%90-Bat-%E2%80%90-Auto-Style) to set it up correctly with bluloco. Auto-dark light mode included. +### Terminal colors + +I've added a bunch of terminal themes for your terminal emulators. I've used the great [iTerm-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes) +repository for this, thanks @mbadolato! + +They are located at `terminal-themes/`. Please follow your terminals installation guide in how to apply them. + ## Contributing I'd be more than happy for any bugs you find and add an [issue](https://github.com/uloco/bluloco.nvim/issues). diff --git a/doc/.gitkeep b/doc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/lua/bluloco/init.lua b/lua/bluloco/init.lua index 27ecf9d..a27dec1 100644 --- a/lua/bluloco/init.lua +++ b/lua/bluloco/init.lua @@ -4,18 +4,26 @@ local M = {} local isGui = vim.fn.has("gui_running") == 1 +---@class Bluloco.Config +---@field style? "auto"|"dark"|"light" +---@field transparent? boolean +---@field italics? boolean +---@field terminal? boolean +---@field guicursor? boolean +---@field float_window? "default"|"transparent" +---@type Bluloco.Config local defaultConfig = { style = "auto", -- auto | light | dark transparent = false, italics = false, terminal = isGui, guicursor = true, - rainbow_headings = false, float_window = "default", -- default | transparent } M.config = defaultConfig +---@param options? Bluloco.Config function M.setup(options) M.config = vim.tbl_deep_extend("force", {}, defaultConfig, options or {}) From 46b257a3a9afbe7fa5c286b27616d4f7af7dfddd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Umut=20Topuzo=C4=9Flu?= Date: Wed, 16 Sep 2026 14:47:15 +0200 Subject: [PATCH 2/3] docs: add help file --- .github/workflows/panvimdoc.yml | 2 + README.md | 36 +++- doc/bluloco.txt | 336 ++++++++++++++++++++++++++++++++ doc/tags | 22 +++ 4 files changed, 386 insertions(+), 10 deletions(-) create mode 100644 doc/bluloco.txt create mode 100644 doc/tags diff --git a/.github/workflows/panvimdoc.yml b/.github/workflows/panvimdoc.yml index cdaead7..c32713d 100644 --- a/.github/workflows/panvimdoc.yml +++ b/.github/workflows/panvimdoc.yml @@ -25,6 +25,8 @@ jobs: treesitter: true ignorerawblocks: true shiftheadinglevelby: -1 + - name: add spacing after callouts + run: perl -0pi -e 's/(^ (?:Notes?|Warning|Deprecated):.*(?:\n .*)*)\n(?=\S)/$1\n\n/gmi' doc/bluloco.txt - uses: stefanzweifel/git-auto-commit-action@v5 with: commit_message: "chore(docs): auto generate vimdoc" diff --git a/README.md b/README.md index 9775254..dd90bf3 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ # Bluloco.nvim +## Overview + A fancy and sophisticated designer neovim theme built with [lush.nvim](https://github.com/rktjmp/lush.nvim). It features a much more comprehensive usage of syntax scopes and color consistency, with due regards to aesthetics, contrast and readability. @@ -76,8 +78,8 @@ vim.pack.add({ ## Usage -> The `setup()` function is optional but please call it -> **before** you set the colorscheme if you want to adjust the config. +> Note: The `setup()` function is optional. Call it before you set the colorscheme +> if you want to adjust the configuration. ```lua vim.opt.termguicolors = true @@ -116,31 +118,45 @@ require("bluloco").setup({ | `guicursor` | `boolean` | `true` | Set a colored `guicursor`. | | `float_window` | `"default"` \| `"transparent"` | `"default"` | Control float backgrounds with transparency. | +### style + There are three styles you can configure here: `auto`, `dark` and `light`. The `auto` setting is the default and will adjust automatically to your `vim.o.background` value. If you change this value during runtime, it will also adjust accordingly. -> The style value only applies if you set the theme with `vim.cmd('colorscheme bluloco')`. -> Setting the theme with a variant directly will override this setting. +> Note: The style value only applies if you set the theme with +> `vim.cmd('colorscheme bluloco')`. Setting a variant directly overrides it. -This setting will disable the background and use the default background of your terminal. -You need to enable this if you want the terminal to be transparent. You would still need to +### transparent + +Disables the background and uses the default background of your terminal. +Enable it if you want the terminal to be transparent. You still need to configure your terminal accordingly for light and dark backgrounds when switching often. -This setting will enable italics for _keywords_, _comments_ and _markup attributes_. +### italics + +Enables italics for _keywords_, _comments_ and _markup attributes_. -This setting will enable the bluloco colors in your integrated terminal. +### terminal + +Enables the bluloco colors in your integrated terminal. You most likely want to keep your terminal colors instead of overriding them if you are running neovim in a terminal. When you are running neovim inside a gui application this setting is enabled per default. You can skip the `terminal` setting completely to have it disabled in terminals and enabled in gui neovim. -> Please note that some terminals will display bold text as the bright color variant but enabling this feature will override this behavior in the integrated terminal. This is by design and has nothing to do with this theme. [see](https://github.com/neovim/neovim/issues/11335) +> Note: Some terminals display bold text with the bright color variant. This +> option overrides that behavior in the integrated terminal. This behavior is not +> related to this theme. [See the Neovim issue](https://github.com/neovim/neovim/issues/11335). + +### guicursor -This setting sets a guicursor to fix your terminal cursor and make it colorful (as intended). +Sets a guicursor to fix your terminal cursor and make it colorful (as intended). It is enabled by default. If you want to override this, make sure to set your `:set guicursor` after loading the theme or disable it completely. +### float_window + Controls how floating windows look when `transparent` is enabled. The default keeps a solid float background for better contrast, while setting it to `"transparent"` will also make floating windows inherit your terminal background (useful if you prefer a fully transparent UI). diff --git a/doc/bluloco.txt b/doc/bluloco.txt new file mode 100644 index 0000000..9f012a5 --- /dev/null +++ b/doc/bluloco.txt @@ -0,0 +1,336 @@ +*bluloco.txt* A fancy and sophisticated designer neovim theme + For Neovim Last change: 2026 September 17 + +============================================================================== +Table of Contents *bluloco-table-of-contents* + +1. Overview |bluloco-overview| +2. Features |bluloco-features| +3. Requirements |bluloco-requirements| +4. Installation |bluloco-installation| + - vim.pack |bluloco-installation-vim.pack| + - lazy.nvim |bluloco-installation-lazy.nvim| +5. Usage |bluloco-usage| +6. Configuration |bluloco-configuration| + - style |bluloco-configuration-style| + - transparent |bluloco-configuration-transparent| + - italics |bluloco-configuration-italics| + - terminal |bluloco-configuration-terminal| + - guicursor |bluloco-configuration-guicursor| + - float_window |bluloco-configuration-float_window| +7. Plugin support |bluloco-plugin-support| +8. Integrations |bluloco-integrations| + - Lualine |bluloco-integrations-lualine| + - Switching light and dark with your OS|bluloco-integrations-switching-light-and-dark-with-your-os| + - Terminal colors |bluloco-integrations-terminal-colors| +9. Contributing |bluloco-contributing| +10. Links |bluloco-links| + +============================================================================== +1. Overview *bluloco-overview* + +A fancy and sophisticated designer neovim theme built with lush.nvim +. It features a much more comprehensive +usage of syntax scopes and color consistency, with due regards to aesthetics, +contrast and readability. There is a light and dark variant. Most popular +plugins are also supported, see Plugins |bluloco-plugin-support| + +This theme also works very good with blue light filters like Apple’s +_Nightshift Mode_ or _f.lux_. + +This is a port of the popular Visual Studio Code Themes Bluloco Light + and Bluloco Dark + + + +============================================================================== +2. Features *bluloco-features* + +- Auto switching light & dark style +- Configurable _transparency_ and _italics_ +- Exhaustive plugin support +- Written in lua + + +============================================================================== +3. Requirements *bluloco-requirements* + +lush.nvim is required. + + +============================================================================== +4. Installation *bluloco-installation* + +Install Bluloco with your favorite package manager. + + +VIM.PACK *bluloco-installation-vim.pack* + +>lua + vim.pack.add({ + 'https://github.com/uloco/bluloco.nvim', + 'https://github.com/rktjmp/lush.nvim', + }) +< + + +LAZY.NVIM *bluloco-installation-lazy.nvim* + +>lua + { + 'uloco/bluloco.nvim', + lazy = false, + priority = 1000, + dependencies = { 'rktjmp/lush.nvim' }, + opts = {}, + } +< + + +============================================================================== +5. Usage *bluloco-usage* + + + Note: The `setup()` function is optional. Call it before you set the + colorscheme if you want to adjust the configuration. + +>lua + vim.opt.termguicolors = true + vim.cmd('colorscheme bluloco') +< + +You can also apply the style variant directly. These are especially helpful +when switching in an already running vim session. + +>vim + :colorscheme bluloco-dark + :colorscheme bluloco-light +< + + +============================================================================== +6. Configuration *bluloco-configuration* + +These are the default values: + +>lua + require("bluloco").setup({ + style = "auto", -- "auto" | "dark" | "light" + transparent = false, + italics = false, + terminal = vim.fn.has("gui_running") == 1, -- bluloco colors are enabled in gui terminals per default. + guicursor = true, + float_window = "default" -- "default" | "transparent" + }) +< + + ------------------------------------------------------------------------- + Option Type Default Description + ----------------- ----------------- ----------------- ------------------- + style "auto" | "dark" | "auto" Select the variant. + "light" "auto" follows + vim.o.background. + + transparent boolean false Use the terminal + background. + + italics boolean false Use italics for + keywords, comments, + and markup + attributes. + + terminal boolean GUI: true; Set builtin + terminal: false terminal colors. + + guicursor boolean true Set a colored + guicursor. + + float_window "default" | "default" Control float + "transparent" backgrounds with + transparency. + ------------------------------------------------------------------------- + +STYLE *bluloco-configuration-style* + +There are three styles you can configure here: `auto`, `dark` and `light`. The +`auto` setting is the default and will adjust automatically to your +`vim.o.background` value. If you change this value during runtime, it will also +adjust accordingly. + + + Note: The style value only applies if you set the theme with + `vim.cmd('colorscheme bluloco')`. Setting a variant directly overrides it. + +TRANSPARENT *bluloco-configuration-transparent* + +Disables the background and uses the default background of your terminal. +Enable it if you want the terminal to be transparent. You still need to +configure your terminal accordingly for light and dark backgrounds when +switching often. + + +ITALICS *bluloco-configuration-italics* + +Enables italics for _keywords_, _comments_ and _markup attributes_. + + +TERMINAL *bluloco-configuration-terminal* + +Enables the bluloco colors in your integrated terminal. You most likely want to +keep your terminal colors instead of overriding them if you are running neovim +in a terminal. When you are running neovim inside a gui application this +setting is enabled per default. + +You can skip the `terminal` setting completely to have it disabled in terminals +and enabled in gui neovim. + + + Note: Some terminals display bold text with the bright color variant. This + option overrides that behavior in the integrated terminal. This behavior is not + related to this theme. See the Neovim issue + . + +GUICURSOR *bluloco-configuration-guicursor* + +Sets a guicursor to fix your terminal cursor and make it colorful (as +intended). It is enabled by default. If you want to override this, make sure to +set your `:set guicursor` after loading the theme or disable it completely. + + +FLOAT_WINDOW *bluloco-configuration-float_window* + +Controls how floating windows look when `transparent` is enabled. The default +keeps a solid float background for better contrast, while setting it to +`"transparent"` will also make floating windows inherit your terminal +background (useful if you prefer a fully transparent UI). + + +============================================================================== +7. Plugin support *bluloco-plugin-support* + +Currently supported (aka. tested) plugins: + +- treesitter +- hlargs +- alpha-nvim +- nvim-notify +- mason.nvim +- nvim-cursorword +- vim-illuminate +- nvim-scrollbar +- lualine.nvim +- barbar.nvim +- nvim-bufferline.lua +- indent-blankline.nvim +- neogit +- diffview.nvim +- codediff.nvim +- render-markdown.nvim +- git-conflict.nvim +- gitsigns.nvim +- vim-fugitive +- nvim-cmp +- blink.cmp +- blink.pairs +- minuet-ai.nvim +- vim-which-key +- which-key.nvim +- todo-comments.nvim +- trouble.nvim +- nvim-tree.lua +- telescope.nvim +- telescope-file-browser.nvim +- fzf-lua +- lsp-config +- lspsaga.nvim +- leap.nvim +- flash.nvim +- snacks.nvim +- neotest +- rainbow-delimiters.nvim +- copilot.vim +- copilot.lua +- nvim-ufo +- virt-column.nvim +- conflict.nvim + + +============================================================================== +8. Integrations *bluloco-integrations* + + +LUALINE *bluloco-integrations-lualine* + +Make sure your lualine settings are set to auto: + +>lua + require('lualine').setup({ + options = { + theme = 'auto' + } + }) +< + + +SWITCHING LIGHT AND DARK WITH YOUR OS*bluloco-integrations-switching-light-and-dark-with-your-os* + +This themes light and dark variant are meant to be used during day and night. +To make this easily possible I am using the auto-dark-mode.nvim + plugin For a seamless +integration make sure your `bluloco.config.style` is set to `"auto"`. My +_auto-dark-mode.nvim_ config looks like this: + +>lua + local auto_dark_mode = require('auto-dark-mode') + + local function isAuto() + return require('bluloco').config.style == 'auto' + end + + auto_dark_mode.setup({ + update_interval = 1000, + set_dark_mode = function() + if isAuto() then + vim.o.background = 'dark' + end + end, + set_light_mode = function() + if isAuto() then + vim.o.background = 'light' + end + end + }) +< + +If you are also using lazygit as your git client, you might be interested in +this wiki guide + +to set it up correctly with bluloco. Auto-dark light mode included. + + +TERMINAL COLORS *bluloco-integrations-terminal-colors* + +I’ve added a bunch of terminal themes for your terminal emulators. I’ve +used the great iTerm-Color-Schemes + repository for this, thanks +@mbadolato! + +They are located at `terminal-themes/`. Please follow your terminals +installation guide in how to apply them. + + +============================================================================== +9. Contributing *bluloco-contributing* + +I’d be more than happy for any bugs you find and add an issue +. Pull requests are warmly +welcome especially for missing plugin support. + +============================================================================== +10. Links *bluloco-links* + +1. *@mbadolato*: + +Generated by panvimdoc + +vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/doc/tags b/doc/tags new file mode 100644 index 0000000..ed7df41 --- /dev/null +++ b/doc/tags @@ -0,0 +1,22 @@ +bluloco-configuration bluloco.txt /*bluloco-configuration* +bluloco-configuration-float_window bluloco.txt /*bluloco-configuration-float_window* +bluloco-configuration-guicursor bluloco.txt /*bluloco-configuration-guicursor* +bluloco-configuration-italics bluloco.txt /*bluloco-configuration-italics* +bluloco-configuration-style bluloco.txt /*bluloco-configuration-style* +bluloco-configuration-terminal bluloco.txt /*bluloco-configuration-terminal* +bluloco-configuration-transparent bluloco.txt /*bluloco-configuration-transparent* +bluloco-contributing bluloco.txt /*bluloco-contributing* +bluloco-features bluloco.txt /*bluloco-features* +bluloco-installation bluloco.txt /*bluloco-installation* +bluloco-installation-lazy.nvim bluloco.txt /*bluloco-installation-lazy.nvim* +bluloco-installation-vim.pack bluloco.txt /*bluloco-installation-vim.pack* +bluloco-integrations bluloco.txt /*bluloco-integrations* +bluloco-integrations-lualine bluloco.txt /*bluloco-integrations-lualine* +bluloco-integrations-terminal-colors bluloco.txt /*bluloco-integrations-terminal-colors* +bluloco-links bluloco.txt /*bluloco-links* +bluloco-overview bluloco.txt /*bluloco-overview* +bluloco-plugin-support bluloco.txt /*bluloco-plugin-support* +bluloco-requirements bluloco.txt /*bluloco-requirements* +bluloco-table-of-contents bluloco.txt /*bluloco-table-of-contents* +bluloco-usage bluloco.txt /*bluloco-usage* +bluloco.txt bluloco.txt /*bluloco.txt* From 46815f9388ab5ee342414cf82e4b048ffdfa3ff3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Umut=20Topuzo=C4=9Flu?= Date: Thu, 17 Sep 2026 11:51:06 +0200 Subject: [PATCH 3/3] docs: generate help tags --- .github/workflows/panvimdoc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/panvimdoc.yml b/.github/workflows/panvimdoc.yml index c32713d..2d89d11 100644 --- a/.github/workflows/panvimdoc.yml +++ b/.github/workflows/panvimdoc.yml @@ -27,6 +27,8 @@ jobs: shiftheadinglevelby: -1 - name: add spacing after callouts run: perl -0pi -e 's/(^ (?:Notes?|Warning|Deprecated):.*(?:\n .*)*)\n(?=\S)/$1\n\n/gmi' doc/bluloco.txt + - name: generate help tags + run: vim -es -u NONE -c "helptags doc" -c "qa" - uses: stefanzweifel/git-auto-commit-action@v5 with: commit_message: "chore(docs): auto generate vimdoc"