*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: * `` starts the debugger; the UI will only appear once a client connects * `` toggle breakpoint Within the debugger: * `` step over * `` step into * `` step out * `` stops the debugged code; a second time closes the debugger * `` run to cursor * `` evaluate variable under cursor NukeVim provides some additionally functionality and mappings for working with the debugger under the ` 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 * 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 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 ` 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 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 ` 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 ` 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 ` d(evelopment) c(ontainers)` and image management with ` 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 * `` kill container * `` inspect container * `a` attach terminal to container * `t` tail log of container * `` delete container Images: * `r` run image * `` delete image * `` 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 ` 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 `` 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 `` 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., `{ '', '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`) * `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/.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`