*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). If something seems missing, check the install section and see if installing a dependency would help. 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 +PlugInstall +NukeVimInstall +qall` to install all the relevant plugins, perform any initial NukeVim or other plugin setup tasks, and exit. This may take several minutes if you have a few coc extensions. npm is sloooow. -------------------------------------------------------------------------------- 2.1 Dependencies *NukeVimDependencies* Your nvim install should have the Python3 provider properly set up. Verify this with the `:checkhealth` command. Generally this requires installing the `pynvim` package, but the checkhealth command should point you in the right direction. // TODO: Add a NukeVim checkhealth provider to just validate all this shit automatically. Several plugins require external programs in order to function (in many cases to even make sense at all). Those are listed below. Generally you should be able to get by without any of these programs installed, the associated plugins should just automatically be disabled. If not, that's a bug. *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/ ================================================================================ 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.2 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* 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., `{ '', '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 = '', label = 'escape' }, Multiple Key Mapping: { mode = 'n', key = { '', '' }, map = ':syn sync fromstart', label = 'recalculate syntax highlighting' }, Virtual Mapping (Label Only): { mode = 'n', key = '-', virtual = true, label = 'browse files with netrw' } Hidden Mapping: { mode = 'n', key = '', map = ':lua nukevim:help()', label = 'help', hidden = true }, Group Mapping (Label Only): { mode = 'n', key = { '', 'd' }, group = true, label = 'development tools' }, { mode = 'n', key = { '', 'd', 'a' }, map = '...', label = 'tool a' }, { mode = 'n', key = { '', 'd', 'b' }, map = '...', label = 'tool b' }, { mode = 'n', key = { '', 'd', 'c' }, map = '...', label = 'tool c' }, Vim Mapping Options: { mode = 'i', key = { '' }, map = '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 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`) * `config`: passed through as-is to both `vim-plug` and the plugin itself, some useful options available from vim-plug: * `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`: a list of programs that should be available in your path in order for this plugin to be enabled (to, e.g., disable a docker plugin if docker isn't installed) * `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/.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. -------------------------------------------------------------------------------- 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`