mirror of
https://github.com/NotAShelf/nvf.git
synced 2026-01-11 13:16:32 +00:00
502 lines
90 KiB
HTML
502 lines
90 KiB
HTML
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||
<title>Hacking nvf</title>
|
||
|
||
<script>
|
||
// Apply sidebar state immediately to prevent flash
|
||
(function () {
|
||
if (localStorage.getItem("sidebar-collapsed") === "true") {
|
||
document.documentElement.classList.add("sidebar-collapsed");
|
||
}
|
||
})();
|
||
</script>
|
||
<link rel="stylesheet" href="assets/style.css" />
|
||
<script defer src="assets/main.js"></script>
|
||
|
||
<script>
|
||
window.searchNamespace = window.searchNamespace || {};
|
||
window.searchNamespace.rootPath = "";
|
||
</script>
|
||
<script defer src="assets/search.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="container">
|
||
<header>
|
||
<div class="header-left">
|
||
<h1 class="site-title">
|
||
<a href="index.html">NVF</a>
|
||
</h1>
|
||
|
||
<nav class="header-nav">
|
||
<ul>
|
||
<li >
|
||
<a href="options.html">Options</a>
|
||
</li>
|
||
|
||
<li><a href="search.html">Search</a></li>
|
||
|
||
</ul>
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
<div class="search-container">
|
||
<input type="text" id="search-input" placeholder="Search..." />
|
||
<div id="search-results" class="search-results"></div>
|
||
</div>
|
||
|
||
</header>
|
||
|
||
<div class="layout">
|
||
<div class="sidebar-toggle" aria-label="Toggle sidebar">
|
||
<svg
|
||
xmlns="http://www.w3.org/2000/svg"
|
||
viewBox="0 0 24 24"
|
||
width="24"
|
||
height="24"
|
||
>
|
||
<path d="M15.41 7.41L14 6l-6 6 6 6 1.41-1.41L10.83 12z"></path>
|
||
</svg>
|
||
</div>
|
||
<nav class="sidebar">
|
||
<div class="docs-nav">
|
||
<h2>Documents</h2>
|
||
<ul>
|
||
<li><a href="index.html">Introduction</a></li>
|
||
<li><a href="configuring.html">Configuring nvf</a></li>
|
||
<li><a href="hacking.html">Hacking nvf</a></li>
|
||
<li><a href="tips.html">Helpful Tips</a></li>
|
||
<li><a href="quirks.html">Known Issues and Quirks</a></li>
|
||
<li><a href="release-notes.html">Release Notes</a></li>
|
||
<li><a href="search.html">Search</a></li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="toc">
|
||
<h2>Contents</h2>
|
||
<ul class="toc-list">
|
||
<li><a href="#ch-hacking">Hacking nvf</a>
|
||
<ul><li><a href="#sec-contrib-getting-started">Getting Started</a>
|
||
<li><a href="#sec-guidelines">Guidelines</a>
|
||
<ul><li><a href="#sec-guidelines-formatting">Formatting</a>
|
||
<li><a href="#sec-guidelines-commit-message-style">Formatting Commits</a>
|
||
<li><a href="#sec-guidelines-commit-style">Commit Style</a>
|
||
<li><a href="#sec-guidelines-code-style">Code Style</a>
|
||
</ul><li><a href="#sec-testing-changes">Testing Changes</a>
|
||
<li><a href="#sec-guidelines-documentation">Adding Documentation</a>
|
||
<ul><li><a href="#building-the-documentation">Building the Documentation</a>
|
||
<li><a href="#formatting-changelog-entries">Formatting Changelog Entries</a>
|
||
<li><a href="#breaking-changes">Breaking Changes</a>
|
||
</ul><li><a href="#sec-additional-plugins">Adding Plugins</a>
|
||
<ul><li><a href="#sec-npins-for-plugins">With npins</a>
|
||
<li><a href="#sec-pkgs-for-plugins">Packaging Complex Plugins</a>
|
||
<li><a href="#sec-modular-setup-options">Modular Setup Options</a>
|
||
<li><a href="#sec-details-of-toluaobject">Details of toLuaObject</a>
|
||
<li><a href="#sec-lazy-plugins">Lazy Loading Plugins</a>
|
||
</ul><li><a href="#sec-keybinds">Keybinds</a>
|
||
<ul><li><a href="#sec-custom-key-mappings">Custom Key Mappings Support for a Plugin</a>
|
||
</li></ul></li></ul></li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
|
||
<main class="content"><html><head></head><body><h1 id="ch-hacking">Hacking nvf</h1>
|
||
<p><strong>nvf</strong> 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 features to the project with minimum possible friction. As
|
||
such, below are the guides and guidelines written to streamline the contribution
|
||
process and to ensure that your valuable input integrates into <strong>nvf</strong>'s
|
||
development as seamlessly as possible without leaving any question marks in your
|
||
head.</p>
|
||
<p>This section is directed mainly towards those who wish to contribute code into
|
||
the project. If you instead wish to report a bug, or discuss a potential new
|
||
feature implementation (which you do not wish to implement yourself) first look
|
||
among the already <a href="https://github.com/notashelf/nvf/issues">open issues</a> and if no matching issue exists you may open a
|
||
<a href="https://github.com/notashelf/nvf/issues/new">new issue</a> and describe your problem/request.</p>
|
||
<p>While creating an issue, please try to include as much information as you can,
|
||
ideally also include relevant context in which an issue occurs or a feature
|
||
should be implemented. If you wish to make a contribution, but feel stuck -
|
||
please do not be afraid to submit a pull request, we will help you get it in.</p>
|
||
<h2 id="sec-contrib-getting-started">Getting Started</h2>
|
||
<p>To contribute to <strong>nvf</strong>, you'll first want to fork the repository. If you are
|
||
new to Git and GitHub, do have a look at GitHub's <a href="https://help.github.com/articles/fork-a-repo/">Fork a repo guide</a> for
|
||
instructions on how you can do this. Once your fork is created, you should
|
||
create a separate branch based on the most recent <code>main</code> branch. While you <em>can</em>
|
||
work on the main branch of your repository, it is generally preferable to use
|
||
feature branches. You should give your branch a reasonably descriptive name
|
||
(e.g. <code>feature/new-debugger</code> or <code>fix/pesky-bug</code>) and you are ready to work on
|
||
your changes!</p>
|
||
<p>Implement your changes and commit them to the newly created branch and when you
|
||
are happy with the result, and positive that it fulfills our
|
||
<a href="#sec-guidelines">Contributing Guidelines</a>, push the branch to GitHub and <a href="https://help.github.com/articles/creating-a-pull-request">Create a Pull Request</a>
|
||
The default pull request template available on the <strong>nvf</strong> repository will guide
|
||
you through the rest of the process, and we'll gently nudge you in the correct
|
||
direction if there are any mistakes.</p>
|
||
<p>Before submitting your pull request, please ensure that:</p>
|
||
<ul>
|
||
<li>The code is formatted as described in the formatting section</li>
|
||
<li>The commit message fits the contributing guidelines (<strong>nvf</strong> does not use
|
||
Conventional Commits!)</li>
|
||
<li>You have updated the changelog entry and optionally updated the documentation
|
||
with important information</li>
|
||
</ul>
|
||
<p>None of those are reasons for a Pull Request to be closed, but it will reduce
|
||
the number of "roundtrips", or rather, the back-and-forth required before we can
|
||
merge your Pull Request.</p>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p>If you do not agree with the idea of using Microsoft GitHub for contributions,
|
||
that is perfectly understandable. Unless you refuse to have your code hosted
|
||
on this platform, you may submit <em>patches</em> through e-mail.</p>
|
||
<p>You may send your patches to <a href="https://github.com/notashelf">@NotAShelf</a> using
|
||
the public e-mail located on the GitHub page. Though, please remember to
|
||
adhere to the contributing guidelines strictly, as e-mail introduces a
|
||
significant overhead to the communication process.</p>
|
||
</div>
|
||
<h2 id="sec-guidelines">Guidelines</h2>
|
||
<p>If your contribution tightly follows the guidelines, then there is a good chance
|
||
it will be merged without too much trouble. Some of the guidelines will be
|
||
strictly enforced, others will remain as gentle nudges towards the correct
|
||
direction. As we have no automated system enforcing those guidelines, please try
|
||
to double check your changes before making your pull request in order to avoid
|
||
"faulty" code slipping by.</p>
|
||
<p>If you are not quite certain how those rules affect the change you are planning
|
||
to make, then please start a friendly discussion in the <a href="https://github.com/NotAShelf/nvf/discussions">discussions tab</a> before
|
||
you begin developing. This is not a requirement, but it might answer some of
|
||
your burning questions and make the contribution process easier for all parties.</p>
|
||
<h3 id="sec-guidelines-formatting">Formatting</h3>
|
||
<p>There are various files within the <strong>nvf</strong> repository. To maintain a sense of
|
||
consistency and to avoid clashing opinions on how formatters should behave, we
|
||
are very opinionated on how those files should be formatted.</p>
|
||
<ul>
|
||
<li>Nix files <strong>must</strong> be formatted with the Alejandra formatter, following some
|
||
specific tips found in <a href="#nix-sec-code-style-nix">Nix style section</a>.</li>
|
||
<li>Markdown files <strong>must</strong> be formatted with the <code>deno fmt</code> command, as described
|
||
in the <a href="#sec-code-style-markdown">Markdown style section</a>.</li>
|
||
</ul>
|
||
<p>Make sure your code is formatted as described in <a href="#sec-guidelines-code-style">code style section</a> before
|
||
your changes are submitted.</p>
|
||
<h3 id="sec-guidelines-commit-message-style">Formatting Commits</h3>
|
||
<p>Similar to <a href="#sec-guidelines-code-style">code style guidelines</a> we encourage a
|
||
consistent commit message format as described in
|
||
<a href="#sec-guidelines-commit-style">commit style guidelines</a>.</p>
|
||
<h3 id="sec-guidelines-commit-style">Commit Style</h3>
|
||
<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
|
||
<a href="https://chris.beams.io/posts/git-commit/#seven-rule">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="language-gitcommit">{component}: {description}
|
||
|
||
{long description}
|
||
</code></pre>
|
||
<p>where <code>{component}</code> refers to the code component (or module) your change
|
||
affects, <code>{description}</code> is a very brief description of your change, and
|
||
<code>{long description}</code> is an optional clarifying description.</p>
|
||
<p>As a rare exception, if there is no clear component, or your change affects many
|
||
components, then the <code>{component}</code> part is optional. See
|
||
<a href="#sec-guidelines-ex-commit-message">example commit message</a> for a commit message that fulfills these requirements.</p>
|
||
<h4 id="sec-guidelines-ex-commit-message">Example Commit</h4>
|
||
<p>The <a href="https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef">sample commit from Home Manager</a> contains the following commit message.</p>
|
||
<pre><code class="language-gitcommit">starship: allow running in Emacs if vterm is used
|
||
|
||
The vterm buffer is backed by libvterm and can handle Starship prompts
|
||
without issues.
|
||
</code></pre>
|
||
<p>Similarly, if you are contributing to <strong>nvf</strong>, you would include the scope of
|
||
the commit followed by the description:</p>
|
||
<pre><code class="language-gitcommit">languages/ruby: init module
|
||
|
||
Adds a language module for Ruby, adds appropriate formatters and Treesitter
|
||
grammars
|
||
</code></pre>
|
||
<p>Long description can be omitted if the change is too simple to warrant it. A
|
||
minor fix in spelling or a formatting change does not warrant long description,
|
||
however, a module addition or removal does as you would like to provide the
|
||
relevant context, i.e., the reasoning for your commit.</p>
|
||
<p>For new plugin additions, the following is a good starting point:</p>
|
||
<pre><code class="language-gitcommit">plugin: init
|
||
</code></pre>
|
||
<p>You can, of course, still include a long description if you wish.</p>
|
||
<pre><code class="language-gitcommit">neotree: init
|
||
|
||
This adds the neo-tree plugin.
|
||
</code></pre>
|
||
<p>In case of nested modules, e.g., <code>modules/languages/java.nix</code> you are
|
||
recommended to contain the parent as well -- for example
|
||
<code>languages/java: some major change</code> , or if it's a new language module,
|
||
<code>languages/java: init</code></p>
|
||
<h3 id="sec-guidelines-code-style">Code Style</h3>
|
||
<h4 id="sec-code-style-treewide">Treewide</h4>
|
||
<p>Across the tree, you're encouraged to follow kebab-case for file names, and keep
|
||
text files (such as Markdown) to 80 characters or less. This 80 character
|
||
recommendation also applies to option descriptions and string literals inside of
|
||
Nix files.</p>
|
||
<h4 id="sec-code-style-markdown">Markdown</h4>
|
||
<p>Various Markdown files are used for documentation in the <strong>nvf</strong> repository.
|
||
Besides the README, the manual is written almost entirely in Markdown. Since
|
||
<strong>nvf</strong> uses a special variant of CommonMark, dubbed "Nixpkgs-flavored
|
||
CommonMark" within this repository, you are encouraged to use the <code>deno fmt</code>
|
||
command (provided by <code>pkgs.deno</code>) to format your Markdown sources. To avoid
|
||
accidentally formatting HTML or CSS files, you might want to specify the file
|
||
extension as follows:</p>
|
||
<pre class="highlight"><code class="language-bash"><span style="color:rgb(92,99,112);font-style: italic;"># Format all Markdown files within the repository</span><br><span style="color:rgb(232,102,113);">$</span> <span style="color:rgb(171,178,191);">deno</span> <span style="color:rgb(232,102,113);">fmt</span> <span style="color:rgb(232,102,113);">--ext</span> <span style="color:rgb(232,102,113);">md</span> <span style="color:rgb(232,102,113);">**/*.md</span><br></code></pre>
|
||
<p>You may also pass <code>--check</code> to the <code>deno fmt</code> command above to see if your
|
||
formatting complies with the project standards.</p>
|
||
<h4 id="sec-code-style-nix">Nix</h4>
|
||
<p><strong>nvf</strong> is formatted by the <a href="https://github.com/kamadorueda/alejandra">alejandra</a> tool and the formatting is checked in
|
||
the pull request and push workflows. Run the <code>nix fmt</code> command inside the
|
||
project repository before submitting your pull request.</p>
|
||
<p>While Alejandra is mostly opinionated on how code looks after formatting,
|
||
certain changes are done at the user's discretion based on how the original code
|
||
was structured.</p>
|
||
<h5>Attribute Sets</h5>
|
||
<p>Please use one line code for attribute sets that contain only one subset. For
|
||
example:</p>
|
||
<!-- markdownlint-disable MD013 -->
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># Parent modules should always be unfolded.</span><br><span style="color:rgb(92,99,112);font-style: italic;"># which means `module = { value = ... }` instead of `module.value = { ... }`.</span><br><span style="color:rgb(97,175,239);">module</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">value</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkEnableOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">some description</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">//</span> <span style="color:rgb(132,139,152);">{</span> <span style="color:rgb(86,182,194);">default</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span> <span style="color:rgb(92,99,112);font-style: italic;"># merges can be done inline where possible</span><br><br> <span style="color:rgb(92,99,112);font-style: italic;"># same as parent modules, unfold submodules</span><br> <span style="color:rgb(86,182,194);">subModule</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># this is an option that contains more than one nested value</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># Note: try to be careful about the ordering of `mkOption` arguments.</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># General rule of thumb is to order from least to most likely to change.</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># This is, for most cases, type < default < description.</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># Example, if present, would be between default and description</span><br> <span style="color:rgb(86,182,194);">someOtherValue</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkOption</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">type</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">types</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">bool</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">default</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">description</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">Some other description</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
|
||
<p>If you move a line down after the merge operator, Alejandra will automatically
|
||
unfold the whole merged attribute set for you, which we <strong>do not</strong> want.</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(97,175,239);">module</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># This is wrong!</span><br> <span style="color:rgb(86,182,194);">key</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkEnableOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">some description</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">//</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">default</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span> <span style="color:rgb(92,99,112);font-style: italic;"># we want this to be inline</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span> <br><br> <span style="color:rgb(92,99,112);font-style: italic;"># ...</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<p>Though, if the right-hand side is more than a single line, it is okay to move to
|
||
a new line. For example:</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(97,175,239);">module</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># This is okay!</span><br> <span style="color:rgb(86,182,194);">key</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkEnableOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">some description</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">//</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">default</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span> <br> <span style="color:rgb(86,182,194);">example</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">false</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><br> <span style="color:rgb(92,99,112);font-style: italic;"># ...</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<h5>Lists</h5>
|
||
<p>For lists, it is mostly up to your own discretion how you want to format them,
|
||
but please try to unfold lists if they contain multiple items and especially if
|
||
they are to include comments.</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># This is ok</span><br><span style="color:rgb(97,175,239);">acceptableList</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><br> <span style="color:rgb(171,178,191);">item1</span> <span style="color:rgb(92,99,112);font-style: italic;"># comment</span><br> <span style="color:rgb(171,178,191);">item2</span><br> <span style="color:rgb(171,178,191);">item3</span> <span style="color:rgb(92,99,112);font-style: italic;"># some other comment</span><br> <span style="color:rgb(171,178,191);">item4</span><br><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br><br><span style="color:rgb(92,99,112);font-style: italic;"># This is *not* ok</span><br><span style="color:rgb(171,178,191);">listToBeAvoided</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><span style="color:rgb(171,178,191);">item1</span> <span style="color:rgb(171,178,191);">item2</span> <span style="color:rgb(92,99,112);font-style: italic;">/* comment */</span> <span style="color:rgb(171,178,191);">item3</span> <span style="color:rgb(171,178,191);">item4</span><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br><br><span style="color:rgb(92,99,112);font-style: italic;"># This is ok</span><br><span style="color:rgb(171,178,191);">acceptableList</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><span style="color:rgb(171,178,191);">item1</span> <span style="color:rgb(171,178,191);">item2</span><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br><br><span style="color:rgb(92,99,112);font-style: italic;"># This is also ok if the list is expected to contain more elements</span><br><span style="color:rgb(171,178,191);">acceptableList</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><br> <span style="color:rgb(171,178,191);">item1</span><br> <span style="color:rgb(171,178,191);">item2</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># more items if needed...</span><br><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br></code></pre>
|
||
<h2 id="sec-testing-changes">Testing Changes</h2>
|
||
<p>Once you have made your changes, you will need to test them thoroughly. To make
|
||
testing easier you may either use the <code>configuration.nix</code> located in the
|
||
repository root, or use the development package located in <code>flake/develop.nix</code>.
|
||
The development package allows you to quickly bootstrap a Neovim configuration
|
||
with only the required modules, instead of the packages that consume the
|
||
<code>configuration.nix</code>, so it is generally preferable. To use it navigate to the
|
||
<code>develop.nix</code> module, and update the <code>configuration</code> set with the Neovim
|
||
configuration that you would like to test with. For example:</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># Let's assume you are adding a new module for the Nix language.</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># You will need to enable it here</span><br> <span style="color:rgb(86,182,194);">configuration</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">languages</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">nix</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">enable</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span><br><br> <span style="color:rgb(92,99,112);font-style: italic;"># You can also enable other plugins that you wish to test with, for example</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># none-ls:</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">lsp</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">null-ls</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">enable</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">setupOpts</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span> <span style="color:rgb(92,99,112);font-style: italic;">/* Your setup options here */</span> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br></code></pre>
|
||
<p>You may then run this package with <code>nix run .#develop</code> and check for build or
|
||
runtime errors. If Neovim builds and opens without any errors, then your changes
|
||
are good to go. Open your pull request, and it will be reviewed as soon as
|
||
possible.</p>
|
||
<p>If your changes are rather large, or if you would like to instead test with a
|
||
more complex configuration then you might use the <code>configuration.nix</code> for
|
||
testing. Make your changes, and then build either the default or <code>maximal</code>
|
||
package to test your changes.</p>
|
||
<div class="admonition important">
|
||
<p class="admonition-title">Important</p>
|
||
<p><code>configuration.nix</code> is a module used to bootstrap <strong>demo</strong> packages and should
|
||
generally not be changed unless migrating old APIs or updating the set of
|
||
default plugins. Similarly, the <code>develop.nix</code> file is for reference, and
|
||
testing configurations <strong>should not be committed</strong>.</p>
|
||
</div>
|
||
<h2 id="sec-guidelines-documentation">Adding Documentation</h2>
|
||
<p>Almost all changes to <strong>nvf</strong>'s codebase warrant updates to the documentation.
|
||
At the very least, you must update the relevant changelog document to describe
|
||
your changes. The documentation files found within the repository use a superset
|
||
of <a href="https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax">Nixpkgs Flavoured Markdown</a> thanks to our
|
||
<a href="https://github.com/feel-co/ndg">in-house documentation generator</a>.</p>
|
||
<p>As a general rule of thumb:</p>
|
||
<ul>
|
||
<li>Everything in the CommonMark spec is supported</li>
|
||
<li>Everything in Nixpkgs Flavoured Markdown is supported</li>
|
||
<li>Github Flavored Markdown is supported for Tables and Admonitions</li>
|
||
</ul>
|
||
<p>By feeding NDG, our documentation generator, Markdown sources we can generate a
|
||
HTML manual with various goodies, including a <strong>search page</strong> and an <strong>options
|
||
page</strong>. The latter, found under <code>options.html</code> contains module options, similar
|
||
to the official Nixpkgs search utility. The supported syntax for NDG can be
|
||
found over at the <a href="https://github.com/feel-co/ndg/blob/main/ndg-commonmark/docs/SYNTAX.md">library documentation</a>.</p>
|
||
<h3>Building the Documentation</h3>
|
||
<p>The HTML version of this documentation, dubbed the "nvf manual", can be
|
||
generated and opened by typing the following in a shell within a clone of the
|
||
<strong>nvf</strong> Git repository:</p>
|
||
<pre class="highlight"><code class="language-sh"><span style="color:rgb(92,99,112);font-style: italic;"># Build the online manual</span><br><span style="color:rgb(232,102,113);">$</span> <span style="color:rgb(171,178,191);">nix</span> <span style="color:rgb(232,102,113);">build</span> <span style="color:rgb(232,102,113);">.#docs-html</span><br><br><span style="color:rgb(92,99,112);font-style: italic;"># Open it with a valid browser</span><br><span style="color:rgb(232,102,113);">$</span> <span style="color:rgb(171,178,191);">xdg</span><span style="color:rgb(152,195,121);">-open</span> <span style="color:rgb(232,102,113);">$</span><span style="color:rgb(232,102,113);">PWD</span><span style="color:rgb(232,102,113);">/result/share/doc/nvf/index.html</span><br></code></pre>
|
||
<p>Additionally, if you are adding new links to the documentation it is <strong>generally
|
||
recommended</strong> that you run the package that identifies dead URLs in the
|
||
documentation:</p>
|
||
<pre class="highlight"><code class="language-sh"><span style="color:rgb(92,99,112);font-style: italic;"># Build the link checker package</span><br><span style="color:rgb(232,102,113);">$</span> <span style="color:rgb(171,178,191);">nix</span> <span style="color:rgb(232,102,113);">build</span> <span style="color:rgb(232,102,113);">.#docs-linkcheck</span><br></code></pre>
|
||
<p>You must ensure that the <strong>HTML Documentation</strong> builds before submitting a pull
|
||
request. If the documentation builds, an automatic "preview" build will be
|
||
deployed automatically for your Pull Request. You may use this preview to view
|
||
your changes as your Pull Request is updated.</p>
|
||
<h3>Formatting Changelog Entries</h3>
|
||
<p>For additions, removals or any general change that concerns the users you must
|
||
add a changelog entry. The changelog entries are later included in the rendered
|
||
manual for users hoping to learn what has changed.</p>
|
||
<p>To maintain consistency, you must follow the following format in the changelog:</p>
|
||
<pre class="highlight"><code class="language-markdown"><span style="color:rgb(97,175,239);">[</span><span style="color:rgb(97,175,239);">username</span><span style="color:rgb(97,175,239);">]</span><span style="color:rgb(97,175,239);">(</span><span style="color:rgb(86,182,194);text-decoration: underline;">https://github.com/username</span><span style="color:rgb(97,175,239);">)</span>:<br><br><span style="color:rgb(232,102,113);">- </span>Added ...<br><span style="color:rgb(232,102,113);">- </span>Removed ...<br><span style="color:rgb(232,102,113);">- </span>Changed ...<br></code></pre>
|
||
<p>If this is your first contribution, you should add yourself to the changelog.
|
||
Linking your GitHub account is not a strict requirement; it can be any page that
|
||
people can use to discover you. Below the link to your profile, you should
|
||
include a brief description of your changes. Those descriptions must be in past
|
||
tense, unlike commit messages.</p>
|
||
<p>While adding a new section, please insert the section at an arbitrary location
|
||
under the <code>## Changelog</code> section rather than the end of the document. This helps
|
||
avoid merge conflicts.</p>
|
||
<h3>Breaking Changes</h3>
|
||
<p>If you are introducing <em>breaking</em> changes to the repository, then you must also
|
||
briefly mention what has changed in the breaking changes section of the
|
||
changelog document that you are editing. If this section does not yet exist, you
|
||
must create it.</p>
|
||
<pre class="highlight"><code class="language-markdown"><span style="color:rgb(209,154,102);font-weight: bold;"># Release 0.9 {#sec-release-0-9}</span><br><br><span style="color:rgb(209,154,102);font-weight: bold;">## Breaking changes</span><br><br><span style="color:rgb(232,102,113);">- </span>We broke everything, please migrate!<br></code></pre>
|
||
<p>This section is <em>critical</em>, as it is used to communicate to the users what has
|
||
changed in the codebase and what breakage they may expect upon an update. To be
|
||
comprehensive, you should include migration steps or how users may mitigate
|
||
breakage depending on the context of the change.</p>
|
||
<h2 id="sec-additional-plugins">Adding Plugins</h2>
|
||
<p><strong>nvf</strong> generally tries to avoid using Neovim plugins from Nixpkgs, and thus
|
||
uses one of the two alternative methods where applicable. 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, C or even Assembly) that need to be
|
||
built with Nix to function correctly. In this case you must use a local overlay.</p>
|
||
<h3 id="sec-npins-for-plugins">With npins</h3>
|
||
<p>npins is the standard, and as described above, the <em>faster</em> method of adding new
|
||
plugins to <strong>nvf</strong>. You simply need the repository URL for the plugin, and you
|
||
can add it as a source to be built automatically with just one command. To add a
|
||
new Neovim plugin, use <code>npins</code>. For example:</p>
|
||
<pre class="highlight"><code class="language-bash"><span style="color:rgb(97,175,239);">nix-shell</span> <span style="color:rgb(232,102,113);">-p</span> <span style="color:rgb(232,102,113);">npins</span> <span style="color:rgb(92,99,112);font-style: italic;"># or nix shell nixpkgs#npins if using flakes</span><br></code></pre>
|
||
<p>Then run:</p>
|
||
<pre class="highlight"><code class="language-bash"><span style="color:rgb(97,175,239);">npins</span> <span style="color:rgb(232,102,113);">add</span> <span style="color:rgb(232,102,113);">--name</span> <span style="color:rgb(171,178,191);"><</span><span style="color:rgb(232,102,113);">plugin</span> <span style="color:rgb(232,102,113);">name</span><span style="color:rgb(171,178,191);">></span> <span style="color:rgb(232,102,113);">github</span> <span style="color:rgb(171,178,191);"><</span><span style="color:rgb(232,102,113);">owner</span><span style="color:rgb(171,178,191);">></span> <span style="color:rgb(171,178,191);"><</span><span style="color:rgb(232,102,113);">repo</span><span style="color:rgb(171,178,191);">></span> <span style="color:rgb(232,102,113);">-b</span> <span style="color:rgb(171,178,191);"><</span><span style="color:rgb(232,102,113);">branch</span><span style="color:rgb(171,178,191);">></span><br></code></pre>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Be sure to replace any non-alphanumeric characters with <code>-</code> for <code>--name</code>. For
|
||
example</p>
|
||
<pre class="highlight"><code class="language-bash"><span style="color:rgb(97,175,239);">npins</span> <span style="color:rgb(232,102,113);">add</span> <span style="color:rgb(232,102,113);">--name</span> <span style="color:rgb(232,102,113);">lazydev-nvim</span> <span style="color:rgb(232,102,113);">github</span> <span style="color:rgb(232,102,113);">folke</span> <span style="color:rgb(232,102,113);">lazydev.nvim</span> <span style="color:rgb(232,102,113);">-b</span> <span style="color:rgb(232,102,113);">main</span><br></code></pre>
|
||
</div>
|
||
<p>Once the <code>npins</code> command is done, you can start referencing the plugin as a
|
||
<strong>string</strong>.</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">config</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">startPlugins</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">lazydev-nvim</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<h3 id="sec-pkgs-for-plugins">Packaging Complex Plugins</h3>
|
||
<p>Some plugins require additional packages to be built and substituted to function
|
||
correctly. For example <a href="https://github.com/Saghen/blink.cmp">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>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>buildRustPackage</code> to build the library from the repository root, and
|
||
copy everything in the <code>postInstall</code> phase.</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># ...</span><br> <br> <span style="color:rgb(86,182,194);">postInstall</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">''</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(97,175,239);">cp</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(232,102,113);">-r</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(232,102,113);">{</span><span style="color:rgb(232,102,113);">lua,plugin</span><span style="color:rgb(232,102,113);">}</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(232,102,113);">$</span><span style="color:rgb(171,178,191);">out</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(97,175,239);">mkdir</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(232,102,113);">-p</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(232,102,113);">$</span><span style="color:rgb(171,178,191);">out</span><span style="color:rgb(152,195,121);">/doc"</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(97,175,239);">cp</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">'doc/'</span><span style="color:rgb(232,102,113);">*</span><span style="color:rgb(152,195,121);">'.txt'</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(232,102,113);">$</span><span style="color:rgb(171,178,191);">out</span><span style="color:rgb(152,195,121);">/doc/"</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(97,175,239);">mkdir</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(232,102,113);">-p</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(232,102,113);">$</span><span style="color:rgb(171,178,191);">out</span><span style="color:rgb(152,195,121);">/target"</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(97,175,239);">mv</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(232,102,113);">$</span><span style="color:rgb(171,178,191);">out</span><span style="color:rgb(152,195,121);">/lib"</span><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(232,102,113);">$</span><span style="color:rgb(171,178,191);">out</span><span style="color:rgb(152,195,121);">/target/release"</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">''</span><span style="color:rgb(132,139,152);">;</span><br> <br> <span style="color:rgb(92,99,112);font-style: italic;"># ...</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<p>In a similar fashion, you may utilize <code>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>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>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>pluginBuilders</code>) function manually in
|
||
<code>modules/wrapper/build/config.nix</code>. Once done, you may refer to your plugin as a
|
||
<strong>string</strong>.</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">config</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">startPlugins</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">blink-cmp</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<h3 id="sec-modular-setup-options">Modular Setup Options</h3>
|
||
<p>Most plugins is initialized with a call to <code>require('plugin').setup({...})</code>.</p>
|
||
<p>We use a special function that lets you easily add support for such setup
|
||
options in a modular way: <code>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 class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># in modules/.../your-plugin/your-plugin.nix</span><br><br><span style="color:rgb(132,139,152);">{</span><span style="color:rgb(232,102,113);">lib</span><span style="color:rgb(132,139,152);">,</span> <span style="color:rgb(232,102,113);">...</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">:</span><br><span style="color:rgb(198,120,221);">let</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">types</span><span style="color:rgb(132,139,152);">)</span> bool int<span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">nvim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">types</span><span style="color:rgb(132,139,152);">)</span> mkPluginSetupOption<span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(198,120,221);">in</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">options</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">your-plugin</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">setupOpts</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkPluginSetupOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">plugin name</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">enable_feature_a</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkOption</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">type</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">bool</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">default</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">false</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># ...</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><br> <span style="color:rgb(86,182,194);">number_option</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkOption</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">type</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">int</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">default</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">3</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># ...</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># in modules/.../your-plugin/config.nix</span><br><span style="color:rgb(132,139,152);">{</span><span style="color:rgb(232,102,113);">lib</span><span style="color:rgb(132,139,152);">,</span> <span style="color:rgb(232,102,113);">config</span><span style="color:rgb(132,139,152);">,</span> <span style="color:rgb(232,102,113);">...</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">:</span><br><span style="color:rgb(198,120,221);">let</span><br> cfg <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">config</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">your-plugin</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(198,120,221);">in</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">luaConfigRC</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">nvim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">dag</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(97,175,239);">entryAnywhere</span> <span style="color:rgb(152,195,121);">''</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> require('plugin-name').setup(</span><span style="color:rgb(232,102,113);">${</span><span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">nvim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">lua</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(97,175,239);">toLuaObject</span> <span style="color:rgb(171,178,191);">cfg</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">setupOpts</span><span style="color:rgb(232,102,113);">}</span><span style="color:rgb(152,195,121);">)</span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">''</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<p>This above config will result in this Lua script:</p>
|
||
<pre class="highlight"><code class="language-lua"><span style="color:rgb(86,182,194);">require</span><span style="color:rgb(132,139,152);">(</span><span style="color:rgb(152,195,121);">'plugin-name'</span><span style="color:rgb(132,139,152);">)</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(97,175,239);">setup</span><span style="color:rgb(132,139,152);">(</span><span style="color:rgb(229,192,123);font-weight: bold;">{</span><br> <span style="color:rgb(86,182,194);">enable_feature_a</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">false</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(86,182,194);">number_option</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">3</span><span style="color:rgb(132,139,152);">,</span><br><span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(132,139,152);">)</span><br></code></pre>
|
||
<p>Now users can set any of the pre-defined option field, and can also add their
|
||
own fields!</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># in user's config</span><br><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">your-plugin</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">setupOpts</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">enable_feature_a</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">number_option</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">4</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">another_field</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">hello</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">size</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span> <span style="color:rgb(92,99,112);font-style: italic;"># nested fields work as well</span><br> <span style="color:rgb(86,182,194);">top</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">10</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<h3 id="sec-details-of-toluaobject">Details of <code>toLuaObject</code></h3>
|
||
<p>As you've seen above, <code>toLuaObject</code> is used to convert our nix attrSet
|
||
<code>cfg.setupOpts</code>, into a lua table. Here are some rules of the conversion:</p>
|
||
<ol>
|
||
<li>
|
||
<p>Nix <code>null</code> converts to lua <code>nil</code></p>
|
||
</li>
|
||
<li>
|
||
<p>Number and strings convert to their lua counterparts</p>
|
||
</li>
|
||
<li>
|
||
<p>Nix attribute sets (<code>{}</code>) and lists (<code>]</code>) convert into Lua dictionaries and
|
||
tables respectively. Here is an example of Nix -> Lua conversion.</p>
|
||
<ul>
|
||
<li><code>{foo = "bar"}</code> -> <code>{["foo"] = "bar"}</code></li>
|
||
<li><code>["foo" "bar"]</code> -> <code>{"foo", "bar"}</code></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>You can write raw Lua code using <code>lib.generators.mkLuaInline</code>. This function
|
||
is part of nixpkgs, and is accessible without relying on <strong>nvf</strong>'s extended
|
||
library.</p>
|
||
<ul>
|
||
<li><code>mkLuaInline "function add(a, b) return a + b end"</code> will yield the
|
||
following result:</li>
|
||
</ul>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">_type</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">lua-inline</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">expr</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">function add(a, b) return a + b end</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<p>The above expression will be interpreted as a Lua expression in the final
|
||
config. Without the <code>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 class="highlight"><code class="language-nix"><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">your-plugin</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">setupOpts</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">on_init</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">generators</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(97,175,239);">mkLuaInline</span> <span style="color:rgb(152,195,121);">''</span><span style="color:rgb(152,195,121);"></span><br><span style="color:rgb(152,195,121);"> function()</span><br><span style="color:rgb(152,195,121);"> print('we can write lua!')</span><br><span style="color:rgb(152,195,121);"> end</span><br><span style="color:rgb(152,195,121);"> </span><span style="color:rgb(152,195,121);">''</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
</li>
|
||
</ol>
|
||
<h3 id="sec-lazy-plugins">Lazy Loading Plugins</h3>
|
||
<p>If the plugin can be lazy-loaded, <code>vim.lazy.plugins</code> should be used to add it.
|
||
Lazy plugins are managed by <code>lz.n</code>.</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># in modules/.../your-plugin/config.nix</span><br><span style="color:rgb(132,139,152);">{</span><span style="color:rgb(232,102,113);">config</span><span style="color:rgb(132,139,152);">,</span> <span style="color:rgb(232,102,113);">...</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">:</span> <span style="color:rgb(198,120,221);">let</span><br> cfg <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">config</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">your-plugin</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(198,120,221);">in</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">lazy</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">plugins</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">your-plugin</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># Instead of vim.startPlugins, use this:</span><br> <span style="color:rgb(86,182,194);">package</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">your-plugin</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br><br> <span style="color:rgb(92,99,112);font-style: italic;"># ıf your plugin uses the `require('your-plugin').setup{...}` pattern</span><br> <span style="color:rgb(86,182,194);">setupModule</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">your-plugin</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">cfg</span><span style="color:rgb(132,139,152);">)</span> setupOpts<span style="color:rgb(132,139,152);">;</span><br><br> <span style="color:rgb(92,99,112);font-style: italic;"># Events that trigger this plugin to be loaded</span><br> <span style="color:rgb(86,182,194);">event</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">DirChanged</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">cmd</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">YourPluginCommand</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br><br> <span style="color:rgb(92,99,112);font-style: italic;"># Plugin Keymaps</span><br> <span style="color:rgb(86,182,194);">keys</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><br> <span style="color:rgb(92,99,112);font-style: italic;"># We'll cover this in detail in the 'keybinds' section</span><br> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">key</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>d</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">mode</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">action</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">:YourPluginCommand</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><br> <span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<p>This results in the following lua code:</p>
|
||
<pre class="highlight"><code class="language-lua"><span style="color:rgb(86,182,194);">require</span><span style="color:rgb(132,139,152);">(</span><span style="color:rgb(152,195,121);">'lz.n'</span><span style="color:rgb(132,139,152);">)</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(97,175,239);">load</span><span style="color:rgb(132,139,152);">(</span><span style="color:rgb(229,192,123);font-weight: bold;">{</span><br> <span style="color:rgb(229,192,123);font-weight: bold;">{</span><br> <span style="color:rgb(152,195,121);">"name-of-your-plugin"</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(97,175,239);">after</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(198,120,221);">function</span><span style="color:rgb(132,139,152);">(</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(86,182,194);">require</span><span style="color:rgb(132,139,152);">(</span><span style="color:rgb(152,195,121);">'your-plugin'</span><span style="color:rgb(132,139,152);">)</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(97,175,239);">setup</span><span style="color:rgb(132,139,152);">(</span><span style="color:rgb(229,192,123);font-weight: bold;">{</span><br> <span style="color:rgb(92,99,112);font-style: italic;">--[[ your setupOpts ]]</span><span style="color:rgb(92,99,112);font-style: italic;">--</span><br> <span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(198,120,221);">end</span><span style="color:rgb(132,139,152);">,</span><br><br> <span style="color:rgb(86,182,194);">event</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(229,192,123);font-weight: bold;">{</span><span style="color:rgb(152,195,121);">"DirChanged"</span><span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(86,182,194);">cmd</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(229,192,123);font-weight: bold;">{</span><span style="color:rgb(152,195,121);">"YourPluginCommand"</span><span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(86,182,194);">keys</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(229,192,123);font-weight: bold;">{</span><br> <span style="color:rgb(229,192,123);font-weight: bold;">{</span><span style="color:rgb(152,195,121);">"<leader>d"</span><span style="color:rgb(132,139,152);">,</span> <span style="color:rgb(152,195,121);">":YourPluginCommand"</span><span style="color:rgb(132,139,152);">,</span> <span style="color:rgb(86,182,194);">mode</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(229,192,123);font-weight: bold;">{</span><span style="color:rgb(152,195,121);">"n"</span><span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(229,192,123);font-weight: bold;">}</span><br><span style="color:rgb(229,192,123);font-weight: bold;">}</span><span style="color:rgb(132,139,152);">)</span><br></code></pre>
|
||
<p>A full list of options can be found in the <a href="./options.html#option-vim-lazy-plugins"><code>vim.lazy.plugins</code> spec</a> on the
|
||
rendered manual.</p>
|
||
<h2 id="sec-keybinds">Keybinds</h2>
|
||
<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 <a href="https://github.com/NotAShelf/nvf/tree/main/lib">extended standard library</a>. The
|
||
following section contains a general overview to how you may utilize said
|
||
functions.</p>
|
||
<h3 id="sec-custom-key-mappings">Custom Key Mappings Support for a Plugin</h3>
|
||
<p>To set a mapping, you should define it in <code>vim.keymaps</code>. As an example, a simple
|
||
keybinding can look like this:</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">keymaps</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><br> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">key</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>wq</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">mode</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">action</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">:wq<CR></span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">silent</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(209,154,102);">true</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">desc</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">Save file and quit</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><br> <span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
<p>There are many other settings available in the keymap module. Please refer to
|
||
the <a href="options.html#option-vim-keymaps">module option documentation</a> for a full and up-to-date list of them.</p>
|
||
<p>To make adding new keymaps for your favorite plugins easier, <strong>nvf</strong> provides a
|
||
helper function. This is so that you do not have to write the mapping attribute
|
||
sets every time:</p>
|
||
<ul>
|
||
<li><code>mkKeymap</code>, which mimics Neovim's <code>vim.keymap.set</code> function</li>
|
||
</ul>
|
||
<p>You can read the source code of some modules to see them in action, but the
|
||
usage should look something like this:</p>
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># pluginDefinition.nix</span><br><span style="color:rgb(132,139,152);">{</span><span style="color:rgb(232,102,113);">lib</span><span style="color:rgb(132,139,152);">,</span> <span style="color:rgb(232,102,113);">...</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">:</span> <span style="color:rgb(198,120,221);">let</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">options</span><span style="color:rgb(132,139,152);">)</span> mkEnableOption<span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">nvim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">binds</span><span style="color:rgb(132,139,152);">)</span> mkMappingOption<span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(198,120,221);">in</span> <span style="color:rgb(132,139,152);">{</span><br> options<span style="color:rgb(132,139,152);">.</span>vim<span style="color:rgb(132,139,152);">.</span>plugin <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">enable</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkEnableOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">Enable plugin</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br><br> <span style="color:rgb(92,99,112);font-style: italic;"># Mappings should always be inside an attrset called mappings</span><br> <span style="color:rgb(86,182,194);">mappings</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">workspaceDiagnostics</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkMappingOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">Workspace diagnostics [trouble]</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>lwd</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">documentDiagnostics</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkMappingOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">Document diagnostics [trouble]</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>ld</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">lspReferences</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkMappingOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">LSP References [trouble]</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>lr</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">quickfix</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkMappingOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">QuickFix [trouble]</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>xq</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">locList</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkMappingOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">LOCList [trouble]</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>xl</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(86,182,194);">symbols</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkMappingOption</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">Symbols [trouble]</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><leader>xs</span><span style="color:rgb(152,195,121);">"</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
|
||
<pre class="highlight"><code class="language-nix"><span style="color:rgb(92,99,112);font-style: italic;"># config.nix</span><br><span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(232,102,113);">config</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(232,102,113);">lib</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(232,102,113);">options</span><span style="color:rgb(132,139,152);">,</span><br> <span style="color:rgb(232,102,113);">...</span><br><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">:</span> <span style="color:rgb(198,120,221);">let</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">modules</span><span style="color:rgb(132,139,152);">)</span> mkIf<span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">lib</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">nvim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">binds</span><span style="color:rgb(132,139,152);">)</span> mkKeymap<span style="color:rgb(132,139,152);">;</span><br><br> cfg <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">config</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">plugin</span><span style="color:rgb(132,139,152);">;</span><br><br> keys <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">cfg</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">mappings</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(198,120,221);">inherit</span> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(171,178,191);">options</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">lsp</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">trouble</span><span style="color:rgb(132,139,152);">)</span> mappings<span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(198,120,221);">in</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">config</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(97,175,239);">mkIf</span> <span style="color:rgb(171,178,191);">cfg</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">enable</span> <span style="color:rgb(132,139,152);">{</span><br> <span style="color:rgb(86,182,194);">vim</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">keymaps</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(132,139,152);">[</span><br> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(97,175,239);">mkKeymap</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">keys</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">workspaceDiagnostics</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><cmd>Trouble toggle diagnostics<CR></span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(132,139,152);">{</span><span style="color:rgb(86,182,194);">desc</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">mappings</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">workspaceDiagnostics</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">description</span><span style="color:rgb(132,139,152);">;</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(97,175,239);">mkKeymap</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">keys</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">documentDiagnostics</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><cmd>Trouble toggle diagnostics filter.buf=0<CR></span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(132,139,152);">{</span><span style="color:rgb(86,182,194);">desc</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">mappings</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">documentDiagnostics</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">description</span><span style="color:rgb(132,139,152);">;</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(97,175,239);">mkKeymap</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">keys</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">lspReferences</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><cmd>Trouble toggle lsp_references<CR></span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(132,139,152);">{</span><span style="color:rgb(86,182,194);">desc</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">mappings</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">lspReferences</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">description</span><span style="color:rgb(132,139,152);">;</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(97,175,239);">mkKeymap</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">keys</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">quickfix</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><cmd>Trouble toggle quickfix<CR></span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(132,139,152);">{</span><span style="color:rgb(86,182,194);">desc</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">mappings</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">quickfix</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">description</span><span style="color:rgb(132,139,152);">;</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(97,175,239);">mkKeymap</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">keys</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">locList</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><cmd>Trouble toggle loclist<CR></span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(132,139,152);">{</span><span style="color:rgb(86,182,194);">desc</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">mappings</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">locList</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">description</span><span style="color:rgb(132,139,152);">;</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(132,139,152);">(</span><span style="color:rgb(97,175,239);">mkKeymap</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);">n</span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(171,178,191);">keys</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">symbols</span> <span style="color:rgb(152,195,121);">"</span><span style="color:rgb(152,195,121);"><cmd>Trouble toggle symbols<CR></span><span style="color:rgb(152,195,121);">"</span> <span style="color:rgb(132,139,152);">{</span><span style="color:rgb(86,182,194);">desc</span> <span style="color:rgb(171,178,191);">=</span> <span style="color:rgb(171,178,191);">mappings</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">symbols</span><span style="color:rgb(132,139,152);">.</span><span style="color:rgb(86,182,194);">description</span><span style="color:rgb(132,139,152);">;</span><span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">)</span><br> <span style="color:rgb(132,139,152);">]</span><span style="color:rgb(132,139,152);">;</span><br> <span style="color:rgb(132,139,152);">}</span><span style="color:rgb(132,139,152);">;</span><br><span style="color:rgb(132,139,152);">}</span><br></code></pre>
|
||
|
||
<div class="admonition tip">
|
||
<p class="admonition-title">Tip</p>
|
||
<p>If you have come across a plugin that has an API that doesn't seem to easily
|
||
allow custom keybindings, don't be scared to implement a draft PR. We'll help
|
||
you get it done.</p>
|
||
</div>
|
||
</body></html><!-- markdownlint-enable MD013 --><!-- markdownlint-disable MD013 --><!-- markdownlint-enable MD013 --></main>
|
||
</div>
|
||
|
||
<footer>
|
||
<p>Generated with ndg</p>
|
||
</footer>
|
||
|
||
</div>
|
||
|
||
|
||
</body>
|
||
</html>
|