You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
732 lines
29 KiB
732 lines
29 KiB
*NukeVim* nucleardog's vim config
|
|
|
|
|
|
~
|
|
~
|
|
\ | | \ \ /_) ~
|
|
. | | | | / -_)\ \ / | ` \ ~
|
|
_|\_|\_,_|_\_\\___| \_/ _|_|_|_| ~
|
|
~
|
|
by nucleardog ~
|
|
~
|
|
~
|
|
|
|
+-------------------------------------------------------------------------+
|
|
| HELP QUICK GUIDE |
|
|
+-------------------------------------------------------------------------+
|
|
| Ctrl+] : follow link Ctrl+O : go back Ctrl+I : go forward |
|
|
| gO : table of contents |
|
|
+-------------------------------------------------------------------------+
|
|
|
|
================================================================================
|
|
CONTENTS *NukeVim-contents*
|
|
|
|
1. Introduction |NukeVimIntro|
|
|
1.1 Goals |NukeVimIntroGoals|
|
|
1.2 Really Quick Start |NukeVimReallyQuickStart|
|
|
1.3 Less Quick Start |NukeVimLessQuickStart|
|
|
2. Installation |NukeVimInstall|
|
|
2.1 Dependencies |NukeVimDependencies|
|
|
3. Features |NukeVimFeature|
|
|
3.1 Development |NukeVimFeatureDev|
|
|
3.1.1 Debugger |NukeVimFeatureDebugger|
|
|
3.1.2 Code Completion |NukeVimFeatureCodeCompletion|
|
|
3.1.3 Tag Bar |NukeVimFeatureTagBar|
|
|
3.1.4 Todos |NukeVimFeatureTodos|
|
|
3.1.5 Git |NukeVimFeatureGit|
|
|
3.1.6 Docker |NukeVimFeatureDocker|
|
|
3.2 PHP |NukeVimFeaturePhp|
|
|
3.2.1 Debugger |NukeVimFeaturePhpDebugger|
|
|
3.2.1 Composer |NukeVimFeaturePhpComposer|
|
|
3.3 UI |NukeVimFeatureUi|
|
|
3.3.1 Fuzzy Find |NukeVimFeatureUiFuzzyFind|
|
|
3.3.2 Terminal |NukevimFeatureUiTerminal|
|
|
4. Architecture |NukeVimArch|
|
|
4.1 Startup |NukeVimArchStartup|
|
|
4.2 Modules |NukeVimArchModule|
|
|
4.3 Plugins |NukeVimArchPlugin|
|
|
5. Modules |NukeVimModule|
|
|
5.1 Keymap |NukeVimModuleKeymap|
|
|
5.2 LSP |NukeVimModuleLSP|
|
|
5.3 PHPUnit |NukeVimModulePhpUnit|
|
|
5.4 Plugins |NukeVimModulePlugins|
|
|
5.5 Settings |NukeVimModuleSettings|
|
|
5.6 Start |NukeVimModuleStart|
|
|
5.7 Syntax |NukeVimModuleSyntax|
|
|
5.8 UI |NukeVimModuleUi|
|
|
|
|
|
|
|
|
|
|
================================================================================
|
|
1. Introduction *NukeVimIntro*
|
|
|
|
|
|
This is my modular-ish and configurable-ish neovim config.
|
|
|
|
It's not intended to serve anyone's purpose but my own, but the core of it
|
|
should be fairly adaptable (even if a bit poorly implemented).
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
1.1 Goals *NukeVimIntroGoals*
|
|
|
|
|
|
The primary thing I try and do with this configuration is _enhance_ vim, not
|
|
make it into something else.
|
|
|
|
* This config should only _add_ or _enhance_ functionality, not make any major
|
|
changes to existing functionality or workflows.
|
|
* If I'm working on a server or any other computer that doesn't have my config,
|
|
I shouldn't be totally lost and useless. Which, conversely, means someone that
|
|
is used to vim should not feel lost when using this config.
|
|
* The core experience should not be complex. Additional functionality should be
|
|
surfaced as it's required or requested.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
1.2 Really Quick Start *NukeVimReallyQuickStart*
|
|
|
|
|
|
Basically... it's vim. Pretty much all of the things you're used to in vim
|
|
should be there exactly where you would expect them.
|
|
|
|
You can press `???` at any time to trigger a pop-up help bar that shows the
|
|
customized key bindings available. (Try it now!)
|
|
|
|
The leader key is, out of the box, the spacebar. Press it and wait briefly and
|
|
a similar legend should pop up to show the actions available.
|
|
|
|
Some actions are only available when specific file types are loaded (e.g.,
|
|
phpunit actions only display when you have a php file open).
|
|
|
|
Several tools are only available when the associated program is found in your
|
|
path (e.g., git tools are only available if git is found). Run `:checkhealth
|
|
nukevim` to see what's going on with all of that.
|
|
|
|
Good luck!
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
1.3 Less Quick Start *NukeVimQuickStart*
|
|
|
|
|
|
This should be a quick run-down of the things that I think are probably most
|
|
important to get immediately productive.
|
|
|
|
*Important Key Mappings:*
|
|
|
|
+------+-------------------+---------------------------------------------------+
|
|
| Mode | Key | Description |
|
|
+------+-------------------+---------------------------------------------------+
|
|
| n | - (hyphen) | Open file browser in current buffer |
|
|
| nit | Alt+H/J/K/L | Select the buffer in the direction |
|
|
| n | Alt+Shift+H/J/K/L | Move the current buffer in the direction |
|
|
| nit | Ctrl+H/L | Switch tab left/right |
|
|
| n t | Ctrl+K | New tab |
|
|
+------+-------------------+---------------------------------------------------+
|
|
|
|
*Important Files:*
|
|
|
|
* `lua/config/_keymap.lua`: customize general key mappings
|
|
* `lua/config/_settings.lua`: customize vim settings and global variables
|
|
* `lua/config/plugins/local.lua`: add your own plugins
|
|
|
|
|
|
================================================================================
|
|
2. Installation *NukeVimInstall*
|
|
|
|
Check out, unzip, copy or otherwise place the repo contents in your
|
|
`~/.config/nvim` folder (or whatever your platform uses).
|
|
|
|
Run `nvim +NukeVimInstall +qall` to install all the relevant plugins, perform
|
|
any initial NukeVim or other plugin setup tasks, and exit.
|
|
|
|
This may take a few minutes and may appear to be frozen. I hope to fix this
|
|
eventually, but the coc extension is a little finnicky about how you can
|
|
install things and this is the best I could get for the time being.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
2.1 Dependencies *NukeVimDependencies*
|
|
|
|
There are providers, external programs, and several other things required in
|
|
order for all plugins and included functionality to work (or even make sense).
|
|
|
|
If any specific functionality is missing a dependency, NukeVim _should_ continue
|
|
to function without that dependency just missing the relevant functionality. If
|
|
it does not, that's a bug.
|
|
|
|
At any time you should be able to validate which plugins are enabled and, if
|
|
they are not, why they failed to function by running `:checkhealth nukevim`.
|
|
|
|
For reference, the external dependencies are listed below:
|
|
|
|
*composer* -- php package manager
|
|
Required By: phpctags, vim-composer
|
|
See: https://getcomposer.org/
|
|
|
|
*ctags* -- code tag parser
|
|
Required By: phpctags, tagbar
|
|
See: https://github.com/universal-ctags/ctags
|
|
|
|
*deno* -- javascript/typescript plugin runtime
|
|
Required By: denops-docker
|
|
See: https://deno.land/
|
|
|
|
*docker* -- build and run containers
|
|
Required By: vim-docker-tools, denops-docker,
|
|
See: https://www.docker.com/
|
|
|
|
*git* -- source code control
|
|
Required By: vim-fugitive, gv, vim-gitgutter, blamer
|
|
See: https://git-scm.com/
|
|
|
|
*npm* -- javascript package manager
|
|
Required By: coc
|
|
See: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
|
|
|
|
*php* -- php language runtime
|
|
Required By: phpctags, vim-composer
|
|
See: https://php.org/
|
|
|
|
*python3* -- neovim python3 provider (python3 + pip3 install pynvim)
|
|
Required By: vdebug
|
|
|
|
|
|
================================================================================
|
|
3. Features *NukeVimFeature*
|
|
|
|
|
|
This section outlines several features included in the NukeVim distribution,
|
|
references back to the relevant projects, and quick information on their use.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1 Development *NukeVimFeatureDev*
|
|
|
|
|
|
Tools for working with code.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.1 Debugger *NukeVimFeatureDebugger*
|
|
|
|
|
|
NukeVim includes the Vdebug plugin to provide a DBGP protocol debugger within
|
|
vim. It can be used for PHP (xdebug), Python, Ruby, Perl, Tcl, NodeJS and more.
|
|
|
|
Further Help: `:h Vdebug`
|
|
URL: https://github.com/vim-vdebug/vdebug
|
|
|
|
In normal mode:
|
|
* `<F5>` starts the debugger; the UI will only appear once a client connects
|
|
* `<F10>` toggle breakpoint
|
|
|
|
Within the debugger:
|
|
* `<F2>` step over
|
|
* `<F3>` step into
|
|
* `<F4>` step out
|
|
* `<F6>` stops the debugged code; a second time closes the debugger
|
|
* `<F9>` run to cursor
|
|
* `<F12>` evaluate variable under cursor
|
|
|
|
NukeVim provides some additionally functionality and mappings for working with
|
|
the debugger under the `<leader> d(evelopment) d(ebug)` prefix:
|
|
|
|
* `b` toggle breakpoint
|
|
* `c` set a conditional breakpoint
|
|
* `e` evaluate code; if you have a visual selection it will evaluate that,
|
|
otherwise it will prompt for code
|
|
* `t` set a trace expression to be evaluated on each stepping; if you have a
|
|
visual selection it will trace that, otherwise it will prompt for code
|
|
* `w` show breakpoint window listing all breakpoints
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.2 Code Completion *NukeVimFeatureCodeCompletion*
|
|
|
|
|
|
NukeVim provides the coc plugin to provide completion.
|
|
|
|
Further Help: `:h coc-nvim`
|
|
URL: https://github.com/neoclide/coc.nvim
|
|
|
|
You can install various coc extensions with the `:CocInstall` command. Some
|
|
useful ones:
|
|
|
|
* `coc-css`: css completion
|
|
* `coc-html`: html completion
|
|
* `coc-json`: json completion
|
|
* `coc-markdownlint`: markdown linting rules
|
|
* `coc-marketplace`: run `:CocList marketplace` to fuzzy find and interactively
|
|
install new extensions
|
|
* `coc-phpls`: php language server using intelephense
|
|
* `coc-sql`: sql completion
|
|
* `coc-yaml`: yaml completion
|
|
|
|
When completion windows pop up, you can either:
|
|
|
|
* Scroll with the arrow keys, commit with <CR>
|
|
* Scroll with Ctrl+J/K and have the changes reflected immediately.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.3 Tag Bar *NukeVimFeatureTagBar*
|
|
|
|
|
|
NukeVim uses the tagbar plugin to provide overview and navigation of your
|
|
code's structure.
|
|
|
|
Further Help: `:h tagbar`
|
|
URL: https://github.com/preservim/tagbar
|
|
|
|
At any point in a source file, you can press `Alt+;` to open a sidebar which
|
|
shows all of the "tags" in your source file--classes and functions. You can
|
|
scroll with j/k and select any tag with <CR> to move the cursor there. The
|
|
window automatically closes.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.4 Todos *NukeVimFeatureTodos*
|
|
|
|
|
|
NukeVim uses trouble and todo-comments to provide highlighting and a project-level
|
|
overview of // TODO, // FIXME, etc style comments.
|
|
|
|
Further Help: none
|
|
URL: https://github.com/folke/todo-comments.nvim
|
|
|
|
todo-comments will search your cwd for relevant tags. Generally this will be
|
|
your project's directory thanks to vim-rooter.
|
|
|
|
You can trigger the quickfix interface with `<leader> w(orkspace) t(odos)`.
|
|
This will open the quickfix window with a list of todos broken down by file.
|
|
Scroll with j/k, select with <CR> to jump to the file and line, or close the
|
|
quickfix window with `q`. It will auto-close when you select a todo to view.
|
|
|
|
Alternatively, you can use `<leader> w(orkspace) T(odos)` to open the todos
|
|
in Telescope. This provides a fuzzy find interface with shows a preview of the
|
|
selected todo in the right pane.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.5 Git *NukeVimFeatureGit*
|
|
|
|
|
|
NukeVim uses several plugins to provide a whole bunch of relevant
|
|
git functionality.
|
|
|
|
All of the functionality can be found under the `<leader> g(it)` prefix.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.1.6 Docker *NukevimFeatureDocker*
|
|
|
|
|
|
NukeVim provides two docker interfaces out of the box, though one is disabled
|
|
by default.
|
|
|
|
| The default plugin requires deno be available (see |NukeVimDependencies|).
|
|
| If you do not want to install deno, you may instead enable
|
|
| the `vim-docker-tools plugin in `lua/config/plugins/development.lua`. This
|
|
| section only discusses the default denops-docker plugin.
|
|
|
|
Further Help: `:h docker.txt`
|
|
URL: https://github.com/skanehira/denops-docker.vim
|
|
|
|
denops-docker provides basic container and image management from within vim.
|
|
You can trigger container management with `<leader> d(evelopment) c(ontainers)`
|
|
and image management with `<leader> d(evelopment) i(mages)`.
|
|
|
|
All key bindings available in both interfaces are registered in the keymap so
|
|
live help can be found by pressing `???` with either window open. Windows can
|
|
be scrolled with j/k and closed with `q`.
|
|
|
|
Containers:
|
|
* `u` start container
|
|
* `d` stop container
|
|
* `r` restart container
|
|
* `<C-k>` kill container
|
|
* `<CR>` inspect container
|
|
* `a` attach terminal to container
|
|
* `t` tail log of container
|
|
* `<C-d>` delete container
|
|
|
|
Images:
|
|
* `r` run image
|
|
* `<C-d>` delete image
|
|
* `<CR>` inspect image
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.2 PHP *NukeVimFeaturePhp*
|
|
|
|
|
|
NukeVim provides some PHP-specific functionality.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.2.1 Debugger *NukeVimFeaturePhpDebugger*
|
|
|
|
|
|
In order to debug PHP with Vdebug (see |NukeVimFeatureDebugger|), you must first
|
|
set up PHP correctly.
|
|
|
|
Ensure you have the xdebug extension (https://xdebug.org/) installed first. It's
|
|
likely available in your package manager.
|
|
|
|
I won't fully replicate the Xdebug documentation here, but you _will_ need to
|
|
properly configure xdebug in your php.ini file. Some core options you'll
|
|
likely need would be:
|
|
|
|
[xdebug]
|
|
zend_extension=xdebug.so
|
|
xdebug.mode=debug
|
|
xdebug.client_host=127.0.0.1
|
|
xdebug.client_port=9000
|
|
xdebug.discover_client_host=true
|
|
xdebug.start_with_request=true
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.2.2 Composer *NukeVimFeaturePhpComposer*
|
|
|
|
|
|
NukeVim provides an extremely basic composer interface thanks to vim-composer.
|
|
|
|
Further Help: `:h composer.txt`
|
|
URL: https://github.com/vim-php/vim-composer
|
|
|
|
The functionality is only available when you have a PHP file open and it is
|
|
all under the `<leader> l(anguage) c(omposer)` prefix:
|
|
|
|
* `i` run composer install
|
|
* `j` open composer.json in a new buffer
|
|
* `u` run composer update
|
|
|
|
// TODO: Add some more composer commands using :ComposerRun -- something generic
|
|
// but also probably some shortcuts for my common stuff like format/validate.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.3 UI *NukeVimFeatureUi*
|
|
|
|
|
|
Most of the UI stuff just... is, but there are a couple of things that aren't
|
|
very discoverable.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.3.1 Fuzzy Find *NukeVimFeatureUiFuzzyFind*
|
|
|
|
|
|
NukeVim uses CtrlP for fuzzy finding files.
|
|
|
|
Further Help: `:h ctrlp`
|
|
URL: https://github.com/ctrlpvim/ctrlp.vim
|
|
|
|
You can trigger the fuzzy find by pressing `<C-p>` in normal mode. This will
|
|
try and fuzzily match any files in the cwd (which should follow your project
|
|
root thanks to vim-rooter).
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
3.3.2 Terminal *NukeVimFeatureUiTerminal*
|
|
|
|
|
|
NukeVim uses toggleterm to provide a persistent, toggleable terminal.
|
|
|
|
Further Help: `:h toggleterm`
|
|
URL: https://github.com/akinsho/toggleterm.nvim
|
|
|
|
In normal mode, press `<C-t>` to show/hide a terminal at the bottom of your
|
|
screen.
|
|
|
|
|
|
================================================================================
|
|
4. Architecture *NukeVimArch*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
4.1 Startup *NukeVimArchStartup*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
4.2 Modules *NukeVimArchModule*
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
4.3 Plugins *NukeVimArchPlugin*
|
|
|
|
|
|
================================================================================
|
|
5. Modules *NukeVimModule*
|
|
|
|
|
|
Modules are the core of NukeVim, generally providing high-level/core
|
|
functionality. Though because of technical limitations there are a couple that
|
|
are quite specific.
|
|
|
|
In addition to the module-specific configuration listed below, every module's
|
|
configuration block supports two top-level properties, though both are optional:
|
|
|
|
* `enable`: if this is set and not `true`, then this module is skipped
|
|
* `order`: all modules are loaded, initialized, etc sorted by the ascending
|
|
value of the order property; any modules which do not specify an order value
|
|
(order = nil) are sorted to the end of the initialization list; any modules
|
|
with matching orders (including nil) are initialized in an undefined order
|
|
relative to each other.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.1 Keymap *NukeVimModuleKeymap*
|
|
|
|
|
|
The keymap module provides the ability to map keys directly as well as is
|
|
used by the Plugins module to register plugin-specific key mappings. If enabled,
|
|
the keymap module also handles generating the help/legend that you can trigger
|
|
with `???` or after pressing the leader key.
|
|
|
|
In `lua/_config.lua`, a couple of options are provided directly:
|
|
|
|
* `ui.enable`: whether to enable the legend when pressing the `???` combo or
|
|
after pressing the leader key.
|
|
* `ui.show_builtin`: if this is enabled then the legend will also show vim's
|
|
built-in key bindings, not just the customized ones.
|
|
|
|
A list of key bindings can be provided on the `keys` property.
|
|
|
|
By default, the general key mappings registered through the `keys` property are
|
|
included from `lua/config/_keymap.lua`. Mappings for plugins are generally
|
|
contained in the plugin config block in the plugin files. See
|
|
|NukeVimModulePlugins|.
|
|
|
|
Supported options for each keymap are:
|
|
|
|
* `mode`: the mode to register this key combo in (e.g., `n`, `i`, `v`, etc)
|
|
* `key`: either a string where each character is expected to represent a single
|
|
key (e.g., 'jj') or an array where each element is a key (e.g.,
|
|
`{ '<leader>', 'g', 'c' }`.
|
|
* `map`: what to bind to this keypress
|
|
* `label`: the label to show in the legend/help
|
|
* `group`: set true if this doesn't actually map a key but just provides a label
|
|
for a group of keys
|
|
* `virtual`: set true if this doesn't actually map a key but instead is just
|
|
intended to provide a label for an existing mapping
|
|
* `hidden`: set true if you want this map registered but to _not_ display in
|
|
the legend; no effect if the legend UI isn't enabled
|
|
* `options`: these are passed through to the map api, you can set `silent`,
|
|
`nowait`, and `noremap`. If the `options` table isn't specified, than the
|
|
default options is `noremap`.
|
|
|
|
Examples:
|
|
|
|
Basic Mapping:
|
|
|
|
{
|
|
mode = 'n',
|
|
key = 'jj',
|
|
map = '<Esc>',
|
|
label = 'escape'
|
|
},
|
|
|
|
Multiple Key Mapping:
|
|
|
|
{
|
|
mode = 'n',
|
|
key = { '<Space>', '<Space>' },
|
|
map = ':syn sync fromstart<CR>',
|
|
label = 'recalculate syntax highlighting'
|
|
},
|
|
|
|
Virtual Mapping (Label Only):
|
|
|
|
{
|
|
mode = 'n',
|
|
key = '-',
|
|
virtual = true,
|
|
label = 'browse files with netrw'
|
|
}
|
|
|
|
Hidden Mapping:
|
|
|
|
{
|
|
mode = 'n',
|
|
key = '<F49>',
|
|
map = ':lua nukevim:help()<CR>',
|
|
label = 'help',
|
|
hidden = true
|
|
},
|
|
|
|
Group Mapping (Label Only):
|
|
|
|
{
|
|
mode = 'n',
|
|
key = { '<leader>', 'd' },
|
|
group = true,
|
|
label = 'development tools'
|
|
},
|
|
{ mode = 'n', key = { '<leader>', 'd', 'a' }, map = '...', label = 'tool a' },
|
|
{ mode = 'n', key = { '<leader>', 'd', 'b' }, map = '...', label = 'tool b' },
|
|
{ mode = 'n', key = { '<leader>', 'd', 'c' }, map = '...', label = 'tool c' },
|
|
|
|
Vim Mapping Options:
|
|
|
|
{
|
|
mode = 'i',
|
|
key = { '<A-j>' },
|
|
map = '<C-O><C-W>j',
|
|
label = 'select buffer down',
|
|
options = { silent = true }
|
|
}
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.2 LSP *NukeVimModuleLSP*
|
|
|
|
|
|
The LSP module is responsible for initializing and configuring NeoVim's built in
|
|
LSP client.
|
|
|
|
It provides only minimal functionality, but must be configured with any LSP
|
|
providers you expect to use in NeoVim.
|
|
|
|
All providers are configured under a top level `provders` property. The LSP
|
|
configuration is fairly specific to each provider, but the general format
|
|
is:
|
|
|
|
providers = {
|
|
intelephense = {
|
|
command = { 'intelephense', '--stdio' },
|
|
filetypes = { 'php' }
|
|
}
|
|
}
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.3 PHPUnit *NukeVimModulePhpUnit*
|
|
|
|
|
|
The PHPUnit module is responsible for providing an interface to PHPUnit. It has
|
|
no configuration options, but registers several key bindings in the <leader>
|
|
interface for running PHPUnit tests when you have a PHP file open.
|
|
|
|
It is hardcoded to run PHPUnit using the path `./vendor/bin/phpunit` so should
|
|
always use the version of PHPUnit included in your project.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.4 Plugins *NukeVimModulePlugins*
|
|
|
|
|
|
The plugins module is responsible for initializing and configuring all external
|
|
vim plugins. By default, this relies on `vim-plug` to provide the actual plugin
|
|
management.
|
|
|
|
The plugins module provides one top-level option:
|
|
|
|
* `path`: the path on disk where plugins should be stored
|
|
|
|
The list of plugins should be provided as the `plugins` property. By default,
|
|
this is included from `lua/config/_plugins.lua` which in turn includes and
|
|
merges all the plugins in the files in `lua/config/plugins/`.
|
|
|
|
Each plugin supports a several properties, all except `name` are optional:
|
|
|
|
* `enable`: if set and not `true`, the plugin will be skipped
|
|
* `name`: the name of the plugin, generally a github reference (`user/plugin`)
|
|
* `opts`: used to control plugin loading options, some available options are:
|
|
* `branch`: override the branch to check out from git
|
|
* `on`: delay loading the plugin until one of the specified commands is called
|
|
* `do`: command to run after install/update
|
|
* `requires`: contains sub-properties:
|
|
* `provider`: a list of vim providers (e.g., 'python3') that must be present
|
|
* `binary`: a list of executables that must be available on your path
|
|
* `plugin`: a list of other plugins that must have been successfully initialized
|
|
* `virtual`: do not register with vim-plug
|
|
* `config`: passed through to the plugin itself as configuration
|
|
* `keys`: a list of key mappings in the format expected by the keymap module
|
|
(see |NukeVimModuleKeymap|) that should be registered if this plugin is enabled
|
|
|
|
In addition to the plugin itself, if a file is present at
|
|
`lua/plugin/<plugin/path>.lua` it will be loaded and registered with the module
|
|
system to allow you to provide additional customization or initialization
|
|
logic. See |NukeVimArchPlugin| for more information.
|
|
|
|
If any of a plugin's requirements are not met it will simply not be loaded. This
|
|
should allow NukeVim to simply adapt to whatever is available at the time. If
|
|
any expected functionality is missing, running `:checkhealth nukevim` should
|
|
report why a plugin wasn't loaded under the plugin module section.
|
|
|
|
"virtual" plugins interact with both of these systems. The primary intention is
|
|
to allow for the quick and easy creation and inclusion of built-in lua plugins
|
|
which have no corresponding plugin to load via vim-plug. By setting a plugin as
|
|
`virtual`, it will not be registered with `vim-plug` but in all other ways will
|
|
be treated as a plugin--including loading an appropriately named lua file from
|
|
the `lua/plugins/` folder. I cannot see the use-case, but a virtual plugin
|
|
would also satisfy a dependency declared in the `requires` section of any other
|
|
plugin.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.5 Settings *NukeVimModuleSettings*
|
|
|
|
|
|
This module is responsible for setting vim settings and global variables.
|
|
|
|
The settings module provides a single top-level option:
|
|
|
|
* `settings`: Set a `o` table to provide options, and a `g` table to set
|
|
global variables.
|
|
|
|
By default, the settings configuration is loaded from `lua/config/_settings.lua`.
|
|
|
|
The `o` property should be set to a table containing vim options and their value.
|
|
Generally, this is anything you would configure with `set option` or
|
|
`set option=value`.
|
|
|
|
In the case of "boolean" options (e.g., `wrap` and `nowrap`) you should not set
|
|
the `no` option, but instead set the option to value. That is, instead of
|
|
`nowrap = true`, set `wrap = false`.
|
|
|
|
The `g` property should be set to a table containing any global variables you
|
|
want to set on startup. Generally, this is anything you would configure with
|
|
`let g:option=value`.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.6 Start *NukeVimModuleStart*
|
|
|
|
|
|
This module has no configuration options available. It provides the NukeVim
|
|
splash screen on startup.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.7 Syntax *NukeVimModuleSyntax*
|
|
|
|
|
|
This module has no configuration options available. It simply exists to resolve
|
|
some conflicts between some syntax highlighting plugins.
|
|
|
|
|
|
--------------------------------------------------------------------------------
|
|
5.8 UI *NukeVimModuleUi*
|
|
|
|
|
|
The UI module is generally responsible for how vim looks.
|
|
|
|
It provides two top level properties:
|
|
|
|
* `tui`: configuration to apply on startup unconditionally
|
|
* `gui`: configuration to apply on top of the `tui` options if we detect
|
|
that vim is running in some sort of gui
|
|
|
|
Each property supports the following options:
|
|
|
|
* `theme`: the colorscheme to apply, this is basically `set colorscheme`
|
|
* `show_whitespace`: if enabled, then highlighting rules will be added to
|
|
make whitespace visible in the editor
|
|
* `font`: supports two properties: `family` and `size`
|
|
|
|
|