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: 2b4683fa81

Browse source
This commit is contained in:
NotAShelf 2024-01-02 23:17:04 +00:00
commit 46af96a938
3 changed files with 130 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

27
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#sec-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-custom-configuration">Custom Configuration</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-new-method">New Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-old-method">Old Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#configuring-plugins">Configuring</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-default-configs">Default Configs</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-default-maximal">Maximal</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-default-nix">Nix</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-default-tidal">Tidal Cycles</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-hm-module">Home Manager</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-hacking">Hacking neovim-flake</a> </span></dt><dd><dl><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></dd><dt> <span class="appendix"> <a href="options.html">A. Neovim Flake Configuration Options</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#sec-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-custom-configuration">Custom Configuration</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-custom-package">Custom Neovim Package</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-custom-plugins">Custom Plugins</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-new-method">New Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-old-method">Old Method</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#configuring-plugins">Configuring</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-default-configs">Default Configs</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-default-maximal">Maximal</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-default-nix">Nix</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-default-tidal">Tidal Cycles</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-hm-module">Home Manager</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-languages">Language Support</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-languages-custom-lsp-packages">LSP Custom Packages/Command</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-hacking">Hacking neovim-flake</a> </span></dt><dd><dl><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></dd><dt> <span class="appendix"> <a href="options.html">A. Neovim Flake Configuration Options</a> </span></dt><dt> <span class="appendix"> <a href="release-notes.html">B. Release Notes</a> </span></dt> </dl></div>
<div class="preface"> <div class="titlepage"> <div> <div> <h1 class="title" > <a id="sec-preface"></a>Preface </h1> </div> </div></div><p>If you noticed a bug caused by neovim-flake then please consider reporting it over
<a class="link" href="https://github.com/notashelf/neovim-flake/issues" target="_top">the neovim-flake issue tracker</a>.
Bugfixes, feature additions and upstreamed changes are welcome over
@ -163,9 +163,7 @@ with your findings so that we can make it available for everyone easily.</p>
</div>
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <a id="ch-default-configs"></a>Default Configs </h1> </div> </div></div><div class="partintro"><p>While you can configure neovim-flake 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="section"> <a href="index.xhtml#sec-default-maximal">Maximal</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-default-nix">Nix</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-default-tidal">Tidal Cycles</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <a id="sec-default-maximal"></a>Maximal </h2> </div> </div></div><pre><code class="programlisting bash">$ nix shell github:notashelf/neovim-flake#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> config, 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>
</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> config, but with every supported language enabled.</p><div class="note"><h3 class="title">Note</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 class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <a id="sec-default-nix"></a>Nix </h2> </div> </div></div><pre><code class="programlisting bash">$ nix run github:notashelf/neovim-flake#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 class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <a id="sec-default-tidal"></a>Tidal Cycles </h2> </div> </div></div><pre><code class="programlisting bash">$ nix run github:notashelf/neovim-flake#tidal file.tidal
@ -254,7 +252,8 @@ direction. As we have no automated system enforcing those guidelines, please try
making your pull request in order to avoid “faulty” code slipping by.</p><p>If you are uncertain how these rules affect the change you would like to make then feel free to start a
discussion in the <a class="link" href="https://github.com/NotAShelf/neovim-flake/discussions" target="_top">discussions tab</a> ideally (but not necessarily)
before you start developing.</p><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <a id="sec-guidelines-documentation"></a>Adding Documentation </h3> </div> </div></div><p>Most, if not all, changes warrant changes to the documentation. Module options should be documented with
<a class="link" href="https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup" target="_top">Nixpkgs-flavoured Markdown</a>, albeit with exceptions.</p><div class="note"><h3 class="title">Note</h3><p>As of v0.6, neovim-flake is itself documented using full markdown in both module options and the manual.</p></div><p>The HTML version of this manual containing both the module option descriptions and the documentation of neovim-flake
<a class="link" href="https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup" target="_top">Nixpkgs-flavoured Markdown</a>, albeit with exceptions.</p><div class="note"><h3 class="title">Note</h3><p>As of v0.5, neovim-flake is itself documented using full markdown in both module options and the manual. With
v0.6, this manual has also been converted to markdown in full.</p></div><p>The HTML version of this manual containing both the module option descriptions and the documentation of neovim-flake
(such as this page) can be generated and opened by typing the following in a shell within a clone of the
neovim-flake Git repository:</p><pre><code class="programlisting console">$ nix build .#docs-html
$ xdg-open $PWD/result/share/doc/neovim-flake/index.html
@ -266,16 +265,16 @@ in <a class="link" href="index.xhtml#sec-guidelines-commit-style" title="Commit
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <a id="sec-guidelines-commit-style"></a>Commit Style </h3> </div> </div></div><p>The commits in your pull request should be reasonably self-contained. Which means each and every commit in
a pull request should make sense both on its own and in general context. That is, a second commit should not resolve
an issue that is introduced in an earlier commit. In particular, you will be asked to amend any commit that
introduces syntax errors or similar problems even if they are fixed in a later commit.</p><p>The commit messages should follow the {seven-rules}[seven rules], except for “Capitalize the subject line”.
We also ask you to include the affected code component or module in the first line.
A commit message ideally, but not necessarily, follow the given template from home-manager’s own documentation</p><pre><code class="programlisting"> {component}: {description}
introduces syntax errors or similar problems even if they are fixed in a later commit.</p><p>The commit messages should follow the <a class="link" href="https://chris.beams.io/posts/git-commit/#seven-rule" target="_top">seven rules</a>,
except for “Capitalize the subject line”. We also ask you to include the affected code component or module in
the first line. A commit message ideally, but not necessarily, follow the given template from home-manager’s own documentation</p><pre><code class="programlisting"> {component}: {description}
{long description}
</code></pre><p>where <code class="literal">{component}</code> refers to the code component (or module) your change affects, <code class="literal">{description}</code> is a very brief
description of your change, and <code class="literal">{long description}</code> is an optional clarifying description. As a rare exception, if
there is no clear component, or your change affects many components, then the <code class="literal">{component}</code> part is optional.
See &lt;&lt;ex-commit-message&gt;&gt; for a commit message that fulfills these requirements.</p>
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <a id="sec-guidelines-ex-commit-message"></a>Example Commit </h3> </div> </div></div><p>The commit {example-commit-message}[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef] contains the commit message</p><pre><code class="programlisting">
See <a class="link" href="index.xhtml#sec-guidelines-ex-commit-message" title="Example Commit" >example commit message</a> for a commit message that fulfills these requirements.</p>
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <a id="sec-guidelines-ex-commit-message"></a>Example Commit </h3> </div> </div></div><p>The commit <a class="link" href="https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef" target="_top">69f8e47e9e74c8d3d060ca22e18246b7f7d988ef</a> contains the commit message</p><pre><code class="programlisting">
starship: allow running in Emacs if vterm is used
The vterm buffer is backed by libvterm and can handle Starship prompts
@ -346,8 +345,8 @@ your changes are good to go. Open your pull request, and it will be reviewed as
maximal configuration by editing <code class="literal">configuration.nix</code>, and then run it with <code class="literal">nix run .#maximal -Lv</code>. Same procedure as
adding a new module will apply here.</p>
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <a id="sec-keybinds"></a>Keybinds </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-custom-key-mappings">Custom Key Mappings Support for a Plugin</a> </span></dt> </dl></div><p>As of 0.4, there exists an API for writing your own keybinds and a couple of useful utility functions are available in
the https://github.com/NotAShelf/neovim-flake/tree/main/lib[extended standard library]. The following section contains
a general overview to how you may utilize said functions.</p><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <a id="sec-custom-key-mappings"></a>Custom Key Mappings Support for a Plugin </h3> </div> </div></div><p>:maps: https://notashelf.github.io/neovim-flake/options.html#opt-vim.maps.command.<span class="emphasis"><em>name</em></span>.action</p><p>To set a mapping, you should define it in <code class="literal">vim.maps.&lt;&lt;mode&gt;&gt;</code>.
the <a class="link" href="https://github.com/NotAShelf/neovim-flake/tree/main/lib" target="_top">extended standard library</a>. The following section contains
a general overview to how you may utilize said functions.</p><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <a id="sec-custom-key-mappings"></a>Custom Key Mappings Support for a Plugin </h3> </div> </div></div><p>To set a mapping, you should define it in <code class="literal">vim.maps.&lt;&lt;mode&gt;&gt;</code>.
The available modes are:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p>normal</p></li><li class="listitem"><p>insert</p></li><li class="listitem"><p>select</p></li><li class="listitem"><p>visual</p></li><li class="listitem"><p>terminal</p></li><li class="listitem"><p>normalVisualOp</p></li><li class="listitem"><p>visualOnly</p></li><li class="listitem"><p>operator</p></li><li class="listitem"><p>insertCommand</p></li><li class="listitem"><p>lang</p></li><li class="listitem"><p>command</p></li></ul></div><p>An example, simple keybinding, can look like this:</p><pre><code class="programlisting nix">{
vim.maps.normal = {
&quot;&lt;leader&gt;wq&quot; = {
@ -357,7 +356,9 @@ The available modes are:</p><div class="itemizedlist"><ul class="itemizedlist co
};
};
}
</code></pre><p>There are many settings available in the options. Please refer to the {maps}[documentation] to see a list of them.</p><p><code class="literal">neovim-flake</code> provides a list of helper commands, so that you don’t have to write the mapping attribute sets every
</code></pre><p>There are many settings available in the options. Please refer to the
<a class="link" href="https://notashelf.github.io/neovim-flake/options.html#opt-vim.maps.command._name_.action" target="_top">documentation</a>
to see a list of them.</p><p><code class="literal">neovim-flake</code> provides a list of helper commands, so that you don’t have to write the mapping attribute sets every
time:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">mkBinding = key: action: desc:</code> - makes a basic binding, with <code class="literal">silent</code> set to true.</p></li><li class="listitem"><p><code class="literal">mkExprBinding = key: action: desc:</code> - makes an expression binding, with <code class="literal">lua</code>, <code class="literal">silent</code>, and <code class="literal">expr</code> set to true.</p></li><li class="listitem"><p><code class="literal">mkLuaBinding = key: action: desc:</code> - makes an expression binding, with <code class="literal">lua</code>, and <code class="literal">silent</code> set to true.</p></li></ul></div><p>Note that the Lua in these bindings is actual Lua, not pasted into a <code class="literal">:lua</code> command.
Therefore, you either pass in a function like <code class="literal">require(&#x27;someplugin&#x27;).some_function</code>, without actually calling it,
or you define your own function, like <code class="literal">function() require(&#x27;someplugin&#x27;).some_function() end</code>.</p><p>Additionally, to not have to repeat the descriptions, there’s another utility function with its own set of functions:</p><p>Utility function that takes two attrsets:</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p><code class="literal">{ someKey = &quot;some_value&quot; }</code></p></li><li class="listitem"><p><code class="literal">{ someKey = { description = &quot;Some Description&quot;; }; }</code></p></li></ul></div><p>and merges them into <code class="literal">{ someKey = { value = &quot;some_value&quot;; description = &quot;Some Description&quot;; }; }</code></p><pre><code class="programlisting">addDescriptionsToMappings = actualMappings: mappingDefinitions: