mirror of
https://github.com/NotAShelf/nvf.git
synced 2025-09-06 02:11:33 +00:00
deploy: 5d229d48c7
This commit is contained in:
NotAShelf
parent
38035d9c04
commit
77e16b93d1
49 changed files with 301 additions and 210426 deletions
395
index.xhtml
395
index.xhtml
|
|
@ -33,7 +33,7 @@
|
|||
</div>
|
||||
<hr />
|
||||
</div>
|
||||
<div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="preface"> <a href="index.xhtml#ch-preface">Preface</a> </span></dt><dt> <span class="preface"> <a href="index.xhtml#ch-try-it-out">Try it out</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-default-configs">Default Configs</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#sec-default-maximal">Maximal</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-default-nix">Nix</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-installation">Installing nvf</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-installation">Standalone Installation</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-module-installation">Module Installation</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-configuring">Configuring nvf</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-overriding-plugins">Overriding plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-using-dags">Using DAGs</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-dag-entries">DAG entries in nvf</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-helpful-tips">Helpful Tips</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#sec-pure-lua-config">Pure Lua Configuration</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-debugging-nvf">Debugging nvf</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-offline-documentation">Offline Documentation</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-hacking">Hacking nvf</a> </span></dt><dt> <span class="appendix"> <a href="quirks.html">A. Known Issues and Quirks</a> </span></dt><dt> <span class="appendix"> <a href="options.html">B. nvf Configuration Options</a> </span></dt><dt> <span class="appendix"> <a href="release-notes.html">C. Release Notes</a> </span></dt> </dl></div>
|
||||
<div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="preface"> <a href="index.xhtml#ch-preface">Preface</a> </span></dt><dt> <span class="preface"> <a href="index.xhtml#ch-try-it-out">Try it out</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-installation">Installing nvf</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-standalone-installation">Standalone Installation</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-module-installation">Module Installation</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-configuring">Configuring nvf</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-overriding-plugins">Overriding plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-using-dags">Using DAGs</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-dag-entries">DAG entries in nvf</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-autocmds-augroups">Autocommands and Autogroups</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-helpful-tips">Helpful Tips</a> </span></dt><dd><dl><dt> <span class="chapter"> <a href="index.xhtml#sec-debugging-nvf">Debugging nvf</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-offline-documentation">Offline Documentation</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-pure-lua-config">Pure Lua Configuration</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-plugin-sources">Adding Plugins From Different Sources</a> </span></dt></dl></dd><dt> <span class="chapter"> <a href="index.xhtml#ch-hacking">Hacking nvf</a> </span></dt><dt> <span class="appendix"> <a href="quirks.html">A. Known Issues and Quirks</a> </span></dt><dt> <span class="appendix"> <a href="options.html">B. nvf Configuration Options</a> </span></dt><dt> <span class="appendix"> <a href="release-notes.html">C. Release Notes</a> </span></dt> </dl></div>
|
||||
<div class="preface"> <div class="titlepage"> <div> <div> <h1 id="ch-preface" class="title" >Preface </h1> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-what-is-it">What is nvf</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-bugs-suggestions">Bugs & Suggestions</a> </span></dt> </dl></div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="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>
|
||||
|
|
@ -50,32 +50,29 @@ configurations are provided:</p><div class="itemizedlist"><ul class="itemizedlis
|
|||
on a system where Nix is installed.</p><pre><code class="programlisting bash">$ cachix use nvf # Optional: it'll save you CPU resources and time
|
||||
$ nix run github:notashelf/nvf#nix # will run the default minimal configuration
|
||||
</code></pre><p>Do keep in mind that this is <span class="strong"><strong>susceptible to garbage collection</strong></span> meaning it
|
||||
will be removed from your Nix store once you garbage collect.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-using-prebuilt-configs" class="title" >Using Prebuilt Configs </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-available-configs">Available Configs</a> </span></dt> </dl></div><pre><code class="programlisting bash">$ nix run github:notashelf/nvf#nix
|
||||
will be removed from your Nix store once you garbage collect.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-using-prebuilt-configs" class="title" >Using Prebuilt Configs </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-available-configs">Available Configurations</a> </span></dt> </dl></div><pre><code class="programlisting bash">$ nix run github:notashelf/nvf#nix
|
||||
$ nix run github:notashelf/nvf#maximal
|
||||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-available-configs" class="title" >Available Configs </h3> </div> </div></div><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-configs-nix" class="title" >Nix </h4> </div> </div></div><p><code class="literal">Nix</code> configuration by default provides LSP/diagnostic support for Nix alongside
|
||||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-available-configs" class="title" >Available Configurations </h3> </div> </div></div><p>:::{.info}</p><p>The below configurations are provided for demonstration purposes, and are
|
||||
<span class="strong"><strong>not</strong></span> designed to be installed as is. You may</p><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-configs-nix" class="title" >Nix </h4> </div> </div></div><p><code class="literal">Nix</code> configuration by default provides LSP/diagnostic support for Nix alongside
|
||||
a set of visual and functional plugins. By running <code class="literal">nix run .#</code>, which is the
|
||||
default package, you will build Neovim with this config.</p>
|
||||
default package, you will build Neovim with this config.</p><pre><code class="programlisting bash">$ nix run github:notashelf/nvf#nix test.nix
|
||||
</code></pre><p>This command will start Neovim with some opinionated plugin configurations, and
|
||||
is designed specifically for Nix. the <code class="literal">nix</code> configuration lets you see how a
|
||||
fully configured Neovim setup <span class="emphasis"><em>might</em></span> look like without downloading too many
|
||||
packages or shell utilities.</p>
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-configs-maximal" class="title" >Maximal </h4> </div> </div></div><p><code class="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><div class="tip"><h3 class="title">Tip</h3><p>You are <span class="emphasis"><em>strongly</em></span> recommended to use the binary cache if you would like to try
|
||||
the Maximal configuration.</p></div>
|
||||
mind, however, that this will pull a lot of dependencies.</p><pre><code class="programlisting bash">$ nix run github:notashelf/nvf#maximal -- test.nix
|
||||
</code></pre><p>It uses the same configuration template with the <a class="link" href="index.xhtml#sec-configs-nix" title="Nix" >Nix</a>
|
||||
configuration, but supports many more languages, and enables more utility,
|
||||
companion or fun plugins.</p><div class="warning"><h3 class="title">Warning</h3><p>Running the maximal config will download <span class="emphasis"><em>a lot</em></span> of packages as it is
|
||||
downloading language servers, formatters, and more.</p></div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-default-configs" class="title" >Default Configs </h1> </div> </div></div><div class="partintro"><p>While you can configure <span class="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><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#sec-default-maximal">Maximal</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-default-nix">Nix</a> </span></dt> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-default-maximal" class="title" >Maximal </h2> </div> </div></div><pre><code class="programlisting bash">$ nix run github:notashelf/nvf#maximal -- test.nix
|
||||
</code></pre><p>It is the same fully configured Neovim as with the <a class="link" href="index.xhtml#sec-default-nix" title="Nix" >Nix</a>
|
||||
configuration, but with every supported language enabled.</p><p>::: {.note} Running the maximal config will download <span class="emphasis"><em>a lot</em></span> of packages as it
|
||||
is downloading language servers, formatters, and more. :::</p>
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-default-nix" class="title" >Nix </h2> </div> </div></div><pre><code class="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><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-installation" class="title" >Installing nvf </h1> </div> </div></div><div class="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
|
||||
|
|
@ -363,10 +360,14 @@ installation sections of the manual. You may find all available options in the
|
|||
|
||||
</div>
|
||||
</div>
|
||||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-configuring" class="title" >Configuring nvf </h1> </div> </div></div><div class="partintro"><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-overriding-plugins">Overriding plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-using-dags">Using DAGs</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-dag-entries">DAG entries in nvf</a> </span></dt> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="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 <code class="literal">vim.package</code> option.</p><pre><code class="programlisting nix">{inputs, pkgs, ...}: {
|
||||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-configuring" class="title" >Configuring nvf </h1> </div> </div></div><div class="partintro"><p>nvf allows for <span class="emphasis"><em>very</em></span> 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 <a class="link" href="index.xhtml#ch-helpful-tips" title="Helpful Tips" >helpful tips section</a> for
|
||||
more advanced or unusual configuration options supported by nvf.</p><p>Note that this section does not cover module <span class="emphasis"><em>options</em></span>. For an overview of all
|
||||
module options provided by nvf, please visit the <a class="link" href="/options.html" target="_top">appendix</a></p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-overriding-plugins">Overriding plugins</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-using-dags">Using DAGs</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-dag-entries">DAG entries in nvf</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#ch-autocmds-augroups">Autocommands and Autogroups</a> </span></dt> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="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 <a class="xref" href="options.html#opt-vim.package" ><code class="option">vim.package</code></a> option.</p><pre><code class="programlisting nix">{inputs, pkgs, ...}: {
|
||||
# using the neovim-nightly overlay
|
||||
vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim;
|
||||
vim.package = inputs.neovim-overlay.packages.${pkgs.stdenv.system}.neovim;
|
||||
}
|
||||
</code></pre><p>The neovim-nightly-overlay always exposes an unwrapped package. If using a
|
||||
different source, you are highly recommended to get an “unwrapped” version of
|
||||
|
|
@ -375,20 +376,28 @@ the neovim package, similar to <code class="literal">neovim-unwrapped</code> in
|
|||
vim.package = pkgs.neovim-unwrapped;
|
||||
}
|
||||
</code></pre>
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-custom-plugins" class="title" >Custom Plugins </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#ch-adding-plugins">Adding Plugins</a> </span></dt> </dl></div><p><span class="strong"><strong>nvf</strong></span>, by default, exposes a wide variety of plugins as module options for
|
||||
your convenience and bundles necessary dependencies into <span class="strong"><strong>nvf</strong></span>’s runtime. In
|
||||
case a plugin is not available in <span class="strong"><strong>nvf</strong></span>, you may consider making a pull
|
||||
request to <span class="strong"><strong>nvf</strong></span> to include it as a module or you may add it to your
|
||||
configuration locally.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-adding-plugins" class="title" style="clear: both">Adding Plugins </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-configuring-plugins">Configuring</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-lazy-method">Lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-non-lazy-method">Non-lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-legacy-method">Legacy Method</a> </span></dt> </dl></div><p>There are multiple ways of adding custom plugins to your <span class="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 <a class="xref" href="options.html#opt-vim.startPlugins" ><code class="option">vim.startPlugins</code></a> list
|
||||
in your configuration.</p><p>Adding a plugin to <code class="literal">startPlugins</code> will not allow you to configure the plugin
|
||||
that you have added, but <span class="strong"><strong>nvf</strong></span> provides multiple ways of configuring any custom
|
||||
plugins that you might have added to your configuration.</p><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-configuring-plugins" class="title" >Configuring </h3> </div> </div></div><p>Just making the plugin to your Neovim configuration available might not always
|
||||
be enough. In that case, you can write custom lua config using either
|
||||
<code class="literal">config.vim.lazy.plugins.*.setupOpts</code> <code class="literal">config.vim.extraPlugins.*.setup</code> or
|
||||
<code class="literal">config.vim.luaConfigRC</code>.</p><p>The first option uses an extended version of <code class="literal">lz.n</code>’s PluginSpec. <code class="literal">setupModule</code>
|
||||
and <code class="literal">setupOpt</code> can be used if the plugin uses a <code class="literal">require('module').setup(...)</code>
|
||||
pattern. Otherwise, the <code class="literal">before</code> and <code class="literal">after</code> hooks should do what you need.</p><pre><code class="programlisting nix">{
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-custom-plugins" class="title" >Custom Plugins </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#ch-adding-plugins">Adding Plugins</a> </span></dt> </dl></div><p><span class="strong"><strong>nvf</strong></span> exposes a very wide variety of plugins by default, which are consumed by
|
||||
module options. This is done for your convenience, and to bundle all necessary
|
||||
dependencies into <span class="strong"><strong>nvf</strong></span>’s runtime with full control of versioning, testing and
|
||||
dependencies. In the case a plugin you need is <span class="emphasis"><em>not</em></span> available, you may consider
|
||||
making a pull request to add the package you’re looking for, or you may add it
|
||||
to your configuration locally. The below section describes how new plugins may
|
||||
be added to the user’s configuration.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-adding-plugins" class="title" style="clear: both">Adding Plugins </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-configuring-plugins">Configuring</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-lazy-method">Lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-non-lazy-method">Non-lazy Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-legacy-method">Legacy Method</a> </span></dt> </dl></div><p>Per <span class="strong"><strong>nvf</strong></span>’s design choices, there are several ways of adding custom plugins to
|
||||
your configuration as you need them. As we aim for extensive configuration, it
|
||||
is possible to add custom plugins (from nixpkgs, pinning tools, flake inputs,
|
||||
etc.) to your Neovim configuration before they are even implemented in <span class="strong"><strong>nvf</strong></span>
|
||||
as a module.</p><p>:::{.info}</p><p>To add a plugin to your runtime, you will need to add it to
|
||||
<a class="xref" href="options.html#opt-vim.startPlugins" ><code class="option">vim.startPlugins</code></a> list in your configuration. This is akin to cloning a
|
||||
plugin to <code class="literal">~/.config/nvim</code>, but they are only ever placed in the Nix store and
|
||||
never exposed to the outside world for purity and full isolation.</p><p>:::</p><p>As you would configure a cloned plugin, you must configure the new plugins that
|
||||
you’ve added to <code class="literal">startPlugins.</code> <span class="strong"><strong>nvf</strong></span> provides multiple ways of configuring
|
||||
any custom plugins that you might have added to your configuration.</p><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-configuring-plugins" class="title" >Configuring </h3> </div> </div></div><p>Just making the plugin to your Neovim configuration available might not always
|
||||
be enough., for example, if the plugin requires a setup table. In that case, you
|
||||
can write custom Lua configuration using one of</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">config.vim.lazy.plugins.*.setupOpts</code></p></li><li class="listitem"><p><code class="literal">config.vim.extraPlugins.*.setup</code></p></li><li class="listitem"><p><code class="literal">config.vim.luaConfigRC</code>.</p></li></ul></div><div class="section"> <div class="titlepage"> <div> <div> <h4 id="ch-vim-lazy-plugins" class="title" >Lazy Plugins </h4> </div> </div></div><p><code class="literal">config.vim.lazy.plugins.*.setupOpts</code> is useful for lazy-loading plugins, and
|
||||
uses an extended version of <code class="literal">lz.n's</code> <code class="literal">PluginSpec</code> to expose a familiar
|
||||
interface. <code class="literal">setupModule</code> and <code class="literal">setupOpt</code> can be used if the plugin uses a
|
||||
<code class="literal">require('module').setup(...)</code> pattern. Otherwise, the <code class="literal">before</code> and <code class="literal">after</code>
|
||||
hooks should do what you need.</p><pre><code class="programlisting nix">{
|
||||
config.vim.lazy.plugins = {
|
||||
aerial.nvim = {
|
||||
# ^^^^^^^^^ this name should match the package.pname or package.name
|
||||
|
|
@ -401,37 +410,49 @@ pattern. Otherwise, the <code class="literal">before</code> and <code class="lit
|
|||
};
|
||||
};
|
||||
}
|
||||
</code></pre><p>The second option uses an attribute set, which maps DAG section names to a
|
||||
</code></pre>
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h4 id="ch-vim-extra-plugins" class="title" >Standard API </h4> </div> </div></div><p><code class="literal">vim.extraPlugins</code> uses an attribute set, which maps DAG section names to a
|
||||
custom type, which has the fields <code class="literal">package</code>, <code class="literal">after</code>, <code class="literal">setup</code>. They allow you to
|
||||
set the package of the plugin, the sections its setup code should be after (note
|
||||
that the <code class="literal">extraPlugins</code> option has its own DAG scope), and the its setup code
|
||||
respectively. For example:</p><pre><code class="programlisting nix">config.vim.extraPlugins = with pkgs.vimPlugins; {
|
||||
aerial = {
|
||||
package = aerial-nvim;
|
||||
setup = "require('aerial').setup {}";
|
||||
};
|
||||
respectively. For example:</p><pre><code class="programlisting nix">{pkgs, ...}: {
|
||||
config.vim.extraPlugins = {
|
||||
aerial = {
|
||||
package = pkgs.vimPlugins.aerial-nvim;
|
||||
setup = "require('aerial').setup {}";
|
||||
};
|
||||
|
||||
harpoon = {
|
||||
package = harpoon;
|
||||
setup = "require('harpoon').setup {}";
|
||||
after = ["aerial"]; # place harpoon configuration after aerial
|
||||
harpoon = {
|
||||
package = pkgs.vimPlugins.harpoon;
|
||||
setup = "require('harpoon').setup {}";
|
||||
after = ["aerial"]; # place harpoon configuration after aerial
|
||||
};
|
||||
};
|
||||
}
|
||||
</code></pre><p>The third option also uses an attribute set, but this one is resolved as a DAG
|
||||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h5 id="setup-using-luaconfigrc" class="title" >Setup using luaConfigRC </h5> </div> </div></div><p><code class="literal">vim.luaConfigRC</code> also uses an attribute set, but this one is resolved as a DAG
|
||||
directly. The attribute names denote the section names, and the values lua code.
|
||||
For example:</p><pre><code class="programlisting nix">{
|
||||
# this will create an "aquarium" section in your init.lua with the contents of your custom config
|
||||
# which will be *appended* to the rest of your configuration, inside your init.vim
|
||||
# This will create a section called "aquarium" in the 'init.lua' with the
|
||||
# contents of your custom configuration. By default 'entryAnywhere' is implied
|
||||
# in DAGs, so this will be inserted to an arbitrary position. In the case you
|
||||
# wish to control the position of this section with more precision, please
|
||||
# look into the DAGs section of the manual.
|
||||
config.vim.luaConfigRC.aquarium = "vim.cmd('colorscheme aquiarum')";
|
||||
}
|
||||
</code></pre><div class="note"><h3 class="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
|
||||
</code></pre><div class="note"><h3 class="title">Note</h3><p>One of the <span class="strong"><strong>greatest strengths</strong></span> of <span class="strong"><strong>nvf</strong></span> is the ability to order
|
||||
configuration snippets precisely using the <a class="link" href="index.xhtml#ch-using-dags" title="Using DAGs" >DAG system</a>. DAGs
|
||||
are a very powerful mechanism that allows specifying positions
|
||||
of individual sections of configuration as needed. We provide helper functions
|
||||
in the extended library, usually under <code class="literal">inputs.nvf.lib.nvim.dag</code> that you may
|
||||
use.</p><p>Please refer to the <a class="link" href="index.xhtml#ch-dag-entries" title="DAG entries in nvf" >DAG section</a> in the nvf manual
|
||||
to find out more about the DAG system.</p></div>
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-lazy-method" class="title" >Lazy Method </h3> </div> </div></div><p>As of version <span class="strong"><strong>0.7</strong></span>, we exposed an API for configuring lazy-loaded plugins via
|
||||
<code class="literal">lz.n</code> and <code class="literal">lzn-auto-require</code>.</p><pre><code class="programlisting nix">{
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-lazy-method" class="title" >Lazy Method </h3> </div> </div></div><p>As of version <span class="strong"><strong>0.7</strong></span>, an API is exposed to allow configuring lazy-loaded
|
||||
plugins via <code class="literal">lz.n</code> and <code class="literal">lzn-auto-require</code>. Below is a comprehensive example of
|
||||
how it may be loaded to lazy-load an arbitrary plugin.</p><pre><code class="programlisting nix">{
|
||||
config.vim.lazy.plugins = {
|
||||
"aerial.nvim" = {
|
||||
package = pkgs.vimPlugins.aerial-nvim;
|
||||
|
|
@ -464,7 +485,8 @@ to find out more about the DAG system.</p></div>
|
|||
};
|
||||
};
|
||||
}
|
||||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-lazyfile-event" class="title" >LazyFile event </h4> </div> </div></div><p>You can use the <code class="literal">LazyFile</code> user event to load a plugin when a file is opened:</p><pre><code class="programlisting nix">{
|
||||
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-lazyfile-event" class="title" >LazyFile event </h4> </div> </div></div><p><span class="strong"><strong>nvf</strong></span> re-implements <code class="literal">LazyFile</code> as a familiar user event to load a plugin when
|
||||
a file is opened:</p><pre><code class="programlisting nix">{
|
||||
config.vim.lazy.plugins = {
|
||||
"aerial.nvim" = {
|
||||
package = pkgs.vimPlugins.aerial-nvim;
|
||||
|
|
@ -473,16 +495,18 @@ to find out more about the DAG system.</p></div>
|
|||
};
|
||||
};
|
||||
}
|
||||
</code></pre><p>You can consider <code class="literal">LazyFile</code> as an alias to
|
||||
<code class="literal">["BufReadPost" "BufNewFile" "BufWritePre"]</code></p>
|
||||
</code></pre><p>You can consider the <code class="literal">LazyFile</code> event as an alias to the combination of
|
||||
<code class="literal">"BufReadPost"</code>, <code class="literal">"BufNewFile"</code> and <code class="literal">"BufWritePre"</code>, i.e., a list containing all
|
||||
three of those events: <code class="literal">["BufReadPost" "BufNewFile" "BufWritePre"]</code></p>
|
||||
</div>
|
||||
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-non-lazy-method" class="title" >Non-lazy Method </h3> </div> </div></div><p>As of version <span class="strong"><strong>0.5</strong></span>, we have a more extensive API for configuring plugins,
|
||||
under <code class="literal">vim.extraPlugins</code>. Instead of using DAGs exposed by the library, you may
|
||||
use the extra plugin module as follows:</p><pre><code class="programlisting nix">{
|
||||
config.vim.extraPlugins = with pkgs.vimPlugins; {
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-non-lazy-method" class="title" >Non-lazy Method </h3> </div> </div></div><p>As of version <span class="strong"><strong>0.5</strong></span>, we have a more extensive API for configuring plugins that
|
||||
should be preferred over the legacy method. This API is available as
|
||||
<a class="xref" href="options.html#opt-vim.extraPlugins" ><code class="option">vim.extraPlugins</code></a>. Instead of using DAGs exposed by the library
|
||||
<span class="emphasis"><em>directly</em></span>, you may use the extra plugin module as follows:</p><pre><code class="programlisting nix">{pkgs, ...}: {
|
||||
config.vim.extraPlugins = {
|
||||
aerial = {
|
||||
package = aerial-nvim;
|
||||
package = pkgs.vimPlugins.aerial-nvim;
|
||||
setup = ''
|
||||
require('aerial').setup {
|
||||
-- some lua configuration here
|
||||
|
|
@ -491,30 +515,37 @@ use the extra plugin module as follows:</p><pre><code class="programlisting nix"
|
|||
};
|
||||
|
||||
harpoon = {
|
||||
package = harpoon;
|
||||
package = pkgs.vimPlugins.harpoon;
|
||||
setup = "require('harpoon').setup {}";
|
||||
after = ["aerial"];
|
||||
};
|
||||
};
|
||||
}
|
||||
</code></pre>
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="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
|
||||
package to <code class="literal">vim.startPlugins</code> and add its configuration as a DAG under one of
|
||||
<code class="literal">vim.configRC</code> or <code class="literal">vim.luaConfigRC</code>. Users who have not yet updated to 0.5, or
|
||||
prefer a more hands-on approach may use the old method where the load order of
|
||||
the plugins is determined by DAGs.</p><div class="section"> <div class="titlepage"> <div> <div> <h4 id="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 <a class="xref" href="options.html#opt-vim.startPlugins" ><code class="option">vim.startPlugins</code></a> in order to make it available to Neovim at
|
||||
runtime.</p><pre><code class="programlisting nix">{pkgs, ...}: {
|
||||
</code></pre><p>This provides a level of abstraction over the DAG system for faster iteration.</p>
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 id="sec-legacy-method" class="title" >Legacy Method </h3> </div> </div></div><p>Prior to version <span class="strong"><strong>0.5</strong></span>, the method of adding new plugins was adding the plugin
|
||||
package to <a class="xref" href="options.html#opt-vim.startPlugins" ><code class="option">vim.startPlugins</code></a> and adding its configuration as a DAG under
|
||||
one of <code class="literal">vim.configRC</code> or <a class="xref" href="options.html#opt-vim.luaConfigRC" ><code class="option">vim.luaConfigRC</code></a>. While <code class="literal">configRC</code> has been
|
||||
deprecated, users who have not yet updated to 0.5 or those who prefer a more
|
||||
hands-on approach may choose to use the old method where the load order of the
|
||||
plugins is explicitly determined by DAGs without internal abstractions.</p><div class="section"> <div class="titlepage"> <div> <div> <h4 id="sec-adding-new-plugins" class="title" >Adding New Plugins </h4> </div> </div></div><p>To add a plugin not available in <span class="strong"><strong>nvf</strong></span> as a module to your configuration using
|
||||
the legacy method, you must add it to <a class="xref" href="options.html#opt-vim.startPlugins" ><code class="option">vim.startPlugins</code></a> in order to make
|
||||
it available to Neovim at runtime.</p><pre><code class="programlisting nix">{pkgs, ...}: {
|
||||
# Add a Neovim plugin from Nixpkgs to the runtime.
|
||||
# This does not need to come explicitly from packages. 'vim.startPlugins'
|
||||
# takes a list of *string* (to load internal plugins) or *package* to load
|
||||
# a Neovim package from any source.
|
||||
vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
|
||||
}
|
||||
</code></pre><p>And to configure the added plugin, you can use the <code class="literal">luaConfigRC</code> option to
|
||||
provide configuration as a DAG using the <span class="strong"><strong>nvf</strong></span> extended library.</p><pre><code class="programlisting nix">{inputs, ...}: let
|
||||
</code></pre><p>Once the package is available in Neovim’s runtime, you may use the <code class="literal">luaConfigRC</code>
|
||||
option to provide configuration as a DAG using the <span class="strong"><strong>nvf</strong></span> extended library in
|
||||
order to configure the added plugin,</p><pre><code class="programlisting nix">{inputs, ...}: let
|
||||
# This assumes you have an input called 'nvf' in your flake inputs
|
||||
# and 'inputs' in your specialArgs. In the case you have passed 'nvf'
|
||||
# to specialArgs, the 'inputs' prefix may be omitted.
|
||||
inherit (inputs.nvf.lib.nvim.dag) entryAnywhere;
|
||||
in {
|
||||
# luaConfigRC takes Lua configuration verbatim and inserts it at an arbitrary
|
||||
# position by default or if 'entryAnywhere' is used.
|
||||
vim.luaConfigRC.aerial-nvim= entryAnywhere ''
|
||||
require('aerial').setup {
|
||||
-- your configuration here
|
||||
|
|
@ -554,15 +585,20 @@ plugins, <code class="literal">treesitter</code> support, <code class="literal">
|
|||
integration. This gets you capabilities ranging from autocompletion to
|
||||
formatting to diagnostics. The following languages have sections under the
|
||||
<code class="literal">vim.languages</code> attribute.</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p>Rust: <a class="link" href="options.html#opt-vim.languages.rust.enable" >vim.languages.rust.enable</a></p></li><li class="listitem"><p>Nix: <a class="link" href="options.html#opt-vim.languages.nix.enable" >vim.languages.nix.enable</a></p></li><li class="listitem"><p>SQL: <a class="link" href="options.html#opt-vim.languages.sql.enable" >vim.languages.sql.enable</a></p></li><li class="listitem"><p>C/C++: <a class="link" href="options.html#opt-vim.languages.clang.enable" >vim.languages.clang.enable</a></p></li><li class="listitem"><p>Typescript/Javascript: <a class="link" href="options.html#opt-vim.languages.ts.enable" >vim.languages.ts.enable</a></p></li><li class="listitem"><p>Python: <a class="link" href="options.html#opt-vim.languages.python.enable" >vim.languages.python.enable</a>:</p></li><li class="listitem"><p>Zig: <a class="link" href="options.html#opt-vim.languages.zig.enable" >vim.languages.zig.enable</a></p></li><li class="listitem"><p>Markdown: <a class="link" href="options.html#opt-vim.languages.markdown.enable" >vim.languages.markdown.enable</a></p></li><li class="listitem"><p>HTML: <a class="link" href="options.html#opt-vim.languages.html.enable" >vim.languages.html.enable</a></p></li><li class="listitem"><p>Dart: <a class="link" href="options.html#opt-vim.languages.dart.enable" >vim.languages.dart.enable</a></p></li><li class="listitem"><p>Go: <a class="link" href="options.html#opt-vim.languages.go.enable" >vim.languages.go.enable</a></p></li><li class="listitem"><p>Lua: <a class="link" href="options.html#opt-vim.languages.lua.enable" >vim.languages.lua.enable</a></p></li><li class="listitem"><p>PHP: <a class="link" href="options.html#opt-vim.languages.php.enable" >vim.languages.php.enable</a></p></li><li class="listitem"><p>F#: <a class="link" href="options.html#opt-vim.languages.fsharp.enable" >vim.languages.fsharp.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><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-languages-custom-lsp-packages" class="title" style="clear: both">LSP Custom Packages/Command </h2> </div> </div></div><p>In any of the <code class="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
|
||||
server, and instead use the one found in your <code class="literal">$PATH</code> during runtime, for
|
||||
example:</p><pre><code class="programlisting nix">vim.languages.java = {
|
||||
great places where you can contribute with a PR.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-languages-custom-lsp-packages" class="title" style="clear: both">LSP Custom Packages/Command </h2> </div> </div></div><p>One of the strengths of <span class="strong"><strong>nvf</strong></span> is convenient aliases to quickly configure LSP
|
||||
servers through the Nix module system. By default the LSP packages for relevant
|
||||
language modules will be pulled into the closure. If this is not desirable, you
|
||||
may provide <span class="strong"><strong>a custom LSP package</strong></span> (e.g., a Bash script that calls a command)
|
||||
or <span class="strong"><strong>a list of strings</strong></span> to be interpreted as the command to launch the language
|
||||
server. By using a list of strings, you can use this to skip automatic
|
||||
installation of a language server, and instead use the one found in your <code class="literal">$PATH</code>
|
||||
during runtime, for example:</p><pre><code class="programlisting nix">vim.languages.java = {
|
||||
lsp = {
|
||||
enable = true;
|
||||
# this expects jdt-language-server to be in your PATH
|
||||
# or in `vim.extraPackages`
|
||||
|
||||
# This expects 'jdt-language-server' to be in your PATH or in
|
||||
# 'vim.extraPackages.' There are no additional checks performed to see
|
||||
# if the command provided is valid.
|
||||
package = ["jdt-language-server" "-data" "~/.cache/jdtls/workspace"];
|
||||
};
|
||||
}
|
||||
|
|
@ -660,8 +696,105 @@ own plugins) DAG, used to set up internal plugins</p></li><li class="listitem"><
|
|||
direct DAG, but is converted to, and resolved as one internally</p></li><li class="listitem"><p><code class="literal">mappings</code> - the result of <code class="literal">vim.maps</code></p></li></ol></div>
|
||||
</div>
|
||||
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-autocmds-augroups" class="title" >Autocommands and Autogroups </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-vim-augroups">Autogroups (<code class="literal">vim.augroups</code>)</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-vim-autocmds">Autocommands (<code class="literal">vim.autocmds</code>)</a> </span></dt> </dl></div><p>This module allows you to declaratively configure Neovim autocommands and
|
||||
autogroups within your Nix configuration.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-vim-augroups" class="title" style="clear: both">Autogroups (<code class="literal">vim.augroups</code>) </h2> </div> </div></div><p>Autogroups (<code class="literal">augroup</code>) organize related autocommands. This allows them to be
|
||||
managed collectively, such as clearing them all at once to prevent duplicates.
|
||||
Each entry in the list is a submodule with the following options:</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Option</th><th align="left">Type</th><th align="left">Default</th><th align="left">Description</th><th align="left">Example</th></tr></thead><tbody><tr><td align="left"><code class="literal">enable</code></td><td align="left"><code class="literal">bool</code></td><td align="left"><code class="literal">true</code></td><td align="left">Enables or disables this autogroup definition.</td><td align="left"><code class="literal">true</code></td></tr><tr><td align="left"><code class="literal">name</code></td><td align="left"><code class="literal">str</code></td><td align="left"><span class="emphasis"><em>None</em></span></td><td align="left"><span class="strong"><strong>Required.</strong></span> The unique name for the autogroup.</td><td align="left"><code class="literal">"MyFormatGroup"</code></td></tr><tr><td align="left"><code class="literal">clear</code></td><td align="left"><code class="literal">bool</code></td><td align="left"><code class="literal">true</code></td><td align="left">Clears any existing autocommands within this group before adding new ones defined in <code class="literal">vim.autocmds</code>.</td><td align="left"><code class="literal">true</code></td></tr></tbody></table></div><p><span class="strong"><strong>Example:</strong></span></p><pre><code class="programlisting nix">{
|
||||
vim.augroups = [
|
||||
{
|
||||
name = "MyCustomAuGroup";
|
||||
clear = true; # Clear previous autocommands in this group on reload
|
||||
}
|
||||
{
|
||||
name = "Formatting";
|
||||
# clear defaults to true
|
||||
}
|
||||
];
|
||||
}
|
||||
</code></pre>
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-vim-autocmds" class="title" style="clear: both">Autocommands (<code class="literal">vim.autocmds</code>) </h2> </div> </div></div><p>Autocommands (<code class="literal">autocmd</code>) trigger actions based on events happening within Neovim
|
||||
(e.g., saving a file, entering a buffer). Each entry in the list is a submodule
|
||||
with the following options:</p><div class="informaltable"><table class="informaltable" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left">Option</th><th align="left">Type</th><th align="left">Default</th><th align="left">Description</th><th align="left">Example</th></tr></thead><tbody><tr><td align="left"><code class="literal">enable</code></td><td align="left"><code class="literal">bool</code></td><td align="left"><code class="literal">true</code></td><td align="left">Enables or disables this autocommand definition.</td><td align="left"><code class="literal">true</code></td></tr><tr><td align="left"><code class="literal">event</code></td><td align="left"><code class="literal">nullOr (listOf str)</code></td><td align="left"><code class="literal">null</code></td><td align="left"><span class="strong"><strong>Required.</strong></span> List of Neovim events that trigger this autocommand (e.g., <code class="literal">BufWritePre</code>, <code class="literal">FileType</code>).</td><td align="left"><code class="literal">[ "BufWritePre" ]</code></td></tr><tr><td align="left"><code class="literal">pattern</code></td><td align="left"><code class="literal">nullOr (listOf str)</code></td><td align="left"><code class="literal">null</code></td><td align="left">List of file patterns (globs) to match against (e.g., <code class="literal">*.py</code>, <code class="literal">*</code>). If <code class="literal">null</code>, matches all files for the given event.</td><td align="left"><code class="literal">[ "*.lua", "*.nix" ]</code></td></tr><tr><td align="left"><code class="literal">callback</code></td><td align="left"><code class="literal">nullOr luaInline</code></td><td align="left"><code class="literal">null</code></td><td align="left">A Lua function to execute when the event triggers. Use <code class="literal">lib.nvim.types.luaInline</code> or <code class="literal">lib.options.literalExpression "mkLuaInline '''...'''"</code>. <span class="strong"><strong>Cannot be used with <code class="literal">command</code>.</strong></span></td><td align="left"><code class="literal">lib.nvim.types.luaInline "function() print('File saved!') end"</code></td></tr><tr><td align="left"><code class="literal">command</code></td><td align="left"><code class="literal">nullOr str</code></td><td align="left"><code class="literal">null</code></td><td align="left">A Vimscript command to execute when the event triggers. <span class="strong"><strong>Cannot be used with <code class="literal">callback</code>.</strong></span></td><td align="left"><code class="literal">"echo 'File saved!'"</code></td></tr><tr><td align="left"><code class="literal">group</code></td><td align="left"><code class="literal">nullOr str</code></td><td align="left"><code class="literal">null</code></td><td align="left">The name of an <code class="literal">augroup</code> (defined in <code class="literal">vim.augroups</code>) to associate this autocommand with.</td><td align="left"><code class="literal">"MyCustomAuGroup"</code></td></tr><tr><td align="left"><code class="literal">desc</code></td><td align="left"><code class="literal">nullOr str</code></td><td align="left"><code class="literal">null</code></td><td align="left">A description for the autocommand (useful for introspection).</td><td align="left"><code class="literal">"Format buffer on save"</code></td></tr><tr><td align="left"><code class="literal">once</code></td><td align="left"><code class="literal">bool</code></td><td align="left"><code class="literal">false</code></td><td align="left">If <code class="literal">true</code>, the autocommand runs only once and then automatically removes itself.</td><td align="left"><code class="literal">false</code></td></tr><tr><td align="left"><code class="literal">nested</code></td><td align="left"><code class="literal">bool</code></td><td align="left"><code class="literal">false</code></td><td align="left">If <code class="literal">true</code>, allows this autocommand to trigger other autocommands.</td><td align="left"><code class="literal">false</code></td></tr></tbody></table></div><div class="warning"><h3 class="title">Warning</h3><p>You cannot define both <code class="literal">callback</code> (for Lua functions) and <code class="literal">command</code> (for
|
||||
Vimscript) for the same autocommand. Choose one.</p></div><p><span class="strong"><strong>Examples:</strong></span></p><pre><code class="programlisting nix">{ lib, ... }:
|
||||
{
|
||||
vim.augroups = [ { name = "UserSetup"; } ];
|
||||
|
||||
vim.autocmds = [
|
||||
# Example 1: Using a Lua callback
|
||||
{
|
||||
event = [ "BufWritePost" ];
|
||||
pattern = [ "*.lua" ];
|
||||
group = "UserSetup";
|
||||
desc = "Notify after saving Lua file";
|
||||
callback = lib.nvim.types.luaInline ''
|
||||
function()
|
||||
vim.notify("Lua file saved!", vim.log.levels.INFO)
|
||||
end
|
||||
'';
|
||||
}
|
||||
|
||||
# Example 2: Using a Vim command
|
||||
{
|
||||
event = [ "FileType" ];
|
||||
pattern = [ "markdown" ];
|
||||
group = "UserSetup";
|
||||
desc = "Set spellcheck for Markdown";
|
||||
command = "setlocal spell";
|
||||
}
|
||||
|
||||
# Example 3: Autocommand without a specific group
|
||||
{
|
||||
event = [ "BufEnter" ];
|
||||
pattern = [ "*.log" ];
|
||||
desc = "Disable line numbers in log files";
|
||||
command = "setlocal nonumber";
|
||||
# No 'group' specified
|
||||
}
|
||||
|
||||
# Example 4: Using Lua for callback
|
||||
{
|
||||
event = [ "BufWinEnter" ];
|
||||
pattern = [ "*" ];
|
||||
desc = "Simple greeting on entering a buffer window";
|
||||
callback = lib.generators.mkLuaInline ''
|
||||
function(args)
|
||||
print("Entered buffer: " .. args.buf)
|
||||
end
|
||||
'';
|
||||
|
||||
# Run only once per session trigger
|
||||
once = true;
|
||||
}
|
||||
];
|
||||
}
|
||||
</code></pre><p>These definitions are automatically translated into the necessary Lua code to
|
||||
configure <code class="literal">vim.api.nvim_create_augroup</code> and <code class="literal">vim.api.nvim_create_autocmd</code> when
|
||||
Neovim starts.</p>
|
||||
</div>
|
||||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-helpful-tips" class="title" >Helpful Tips </h1> </div> </div></div><div class="partintro"><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#sec-pure-lua-config">Pure Lua Configuration</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-debugging-nvf">Debugging nvf</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-offline-documentation">Offline Documentation</a> </span></dt> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-pure-lua-config" class="title" >Pure Lua Configuration </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-pure-nvf-runtime">Pure Runtime Directory</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-impure-absolute-dir">Impure Absolute Directory</a> </span></dt> </dl></div><p>We recognize that you might not always want to configure your setup purely in
|
||||
|
||||
</div>
|
||||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 id="ch-helpful-tips" class="title" >Helpful Tips </h1> </div> </div></div><div class="partintro"><p>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 <span class="strong"><strong>nvf</strong></span> with pure Lua and using custom plugin sources
|
||||
in <span class="strong"><strong>nvf</strong></span> in this section. For general configuration tips, please see previous
|
||||
chapters.</p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="chapter"> <a href="index.xhtml#sec-debugging-nvf">Debugging nvf</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-offline-documentation">Offline Documentation</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-pure-lua-config">Pure Lua Configuration</a> </span></dt><dt> <span class="chapter"> <a href="index.xhtml#sec-plugin-sources">Adding Plugins From Different Sources</a> </span></dt> </dl></div></div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-debugging-nvf" class="title" >Debugging nvf </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-accessing-config">Accessing <code class="literal">neovimConfig</code></a> </span></dt> </dl></div><p>There may be instances where the your Nix configuration evaluates to invalid
|
||||
Lua, or times when you will be asked to provide your built Lua configuration for
|
||||
easier debugging by nvf maintainers. nvf provides two helpful utilities out of
|
||||
the box.</p><p><span class="strong"><strong>nvf-print-config</strong></span> and <span class="strong"><strong>nvf-print-config-path</strong></span> will be bundled with nvf as
|
||||
lightweight utilities to help you view or share your built configuration when
|
||||
necessary.</p><p>To view your configuration with syntax highlighting, you may use the
|
||||
<a class="link" href="https://github.com/sharkdp/bat" target="_top">bat pager</a>.</p><pre><code class="programlisting bash">nvf-print-config | bat --language=lua
|
||||
</code></pre><p>Alternatively, <code class="literal">cat</code> or <code class="literal">less</code> may also be used.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-accessing-config" class="title" style="clear: both">Accessing <code class="literal">neovimConfig</code> </h2> </div> </div></div><p>It is also possible to access the configuration for the wrapped package. The
|
||||
<span class="emphasis"><em>built</em></span> Neovim package will contain a <code class="literal">neovimConfig</code> attribute in its
|
||||
<code class="literal">passthru</code>.</p>
|
||||
</div>
|
||||
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-offline-documentation" class="title" >Offline Documentation </h2> </div> </div></div><p>The manpages provided by nvf contains an offline version of the option search
|
||||
normally available at <a class="link" href="https://notashelf.github.io/nvf/options.html" target="_top">https://notashelf.github.io/nvf/options.html</a>. You may
|
||||
use the <code class="literal">man 5 nvf</code> command to view option documentation from the comfort of
|
||||
your terminal.</p><p>Note that this is only available for NixOS and Home-Manager module
|
||||
installations.</p>
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-pure-lua-config" class="title" >Pure Lua Configuration </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-pure-nvf-runtime">Pure Runtime Directory</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-impure-absolute-dir">Impure Absolute Directory</a> </span></dt> </dl></div><p>We recognize that you might not always want to configure your setup purely in
|
||||
Nix, sometimes doing things in Lua is simply the “superior” option. In such a
|
||||
case you might want to configure your Neovim instance using Lua, and nothing but
|
||||
Lua. It is also possible to mix Lua and Nix configurations.</p><p>Pure Lua or hybrid Lua/Nix configurations can be achieved in two different ways.
|
||||
|
|
@ -743,23 +876,97 @@ specific position (i.e., before or after options you set in nvf) the
|
|||
choosing.</p>
|
||||
</div>
|
||||
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-debugging-nvf" class="title" >Debugging nvf </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-accessing-config">Accessing <code class="literal">neovimConfig</code></a> </span></dt> </dl></div><p>There may be instances where the your Nix configuration evaluates to invalid
|
||||
Lua, or times when you will be asked to provide your built Lua configuration for
|
||||
easier debugging by nvf maintainers. nvf provides two helpful utilities out of
|
||||
the box.</p><p><span class="strong"><strong>nvf-print-config</strong></span> and <span class="strong"><strong>nvf-print-config-path</strong></span> will be bundled with nvf as
|
||||
lightweight utilities to help you view or share your built configuration when
|
||||
necessary.</p><p>To view your configuration with syntax highlighting, you may use the
|
||||
<a class="link" href="https://github.com/sharkdp/bat" target="_top">bat pager</a>.</p><pre><code class="programlisting bash">nvf-print-config | bat --language=lua
|
||||
</code></pre><p>Alternatively, <code class="literal">cat</code> or <code class="literal">less</code> may also be used.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-accessing-config" class="title" style="clear: both">Accessing <code class="literal">neovimConfig</code> </h2> </div> </div></div><p>It is also possible to access the configuration for the wrapped package. The
|
||||
<span class="emphasis"><em>built</em></span> Neovim package will contain a <code class="literal">neovimConfig</code> attribute in its
|
||||
<code class="literal">passthru</code>.</p>
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-plugin-sources" class="title" >Adding Plugins From Different Sources </h2> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#ch-plugins-from-nixpkgs">Nixpkgs & Friends</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ch-plugins-from-source">Building Your Own Plugins</a> </span></dt> </dl></div><p><span class="strong"><strong>nvf</strong></span> attempts to avoid depending on Nixpkgs for Neovim plugins. For the most
|
||||
part, this is accomplished by defining each plugin’s source and building them
|
||||
from source.</p><p>To define plugin sources, we use <a class="link" href="https://github.com/andir/npins" target="_top">npins</a> and pin each plugin source using
|
||||
builtin fetchers. You are not bound by this restriction. In your own
|
||||
configuration, any kind of fetcher or plugin source is fine.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-plugins-from-nixpkgs" class="title" style="clear: both">Nixpkgs & Friends </h2> </div> </div></div><p><code class="literal">vim.startPlugins</code> and <code class="literal">vim.optPlugins</code> options take either a <span class="strong"><strong>string</strong></span>, in
|
||||
which case a plugin from nvf’s internal plugins registry will be used, or a
|
||||
<span class="strong"><strong>package</strong></span>. If your plugin does not require any setup, or ordering for it s
|
||||
configuration, then it is possible to add it to <code class="literal">vim.startPlugins</code> to load it on
|
||||
startup.</p><pre><code class="programlisting nix">{pkgs, ...}: {
|
||||
# Aerial does require some setup. In the case you pass a plugin that *does*
|
||||
# require manual setup, then you must also call the setup function.
|
||||
vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
|
||||
}
|
||||
</code></pre><p>This will fetch aerial.nvim from nixpkgs, and add it to Neovim’s runtime path to
|
||||
be loaded manually. Although for plugins that require manual setup, you are
|
||||
encouraged to use <a class="link" href="https://notashelf.github.io/nvf/options.html#opt-vim.extraPlugins" target="_top"><code class="literal">vim.extraPlugins</code></a>.</p><pre><code class="programlisting nix">{
|
||||
vim.extraPlugins = {
|
||||
aerial = {
|
||||
package = pkgs.vimPlugins.aerial-nvim;
|
||||
setup = "require('aerial').setup {}";
|
||||
};
|
||||
};
|
||||
}
|
||||
</code></pre><p>More details on the extraPlugins API is documented in the
|
||||
<a class="link" href="https://notashelf.github.io/nvf/index.xhtml#ch-custom-plugins" target="_top">custom plugins section</a>.</p>
|
||||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="ch-plugins-from-source" class="title" style="clear: both">Building Your Own Plugins </h2> </div> </div></div><p>In the case a plugin is not available in Nixpkgs, or the Nixpkgs package is
|
||||
outdated (or, more likely, broken) it is possible to build the plugins from
|
||||
source using a tool, such as <a class="link" href="https://github.com/andir/npins" target="_top">npins</a>. You may also use your <span class="emphasis"><em>flake inputs</em></span> as
|
||||
sources.</p><p>Example using plugin inputs:</p><pre><code class="programlisting nix">{
|
||||
# In your flake.nix
|
||||
inputs = {
|
||||
aerial-nvim = {
|
||||
url = "github:stevearc/aerial.nvim"
|
||||
flake = false;
|
||||
};
|
||||
};
|
||||
|
||||
# Make sure that 'inputs' is properly propagated into Nvf, for example, through
|
||||
# specialArgs.
|
||||
outputs = { ... };
|
||||
}
|
||||
</code></pre><p>In the case, you may use the input directly for the plugin’s source attribute in
|
||||
<code class="literal">buildVimPlugin</code>.</p><pre><code class="programlisting nix"># Make sure that 'inputs' is properly propagated! It will be missing otherwise
|
||||
# and the resulting errors might be too obscure.
|
||||
{inputs, ...}: let
|
||||
aerial-from-source = pkgs.vimUtils.buildVimPlugin {
|
||||
name = "aerial-nvim";
|
||||
src = inputs.aerial-nvim;
|
||||
};
|
||||
in {
|
||||
vim.extraPlugins = {
|
||||
aerial = {
|
||||
package = aerial-from-source;
|
||||
setup = "require('aerial').setup {}";
|
||||
};
|
||||
};
|
||||
}
|
||||
</code></pre><p>Alternatively, if you do not want to keep track of the source using flake inputs
|
||||
or npins, you may call <code class="literal">fetchFromGitHub</code> (or other fetchers) directly. An
|
||||
example would look like this.</p><pre><code class="programlisting nix">regexplainer = buildVimPlugin {
|
||||
name = "nvim-regexplainer";
|
||||
src = fetchFromGitHub {
|
||||
owner = "bennypowers";
|
||||
repo = "nvim-regexplainer";
|
||||
rev = "4250c8f3c1307876384e70eeedde5149249e154f";
|
||||
hash = "sha256-15DLbKtOgUPq4DcF71jFYu31faDn52k3P1x47GL3+b0=";
|
||||
};
|
||||
|
||||
# The 'buildVimPlugin' imposes some "require checks" on all plugins build from
|
||||
# source. Failing tests, if they are not relevant, can be disabled using the
|
||||
# 'nvimSkipModule' argument to the 'buildVimPlugin' function.
|
||||
nvimSkipModule = [
|
||||
"regexplainer"
|
||||
"regexplainer.buffers.init"
|
||||
"regexplainer.buffers.popup"
|
||||
"regexplainer.buffers.register"
|
||||
"regexplainer.buffers.shared"
|
||||
"regexplainer.buffers.split"
|
||||
"regexplainer.component.descriptions"
|
||||
"regexplainer.component.init"
|
||||
"regexplainer.renderers.narrative.init"
|
||||
"regexplainer.renderers.narrative.narrative"
|
||||
"regexplainer.renderers.init"
|
||||
"regexplainer.utils.defer"
|
||||
"regexplainer.utils.init"
|
||||
"regexplainer.utils.treesitter"
|
||||
];
|
||||
}
|
||||
</code></pre>
|
||||
</div>
|
||||
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="sec-offline-documentation" class="title" >Offline Documentation </h2> </div> </div></div><p>The manpages provided by nvf contains an offline version of the option search
|
||||
normally available at <a class="link" href="https://notashelf.github.io/nvf/options.html" target="_top">https://notashelf.github.io/nvf/options.html</a>. You may
|
||||
use the <code class="literal">man 5 nvf</code> command to view option documentation from the comfort of
|
||||
your terminal.</p><p>Note that this is only available for NixOS and Home-Manager module
|
||||
installations.</p>
|
||||
</div>
|
||||
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h1 id="ch-hacking" class="title" >Hacking nvf </h1> </div> </div></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-contrib-getting-started">Getting Started</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines">Guidelines</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-testing-changes">Testing Changes</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-keybinds">Keybinds</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-additional-plugins">Adding Plugins</a> </span></dt> </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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue