NotAShelf/nvf
2
1
Fork 0
mirror of https://github.com/NotAShelf/nvf.git synced 2025-09-05 18:01:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Deploy PR #1030 preview

Browse source
This commit is contained in:
GitHub Actions 2025-07-21 20:48:39 +00:00
commit acddfd6d38
1 changed files with 78 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

100
docs-preview-1030/index.xhtml
View file

@ -1258,8 +1258,52 @@ allow custom keybindings, don’t be scared to implement a draft PR. We’ll hel
you get it done.</p></div>
</div>
</div><div class="section"> <div class="titlepage"> <div> <div> <h1 id="sec-additional-plugins" class="title" style="clear: both">Adding Plugins </h1> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-modular-setup-options">Modular setup options</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-details-of-toluaobject">Details of toLuaObject</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-lazy-plugins">Lazy plugins</a> </span></dt> </dl></div><p>To add a new Neovim plugin, use <code class="literal">npins</code></p><p>Use:</p><p><code class="literal">nix-shell -p npins</code> or <code class="literal">nix shell nixpkgs#npins</code></p><p>Then run:</p><p><code class="literal">npins add --name &lt;plugin name&gt; github &lt;owner&gt; &lt;repo&gt; -b &lt;branch&gt;</code></p><p>Be sure to replace any non-alphanumeric characters with <code class="literal">-</code> for <code class="literal">--name</code></p><p>For example</p><p><code class="literal">npins add --name lazydev-nvim github folke lazydev.nvim -b main</code></p><p>You can now reference this plugin as a <span class="strong"><strong>string</strong></span>.</p><pre><code class="programlisting nix">config.vim.startPlugins = [&quot;lazydev-nvim&quot;];
</code></pre><div class="section"> <div class="titlepage"> <div> <div> <h2 id="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 <code class="literal">require(&#x27;plugin&#x27;).setup({...})</code>.</p><p>We use a special function that lets you easily add support for such setup
</div><div class="section"> <div class="titlepage"> <div> <div> <h1 id="sec-additional-plugins" class="title" style="clear: both">Adding Plugins </h1> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-npins-for-plugins">With npins</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-pkgs-for-plugins">Packaging Complex Plugins</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-modular-setup-options">Modular setup options</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-details-of-toluaobject">Details of toLuaObject</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-lazy-plugins">Lazy plugins</a> </span></dt> </dl></div><p>There are two methods for adding new Neovim plugins to <span class="strong"><strong>nvf</strong></span>. npins is the
faster option that should be preferred if the plugin consists of pure Lua or
Vimscript code. In which case there is no building required, and we can easily
handle the copying of plugin files. Alternative method, which is required when
plugins try to build their own libraries (e.g., in Rust or C) that need to be
built with Nix to function correctly.</p><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-npins-for-plugins" class="title" style="clear: both">With npins </h2> </div> </div></div><p>npins is the standard method of adding new plugins to <span class="strong"><strong>nvf</strong></span>. You simply need
the repository URL for the plugin, and can add it as a source to be built
automatically with one command. To add a new Neovim plugin, use <code class="literal">npins</code>. For
example:</p><pre><code class="programlisting bash">nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
</code></pre><p>Then run:</p><pre><code class="programlisting bash">npins add --name &lt;plugin name&gt; github &lt;owner&gt; &lt;repo&gt; -b &lt;branch&gt;
</code></pre><div class="note"><h3 class="title">Note</h3><p>Be sure to replace any non-alphanumeric characters with <code class="literal">-</code> for <code class="literal">--name</code>. For
example</p><pre><code class="programlisting bash">npins add --name lazydev-nvim github folke lazydev.nvim -b main
</code></pre></div><p>Once the <code class="literal">npins</code> command is done, you can start referencing the plugin as a
<span class="strong"><strong>string</strong></span>.</p><pre><code class="programlisting nix">{
config.vim.startPlugins = [&quot;lazydev-nvim&quot;];
}
</code></pre>
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-pkgs-for-plugins" class="title" style="clear: both">Packaging Complex Plugins </h2> </div> </div></div><p>Some plugins require additional packages to be built and substituted to function
correctly. For example <a class="link" href="https://github.com/Saghen/blink.cmp" target="_top">blink.cmp</a> requires its own fuzzy matcher library, built
with Rust, to be installed or else defaults to a much slower Lua implementation.
In the Blink documentation, you are advised to build with <code class="literal">cargo</code> but that is
not ideal since we are leveraging the power of Nix. In this case the ideal
solution is to write a derivation for the plugin.</p><p>We use <code class="literal">buildRustPackage</code> to build the library from the repository root, and
copy everything in the <code class="literal">postInstall</code> phase.</p><pre><code class="programlisting nix">postInstall = &#x27;&#x27;
cp -r {lua,plugin} &quot;$out&quot;
mkdir -p &quot;$out/doc&quot;
cp &#x27;doc/&#x27;*&#x27;.txt&#x27; &quot;$out/doc/&quot;
mkdir -p &quot;$out/target&quot;
mv &quot;$out/lib&quot; &quot;$out/target/release&quot;
&#x27;&#x27;;
</code></pre><p>In a similar fashion, you may utilize <code class="literal">stdenv.mkDerivation</code> and other Nixpkgs
builders to build your library from source, and copy the relevant files and Lua
plugin files in the <code class="literal">postInstall</code> phase. Do note, however, that you still need
to fetch the plugin sources somehow. npins is, once again, the recommended
option to fetch the plugin sources. Refer to the previous section on how to use
npins to add a new plugin.</p><p>Plugins built from source must go into the <code class="literal">flake/pkgs/by-name</code> overlay. It will
automatically create flake outputs for individual packages. Lastly, you must add
your package to the plugin builder (<code class="literal">pluginBuilders</code>) function manually in
<code class="literal">modules/wrapper/build/config.nix</code>. Once done, you may refer to your plugin as a
<span class="strong"><strong>string</strong></span>.</p><pre><code class="programlisting nix">{
config.vim.startPlugins = [&quot;blink-cmp&quot;];
}
</code></pre>
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="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 <code class="literal">require(&#x27;plugin&#x27;).setup({...})</code>.</p><p>We use a special function that lets you easily add support for such setup
options in a modular way: <code class="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><code class="programlisting nix"># in modules/.../your-plugin/your-plugin.nix
@ -1293,7 +1337,7 @@ in {
require(&#x27;plugin-name&#x27;).setup(${lib.nvim.lua.toLuaObject cfg.setupOpts})
&#x27;&#x27;;
}
</code></pre><p>This above config will result in this lua script:</p><pre><code class="programlisting lua">require(&#x27;plugin-name&#x27;).setup({
</code></pre><p>This above config will result in this Lua script:</p><pre><code class="programlisting lua">require(&#x27;plugin-name&#x27;).setup({
enable_feature_a = false,
number_option = 3,
})
@ -1311,36 +1355,47 @@ own fields!</p><pre><code class="programlisting nix"># in user&#x27;s config
}
</code></pre>
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-details-of-toluaobject" class="title" style="clear: both">Details of toLuaObject </h2> </div> </div></div><p>As you’ve seen above, <code class="literal">toLuaObject</code> is used to convert our nix attrSet
<code class="literal">cfg.setupOpts</code>, into a lua table. Here are some rules of the conversion:</p><div class="orderedlist"><ol class="orderedlist compact" type="1"><li class="listitem"><p>nix <code class="literal">null</code> converts to lua <code class="literal">nil</code></p></li><li class="listitem"><p>number and strings convert to their lua counterparts</p></li><li class="listitem"><p>nix attrSet/list convert into lua tables</p></li><li class="listitem"><p>you can write raw lua code using <code class="literal">lib.generators.mkLuaInline</code>. This function
is part of nixpkgs.</p></li></ol></div><p>Example:</p><pre><code class="programlisting nix">vim.your-plugin.setupOpts = {
on_init = lib.generators.mkLuaInline &#x27;&#x27;
function()
print(&#x27;we can write lua!&#x27;)
end
&#x27;&#x27;;
<code class="literal">cfg.setupOpts</code>, into a lua table. Here are some rules of the conversion:</p><div class="orderedlist"><ol class="orderedlist " type="1"><li class="listitem"><p>Nix <code class="literal">null</code> converts to lua <code class="literal">nil</code></p></li><li class="listitem"><p>Number and strings convert to their lua counterparts</p></li><li class="listitem"><p>Nix attribute sets (<code class="literal">{}</code>) and lists (<code class="literal">[]</code>) convert into Lua dictionaries and
tables respectively. Here is an example of Nix -&gt; Lua conversion.</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">{foo = &quot;bar&quot;}</code> -&gt; <code class="literal">{[&quot;foo&quot;] = &quot;bar&quot;}</code></p></li><li class="listitem"><p><code class="literal">[&quot;foo&quot; &quot;bar&quot;]</code> -&gt; <code class="literal">{&quot;foo&quot;, &quot;bar&quot;}</code></p></li></ul></div></li><li class="listitem"><p>You can write raw Lua code using <code class="literal">lib.generators.mkLuaInline</code>. This function
is part of nixpkgs, and is accessible without relying on <span class="strong"><strong>nvf</strong></span>’s extended
library.</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">mkLuaInline &quot;function add(a, b) return a + b end&quot;</code> will yield the
following result:</p></li></ul></div><pre><code class="programlisting nix">{
_type = &quot;lua-inline&quot;;
expr = &quot;function add(a, b) return a + b end&quot;;
}
</code></pre>
</code></pre><p>The above expression will be interpreted as a Lua expression in the final
config. Without the <code class="literal">mkLuaInline</code> function, you will only receive a string
literal. You can use it to feed plugin configuration tables Lua functions
that return specific values as expected by the plugins.</p><pre><code class="programlisting nix">{
vim.your-plugin.setupOpts = {
on_init = lib.generators.mkLuaInline &#x27;&#x27;
function()
print(&#x27;we can write lua!&#x27;)
end
&#x27;&#x27;;
};
}
</code></pre></li></ol></div>
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-lazy-plugins" class="title" style="clear: both">Lazy plugins </h2> </div> </div></div><p>If the plugin can be lazy-loaded, <code class="literal">vim.lazy.plugins</code> should be used to add it.
Lazy plugins are managed by <code class="literal">lz.n</code>.</p><pre><code class="programlisting nix"># in modules/.../your-plugin/config.nix
{lib, config, ...}:
let
{config, ...}: let
cfg = config.vim.your-plugin;
in {
vim.lazy.plugins.your-plugin = {
# instead of vim.startPlugins, use this:
# Instead of vim.startPlugins, use this:
package = &quot;your-plugin&quot;;
# if your plugin uses the `require(&#x27;your-plugin&#x27;).setup{...}` pattern
# ıf your plugin uses the `require(&#x27;your-plugin&#x27;).setup{...}` pattern
setupModule = &quot;your-plugin&quot;;
inherit (cfg) setupOpts;
# events that trigger this plugin to be loaded
# Events that trigger this plugin to be loaded
event = [&quot;DirChanged&quot;];
cmd = [&quot;YourPluginCommand&quot;];
# keymaps
# Plugin Keymaps
keys = [
# we&#x27;ll cover this in detail in the keymaps section
# We&#x27;ll cover this in detail in the &#x27;keybinds&#x27; section
{
key = &quot;&lt;leader&gt;d&quot;;
mode = &quot;n&quot;;
@ -1348,13 +1403,14 @@ in {
}
];
};
;
}
</code></pre><p>This results in the following lua code:</p><pre><code class="programlisting lua">require(&#x27;lz.n&#x27;).load({
{
&quot;name-of-your-plugin&quot;,
after = function()
require(&#x27;your-plugin&#x27;).setup({--[[ your setupOpts ]]})
require(&#x27;your-plugin&#x27;).setup({
--[[ your setupOpts ]]--
})
end,
event = {&quot;DirChanged&quot;},
@ -1364,8 +1420,8 @@ in {
},
}
})
</code></pre><p>A full list of options can be found
[here](https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins</p>
</code></pre><p>A full list of options can be found in the <a class="link" href="https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins" target="_top"><code class="literal">vim.lazy.plugins</code> spec</a> on the
rendered manual.</p>
</div>
</div>