nvf manual

Version @NVF_VERSION@

Preface

What is nvf

nvf is a highly modular, configurable, extensible and easy to use Neovim configuration in Nix. Designed for flexibility and ease of use, nvf allows you to easily configure your fully featured Neovim instance with a few lines of Nix.

Bugs & Suggestions

If you notice any issues with nvf, or this documentation, then please consider reporting them over at the https://github.com/notashelf/nvf/issues">issue tracker. Issues tab, in addition to the https://github.com/notashelf/nvf/discussions">discussions tab is a good place as any to request new features.

You may also consider submitting bugfixes, feature additions and upstreamed changes that you think are critical over at the https://github.com/notashelf/nvf/pulls">pull requests tab.

Try it out

Thanks to the portability of Nix, you can try out nvf without actually installing it to your machine. Below are the commands you may run to try out different configurations provided by this flake. As of v0.5, two specialized configurations are provided:

• Nix - Nix language server + simple utility plugins
• Maximal - Variable language servers + utility and decorative plugins

You may try out any of the provided configurations using the nix run command on a system where Nix is installed.

$ cachix use nvf                   # Optional: it'll save you CPU resources and time
$ nix run github:notashelf/nvf#nix # will run the default minimal configuration

Do keep in mind that this is susceptible to garbage collection meaning it will be removed from your Nix store once you garbage collect.

Using Prebuilt Configs

$ nix run github:notashelf/nvf#nix
$ nix run github:notashelf/nvf#maximal

Available Configurations

$ nix run github:notashelf/nvf#nix test.nix

$ nix run github:notashelf/nvf#maximal -- test.nix

Installing nvf

There are multiple ways of installing nvf on your system. You may either choose the standalone installation method, which does not depend on a module system and may be done on any system that has the Nix package manager or the appropriate modules for NixOS and home-manager as described in the module installation section.

installation/custom-configuration.md
installation/modules.md

Configuring nvf

nvf allows for very extensive configuration in Neovim through the Nix module interface. The below chapters describe several of the options exposed in nvf for your convenience. You might also be interested in the helpful tips section for more advanced or unusual configuration options supported by nvf.

Note that this section does not cover module options. For an overview of all module options provided by nvf, please visit the appendix

configuring/custom-package.md
configuring/custom-plugins.md
configuring/overriding-plugins.md
configuring/languages.md
configuring/dags.md
configuring/dag-entries.md
configuring/autocmds.md

Helpful Tips

This section provides helpful tips that may be considered "unorthodox" or "too advanced" for some users. We will cover basic debugging steps, offline documentation, configuring nvf with pure Lua and using custom plugin sources in nvf in this section. For general configuration tips, please see previous chapters.

tips/debugging-nvf.md
tips/offline-docs.md
tips/pure-lua-config.md
tips/plugin-sources.md

Hacking nvf

nvf is designed for the developer as much as it is designed for the end-user. We would like for any contributor to be able to propagate their changes, or add new features to the project with minimum possible friction. As such, below are the guides and guidelines written to streamline the contribution process and to ensure that your valuable input integrates into nvf's development as seamlessly as possible without leaving any question marks in your head.

This section is directed mainly towards those who wish to contribute code into the project. If you instead wish to report a bug, or discuss a potential new feature implementation (which you do not wish to implement yourself) first look among the already https://github.com/notashelf/nvf/issues">open issues and if no matching issue exists you may open a https://github.com/notashelf/nvf/issues/new">new issue and describe your problem/request.

While creating an issue, please try to include as much information as you can, ideally also include relevant context in which an issue occurs or a feature should be implemented. If you wish to make a contribution, but feel stuck - please do not be afraid to submit a pull request, we will help you get it in.

hacking/getting-started.md
hacking/guidelines.md
hacking/testing.md
hacking/keybinds.md
hacking/additional-plugins.md

Known Issues and Quirks

At times, certain plugins and modules may refuse to play nicely with your setup, be it a result of generating Lua from Nix, or the state of packaging. This page, in turn, will list any known modules or plugins that are known to misbehave, and possible workarounds that you may apply.

quirks/nodejs.md

nvf Configuration Options

Below are the module options provided by nvf, in no particular order. Most options will include useful comments, warnings or setup tips on how a module option is meant to be used as well as examples in complex cases.

An offline version of this page is bundled with nvf as a part of the manpages which you can access with man 5 nvf. Please let us know if you believe any of the options below are missing useful examples.

id-prefix: opt-
list-id: nvf-options
source: @OPTIONS_JSON@