<divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="preface"><ahref="index.xhtml#ch-preface">Preface</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-what-is-it">What is nvf</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-bugs-suggestions">Bugs & Suggestions</a></span></dt></dl></dd><dt><spanclass="preface"><ahref="index.xhtml#ch-try-it-out">Try it out</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-using-prebuilt-configs">Using Prebuilt Configs</a></span></dt></dl></dd><dt><spanclass="part"><ahref="index.xhtml#ch-default-configs">Default Configs</a></span></dt><dd><dl><dt><spanclass="chapter"><ahref="index.xhtml#sec-default-maximal">Maximal</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#sec-default-nix">Nix</a></span></dt></dl></dd><dt><spanclass="part"><ahref="index.xhtml#ch-installation">Installing nvf</a></span></dt><dd><dl><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-installation">Standalone Installation</a></span></dt><dd><dl><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-nixos">Standalone Installation on NixOS</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-hm">Standalone Installation on Home-Manager</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-module-installation">Module Installation</a></span></dt><dd><dl><dt><spanclass="chapter"><ahref="index.xhtml#ch-nixos-module">NixOS Module</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-hm-module">Home-Manager Module</a></span></dt></dl></dd></dl></dd><dt><spanclass="part"><ahref="index.xhtml#ch-configuring">Configuring nvf</a></span></dt><dd><dl><dt><spanclass="chapter"><ahref="index.xhtml#ch-custom-package">Custom Neovim Package</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-custom-plugins">Custom Plugins</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#ch-adding-plugins">Adding Plugins</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-custom-inputs">Custom Inputs</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-languages">Language Support</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-using-dags">Using DAGs</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entryAnywhere">entryAnywhere</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#ch-types-dag-entryAfter">entryAfter</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#ch-types-dag-entryBefore">entryBefore</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entryBetween">entryBetween</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesAnywhere">entriesAnywhere</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesAfter">entriesAfter</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesBefore">entriesBefore</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesBetween">entriesBetween</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-dag-entries">DAG entries in nvf</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#ch-vim-luaconfigrc"><codeclass="literal">vim.luaConfigRC</code> (top-level DAG)</a></span></dt></dl></dd></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-hacking">Hacking nvf</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-contrib-getting-started">Getting Started</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines">Guidelines</a></span></dt><dt><spanclass="section"><ahref="index.x
<divclass="preface"><divclass="titlepage"><div><div><h1id="ch-preface"class="title">Preface </h1></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-what-is-it">What is nvf</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-bugs-suggestions">Bugs & Suggestions</a></span></dt></dl></div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-what-is-it"class="title">What is nvf </h2></div></div></div><p>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.</p>
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-bugs-suggestions"class="title">Bugs & Suggestions </h2></div></div></div><p>If you notice any issues with nvf, or this documentation, then please consider
reporting them over at the <aclass="link"href="https://github.com/notashelf/nvf/issues"target="_top">issue tracker</a>. Issues tab, in addition to the
<aclass="link"href="https://github.com/notashelf/nvf/discussions"target="_top">discussions tab</a> is a good place as any to request new features.</p><p>You may also consider submitting bugfixes, feature additions and upstreamed
changes that you think are critical over at the <aclass="link"href="https://github.com/notashelf/nvf/pulls"target="_top">pull requests tab</a>.</p>
</div>
</div><divclass="preface"><divclass="titlepage"><div><div><h1id="ch-try-it-out"class="title">Try it out </h1></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-using-prebuilt-configs">Using Prebuilt Configs</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-available-configs">Available Configs</a></span></dt></dl></dd></dl></div><p>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:</p><divclass="itemizedlist"><ulclass="itemizedlist compact"style="list-style-type: disc;"><liclass="listitem"><p><spanclass="strong"><strong>Nix</strong></span> - Nix language server + simple utility plugins</p></li><liclass="listitem"><p><spanclass="strong"><strong>Maximal</strong></span> - Variable language servers + utility and decorative plugins</p></li></ul></div><p>You may try out any of the provided configurations using the <codeclass="literal">nix run</code> command
on a system where Nix is installed.</p><pre><codeclass="programlisting bash">$ cachix use nvf # Optional: it'll save you CPU resources and time
</code></pre><p>Do keep in mind that this is <spanclass="strong"><strong>susceptible to garbage collection</strong></span> meaning it
will be removed from your Nix store once you garbage collect.</p><divclass="section"><divclass="titlepage"><div><div><h2id="sec-using-prebuilt-configs"class="title">Using Prebuilt Configs </h2></div></div></div><divclass="toc"><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-available-configs">Available Configs</a></span></dt></dl></div><pre><codeclass="programlisting bash">$ nix run github:notashelf/nvf#nix
</code></pre><divclass="section"><divclass="titlepage"><div><div><h3id="sec-available-configs"class="title">Available Configs </h3></div></div></div><divclass="section"><divclass="titlepage"><div><div><h4id="sec-configs-nix"class="title">Nix </h4></div></div></div><p><codeclass="literal">Nix</code> configuration by default provides LSP/diagnostic support for Nix alongside
a set of visual and functional plugins. By running <codeclass="literal">nix run .#</code>, which is the
default package, you will build Neovim with this config.</p>
</div><divclass="section"><divclass="titlepage"><div><div><h4id="sec-configs-maximal"class="title">Maximal </h4></div></div></div><p><codeclass="literal">Maximal</code> is the ultimate configuration that will enable support for more
commonly used language as well as additional complementary plugins. Keep in
mind, however, that this will pull a lot of dependencies.</p><divclass="tip"><h3class="title">Tip</h3><p>You are <spanclass="emphasis"><em>strongly</em></span> recommended to use the binary cache if you would like to try
</div><divclass="part"><divclass="titlepage"><div><div><h1id="ch-default-configs"class="title">Default Configs </h1></div></div></div><divclass="partintro"><p>While you can configure <spanclass="strong"><strong>nvf</strong></span> yourself using the builder, you can also use the
pre-built configs that are available. Here are a few default configurations you
can use.</p><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="chapter"><ahref="index.xhtml#sec-default-maximal">Maximal</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#sec-default-nix">Nix</a></span></dt></dl></div></div><divclass="chapter"><divclass="titlepage"><div><div><h2id="sec-default-maximal"class="title">Maximal </h2></div></div></div><pre><codeclass="programlisting bash">$ nix shell github:notashelf/nvf#maximal test.nix
configuration, but with every supported language enabled.</p><p>::: {.note} Running the maximal config will download <spanclass="emphasis"><em>a lot</em></span> of packages as it
is downloading language servers, formatters, and more. :::</p>
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="sec-default-nix"class="title">Nix </h2></div></div></div><pre><codeclass="programlisting bash">$ nix run github:notashelf/nvf#nix test.nix
</code></pre><p>Enables all the of Neovim plugins, with language support for specifically Nix.
This lets you see what a fully configured neovim setup looks like without
downloading a whole bunch of language servers and associated tools.</p>
</div>
</div><divclass="part"><divclass="titlepage"><div><div><h1id="ch-installation"class="title">Installing nvf </h1></div></div></div><divclass="partintro"><p>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
<aclass="link"href="index.xhtml#ch-module-installation"title="Module Installation">module installation section</a>.</p><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-installation">Standalone Installation</a></span></dt><dd><dl><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-nixos">Standalone Installation on NixOS</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-hm">Standalone Installation on Home-Manager</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-module-installation">Module Installation</a></span></dt><dd><dl><dt><spanclass="chapter"><ahref="index.xhtml#ch-nixos-module">NixOS Module</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-hm-module">Home-Manager Module</a></span></dt></dl></dd></dl></div></div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-standalone-installation"class="title">Standalone Installation </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-nixos">Standalone Installation on NixOS</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-standalone-hm">Standalone Installation on Home-Manager</a></span></dt></dl></div><p>It is possible to install nvf without depending on NixOS or Home-Manager as the
parent module system, using the <codeclass="literal">neovimConfiguration</code> function exposed in the
extended library. This function will take <codeclass="literal">modules</code> and <codeclass="literal">extraSpecialArgs</code> as
arguments, and return the following schema as a result.</p><pre><codeclass="programlisting nix">{
# Set the default package to the wrapped instance of Neovim.
# This will allow running your Neovim configuration with
# `nix run` and in addition, sharing your configuration with
# other users in case your repository is public.
default = neovimConfigured.neovim;
};
};
}
</code></pre><p>The above setup will allow to set up nvf as a standalone flake, which you can
build independently from your system configuration while also possibly sharing
it with others. The next two chapters will detail specific usage of such a setup
for a package output in the context of NixOS or Home-Manager installation.</p><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-standalone-nixos"class="title">Standalone Installation on NixOS </h2></div></div></div><p>Your built Neovim configuration can be exposed as a flake output to make it
easier to share across machines, repositories and so on. Or it can be added to
your system packages to make it available across your system.</p><p>The following is an example installation of <codeclass="literal">nvf</code> as a standalone package with
the default theme enabled. You may use other options inside <codeclass="literal">config.vim</code> in
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-standalone-hm"class="title">Standalone Installation on Home-Manager </h2></div></div></div><p>Your built Neovim configuration can be exposed as a flake output to make it
easier to share across machines, repositories and so on. Or it can be added to
your system packages to make it available across your system.</p><p>The following is an example installation of <codeclass="literal">nvf</code> as a standalone package with
the default theme enabled. You may use other options inside <codeclass="literal">config.vim</code> in
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-module-installation"class="title">Module Installation </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="chapter"><ahref="index.xhtml#ch-nixos-module">NixOS Module</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-example-installation-nixos">Example Installation</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-hm-module">Home-Manager Module</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-example-installation-hm">Example Installation</a></span></dt></dl></dd></dl></div><p>The below chapters will describe installing nvf as NixOS and Home-Manager
modules. Note that those methods are mutually exclusive, and will likely cause
path collisions if used simultaneously.</p><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-nixos-module"class="title">NixOS Module </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-example-installation-nixos">Example Installation</a></span></dt></dl></div><p>The NixOS module allows us to customize the different <codeclass="literal">vim</code> options from inside
# your settings need to go into the settings attribute set
# most settings are documented in the appendix
settings = {
vim.viAlias = false;
vim.vimAlias = true;
vim.lsp = {
enable = true;
};
};
};
}
</code></pre><divclass="note"><h3class="title">Note</h3><p><spanclass="strong"><strong>nvf</strong></span> exposes a lot of options, most of which are not referenced in the
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-hm-module"class="title">Home-Manager Module </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-example-installation-hm">Example Installation</a></span></dt></dl></div><p>The home-manager module allows us to customize the different <codeclass="literal">vim</code> options from
inside the home-manager configuration without having to call for the wrapper
yourself. It is the recommended way to use <spanclass="strong"><strong>nvf</strong></span> alongside the NixOS module
depending on your needs.</p><p>To use it, we first add the input flake.</p><pre><codeclass="programlisting nix">{
</code></pre><divclass="note"><h3class="title">Note</h3><p><spanclass="strong"><strong>nvf</strong></span> exposes a lot of options, most of which are not referenced in the
</div><divclass="part"><divclass="titlepage"><div><div><h1id="ch-configuring"class="title">Configuring nvf </h1></div></div></div><divclass="partintro"><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="chapter"><ahref="index.xhtml#ch-custom-package">Custom Neovim Package</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-custom-plugins">Custom Plugins</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#ch-adding-plugins">Adding Plugins</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-custom-inputs">Custom Inputs</a></span></dt><dt><spanclass="chapter"><ahref="index.xhtml#ch-languages">Language Support</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-using-dags">Using DAGs</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entryAnywhere">entryAnywhere</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#ch-types-dag-entryAfter">entryAfter</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#ch-types-dag-entryBefore">entryBefore</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entryBetween">entryBetween</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesAnywhere">entriesAnywhere</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesAfter">entriesAfter</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesBefore">entriesBefore</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesBetween">entriesBetween</a></span></dt></dl></dd><dt><spanclass="chapter"><ahref="index.xhtml#ch-dag-entries">DAG entries in nvf</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#ch-vim-luaconfigrc"><codeclass="literal">vim.luaConfigRC</code> (top-level DAG)</a></span></dt></dl></dd></dl></div></div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-custom-package"class="title">Custom Neovim Package </h2></div></div></div><p>As of v0.5, you may now specify the Neovim package that will be wrapped with
your configuration. This is done with the <codeclass="literal">vim.package</code> option.</p><pre><codeclass="programlisting nix">{inputs, pkgs, ...}: {
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-custom-plugins"class="title">Custom Plugins </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#ch-adding-plugins">Adding Plugins</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-configuring-plugins">Configuring</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-lazy-method">Lazy Method</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-non-lazy-method">Non-lazy Method</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-legacy-method">Legacy Method</a></span></dt></dl></dd></dl></div><p><spanclass="strong"><strong>nvf</strong></span>, by default, exposes a wide variety of plugins as module options for
your convenience and bundles necessary dependencies into <spanclass="strong"><strong>nvf</strong></span>’s runtime. In
case a plugin is not available in <spanclass="strong"><strong>nvf</strong></span>, you may consider making a pull
configuration locally.</p><divclass="section"><divclass="titlepage"><div><div><h2id="ch-adding-plugins"class="title"style="clear: both">Adding Plugins </h2></div></div></div><divclass="toc"><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-configuring-plugins">Configuring</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-lazy-method">Lazy Method</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-non-lazy-method">Non-lazy Method</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-legacy-method">Legacy Method</a></span></dt></dl></div><p>There are multiple ways of adding custom plugins to your <spanclass="strong"><strong>nvf</strong></span> configuration.</p><p>You can use custom plugins, before they are implemented in the flake. To add a
plugin to the runtime, you need to add it to the <aclass="xref"href="options.html#opt-vim.startPlugins"><codeclass="option">vim.startPlugins</code></a> list
in your configuration.</p><p>Adding a plugin to <codeclass="literal">startPlugins</code> will not allow you to configure the plugin
that you have added, but <spanclass="strong"><strong>nvf</strong></span> provides multiple way of configuring any custom
plugins that you might have added to your configuration.</p><divclass="section"><divclass="titlepage"><div><div><h3id="sec-configuring-plugins"class="title">Configuring </h3></div></div></div><p>Just making the plugin to your Neovim configuration available might not always
<codeclass="literal">config.vim.lazy.plugins.*.setupOpts</code><codeclass="literal">config.vim.extraPlugins.*.setup</code> or
<codeclass="literal">config.vim.luaConfigRC</code>.</p><p>The first option uses an extended version of <codeclass="literal">lz.n</code>’s PluginSpec. <codeclass="literal">setupModule</code>
and <codeclass="literal">setupOpt</code> can be used if the plugin uses a <codeclass="literal">require('module').setup(...)</code>
pattern. Otherwise, the <codeclass="literal">before</code> and <codeclass="literal">after</code> hooks should do what you need.</p><pre><codeclass="programlisting nix">{
config.vim.lazy.plugins = {
aerial.nvim = {
# ^^^^^^^^^ this name should match the package.pname or package.name
package = aerial-nvim;
setupModule = "aerial";
setupOpts = {option_name = false;};
after = "print('aerial loaded')";
};
};
}
</code></pre><p>The second option uses an attribute set, which maps DAG section names to a
custom type, which has the fields <codeclass="literal">package</code>, <codeclass="literal">after</code>, <codeclass="literal">setup</code>. They allow you to
set the package of the plugin, the sections its setup code should be after (note
that the <codeclass="literal">extraPlugins</code> option has its own DAG scope), and the its setup code
respectively. For example:</p><pre><codeclass="programlisting nix">config.vim.extraPlugins = with pkgs.vimPlugins; {
</code></pre><divclass="note"><h3class="title">Note</h3><p>One of the greatest strengths of nvf is the ability to order
snippets of configuration via the DAG system. It will allow specifying positions
of individual sections of configuration as needed. nvf provides helper functions
in the extended library, usually under <codeclass="literal">inputs.nvf.lib.nvim.dag</code> that you may
use.</p><p>Please refer to the <aclass="link"href="/index.xhtml#ch-dag-entries"target="_top">DAG section</a> in the nvf manual
to find out more about the DAG system.</p></div>
</div><divclass="section"><divclass="titlepage"><div><div><h3id="sec-lazy-method"class="title">Lazy Method </h3></div></div></div><p>As of version <spanclass="strong"><strong>0.7</strong></span>, we exposed an API for configuring lazy-loaded plugins via
<codeclass="literal">lz.n</code> and <codeclass="literal">lzn-auto-require</code>.</p><pre><codeclass="programlisting nix">{
config.vim.lazy.plugins = {
"aerial.nvim" = {
package = pkgs.vimPlugins.aerial-nvim;
setupModule = "aerial";
setupOpts = {
option_name = true;
};
after = ''
-- custom lua code to run after plugin is loaded
print('aerial loaded')
'';
# Explicitly mark plugin as lazy. You don't need this if you define one of
# the trigger "events" below
lazy = true;
# load on command
cmd = ["AerialOpen"];
# load on event
event = ["BufEnter"];
# load on keymap
keys = [
{
key = "<leader>a";
action = ":AerialToggle<CR>";
}
];
};
};
}
</code></pre>
</div><divclass="section"><divclass="titlepage"><div><div><h3id="sec-non-lazy-method"class="title">Non-lazy Method </h3></div></div></div><p>As of version <spanclass="strong"><strong>0.5</strong></span>, we have a more extensive API for configuring plugins,
</div><divclass="section"><divclass="titlepage"><div><div><h3id="sec-legacy-method"class="title">Legacy Method </h3></div></div></div><p>Prior to version v0.5, the method of adding new plugins was adding the plugin
the plugins is determined by DAGs.</p><divclass="section"><divclass="titlepage"><div><div><h4id="sec-adding-plugins"class="title">Adding plugins </h4></div></div></div><p>To add a plugin not available in nvf as a module to your configuration, you may
add it to <aclass="xref"href="options.html#opt-vim.startPlugins"><codeclass="option">vim.startPlugins</code></a> in order to make it available to Neovim at
</code></pre><p>And to configure the added plugin, you can use the <codeclass="literal">luaConfigRC</code> option to
provide configuration as a DAG using the <spanclass="strong"><strong>nvf</strong></span> extended library.</p><pre><codeclass="programlisting nix">{inputs, ...}: let
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-custom-inputs"class="title">Custom Inputs </h2></div></div></div><p>One of the greatest strengths of <spanclass="strong"><strong>nvf</strong></span> is its ability to get plugins from
flake inputs and build them locally from any given source. For plugins that do
not require any kind of additional building step, this is a powerful method of
adding plugins to your configuration that are not packaged in nixpkgs, or those
you want to track from source without relying on nixpkgs.</p><p>The <aclass="link"href="index.xhtml#sec-additional-plugins"title="Adding Plugins">additional plugins section</a> details the addition
of new plugins to nvf under regular circumstances, i.e. while making a pull
request to the project. You may <spanclass="emphasis"><em>override</em></span> those plugin inputs in your own
<codeclass="literal">flake.nix</code> to change source versions, e.g., to use newer versions of plugins
that are not yet updated in <spanclass="strong"><strong>nvf</strong></span>.</p><pre><codeclass="programlisting nix">{
inputs = {
# ...
# The name here is arbitrary, you can name it whatever.
# This will add a plugin input called "your-neodev-input"
# that you can reference in a `follows` line.
your-neodev-input = {
url = "github:folke/neodev.nvim";
flake = false;
};
nvf = {
url = "github:notashelf/nvf";
# The name of the input must match for the follows line
# plugin-neodev-nvim is what the input is called inside nvf
</code></pre><p>This will override the source for the <codeclass="literal">neodev.nvim</code> plugin that is used in nvf
with your own input. You can update your new input via <codeclass="literal">nix flake update</code> or
more specifically <codeclass="literal">nix flake update <name of your input></code> to keep it up to date.</p><divclass="warning"><h3class="title">Warning</h3><p>While updating plugin inputs, make sure that any configuration that has been
deprecated in newer versions is changed in the plugin’s <codeclass="literal">setupOpts</code>. If you
depend on a new version, requesting a version bump in the issues section is a
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-languages"class="title">Language Support </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a></span></dt></dl></div><p>Language specific support means there is a combination of language specific
plugins, <codeclass="literal">treesitter</code> support, <codeclass="literal">nvim-lspconfig</code> language servers, and <codeclass="literal">null-ls</code>
integration. This gets you capabilities ranging from autocompletion to
formatting to diagnostics. The following languages have sections under the
<codeclass="literal">vim.languages</code> attribute.</p><divclass="itemizedlist"><ulclass="itemizedlist compact"style="list-style-type: disc;"><liclass="listitem"><p>Rust: <aclass="link"href="options.html#opt-vim.languages.rust.enable">vim.languages.rust.enable</a></p></li><liclass="listitem"><p>Nix: <aclass="link"href="options.html#opt-vim.languages.nix.enable">vim.languages.nix.enable</a></p></li><liclass="listitem"><p>SQL: <aclass="link"href="options.html#opt-vim.languages.sql.enable">vim.languages.sql.enable</a></p></li><liclass="listitem"><p>C/C++: <aclass="link"href="options.html#opt-vim.languages.clang.enable">vim.languages.clang.enable</a></p></li><liclass="listitem"><p>Typescript/Javascript: <aclass="link"href="options.html#opt-vim.languages.ts.enable">vim.languages.ts.enable</a></p></li><liclass="listitem"><p>Python: <aclass="link"href="options.html#opt-vim.languages.python.enable">vim.languages.python.enable</a>:</p></li><liclass="listitem"><p>Zig: <aclass="link"href="options.html#opt-vim.languages.zig.enable">vim.languages.zig.enable</a></p></li><liclass="listitem"><p>Markdown: <aclass="link"href="options.html#opt-vim.languages.markdown.enable">vim.languages.markdown.enable</a></p></li><liclass="listitem"><p>HTML: <aclass="link"href="options.html#opt-vim.languages.html.enable">vim.languages.html.enable</a></p></li><liclass="listitem"><p>Dart: <aclass="link"href="options.html#opt-vim.languages.dart.enable">vim.languages.dart.enable</a></p></li><liclass="listitem"><p>Go: <aclass="link"href="options.html#opt-vim.languages.go.enable">vim.languages.go.enable</a></p></li><liclass="listitem"><p>Lua: <aclass="link"href="options.html#opt-vim.languages.lua.enable">vim.languages.lua.enable</a></p></li><liclass="listitem"><p>PHP: <aclass="link"href="options.html#opt-vim.languages.php.enable">vim.languages.php.enable</a></p></li></ul></div><p>Adding support for more languages, and improving support for existing ones are
great places where you can contribute with a PR.</p><divclass="section"><divclass="titlepage"><div><div><h2id="sec-languages-custom-lsp-packages"class="title"style="clear: both">LSP Custom Packages/Command </h2></div></div></div><p>In any of the <codeclass="literal">opt.languages.<language>.lsp.package</code> options you can provide
your own LSP package, or provide the command to launch the language server, as a
list of strings. You can use this to skip automatic installation of a language
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-using-dags"class="title">Using DAGs </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entryAnywhere">entryAnywhere</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#ch-types-dag-entryAfter">entryAfter</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#ch-types-dag-entryBefore">entryBefore</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entryBetween">entryBetween</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesAnywhere">entriesAnywhere</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesAfter">entriesAfter</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesBefore">entriesBefore</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-types-dag-entriesBetween">entriesBetween</a></span></dt></dl></div><p>We conform to the NixOS options types for the most part, however, a noteworthy
explains in more detail the overall usage logic of the DAG type.</p><divclass="section"><divclass="titlepage"><div><div><h2id="sec-types-dag-entryAnywhere"class="title"style="clear: both">entryAnywhere </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entryAnywhere (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <codeclass="literal">value</code> can be placed anywhere within the DAG. This is also the
default for plain attribute set entries, that is</p><pre><codeclass="programlisting nix">foo.bar = {
</div><divclass="section"><divclass="titlepage"><div><div><h2id="ch-types-dag-entryAfter"class="title"style="clear: both">entryAfter </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entryAfter (afters: list string) (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <codeclass="literal">value</code> must be placed <spanclass="emphasis"><em>after</em></span> each of the attribute names in the
given list. For example</p><pre><codeclass="programlisting nix">foo.bar = {
</div><divclass="section"><divclass="titlepage"><div><div><h2id="ch-types-dag-entryBefore"class="title"style="clear: both">entryBefore </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entryBefore (befores: list string) (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <codeclass="literal">value</code> must be placed <spanclass="emphasis"><em>before</em></span> each of the attribute names in
the given list. For example</p><pre><codeclass="programlisting nix">foo.bar = {
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-types-dag-entryBetween"class="title"style="clear: both">entryBetween </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry<T></code></p></blockquote></div><p>Indicates that <codeclass="literal">value</code> must be placed <spanclass="emphasis"><em>before</em></span> the attribute names in the first
list and <spanclass="emphasis"><em>after</em></span> the attribute names in the second list. For example</p><pre><codeclass="programlisting nix">foo.bar = {
</code></pre><p>would place <codeclass="literal">c</code> before <codeclass="literal">b</code> and after <codeclass="literal">a</code> in the graph.</p><p>There are also a set of functions that generate a DAG from a list. These are
convenient when you just want to have a linear list of DAG entries, without
having to manually enter the relationship between each entry. Each of these
functions take a <codeclass="literal">tag</code> as argument and the DAG entries will be named
<codeclass="literal">${tag}-${index}</code>.</p>
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-types-dag-entriesAnywhere"class="title"style="clear: both">entriesAnywhere </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled using the given tag.
For example</p><pre><codeclass="programlisting nix">foo.bar = lib.dag.entriesAnywhere "a" [ 0 1 ];
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-types-dag-entriesAfter"class="title"style="clear: both">entriesAfter </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled using the given tag.
The list of values are placed are placed <spanclass="emphasis"><em>after</em></span> each of the attribute names in
<codeclass="literal">afters</code>. For example</p><pre><codeclass="programlisting nix">foo.bar =
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-types-dag-entriesBefore"class="title"style="clear: both">entriesBefore </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled using the given tag.
The list of values are placed <spanclass="emphasis"><em>before</em></span> each of the attribute names in <codeclass="literal">befores</code>.
For example</p><pre><codeclass="programlisting nix">foo.bar =
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-types-dag-entriesBetween"class="title"style="clear: both">entriesBetween </h2></div></div></div><divclass="blockquote"><blockquoteclass="blockquote"><p><codeclass="literal">lib.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag<T></code></p></blockquote></div><p>Creates a DAG with the given values with each entry labeled using the given tag.
The list of values are placed <spanclass="emphasis"><em>before</em></span> each of the attribute names in <codeclass="literal">befores</code>
and <spanclass="emphasis"><em>after</em></span> each of the attribute names in <codeclass="literal">afters</code>. For example</p><pre><codeclass="programlisting nix">foo.bar =
</div><divclass="chapter"><divclass="titlepage"><div><div><h2id="ch-dag-entries"class="title">DAG entries in nvf </h2></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#ch-vim-luaconfigrc"><codeclass="literal">vim.luaConfigRC</code> (top-level DAG)</a></span></dt></dl></div><p>From the previous chapter, it should be clear that DAGs are useful, because you
entries in nvf:</p><divclass="section"><divclass="titlepage"><div><div><h2id="ch-vim-luaconfigrc"class="title"style="clear: both"><codeclass="literal">vim.luaConfigRC</code> (top-level DAG) </h2></div></div></div><divclass="orderedlist"><olclass="orderedlist compact"type="1"><liclass="listitem"><p>(<codeclass="literal">luaConfigPre</code>) - not a part of the actual DAG, instead, it’s simply
inserted before the rest of the DAG</p></li><liclass="listitem"><p><codeclass="literal">globalsScript</code> - used to set globals defined in <codeclass="literal">vim.globals</code></p></li><liclass="listitem"><p><codeclass="literal">basic</code> - used to set basic configuration options</p></li><liclass="listitem"><p><codeclass="literal">optionsScript</code> - used to set options defined in <codeclass="literal">vim.o</code></p></li><liclass="listitem"><p><codeclass="literal">theme</code> (this is simply placed before <codeclass="literal">pluginConfigs</code> and <codeclass="literal">lazyConfigs</code>,
meaning that surrounding entries don’t depend on it) - used to set up the
theme, which has to be done before other plugins</p></li><liclass="listitem"><p><codeclass="literal">lazyConfigs</code> - <codeclass="literal">lz.n</code> and <codeclass="literal">lzn-auto-require</code> configs. If <codeclass="literal">vim.lazy.enable</code>
is false, this will contain each plugin’s config instead.</p></li><liclass="listitem"><p><codeclass="literal">pluginConfigs</code> - the result of the nested <codeclass="literal">vim.pluginRC</code> (internal option,
see the <aclass="link"href="/index.xhtml#ch-custom-plugins"target="_top">Custom Plugins</a> page for adding your
own plugins) DAG, used to set up internal plugins</p></li><liclass="listitem"><p><codeclass="literal">extraPluginConfigs</code> - the result of <codeclass="literal">vim.extraPlugins</code>, which is not a
direct DAG, but is converted to, and resolved as one internally</p></li><liclass="listitem"><p><codeclass="literal">mappings</code> - the result of <codeclass="literal">vim.maps</code></p></li></ol></div>
</div><divclass="chapter"><divclass="titlepage"><div><div><h1id="ch-hacking"class="title">Hacking nvf </h1></div></div></div><divclass="toc"><p><strong>Table of Contents</strong></p><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-contrib-getting-started">Getting Started</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines">Guidelines</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-documentation">Adding Documentation</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-formatting">Formatting Code</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-commit-message-style">Formatting Commits</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-commit-style">Commit Style</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-ex-commit-message">Example Commit</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-code-style">Code Style</a></span></dt></dl></dd><dt><spanclass="section"><ahref="index.xhtml#sec-testing-changes">Testing Changes</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-keybinds">Keybinds</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-custom-key-mappings">Custom Key Mappings Support for a Plugin</a></span></dt></dl></dd><dt><spanclass="section"><ahref="index.xhtml#sec-additional-plugins">Adding Plugins</a></span></dt><dd><dl><dt><spanclass="section"><ahref="index.xhtml#sec-modular-setup-options">Modular setup options</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-details-of-toluaobject">Details of toLuaObject</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-lazy-plugins">Lazy plugins</a></span></dt></dl></dd></dl></div><p>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.</p><p>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 <aclass="link"href="https://github.com/notashelf/nvf/issues"target="_top">open issues</a> and if no matching issue exists you may open a
<aclass="link"href="https://github.com/notashelf/nvf/issues/new"target="_top">new issue</a> and describe your problem/request.</p><p>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.</p><divclass="section"><divclass="titlepage"><div><div><h1id="sec-contrib-getting-started"class="title"style="clear: both">Getting Started </h1></div></div></div><p>You, naturally, would like to start by forking the repository to get started. If
you are new to Git and GitHub, do have a look at GitHub’s
<aclass="link"href="https://help.github.com/articles/fork-a-repo/"target="_top">Fork a repo guide</a> for
instructions on how you can do this. Once you have a fork of <spanclass="strong"><strong>nvf</strong></span>, you should
create a separate branch based on the most recent <codeclass="literal">main</code> branch. Give your
branch a reasonably descriptive name (e.g. <codeclass="literal">feature/debugger</code> or
<codeclass="literal">fix/pesky-bug</code>) and you are ready to work on your changes</p><p>Implement your changes and commit them to the newly created branch and when you
</div><divclass="section"><divclass="titlepage"><div><div><h1id="sec-guidelines"class="title"style="clear: both">Guidelines </h1></div></div></div><divclass="toc"><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-documentation">Adding Documentation</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-formatting">Formatting Code</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-commit-message-style">Formatting Commits</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-commit-style">Commit Style</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-ex-commit-message">Example Commit</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-guidelines-code-style">Code Style</a></span></dt></dl></div><p>If your contribution tightly follows the guidelines, then there is a good chance
it will be merged without too much trouble. Some of the guidelines will be
strictly enforced, others will remain as gentle nudges towards the correct
direction. As we have no automated system enforcing those guidelines, please try
to double check your changes before making your pull request in order to avoid
“faulty” code slipping by.</p><p>If you are uncertain how these rules affect the change you would like to make
then feel free to start a discussion in the
<aclass="link"href="https://github.com/NotAShelf/nvf/discussions"target="_top">discussions tab</a> ideally (but not
necessarily) before you start developing.</p><divclass="section"><divclass="titlepage"><div><div><h2id="sec-guidelines-documentation"class="title"style="clear: both">Adding Documentation </h2></div></div></div><p>Most, if not all, changes warrant changes to the documentation. Module options
albeit with exceptions.</p><p>::: {.note} As of <spanclass="strong"><strong>v0.5</strong></span>, <spanclass="strong"><strong>nvf</strong></span> is itself documented using full markdown in
both module options and the manual. With <spanclass="strong"><strong>v0.6</strong></span>, this manual has also been
converted to markdown in full. :::</p><p>The HTML version of this manual containing both the module option descriptions
and the documentation of <spanclass="strong"><strong>nvf</strong></span> (such as this page) can be generated and opened
by typing the following in a shell within a clone of the <spanclass="strong"><strong>nvf</strong></span> Git repository:</p><pre><codeclass="programlisting console">$ nix build .#docs-html
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-guidelines-formatting"class="title"style="clear: both">Formatting Code </h2></div></div></div><p>Make sure your code is formatted as described in
<aclass="link"href="index.xhtml#sec-guidelines-code-style"title="Code Style">code-style section</a>. To maintain consistency
throughout the project you are encouraged to browse through existing code and
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-guidelines-commit-message-style"class="title"style="clear: both">Formatting Commits </h2></div></div></div><p>Similar to <aclass="link"href="index.xhtml#sec-guidelines-code-style"title="Code Style">code style guidelines</a> we encourage a
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-guidelines-commit-style"class="title"style="clear: both">Commit Style </h2></div></div></div><p>The commits in your pull request should be reasonably self-contained. Which
minor fix in spelling or a formatting change does not warrant long description,
however, a module addition or removal does as you would like to provide the
relevant context, i.e. the reasoning behind it, for your commit.</p><p>Finally, when adding a new module, say <codeclass="literal">modules/foo.nix</code>, we use the fixed
commit format <codeclass="literal">foo: add module</code>. You can, of course, still include a long
description if you wish.</p><p>In case of nested modules, i.e <codeclass="literal">modules/languages/java.nix</code> you are recommended
to contain the parent as well - for example <codeclass="literal">languages/java: some major change</code>.</p>
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-guidelines-code-style"class="title"style="clear: both">Code Style </h2></div></div></div><divclass="section"><divclass="titlepage"><div><div><h3id="sec-code-style-treewide"class="title">Treewide </h3></div></div></div><p>Keep lines at a reasonable width, ideally 80 characters or less. This also
applies to string literals and module descriptions and documentation.</p>
</div><divclass="section"><divclass="titlepage"><div><div><h3id="sec-code-style-nix"class="title">Nix </h3></div></div></div><p><spanclass="strong"><strong>nvf</strong></span> is formatted by the
<aclass="link"href="https://github.com/kamadorueda/alejandra"target="_top">alejandra</a> tool and the formatting is
checked in the pull request and push workflows. Run the <codeclass="literal">nix fmt</code> command inside
the project repository before submitting your pull request.</p><p>While Alejandra is mostly opinionated on how code looks after formatting,
certain changes are done at the user’s discretion based on how the original code
was structured.</p><p>Please use one line code for attribute sets that contain only one subset. For
example:</p><pre><codeclass="programlisting nix"># parent modules should always be unfolded
</code></pre><p>If you move a line down after the merge operator, Alejandra will automatically
unfold the whole merged attrset for you, which we <spanclass="strong"><strong>do not</strong></span> want.</p><pre><codeclass="programlisting nix">module = {
</div><divclass="section"><divclass="titlepage"><div><div><h1id="sec-testing-changes"class="title"style="clear: both">Testing Changes </h1></div></div></div><p>Once you have made your changes, you will need to test them thoroughly. If it is
</div><divclass="section"><divclass="titlepage"><div><div><h1id="sec-keybinds"class="title"style="clear: both">Keybinds </h1></div></div></div><divclass="toc"><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-custom-key-mappings">Custom Key Mappings Support for a Plugin</a></span></dt></dl></div><p>As of 0.4, there exists an API for writing your own keybinds and a couple of
<aclass="link"href="https://github.com/NotAShelf/nvf/tree/main/lib"target="_top">extended standard library</a>. The
following section contains a general overview to how you may utilize said
functions.</p><divclass="section"><divclass="titlepage"><div><div><h2id="sec-custom-key-mappings"class="title"style="clear: both">Custom Key Mappings Support for a Plugin </h2></div></div></div><p>To set a mapping, you should define it in <codeclass="literal">vim.keymaps</code>.</p><p>An example, simple keybinding, can look like this:</p><pre><codeclass="programlisting nix">{
<aclass="link"href="https://notashelf.github.io/nvf/options.html#opt-vim.keymaps"target="_top">documentation</a> to
see a list of them.</p><p><spanclass="strong"><strong>nvf</strong></span> provides a helper function, so that you don’t have to write the
mapping attribute sets every time:</p><divclass="itemizedlist"><ulclass="itemizedlist compact"style="list-style-type: disc;"><liclass="listitem"><p><codeclass="literal">mkKeymap</code>, which mimics neovim’s <codeclass="literal">vim.keymap.set</code> function</p></li></ul></div><p>You can read the source code of some modules to see them in action, but the
</div><divclass="section"><divclass="titlepage"><div><div><h1id="sec-additional-plugins"class="title"style="clear: both">Adding Plugins </h1></div></div></div><divclass="toc"><dlclass="toc"><dt><spanclass="section"><ahref="index.xhtml#sec-modular-setup-options">Modular setup options</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-details-of-toluaobject">Details of toLuaObject</a></span></dt><dt><spanclass="section"><ahref="index.xhtml#sec-lazy-plugins">Lazy plugins</a></span></dt></dl></div><p>To add a new Neovim plugin, first add the source url in the inputs section of
<codeclass="literal">flake.nix</code> with the prefix <codeclass="literal">plugin-</code></p><pre><codeclass="programlisting nix">{
</code></pre><p>Prepending <codeclass="literal">plugin-</code> to the name of the input will allow nvf to automatically
discover inputs that are marked as plugins, and make them available in
<codeclass="literal">vim.startPlugins</code> or other areas that require a very specific plugin type as it
is defined in <codeclass="literal">https://github.com/notashelf/nvf/blob/v0.7/lib/types/plugins.nix</code></p><p>The addition of the <codeclass="literal">plugin-</code> prefix will allow <spanclass="strong"><strong>nvf</strong></span> to autodiscover the
input from the flake inputs automatically, allowing you to refer to it in areas
that require a very specific plugin type as defined in <codeclass="literal">lib/types/plugins.nix</code></p><p>You can now reference this plugin using its string name, the plugin will be
built with the name and source URL from the flake input, allowing you to refer
to it as a <spanclass="strong"><strong>string</strong></span>.</p><pre><codeclass="programlisting nix">config.vim.startPlugins = ["neodev-nvim"];
</code></pre><divclass="section"><divclass="titlepage"><div><div><h2id="sec-modular-setup-options"class="title"style="clear: both">Modular setup options </h2></div></div></div><p>Most plugins is initialized with a call to <codeclass="literal">require('plugin').setup({...})</code>.</p><p>We use a special function that lets you easily add support for such setup
options in a modular way: <codeclass="literal">mkPluginSetupOption</code>.</p><p>Once you have added the source of the plugin as shown above, you can define the
setup options like this:</p><pre><codeclass="programlisting nix"># in modules/.../your-plugin/your-plugin.nix
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-details-of-toluaobject"class="title"style="clear: both">Details of toLuaObject </h2></div></div></div><p>As you’ve seen above, <codeclass="literal">toLuaObject</code> is used to convert our nix attrSet
<codeclass="literal">cfg.setupOpts</code>, into a lua table. Here are some rules of the conversion:</p><divclass="orderedlist"><olclass="orderedlist compact"type="1"><liclass="listitem"><p>nix <codeclass="literal">null</code> converts to lua <codeclass="literal">nil</code></p></li><liclass="listitem"><p>number and strings convert to their lua counterparts</p></li><liclass="listitem"><p>nix attrSet/list convert into lua tables</p></li><liclass="listitem"><p>you can write raw lua code using <codeclass="literal">lib.generators.mkLuaInline</code>. This function
is part of nixpkgs.</p></li></ol></div><p>Example:</p><pre><codeclass="programlisting nix">vim.your-plugin.setupOpts = {
</div><divclass="section"><divclass="titlepage"><div><div><h2id="sec-lazy-plugins"class="title"style="clear: both">Lazy plugins </h2></div></div></div><p>If the plugin can be lazy-loaded, <codeclass="literal">vim.lazy.plugins</code> should be used to add it.
Lazy plugins are managed by <codeclass="literal">lz.n</code>.</p><pre><codeclass="programlisting nix"># in modules/.../your-plugin/config.nix
{lib, config, ...}:
let
cfg = config.vim.your-plugin;
in {
vim.lazy.plugins.your-plugin = {
# instead of vim.startPlugins, use this:
package = "your-plugin";
# if your plugin uses the `require('your-plugin').setup{...}` pattern
setupModule = "your-plugin";
inherit (cfg) setupOpts;
# events that trigger this plugin to be loaded
event = ["DirChanged"];
cmd = ["YourPluginCommand"];
# keymaps
keys = [
# we'll cover this in detail in the keymaps section
{
key = "<leader>d";
mode = "n";
action = ":YourPluginCommand";
}
];
};
;
}
</code></pre><p>This results in the following lua code:</p><pre><codeclass="programlisting lua">require('lz.n').load({
{
"name-of-your-plugin",
after = function()
require('your-plugin').setup({--[[ your setupOpts ]]})
