NotAShelf/nvf
2
1
Fork 0
mirror of https://github.com/NotAShelf/nvf.git synced 2025-09-06 10:21:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

deploy: 6469e061f6

Browse source
This commit is contained in:
NotAShelf 2025-02-11 11:32:29 +00:00
commit 6e6e429d8f
86 changed files with 878 additions and 326147 deletions
Download patch file Download diff file Expand all files Collapse all files

162
index.xhtml
View file

@ -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-custom-inputs">Custom Inputs</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-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="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 &amp; 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>
@ -95,15 +95,17 @@ arguments, and return the following schema as a result.</p><pre><code class="pro
nvf.url = &quot;github:notashelf/nvf&quot;;
};
outputs = {
self,
nixpkgs,
...
} @ inputs: {
packages.&quot;x86_64-linux&quot; = let
neovimConfigured = (inputs.nvf.lib.neovimConfiguration {
inherit (nixpkgs.legacyPackages.&quot;x86_64-linux&quot;) pkgs;
modules = [{
outputs = {nixpkgs, ...} @ inputs: {
packages.x86_64-linux = {
# Set the default package to the wrapped instance of Neovim.
# This will allow running your Neovim configuration with
# `nix run` and in addition, sharing your configuration with
# other users in case your repository is public.
default =
(inputs.nvf.lib.neovimConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
{
config.vim = {
# Enable custom theming options
theme.enable = true;
@ -115,14 +117,10 @@ arguments, and return the following schema as a result.</p><pre><code class="pro
# reference in Appendix B of the nvf manual.
# ...
};
}];
});
in {
# Set the default package to the wrapped instance of Neovim.
# This will allow running your Neovim configuration with
# `nix run` and in addition, sharing your configuration with
# other users in case your repository is public.
default = neovimConfigured.neovim;
}
];
})
.neovim;
};
};
}
@ -140,26 +138,32 @@ the default theme enabled. You may use other options inside <code class="literal
nvf.url = &quot;github:notashelf/nvf&quot;;
};
outputs = {nixpkgs, nvf, ...}: let
system = &quot;x86_64-linux&quot;;
pkgs = nixpkgs.legacyPackages.${system};
configModule = {
# Add any custom options (and do feel free to upstream them!)
# options = { ... };
config.vim = {
theme.enable = true;
# and more options as you see fit...
};
};
customNeovim = nvf.lib.neovimConfiguration {
inherit pkgs;
modules = [configModule];
};
in {
outputs = {
nixpkgs,
nvf,
self,
...
}: {
# This will make the package available as a flake output under &#x27;packages&#x27;
packages.${system}.my-neovim = customNeovim.neovim;
packages.x86_64-linux.my-neovim =
(nvf.lib.neovimConfiguration {
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
# Or move this to a separate file and add it&#x27;s path here instead
# IE: ./nvf_module.nix
(
{pkgs, ...}: {
# Add any custom options (and do feel free to upstream them!)
# options = { ... };
config.vim = {
theme.enable = true;
# and more options as you see fit...
};
}
)
];
})
.neovim;
# Example nixosConfiguration using the configured Neovim package
nixosConfigurations = {
@ -167,13 +171,16 @@ the default theme enabled. You may use other options inside <code class="literal
# ...
modules = [
# This will make wrapped neovim available in your system packages
{environment.systemPackages = [customNeovim.neovim];}
# Can also move this to another config file if you pass inputs/self around with specialArgs
({pkgs, ...}: {
environment.systemPackages = [self.packages.${pkgs.stdenv.system}.neovim];
})
];
# ...
};
};
};
}
}```
</code></pre>
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-standalone-hm" class="title" >Standalone Installation on Home-Manager </h2> </div> </div></div><p>Your built Neovim configuration can be exposed as a flake output to make it
easier to share across machines, repositories and so on. Or it can be added to
@ -323,13 +330,10 @@ depending on your needs.</p><p>To use it, we first add the input flake.</p><pre>
nvf.url = &quot;github:notashelf/nvf&quot;;
};
outputs = { nixpkgs, home-manager, nvf, ... }: let
system = &quot;x86_64-linux&quot;;
pkgs = nixpkgs.legacyPackages.${system};
in {
outputs = { nixpkgs, home-manager, nvf, ... }: {
# ↓ this is your home output in the flake schema, expected by home-manager
&quot;your-username@your-hostname&quot; = home-manager.lib.homeManagerConfiguration {
inherit pkgs;
pkgs = nixpkgs.legacyPackages.x86_64-linux;
modules = [
nvf.homeManagerModules.default # &lt;- this imports the home-manager module that provides the options
./home.nix # &lt;- your home entrypoint, `programs.nvf.*` may be defined here
@ -359,7 +363,7 @@ 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-custom-inputs">Custom Inputs</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
</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, ...}: {
# using the neovim-nightly overlay
vim.package = inputs.neovim-overlay.packages.${pkgs.system}.neovim;
@ -511,41 +515,25 @@ in {
</div>
</div>
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-custom-inputs" class="title" >Custom Inputs </h2> </div> </div></div><p>One of the greatest strengths of <span class="strong"><strong>nvf</strong></span> is its ability to get plugins from
flake inputs and build them locally from any given source. For plugins that do
not require any kind of additional building step, this is a powerful method of
adding plugins to your configuration that are not packaged in nixpkgs, or those
you want to track from source without relying on nixpkgs.</p><p>The <a class="link" href="index.xhtml#sec-additional-plugins" title="Adding Plugins" >additional plugins section</a> details the addition
</div><div class="chapter"> <div class="titlepage"> <div> <div> <h2 id="ch-overriding-plugins" class="title" >Overriding plugins </h2> </div> </div></div><p>The <a class="link" href="index.xhtml#sec-additional-plugins" title="Adding Plugins" >additional plugins section</a> details the addition
of new plugins to nvf under regular circumstances, i.e. while making a pull
request to the project. You may <span class="emphasis"><em>override</em></span> those plugin inputs in your own
<code class="literal">flake.nix</code> to change source versions, e.g., to use newer versions of plugins
that are not yet updated in <span class="strong"><strong>nvf</strong></span>.</p><pre><code class="programlisting nix">{
inputs = {
# ...
# The name here is arbitrary, you can name it whatever.
# This will add a plugin input called &quot;your-neodev-input&quot;
# that you can reference in a `follows` line.
your-neodev-input = {
url = &quot;github:folke/neodev.nvim&quot;;
flake = false;
};
nvf = {
url = &quot;github:notashelf/nvf&quot;;
# The name of the input must match for the follows line
# plugin-neodev-nvim is what the input is called inside nvf
# so you must match the exact name here.
inputs.plugin-neodev-nvim.follows = &quot;your-neodev-input&quot;;
};
# ...
request to the project. You may <span class="emphasis"><em>override</em></span> those plugins in your config
to change source versions, e.g., to use newer versions of plugins
that are not yet updated in <span class="strong"><strong>nvf</strong></span>.</p><pre><code class="programlisting nix">vim.pluginOverrides = {
lazydev-nvim = pkgs.fetchFromGitHub {
owner = &quot;folke&quot;;
repo = &quot;lazydev.nvim&quot;;
rev = &quot;&quot;;
hash = &quot;&quot;;
};
}
# It&#x27;s also possible to use a flake input
lazydev-nvim = inputs.lazydev-nvim;
# Or a local path
lazydev-nvim = ./lazydev;
# Or a npins pin... etc
};
</code></pre><p>This will override the source for the <code class="literal">neodev.nvim</code> plugin that is used in nvf
with your own input. You can update your new input via <code class="literal">nix flake update</code> or
more specifically <code class="literal">nix flake update &lt;name of your input&gt;</code> to keep it up to date.</p><div class="warning"><h3 class="title">Warning</h3><p>While updating plugin inputs, make sure that any configuration that has been
with your own plugin.</p><div class="warning"><h3 class="title">Warning</h3><p>While updating plugin inputs, make sure that any configuration that has been
deprecated in newer versions is changed in the plugin’s <code class="literal">setupOpts</code>. If you
depend on a new version, requesting a version bump in the issues section is a
more reliable option.</p></div>
@ -982,25 +970,7 @@ 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, first add the source url in the inputs section of
<code class="literal">flake.nix</code> with the prefix <code class="literal">plugin-</code></p><pre><code class="programlisting nix">{
inputs = {
# ...
plugin-neodev-nvim = {
url = &quot;github:folke/neodev.nvim&quot;;
flake = false;
};
# ...
};
}
</code></pre><p>Prepending <code class="literal">plugin-</code> to the name of the input will allow nvf to automatically
discover inputs that are marked as plugins, and make them available in
<code class="literal">vim.startPlugins</code> or other areas that require a very specific plugin type as it
is defined in <code class="literal">https://github.com/notashelf/nvf/blob/v0.8/lib/types/plugins.nix</code></p><p>The addition of the <code class="literal">plugin-</code> prefix will allow <span class="strong"><strong>nvf</strong></span> to autodiscover the
input from the flake inputs automatically, allowing you to refer to it in areas
that require a very specific plugin type as defined in <code class="literal">lib/types/plugins.nix</code></p><p>You can now reference this plugin using its string name, the plugin will be
built with the name and source URL from the flake input, allowing you to refer
to it as a <span class="strong"><strong>string</strong></span>.</p><pre><code class="programlisting nix">config.vim.startPlugins = [&quot;neodev-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-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 --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 --name lazydev-nvim github folke laztdev.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
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