Deploy PR #1030 preview

docs-preview-1030/index.xhtml

@@ -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;];
+</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
-</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
+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
+<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
-is part of nixpkgs.</p></li></ol></div><p>Example:</p><pre><code class="programlisting nix">vim.your-plugin.setupOpts = {
+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
-  on_init = lib.generators.mkLuaInline &#x27;&#x27;
+is part of nixpkgs, and is accessible without relying on <span class="strong"><strong>nvf</strong></span>’s extended
-    function()
+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
-      print(&#x27;we can write lua!&#x27;)
+following result:</p></li></ul></div><pre><code class="programlisting nix">{
-    end
+ _type = &quot;lua-inline&quot;;
-  &#x27;&#x27;;
+ 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, ...}:
+{config, ...}: let
-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
+</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
-[here](https://notashelf.github.io/nvf/options.html#opt-vim.lazy.plugins</p>
+rendered manual.</p>
 </div>
 
 </div>