From 05602b6cafeb2495e2ddaae18198a439a5b5efd0 Mon Sep 17 00:00:00 2001 From: Folke Lemaitre Date: Sun, 15 Dec 2024 11:17:32 +0100 Subject: [PATCH] docs: added documentation on how to customize styles --- README.md | 1 + doc/snacks-animate.txt | 1 + doc/snacks-bigfile.txt | 1 + doc/snacks-dashboard.txt | 5 + doc/snacks-dim.txt | 1 + doc/snacks-git.txt | 4 + doc/snacks-gitbrowse.txt | 1 + doc/snacks-indent.txt | 1 + doc/snacks-input.txt | 5 + doc/snacks-lazygit.txt | 5 + doc/snacks-notifier.txt | 9 +- doc/snacks-profiler.txt | 1 + doc/snacks-quickfile.txt | 1 + doc/snacks-scope.txt | 1 + doc/snacks-scratch.txt | 5 + doc/snacks-scroll.txt | 1 + doc/snacks-statuscolumn.txt | 1 + doc/snacks-styles.txt | 328 ++++++++++++++++++++++++++++++++++++ doc/snacks-terminal.txt | 5 + doc/snacks-toggle.txt | 1 + doc/snacks-win.txt | 5 + doc/snacks-words.txt | 1 + doc/snacks-zen.txt | 5 + docs/animate.md | 1 + docs/bigfile.md | 1 + docs/dashboard.md | 4 + docs/dim.md | 1 + docs/git.md | 3 + docs/gitbrowse.md | 1 + docs/indent.md | 1 + docs/input.md | 4 + docs/lazygit.md | 4 + docs/notifier.md | 6 +- docs/profiler.md | 1 + docs/quickfile.md | 1 + docs/scope.md | 1 + docs/scratch.md | 4 + docs/scroll.md | 1 + docs/statuscolumn.md | 1 + docs/styles.md | 293 ++++++++++++++++++++++++++++++++ docs/terminal.md | 4 + docs/toggle.md | 1 + docs/win.md | 4 + docs/words.md | 1 + docs/zen.md | 4 + lua/snacks/meta/docs.lua | 37 +++- 46 files changed, 759 insertions(+), 9 deletions(-) create mode 100644 doc/snacks-styles.txt create mode 100644 docs/styles.md diff --git a/README.md b/README.md index 638b5044..7404410e 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,7 @@ Install the plugin with your package manager: "folke/snacks.nvim", priority = 1000, lazy = false, + ---@type snacks.Config opts = { -- your configuration comes here -- or leave it empty to use the default settings diff --git a/doc/snacks-animate.txt b/doc/snacks-animate.txt index 8719cc3c..f476bf0f 100644 --- a/doc/snacks-animate.txt +++ b/doc/snacks-animate.txt @@ -34,6 +34,7 @@ Doing this, will disable `scroll`, `indent`, `dim` and all other animations. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { animate = { -- your animate configuration comes here diff --git a/doc/snacks-bigfile.txt b/doc/snacks-bigfile.txt index 11f8b126..555d2f5c 100644 --- a/doc/snacks-bigfile.txt +++ b/doc/snacks-bigfile.txt @@ -23,6 +23,7 @@ mini.animate (if used) -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { bigfile = { -- your bigfile configuration comes here diff --git a/doc/snacks-dashboard.txt b/doc/snacks-dashboard.txt index bd0b679c..cc613cbe 100644 --- a/doc/snacks-dashboard.txt +++ b/doc/snacks-dashboard.txt @@ -149,6 +149,7 @@ In the example below, both sections are equivalent. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { dashboard = { -- your dashboard configuration comes here @@ -486,6 +487,10 @@ Similar to the Vim Startify dashboard ============================================================================== 6. Styles *snacks-dashboard-styles* +Check the styles + docs for more +information on how to customize these styles + DASHBOARD *snacks-dashboard-styles-dashboard* diff --git a/doc/snacks-dim.txt b/doc/snacks-dim.txt index 59d39d2f..cde04b60 100644 --- a/doc/snacks-dim.txt +++ b/doc/snacks-dim.txt @@ -26,6 +26,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { dim = { -- your dim configuration comes here diff --git a/doc/snacks-git.txt b/doc/snacks-git.txt index 77fc3d07..b755f63d 100644 --- a/doc/snacks-git.txt +++ b/doc/snacks-git.txt @@ -12,6 +12,10 @@ Table of Contents *snacks-git-table-of-contents* ============================================================================== 1. Styles *snacks-git-styles* +Check the styles + docs for more +information on how to customize these styles + BLAME_LINE *snacks-git-styles-blame_line* diff --git a/doc/snacks-gitbrowse.txt b/doc/snacks-gitbrowse.txt index 6c7e1d16..7417142a 100644 --- a/doc/snacks-gitbrowse.txt +++ b/doc/snacks-gitbrowse.txt @@ -20,6 +20,7 @@ Open the repo of the active file in the browser (e.g., GitHub) -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { gitbrowse = { -- your gitbrowse configuration comes here diff --git a/doc/snacks-indent.txt b/doc/snacks-indent.txt index 698ddfb5..5b445ba7 100644 --- a/doc/snacks-indent.txt +++ b/doc/snacks-indent.txt @@ -25,6 +25,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { indent = { -- your indent configuration comes here diff --git a/doc/snacks-input.txt b/doc/snacks-input.txt index ae623723..30c6653b 100644 --- a/doc/snacks-input.txt +++ b/doc/snacks-input.txt @@ -24,6 +24,7 @@ Better `vim.ui.input`. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { input = { -- your input configuration comes here @@ -59,6 +60,10 @@ Better `vim.ui.input`. ============================================================================== 3. Styles *snacks-input-styles* +Check the styles + docs for more +information on how to customize these styles + INPUT *snacks-input-styles-input* diff --git a/doc/snacks-lazygit.txt b/doc/snacks-lazygit.txt index 857698e2..1220fa9d 100644 --- a/doc/snacks-lazygit.txt +++ b/doc/snacks-lazygit.txt @@ -25,6 +25,7 @@ colorscheme and integrate edit with the current neovim instance. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { lazygit = { -- your lazygit configuration comes here @@ -81,6 +82,10 @@ colorscheme and integrate edit with the current neovim instance. ============================================================================== 3. Styles *snacks-lazygit-styles* +Check the styles + docs for more +information on how to customize these styles + LAZYGIT *snacks-lazygit-styles-lazygit* diff --git a/doc/snacks-notifier.txt b/doc/snacks-notifier.txt index e324cde0..faa9681c 100644 --- a/doc/snacks-notifier.txt +++ b/doc/snacks-notifier.txt @@ -9,7 +9,7 @@ Table of Contents *snacks-notifier-table-of-contents* 4. Config |snacks-notifier-config| 5. Styles |snacks-notifier-styles| - notification |snacks-notifier-styles-notification| - - notification.history |snacks-notifier-styles-notification.history| + - notification_history |snacks-notifier-styles-notification_history| 6. Types |snacks-notifier-types| - Notifications |snacks-notifier-types-notifications| - Rendering |snacks-notifier-types-rendering| @@ -116,6 +116,7 @@ Advanced LSP Progress ~ -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { notifier = { -- your notifier configuration comes here @@ -172,6 +173,10 @@ Advanced LSP Progress ~ ============================================================================== 5. Styles *snacks-notifier-styles* +Check the styles + docs for more +information on how to customize these styles + NOTIFICATION *snacks-notifier-styles-notification* @@ -191,7 +196,7 @@ NOTIFICATION *snacks-notifier-styles-notification* < -NOTIFICATION.HISTORY *snacks-notifier-styles-notification.history* +NOTIFICATION_HISTORY *snacks-notifier-styles-notification_history* >lua { diff --git a/doc/snacks-profiler.txt b/doc/snacks-profiler.txt index 47dd1df2..2e36a64b 100644 --- a/doc/snacks-profiler.txt +++ b/doc/snacks-profiler.txt @@ -175,6 +175,7 @@ field. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { profiler = { -- your profiler configuration comes here diff --git a/doc/snacks-quickfile.txt b/doc/snacks-quickfile.txt index 3f854872..8c8cc398 100644 --- a/doc/snacks-quickfile.txt +++ b/doc/snacks-quickfile.txt @@ -16,6 +16,7 @@ before loading your plugins. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { quickfile = { -- your quickfile configuration comes here diff --git a/doc/snacks-scope.txt b/doc/snacks-scope.txt index 5673595f..a862dd3c 100644 --- a/doc/snacks-scope.txt +++ b/doc/snacks-scope.txt @@ -24,6 +24,7 @@ The indent-based algorithm is similar to what is used in mini.indentscope -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { scope = { -- your scope configuration comes here diff --git a/doc/snacks-scratch.txt b/doc/snacks-scratch.txt index 07f69ca6..2b5674f4 100644 --- a/doc/snacks-scratch.txt +++ b/doc/snacks-scratch.txt @@ -49,6 +49,7 @@ Suggested config: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { scratch = { -- your scratch configuration comes here @@ -116,6 +117,10 @@ Suggested config: ============================================================================== 4. Styles *snacks-scratch-styles* +Check the styles + docs for more +information on how to customize these styles + SCRATCH *snacks-scratch-styles-scratch* diff --git a/doc/snacks-scroll.txt b/doc/snacks-scroll.txt index 9afbd4b9..adc3db4a 100644 --- a/doc/snacks-scroll.txt +++ b/doc/snacks-scroll.txt @@ -24,6 +24,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { scroll = { -- your scroll configuration comes here diff --git a/doc/snacks-statuscolumn.txt b/doc/snacks-statuscolumn.txt index 67dd572b..28713ff5 100644 --- a/doc/snacks-statuscolumn.txt +++ b/doc/snacks-statuscolumn.txt @@ -17,6 +17,7 @@ Table of Contents *snacks-statuscolumn-table-of-contents* -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { statuscolumn = { -- your statuscolumn configuration comes here diff --git a/doc/snacks-styles.txt b/doc/snacks-styles.txt new file mode 100644 index 00000000..feb508b5 --- /dev/null +++ b/doc/snacks-styles.txt @@ -0,0 +1,328 @@ +*snacks-styles.txt* snacks.nvim + +============================================================================== +Table of Contents *snacks-styles-table-of-contents* + +1. Setup |snacks-styles-setup| +2. Styles |snacks-styles-styles| + - blame_line |snacks-styles-styles-blame_line| + - dashboard |snacks-styles-styles-dashboard| + - float |snacks-styles-styles-float| + - input |snacks-styles-styles-input| + - lazygit |snacks-styles-styles-lazygit| + - minimal |snacks-styles-styles-minimal| + - notification |snacks-styles-styles-notification| + - notification_history |snacks-styles-styles-notification_history| + - scratch |snacks-styles-styles-scratch| + - split |snacks-styles-styles-split| + - terminal |snacks-styles-styles-terminal| + - zen |snacks-styles-styles-zen| + - zoom_indicator |snacks-styles-styles-zoom_indicator| +Plugins provide window styles that can be customized with the `opts.styles` +option of `snacks.nvim`. + + +============================================================================== +1. Setup *snacks-styles-setup* + +>lua + -- lazy.nvim + { + "folke/snacks.nvim", + ---@type snacks.Config + opts = { + ---@type table + styles = { + -- your styles configuration comes here + -- or leave it empty to use the default settings + -- refer to the configuration section below + } + } + } +< + + +============================================================================== +2. Styles *snacks-styles-styles* + +These are the default styles that Snacks provides. You can customize them by +adding your own styles to `opts.styles`. + + +BLAME_LINE *snacks-styles-styles-blame_line* + +>lua + { + width = 0.6, + height = 0.6, + border = "rounded", + title = " Git Blame ", + title_pos = "center", + ft = "git", + } +< + + +DASHBOARD *snacks-styles-styles-dashboard* + +The default style for the dashboard. When opening the dashboard during startup, +only the `bo` and `wo` options are used. The other options are used with `:lua +Snacks.dashboard()` + +>lua + { + zindex = 10, + height = 0, + width = 0, + bo = { + bufhidden = "wipe", + buftype = "nofile", + buflisted = false, + filetype = "snacks_dashboard", + swapfile = false, + undofile = false, + }, + wo = { + colorcolumn = "", + cursorcolumn = false, + cursorline = false, + foldmethod = "manual", + list = false, + number = false, + relativenumber = false, + sidescrolloff = 0, + signcolumn = "no", + spell = false, + statuscolumn = "", + statusline = "", + winbar = "", + winhighlight = "Normal:SnacksDashboardNormal,NormalFloat:SnacksDashboardNormal", + wrap = false, + }, + } +< + + +FLOAT *snacks-styles-styles-float* + +>lua + { + position = "float", + backdrop = 60, + height = 0.9, + width = 0.9, + zindex = 50, + } +< + + +INPUT *snacks-styles-styles-input* + +>lua + { + backdrop = false, + position = "float", + border = "rounded", + title_pos = "center", + height = 1, + width = 60, + relative = "editor", + noautocmd = true, + row = 2, + -- relative = "cursor", + -- row = -3, + -- col = 0, + wo = { + winhighlight = "NormalFloat:SnacksInputNormal,FloatBorder:SnacksInputBorder,FloatTitle:SnacksInputTitle", + cursorline = false, + }, + bo = { filetype = "snacks_input" }, + keys = { + i_esc = { "", { "cmp_close", "cancel" }, mode = "i" }, + -- i_esc = { "", "stopinsert", mode = "i" }, + i_cr = { "", { "cmp_accept", "confirm" }, mode = "i" }, + i_tab = { "", { "cmp_select_next", "cmp" }, mode = "i" }, + q = "cancel", + }, + } +< + + +LAZYGIT *snacks-styles-styles-lazygit* + +>lua + {} +< + + +MINIMAL *snacks-styles-styles-minimal* + +>lua + { + wo = { + cursorcolumn = false, + cursorline = false, + cursorlineopt = "both", + fillchars = "eob: ,lastline:…", + list = false, + listchars = "extends:…,tab: ", + number = false, + relativenumber = false, + signcolumn = "no", + spell = false, + winbar = "", + statuscolumn = "", + wrap = false, + sidescrolloff = 0, + }, + } +< + + +NOTIFICATION *snacks-styles-styles-notification* + +>lua + { + border = "rounded", + zindex = 100, + ft = "markdown", + wo = { + winblend = 5, + wrap = false, + conceallevel = 2, + colorcolumn = "", + }, + bo = { filetype = "snacks_notif" }, + } +< + + +NOTIFICATION_HISTORY *snacks-styles-styles-notification_history* + +>lua + { + border = "rounded", + zindex = 100, + width = 0.6, + height = 0.6, + minimal = false, + title = " Notification History ", + title_pos = "center", + ft = "markdown", + bo = { filetype = "snacks_notif_history", modifiable = false }, + wo = { winhighlight = "Normal:SnacksNotifierHistory" }, + keys = { q = "close" }, + } +< + + +SCRATCH *snacks-styles-styles-scratch* + +>lua + { + width = 100, + height = 30, + bo = { buftype = "", buflisted = false, bufhidden = "hide", swapfile = false }, + minimal = false, + noautocmd = false, + -- position = "right", + zindex = 20, + wo = { winhighlight = "NormalFloat:Normal" }, + border = "rounded", + title_pos = "center", + footer_pos = "center", + } +< + + +SPLIT *snacks-styles-styles-split* + +>lua + { + position = "bottom", + height = 0.4, + width = 0.4, + } +< + + +TERMINAL *snacks-styles-styles-terminal* + +>lua + { + bo = { + filetype = "snacks_terminal", + }, + wo = {}, + keys = { + q = "hide", + gf = function(self) + local f = vim.fn.findfile(vim.fn.expand(""), "**") + if f == "" then + Snacks.notify.warn("No file under cursor") + else + self:hide() + vim.schedule(function() + vim.cmd("e " .. f) + end) + end + end, + term_normal = { + "", + function(self) + self.esc_timer = self.esc_timer or (vim.uv or vim.loop).new_timer() + if self.esc_timer:is_active() then + self.esc_timer:stop() + vim.cmd("stopinsert") + else + self.esc_timer:start(200, 0, function() end) + return "" + end + end, + mode = "t", + expr = true, + desc = "Double escape to normal mode", + }, + }, + } +< + + +ZEN *snacks-styles-styles-zen* + +>lua + { + enter = true, + fixbuf = false, + minimal = false, + width = 120, + height = 0, + backdrop = { transparent = true, blend = 40 }, + keys = { q = false }, + wo = { + winhighlight = "NormalFloat:Normal", + }, + } +< + + +ZOOM_INDICATOR *snacks-styles-styles-zoom_indicator* + +fullscreen indicator only shown when the window is maximized + +>lua + { + text = "▍ zoom 󰊓 ", + minimal = true, + enter = false, + focusable = false, + height = 1, + row = 0, + col = -1, + backdrop = false, + } +< + +Generated by panvimdoc + +vim:tw=78:ts=8:noet:ft=help:norl: diff --git a/doc/snacks-terminal.txt b/doc/snacks-terminal.txt index 263bb4e1..6b82ac41 100644 --- a/doc/snacks-terminal.txt +++ b/doc/snacks-terminal.txt @@ -64,6 +64,7 @@ EDGY INTEGRATION *snacks-terminal-usage-edgy-integration* -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { terminal = { -- your terminal configuration comes here @@ -91,6 +92,10 @@ EDGY INTEGRATION *snacks-terminal-usage-edgy-integration* ============================================================================== 4. Styles *snacks-terminal-styles* +Check the styles + docs for more +information on how to customize these styles + TERMINAL *snacks-terminal-styles-terminal* diff --git a/doc/snacks-toggle.txt b/doc/snacks-toggle.txt index 955cdedd..f71cb5f7 100644 --- a/doc/snacks-toggle.txt +++ b/doc/snacks-toggle.txt @@ -35,6 +35,7 @@ Toggle keymaps integrated with which-key icons / colors -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { toggle = { -- your toggle configuration comes here diff --git a/doc/snacks-win.txt b/doc/snacks-win.txt index 89d43fce..aa9dfff9 100644 --- a/doc/snacks-win.txt +++ b/doc/snacks-win.txt @@ -63,6 +63,7 @@ Easily create and manage floating windows or splits -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { win = { -- your win configuration comes here @@ -118,6 +119,10 @@ Easily create and manage floating windows or splits ============================================================================== 4. Styles *snacks-win-styles* +Check the styles + docs for more +information on how to customize these styles + FLOAT *snacks-win-styles-float* diff --git a/doc/snacks-words.txt b/doc/snacks-words.txt index f21b8779..be19592e 100644 --- a/doc/snacks-words.txt +++ b/doc/snacks-words.txt @@ -21,6 +21,7 @@ Auto-show LSP references and quickly navigate between them -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { words = { -- your words configuration comes here diff --git a/doc/snacks-zen.txt b/doc/snacks-zen.txt index 533bf820..1f2a7ff5 100644 --- a/doc/snacks-zen.txt +++ b/doc/snacks-zen.txt @@ -29,6 +29,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { zen = { -- your zen configuration comes here @@ -86,6 +87,10 @@ Similar plugins: ============================================================================== 3. Styles *snacks-zen-styles* +Check the styles + docs for more +information on how to customize these styles + ZEN *snacks-zen-styles-zen* diff --git a/docs/animate.md b/docs/animate.md index 362cf12b..61e137b9 100644 --- a/docs/animate.md +++ b/docs/animate.md @@ -23,6 +23,7 @@ Doing this, will disable `scroll`, `indent`, `dim` and all other animations. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { animate = { -- your animate configuration comes here diff --git a/docs/bigfile.md b/docs/bigfile.md index a9fed4fe..ced4d0eb 100644 --- a/docs/bigfile.md +++ b/docs/bigfile.md @@ -18,6 +18,7 @@ The default implementation enables `syntax` for the buffer and disables -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { bigfile = { -- your bigfile configuration comes here diff --git a/docs/dashboard.md b/docs/dashboard.md index 0eeec7a9..e2bc429a 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -105,6 +105,7 @@ In the example below, both sections are equivalent. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { dashboard = { -- your dashboard configuration comes here @@ -436,6 +437,9 @@ Similar to the Vim Startify dashboard ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `dashboard` The default style for the dashboard. diff --git a/docs/dim.md b/docs/dim.md index 9e2bb45f..fc364d40 100644 --- a/docs/dim.md +++ b/docs/dim.md @@ -19,6 +19,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { dim = { -- your dim configuration comes here diff --git a/docs/git.md b/docs/git.md index dd6bbbed..9578e35f 100644 --- a/docs/git.md +++ b/docs/git.md @@ -4,6 +4,9 @@ ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `blame_line` ```lua diff --git a/docs/gitbrowse.md b/docs/gitbrowse.md index 31498f13..e2729a92 100644 --- a/docs/gitbrowse.md +++ b/docs/gitbrowse.md @@ -10,6 +10,7 @@ Open the repo of the active file in the browser (e.g., GitHub) -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { gitbrowse = { -- your gitbrowse configuration comes here diff --git a/docs/indent.md b/docs/indent.md index e836357e..e1dfb2e6 100644 --- a/docs/indent.md +++ b/docs/indent.md @@ -17,6 +17,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { indent = { -- your indent configuration comes here diff --git a/docs/input.md b/docs/input.md index 645ebb45..12cac294 100644 --- a/docs/input.md +++ b/docs/input.md @@ -12,6 +12,7 @@ Better `vim.ui.input`. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { input = { -- your input configuration comes here @@ -43,6 +44,9 @@ Better `vim.ui.input`. ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `input` ```lua diff --git a/docs/lazygit.md b/docs/lazygit.md index e8469e01..ab4ce30b 100644 --- a/docs/lazygit.md +++ b/docs/lazygit.md @@ -13,6 +13,7 @@ and integrate edit with the current neovim instance. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { lazygit = { -- your lazygit configuration comes here @@ -65,6 +66,9 @@ and integrate edit with the current neovim instance. ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `lazygit` ```lua diff --git a/docs/notifier.md b/docs/notifier.md index e24b2f7f..745ace10 100644 --- a/docs/notifier.md +++ b/docs/notifier.md @@ -103,6 +103,7 @@ vim.api.nvim_create_autocmd("LspProgress", { -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { notifier = { -- your notifier configuration comes here @@ -155,6 +156,9 @@ vim.api.nvim_create_autocmd("LspProgress", { ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `notification` ```lua @@ -172,7 +176,7 @@ vim.api.nvim_create_autocmd("LspProgress", { } ``` -### `notification.history` +### `notification_history` ```lua { diff --git a/docs/profiler.md b/docs/profiler.md index c5f2cddb..db2bde9f 100644 --- a/docs/profiler.md +++ b/docs/profiler.md @@ -139,6 +139,7 @@ All other fields equal to `true` will match if the trace has a value for that fi -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { profiler = { -- your profiler configuration comes here diff --git a/docs/quickfile.md b/docs/quickfile.md index 37ec26db..aa416299 100644 --- a/docs/quickfile.md +++ b/docs/quickfile.md @@ -11,6 +11,7 @@ before loading your plugins. -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { quickfile = { -- your quickfile configuration comes here diff --git a/docs/scope.md b/docs/scope.md index 9ca86264..7f48c6ed 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -13,6 +13,7 @@ in [mini.indentscope](https://github.com/echasnovski/mini.indentscope). -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { scope = { -- your scope configuration comes here diff --git a/docs/scratch.md b/docs/scratch.md index 61dddf68..b2cde610 100644 --- a/docs/scratch.md +++ b/docs/scratch.md @@ -35,6 +35,7 @@ Suggested config: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { scratch = { -- your scratch configuration comes here @@ -98,6 +99,9 @@ Suggested config: ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `scratch` ```lua diff --git a/docs/scroll.md b/docs/scroll.md index c7cd4546..69c7a8e3 100644 --- a/docs/scroll.md +++ b/docs/scroll.md @@ -16,6 +16,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { scroll = { -- your scroll configuration comes here diff --git a/docs/statuscolumn.md b/docs/statuscolumn.md index f2865f69..fc7f649e 100644 --- a/docs/statuscolumn.md +++ b/docs/statuscolumn.md @@ -8,6 +8,7 @@ -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { statuscolumn = { -- your statuscolumn configuration comes here diff --git a/docs/styles.md b/docs/styles.md new file mode 100644 index 00000000..9de3c29a --- /dev/null +++ b/docs/styles.md @@ -0,0 +1,293 @@ +# 🍿 styles + +Plugins provide window styles that can be customized +with the `opts.styles` option of `snacks.nvim`. + + + +## 📦 Setup + +```lua +-- lazy.nvim +{ + "folke/snacks.nvim", + ---@type snacks.Config + opts = { + ---@type table + styles = { + -- your styles configuration comes here + -- or leave it empty to use the default settings + -- refer to the configuration section below + } + } +} +``` + +## 🎨 Styles + +These are the default styles that Snacks provides. +You can customize them by adding your own styles to `opts.styles`. + + +### `blame_line` + +```lua +{ + width = 0.6, + height = 0.6, + border = "rounded", + title = " Git Blame ", + title_pos = "center", + ft = "git", +} +``` + +### `dashboard` + +The default style for the dashboard. +When opening the dashboard during startup, only the `bo` and `wo` options are used. +The other options are used with `:lua Snacks.dashboard()` + +```lua +{ + zindex = 10, + height = 0, + width = 0, + bo = { + bufhidden = "wipe", + buftype = "nofile", + buflisted = false, + filetype = "snacks_dashboard", + swapfile = false, + undofile = false, + }, + wo = { + colorcolumn = "", + cursorcolumn = false, + cursorline = false, + foldmethod = "manual", + list = false, + number = false, + relativenumber = false, + sidescrolloff = 0, + signcolumn = "no", + spell = false, + statuscolumn = "", + statusline = "", + winbar = "", + winhighlight = "Normal:SnacksDashboardNormal,NormalFloat:SnacksDashboardNormal", + wrap = false, + }, +} +``` + +### `float` + +```lua +{ + position = "float", + backdrop = 60, + height = 0.9, + width = 0.9, + zindex = 50, +} +``` + +### `input` + +```lua +{ + backdrop = false, + position = "float", + border = "rounded", + title_pos = "center", + height = 1, + width = 60, + relative = "editor", + noautocmd = true, + row = 2, + -- relative = "cursor", + -- row = -3, + -- col = 0, + wo = { + winhighlight = "NormalFloat:SnacksInputNormal,FloatBorder:SnacksInputBorder,FloatTitle:SnacksInputTitle", + cursorline = false, + }, + bo = { filetype = "snacks_input" }, + keys = { + i_esc = { "", { "cmp_close", "cancel" }, mode = "i" }, + -- i_esc = { "", "stopinsert", mode = "i" }, + i_cr = { "", { "cmp_accept", "confirm" }, mode = "i" }, + i_tab = { "", { "cmp_select_next", "cmp" }, mode = "i" }, + q = "cancel", + }, +} +``` + +### `lazygit` + +```lua +{} +``` + +### `minimal` + +```lua +{ + wo = { + cursorcolumn = false, + cursorline = false, + cursorlineopt = "both", + fillchars = "eob: ,lastline:…", + list = false, + listchars = "extends:…,tab: ", + number = false, + relativenumber = false, + signcolumn = "no", + spell = false, + winbar = "", + statuscolumn = "", + wrap = false, + sidescrolloff = 0, + }, +} +``` + +### `notification` + +```lua +{ + border = "rounded", + zindex = 100, + ft = "markdown", + wo = { + winblend = 5, + wrap = false, + conceallevel = 2, + colorcolumn = "", + }, + bo = { filetype = "snacks_notif" }, +} +``` + +### `notification_history` + +```lua +{ + border = "rounded", + zindex = 100, + width = 0.6, + height = 0.6, + minimal = false, + title = " Notification History ", + title_pos = "center", + ft = "markdown", + bo = { filetype = "snacks_notif_history", modifiable = false }, + wo = { winhighlight = "Normal:SnacksNotifierHistory" }, + keys = { q = "close" }, +} +``` + +### `scratch` + +```lua +{ + width = 100, + height = 30, + bo = { buftype = "", buflisted = false, bufhidden = "hide", swapfile = false }, + minimal = false, + noautocmd = false, + -- position = "right", + zindex = 20, + wo = { winhighlight = "NormalFloat:Normal" }, + border = "rounded", + title_pos = "center", + footer_pos = "center", +} +``` + +### `split` + +```lua +{ + position = "bottom", + height = 0.4, + width = 0.4, +} +``` + +### `terminal` + +```lua +{ + bo = { + filetype = "snacks_terminal", + }, + wo = {}, + keys = { + q = "hide", + gf = function(self) + local f = vim.fn.findfile(vim.fn.expand(""), "**") + if f == "" then + Snacks.notify.warn("No file under cursor") + else + self:hide() + vim.schedule(function() + vim.cmd("e " .. f) + end) + end + end, + term_normal = { + "", + function(self) + self.esc_timer = self.esc_timer or (vim.uv or vim.loop).new_timer() + if self.esc_timer:is_active() then + self.esc_timer:stop() + vim.cmd("stopinsert") + else + self.esc_timer:start(200, 0, function() end) + return "" + end + end, + mode = "t", + expr = true, + desc = "Double escape to normal mode", + }, + }, +} +``` + +### `zen` + +```lua +{ + enter = true, + fixbuf = false, + minimal = false, + width = 120, + height = 0, + backdrop = { transparent = true, blend = 40 }, + keys = { q = false }, + wo = { + winhighlight = "NormalFloat:Normal", + }, +} +``` + +### `zoom_indicator` + +fullscreen indicator +only shown when the window is maximized + +```lua +{ + text = "▍ zoom 󰊓 ", + minimal = true, + enter = false, + focusable = false, + height = 1, + row = 0, + col = -1, + backdrop = false, +} +``` diff --git a/docs/terminal.md b/docs/terminal.md index 6347ccd5..1db81b47 100644 --- a/docs/terminal.md +++ b/docs/terminal.md @@ -46,6 +46,7 @@ Based on the provided options, some defaults will be set: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { terminal = { -- your terminal configuration comes here @@ -69,6 +70,9 @@ Based on the provided options, some defaults will be set: ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `terminal` ```lua diff --git a/docs/toggle.md b/docs/toggle.md index 0689f0b5..287a4865 100644 --- a/docs/toggle.md +++ b/docs/toggle.md @@ -12,6 +12,7 @@ Toggle keymaps integrated with which-key icons / colors -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { toggle = { -- your toggle configuration comes here diff --git a/docs/win.md b/docs/win.md index 4c2e7b2a..bb8b5f59 100644 --- a/docs/win.md +++ b/docs/win.md @@ -28,6 +28,7 @@ Snacks.win({ -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { win = { -- your win configuration comes here @@ -79,6 +80,9 @@ Snacks.win({ ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `float` ```lua diff --git a/docs/words.md b/docs/words.md index 04051378..9b0b90f1 100644 --- a/docs/words.md +++ b/docs/words.md @@ -10,6 +10,7 @@ Auto-show LSP references and quickly navigate between them -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { words = { -- your words configuration comes here diff --git a/docs/zen.md b/docs/zen.md index c342cf84..fb317ff7 100644 --- a/docs/zen.md +++ b/docs/zen.md @@ -19,6 +19,7 @@ Similar plugins: -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { zen = { -- your zen configuration comes here @@ -72,6 +73,9 @@ Similar plugins: ## 🎨 Styles +Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles + ### `zen` ```lua diff --git a/lua/snacks/meta/docs.lua b/lua/snacks/meta/docs.lua index 95f9f4ba..ed6380dd 100644 --- a/lua/snacks/meta/docs.lua +++ b/lua/snacks/meta/docs.lua @@ -61,6 +61,7 @@ local query = vim.treesitter.query.parse( ---@field mod? string ---@field methods {name: string, args: string, comment?: string, types?: string, type: "method"|"function"}[] ---@field types string[] +---@field setup? string ---@field examples table ---@field styles {name:string, opts:string, comment?:string}[] @@ -239,14 +240,14 @@ function M.render(name, info) prefix = "Snacks" end - if info.config then - if name ~= "init" then - add("## 📦 Setup\n") - add(([[ + if name ~= "init" and (info.config or info.setup) then + add("## 📦 Setup\n") + add(([[ ```lua -- lazy.nvim { "folke/snacks.nvim", + ---@type snacks.Config opts = { %s = { -- your %s configuration comes here @@ -256,9 +257,10 @@ function M.render(name, info) } } ``` -]]):format(name, name)) - end +]]):format(info.setup or name, name)) + end + if info.config then add("## ⚙️ Config\n") add(M.md(info.config)) end @@ -280,6 +282,18 @@ function M.render(name, info) return a.name < b.name end) add("## 🎨 Styles\n") + + if name == "styles" then + add([[These are the default styles that Snacks provides. +You can customize them by adding your own styles to `opts.styles`. + +]]) + else + add([[Check the [styles](https://github.com/folke/snacks.nvim/blob/main/docs/styles.md) +docs for more information on how to customize these styles +]]) + end + for _, style in pairs(info.styles) do add(("### `%s`\n"):format(style.name)) if style.comment and style.comment ~= "" then @@ -380,12 +394,22 @@ function M._build() config = {}, ---@type string[] } + ---@type snacks.docs.Info + local styles = { + methods = {}, + types = {}, + examples = {}, + styles = {}, + setup = "---@type table\n styles", + } + for _, plugin in pairs(plugins) do if plugin.meta.docs then local name = plugin.name print("[gen] " .. name .. ".md") local lines = vim.fn.readfile(plugin.file) local info = M.extract(lines) + vim.list_extend(styles.styles, info.styles) info.config = name ~= "init" and info.config or nil plugin.meta.config = info.config ~= nil M.write(name, M.render(name, info)) @@ -397,6 +421,7 @@ function M._build() end end end + M.write("styles", M.render("styles", styles)) M.readme(plugins, types) M.types(types)