raf/neovim-flake
1
0
Fork 0
mirror of https://github.com/NotAShelf/neovim-flake.git synced 2025-12-20 12:50:09 +01:00
Code Issues Projects Releases Packages Wiki Activity

Merge 797748a20c into cd81bbb904

Browse source
This commit is contained in:
raf 2025-12-18 13:38:18 +00:00 • committed by GitHub
commit f06b89ef34
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
15 changed files with 545 additions and 274 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/check.yml vendored
View file

@ -28,7 +28,7 @@ jobs:
- name: Check Flake
run: nix flake check
format-with-alejandra:
format-sources:
name: "Check formatting"
runs-on: ubuntu-latest
if: "!contains(github.event.pull_request.title, '[skip ci]')"

9
docs/manual/configuring.md
View file

@ -3,10 +3,11 @@
[helpful tips section]: ./tips.html#ch-helpful-tips
[options reference]: ./options.html
nvf allows for _very_ extensive configuration in Neovim through the Nix module
interface. The below chapters describe several of the options exposed in nvf for
your convenience. You might also be interested in the [helpful tips section] for
more advanced or unusual configuration options supported by nvf.
**nvf** allows for _very_ extensive configuration in Neovim through the Nix
module interface. The below chapters describe several of the options exposed in
nvf for your convenience. You might also be interested in the
[helpful tips section] for more advanced or unusual configuration options
supported by nvf.
Note that this section does not cover module _options_. For an overview of all
module options provided by nvf, please visit the [options reference]

613
docs/manual/hacking.md
View file

@ -3,12 +3,13 @@
[open issues]: https://github.com/notashelf/nvf/issues
[new issue]: https://github.com/notashelf/nvf/issues/new
nvf 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 nvf's development as seamlessly
as possible without leaving any question marks in your head.
**nvf** 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 **nvf**'s
development as seamlessly as possible without leaving any question marks in your
head.
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
@ -23,24 +24,51 @@ please do not be afraid to submit a pull request, we will help you get it in.
## Getting Started {#sec-contrib-getting-started}
You, naturally, would like to start by forking the repository to get started. If
you are new to Git and GitHub, do have a look at GitHub's
[Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for
instructions on how you can do this. Once you have a fork of **nvf**, you should
create a separate branch based on the most recent `main` branch. Give your
branch a reasonably descriptive name (e.g. `feature/debugger` or
`fix/pesky-bug`) and you are ready to work on your changes
[Fork a repo guide]: https://help.github.com/articles/fork-a-repo/
[Contributing Guidelines]: #sec-guidelines
[Create a Pull Request]: https://help.github.com/articles/creating-a-pull-request
To contribute to **nvf**, you'll first want to fork the repository. If you are
new to Git and GitHub, do have a look at GitHub's [Fork a repo guide] for
instructions on how you can do this. Once your fork is created, you should
create a separate branch based on the most recent `main` branch. While you _can_
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. `feature/new-debugger` or `fix/pesky-bug`) and you are ready to work on
your changes!
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
[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and
[create a pull request](https://help.github.com/articles/creating-a-pull-request).
[Contributing Guidelines], push the branch to GitHub and [Create a Pull Request]
The default pull request template available on the **nvf** 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.
Before submitting your pull request, please ensure that:
- The code is formatted as described in the formatting section
- The commit message fits the contributing guidelines (**nvf** does not use
Conventional Commits!)
- You have updated the changelog entry and optionally updated the documentation
with important information
None of those are reasons for a Pull Request to be closed, but it will reduce
the number of roundtrips required before we can merge your Pull Request.
> [!IMPORTANT]
> 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 _patches_ through e-mail.
>
> You may send your patches to [@NotAShelf](https://github.com/notashelf) using
> the public e-mail located on the GitHub page. Though, please remember to
> adhere to the contributing guidelines strictly as e-mail instroduces a
> significant overhead to the communication process.
## Guidelines {#sec-guidelines}
[discussions tab]: https://github.com/NotAShelf/nvf/discussions
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
@ -48,34 +76,26 @@ 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.
If you are uncertain how these rules affect the change you would like to make
then feel free to start a discussion in the
[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not
necessarily) before you start developing.
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 [discussions tab] 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.
### Adding Documentation {#sec-guidelines-documentation}
### Formatting {#sec-guidelines-formatting}
[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
[code style section]: #sec-guidelines-code-style
Almost all changes warrant updates to the documentation: at the very least, you
must update the changelog. Both the manual and module options use
[Nixpkgs Flavoured Markdown].
There are various files within the **nvf** 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.
The HTML version of this manual containing both the module option descriptions
and the documentation of **nvf** (such as this page) can be generated and opened
by typing the following in a shell within a clone of the **nvf** Git repository:
- Nix files **must** be formatted with the Alejandra formatter, following some
specific tips found in [Nix style section](#nix-sec-code-style-nix).
- Markdown files **must** be formatted with the `deno fmt` command, as described
in the [Markdown style section](#sec-code-style-markdown).
```console
$ nix build .#docs-html
$ xdg-open $PWD/result/share/doc/nvf/index.html
```
### Formatting Code {#sec-guidelines-formatting}
Make sure your code is formatted as described in
[code-style section](#sec-guidelines-code-style). To maintain consistency
throughout the project you are encouraged to browse through existing code and
adopt its style also in new code.
Make sure your code is formatted as described in [code style section] before
your changes are submitted.
### Formatting Commits {#sec-guidelines-commit-message-style}
@ -98,27 +118,29 @@ The commit messages should follow the
component or module in the first line. A commit message ideally, but not
necessarily, follow the given template from home-manager's own documentation
```
{component}: {description}
```gitcommit
{component}: {description}
{long description}
{long description}
```
where `{component}` refers to the code component (or module) your change
affects, `{description}` is a very brief description of your change, and
`{long description}` is an optional clarifying description. As a rare exception,
if there is no clear component, or your change affects many components, then the
`{component}` part is optional. See
[example commit message](#sec-guidelines-ex-commit-message) for a commit message
that fulfills these requirements.
`{long description}` is an optional clarifying description.
[example commit message]: #sec-guidelines-ex-commit-message
As a rare exception, if there is no clear component, or your change affects many
components, then the `{component}` part is optional. See
[example commit message] for a commit message that fulfills these requirements.
#### Example Commit {#sec-guidelines-ex-commit-message}
The commit
[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
in home-manager contains the following commit message.
[sample commit from Home Manager]: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
```
The [sample commit from Home Manager] contains the following commit message.
```gitcommit
starship: allow running in Emacs if vterm is used
The vterm buffer is backed by libvterm and can handle Starship prompts
@ -128,30 +150,63 @@ without issues.
Similarly, if you are contributing to **nvf**, you would include the scope of
the commit followed by the description:
```
```gitcommit
languages/ruby: init module
Adds a language module for Ruby, adds appropriate formatters and Treesitter grammars
Adds a language module for Ruby, adds appropriate formatters and Treesitter
grammars
```
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 behind it, for your commit.
relevant context, i.e., the reasoning for your commit.
Finally, when adding a new module, say `modules/foo.nix`, we use the fixed
commit format `foo: add module`. You can, of course, still include a long
description if you wish.
For new plugin additions, the following is a good starting point:
In case of nested modules, i.e `modules/languages/java.nix` you are recommended
to contain the parent as well - for example `languages/java: some major change`.
```gitcommit
plugin: init
```
You can, of course, still include a long description if you wish.
```gitcommit
neotree: init
This adds the neo-tree plugin.
```
In case of nested modules, e.g., `modules/languages/java.nix` you are
recommended to contain the parent as well -- for example
`languages/java: some major change` , or if it's a new language module,
`languages/java: init`
### Code Style {#sec-guidelines-code-style}
#### Treewide {#sec-code-style-treewide}
Keep lines at a reasonable width, ideally 80 characters or less. This also
applies to string literals and module descriptions and documentation.
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.
#### Markdown {#sec-code-style-markdown}
Various Markdown files are used for documentation in the **nvf** repository.
Besides the README, the manual is written almost entirely in Markdown. Since
**nvf** uses a special variant of CommonMark, dubbed "Nixpkgs-flavored
CommonMark" within this repository, you are encouraged to use the `deno fmt`
command (provided by `pkgs.deno`) to format your Markdown sources. To avoid
accidentally formatting HTML or CSS files, you might want to specify the file
extension as follows:
```bash
# Format all Markdown files within the repository
$ deno fmt --ext md **/*.md
```
You may also pass `--check` to the `deno fmt` command above to see if your
formatting complies with the project standards.
#### Nix {#sec-code-style-nix}
@ -165,12 +220,16 @@ 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.
##### Attribute Sets
Please use one line code for attribute sets that contain only one subset. For
example:
<!-- markdownlint-disable MD013 -->
```nix
# parent modules should always be unfolded
# which means module = { value = ... } instead of module.value = { ... }
# Parent modules should always be unfolded.
# which means `module = { value = ... }` instead of `module.value = { ... }`.
module = {
value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
@ -190,23 +249,45 @@ module = {
}
```
<!-- markdownlint-enable MD013 -->
If you move a line down after the merge operator, Alejandra will automatically
unfold the whole merged attrset for you, which we **do not** want.
unfold the whole merged attribute set for you, which we **do not** want.
```nix
module = {
# This is wrong!
key = mkEnableOption "some description" // {
default = true; # we want this to be inline
}; # ...
};
# ...
}
```
Though, if the right-hand side is more than a single line, it is okay to move to
a new line. For example:
```nix
module = {
# This is okay!
key = mkEnableOption "some description" // {
default = true;
example = false;
};
# ...
}
```
##### Lists
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.
```nix
# this is ok
# This is ok
acceptableList = [
item1 # comment
item2
@ -214,14 +295,14 @@ acceptableList = [
item4
];
# this is not ok
# This is *not* ok
listToBeAvoided = [item1 item2 /* comment */ item3 item4];
# this is ok
# This is ok
acceptableList = [item1 item2];
# this is also ok if the list is expected to contain more elements
acceptableList= [
# This is also ok if the list is expected to contain more elements
acceptableList = [
item1
item2
# more items if needed...
@ -230,129 +311,161 @@ acceptableList= [
## Testing Changes {#sec-testing-changes}
Once you have made your changes, you will need to test them thoroughly. If it is
a module, add your module option to `configuration.nix` (located in the root of
this project) inside `neovimConfiguration`. Enable it, and then run the maximal
configuration with `nix run .#maximal -Lv` to check for build errors. If neovim
opens in the current directory without any error messages (you can check the
output of `:messages` inside neovim to see if there are any errors), then your
changes are good to go. Open your pull request, and it will be reviewed as soon
as possible.
If it is not a new module, but a change to an existing one, then make sure the
module you have changed is enabled in the maximal configuration by editing
`configuration.nix`, and then run it with `nix run .#maximal -Lv`. Same
procedure as adding a new module will apply here.
## Keybinds {#sec-keybinds}
As of 0.4, there exists an API for writing your own keybinds and a couple of
useful utility functions are available in the
[extended standard library](https://github.com/NotAShelf/nvf/tree/main/lib). The
following section contains a general overview to how you may utilize said
functions.
## Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
To set a mapping, you should define it in `vim.keymaps`.
An example, simple keybinding, can look like this:
Once you have made your changes, you will need to test them thoroughly. To make
testing easier you may either use the `configuration.nix` located in the
repository root, or use the development package located in `flake/develop.nix`.
The development package allows you to quickly bootstrap a Neovim configuration
with only the required modules, instead of the packages that consume the
`configuration.nix`, so it is generally preferable. To use it navigate to the
`develop.nix` module, and update the `configuration` set with the Neovim
configuration that you would like to test with. For example:
```nix
{
vim.keymaps = [
{
key = "<leader>wq";
mode = ["n"];
action = ":wq<CR>";
silent = true;
desc = "Save file and quit";
}
];
}
```
# Let's assume you are adding a new module for the Nix language.
# You will need to enable it here
configuration = {
vim.languages.nix.enable = true;
There are many settings available in the options. Please refer to the
[documentation](./options.html#option-vim-keymaps) to see a list of them.
**nvf** provides a helper function, so that you don't have to write the mapping
attribute sets every time:
- `mkKeymap`, which mimics neovim's `vim.keymap.set` function
You can read the source code of some modules to see them in action, but the
usage should look something like this:
```nix
# plugindefinition.nix
{lib, ...}: let
inherit (lib.options) mkEnableOption;
inherit (lib.nvim.binds) mkMappingOption;
in {
options.vim.plugin = {
enable = mkEnableOption "Enable plugin";
# Mappings should always be inside an attrset called mappings
mappings = {
workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "<leader>lwd";
documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "<leader>ld";
lspReferences = mkMappingOption "LSP References [trouble]" "<leader>lr";
quickfix = mkMappingOption "QuickFix [trouble]" "<leader>xq";
locList = mkMappingOption "LOCList [trouble]" "<leader>xl";
symbols = mkMappingOption "Symbols [trouble]" "<leader>xs";
# You can also enable other plugins that you wish to test with, for example
# none-ls:
vim.lsp.null-ls = {
enable = true;
setupOpts = { /* Your setup options here */ };
};
}
```
```nix
# config.nix
{
config,
lib,
options,
...
}: let
inherit (lib.modules) mkIf;
inherit (lib.nvim.binds) mkKeymap;
cfg = config.vim.plugin;
keys = cfg.mappings;
inherit (options.vim.lsp.trouble) mappings;
in {
config = mkIf cfg.enable {
vim.keymaps = [
(mkKeymap "n" keys.workspaceDiagnostics "<cmd>Trouble toggle diagnostics<CR>" {desc = mappings.workspaceDiagnostics.description;})
(mkKeymap "n" keys.documentDiagnostics "<cmd>Trouble toggle diagnostics filter.buf=0<CR>" {desc = mappings.documentDiagnostics.description;})
(mkKeymap "n" keys.lspReferences "<cmd>Trouble toggle lsp_references<CR>" {desc = mappings.lspReferences.description;})
(mkKeymap "n" keys.quickfix "<cmd>Trouble toggle quickfix<CR>" {desc = mappings.quickfix.description;})
(mkKeymap "n" keys.locList "<cmd>Trouble toggle loclist<CR>" {desc = mappings.locList.description;})
(mkKeymap "n" keys.symbols "<cmd>Trouble toggle symbols<CR>" {desc = mappings.symbols.description;})
];
};
}
```
> [!NOTE]
> 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.
You may then run this package with `nix run .#develop` 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.
If your changes are rather large, or if you would like to instead test with a
more complex configuration then you might use the `configuration.nix` for
testing. Make your changes, and then build either the default or `maximal`
package to test your changes.
> [!IMPORTANT]
> `configuration.nix` is a module used to bootstrap **demo** packages and should
> generally not be changed unless migrating old APIs or updating the set of
> default plugins. Similarly, the `develop.nix` file is for reference, and
> testing configurations **should not be committed**.
## Adding Documentation {#sec-guidelines-documentation}
[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax
[in-house documentation generator]: https://github.com/feel-co/ndg
[library documentation]: https://github.com/feel-co/ndg/blob/main/ndg-commonmark/docs/SYNTAX.md
Almost all changes to **nvf**'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 [Nixpkgs Flavoured Markdown] thanks to our
[in-house documentation generator].
As a general rule of thumb:
- Everything in the CommonMark spec is supported
- Everything in Nixpkgs Flavoured Markdown is supported
- Github Flavored Markdown is supported for Tables and Admonitions
By feeding NDG, our documentation generator, Markdown sources we can generate a
HTML manual with various goodies, including a **search page** and an **options
page**. The latter, found under `options.html` contains module options, similar
to the official Nixpkgs search utility. The supported syntax for NDG can be
found over at the [library documentation].
### Building the Documentation
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
**nvf** Git repository:
```sh
# Build the online manual
$ nix build .#docs-html
# Open it with a valid browser
$ xdg-open $PWD/result/share/doc/nvf/index.html
```
Additionally, if you are adding new links to the documentation it is **generally
recommended** that you run the package that identifies dead URLs in the
documentation:
```sh
# Build the link checker package
$ nix build .#docs-linkcheck
```
You must ensure that the **HTML Documentation** 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.
### Formatting Changelog Entries
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.
To maintain consistency, you must follow the following format in the changelog:
```markdown
[username](https://github.com/username):
- Added ...
- Removed ...
- Changed ...
```
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.
While adding a new section, please insert the section at an arbitrary location
under the `## Changelog` section rather than the end of the document. This helps
avoid merge conflicts.
### Breaking Changes
If you are introducing _breaking_ 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.
```markdown
# Release 0.9 {#sec-release-0-9}
## Breaking changes
- We broke everything, please migrate!
```
This section is _critical_, 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.
## Adding Plugins {#sec-additional-plugins}
There are two methods for adding new Neovim plugins to **nvf**. npins is the
faster option that should be preferred if the plugin consists of pure Lua or
Vimscript code. In which case there is no building required, and we can easily
handle the copying of plugin files. Alternative method, which is required when
plugins try to build their own libraries (e.g., in Rust or C) that need to be
built with Nix to function correctly.
**nvf** 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.
### With npins {#sec-npins-for-plugins}
npins is the standard method of adding new plugins to **nvf**. You simply need
the repository URL for the plugin, and can add it as a source to be built
automatically with one command. To add a new Neovim plugin, use `npins`. For
example:
npins is the standard, and as described above, the _faster_ method of adding new
plugins to **nvf**. 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 `npins`. For example:
```bash
nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
@ -364,16 +477,13 @@ Then run:
npins add --name <plugin name> github <owner> <repo> -b <branch>
```
::: {.note}
Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
example
```bash
npins add --name lazydev-nvim github folke lazydev.nvim -b main
```
:::
> [!NOTE]
> Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
> example
>
> ```bash
> npins add --name lazydev-nvim github folke lazydev.nvim -b main
> ```
Once the `npins` command is done, you can start referencing the plugin as a
**string**.
@ -399,15 +509,21 @@ We use `buildRustPackage` to build the library from the repository root, and
copy everything in the `postInstall` phase.
```nix
postInstall = ''
cp -r {lua,plugin} "$out"
{
# ...
mkdir -p "$out/doc"
cp 'doc/'*'.txt' "$out/doc/"
postInstall = ''
cp -r {lua,plugin} "$out"
mkdir -p "$out/target"
mv "$out/lib" "$out/target/release"
'';
mkdir -p "$out/doc"
cp 'doc/'*'.txt' "$out/doc/"
mkdir -p "$out/target"
mv "$out/lib" "$out/target/release"
'';
# ...
}
```
In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs
@ -429,7 +545,7 @@ your package to the plugin builder (`pluginBuilders`) function manually in
}
```
### Modular setup options {#sec-modular-setup-options}
### Modular Setup Options {#sec-modular-setup-options}
Most plugins is initialized with a call to `require('plugin').setup({...})`.
@ -503,7 +619,7 @@ own fields!
}
```
### Details of toLuaObject {#sec-details-of-toluaobject}
### Details of `toLuaObject` {#sec-details-of-toluaobject}
As you've seen above, `toLuaObject` is used to convert our nix attrSet
`cfg.setupOpts`, into a lua table. Here are some rules of the conversion:
@ -544,7 +660,7 @@ As you've seen above, `toLuaObject` is used to convert our nix attrSet
}
```
### Lazy plugins {#sec-lazy-plugins}
### Lazy Loading Plugins {#sec-lazy-plugins}
If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it.
Lazy plugins are managed by `lz.n`.
@ -604,3 +720,104 @@ require('lz.n').load({
A full list of options can be found in the [`vim.lazy.plugins` spec] on the
rendered manual.
## Keybinds {#sec-keybinds}
[extended standard library]: https://github.com/NotAShelf/nvf/tree/main/lib
As of 0.4, there exists an API for writing your own keybinds and a couple of
useful utility functions are available in the [extended standard library]. The
following section contains a general overview to how you may utilize said
functions.
### Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings}
To set a mapping, you should define it in `vim.keymaps`. As an example, a simple
keybinding can look like this:
```nix
{
vim.keymaps = [
{
key = "<leader>wq";
mode = ["n"];
action = ":wq<CR>";
silent = true;
desc = "Save file and quit";
}
];
}
```
[module option documentation]: options.html#option-vim-keymaps
There are many other settings available in the keymap module. Please refer to
the [module option documentation] for a full and up-to-date list of them.
To make adding new keymaps for your favorite plugins easier, **nvf** provides a
helper function. This is so that you do not have to write the mapping attribute
sets every time:
- `mkKeymap`, which mimics Neovim's `vim.keymap.set` function
You can read the source code of some modules to see them in action, but the
usage should look something like this:
```nix
# pluginDefinition.nix
{lib, ...}: let
inherit (lib.options) mkEnableOption;
inherit (lib.nvim.binds) mkMappingOption;
in {
options.vim.plugin = {
enable = mkEnableOption "Enable plugin";
# Mappings should always be inside an attrset called mappings
mappings = {
workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "<leader>lwd";
documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "<leader>ld";
lspReferences = mkMappingOption "LSP References [trouble]" "<leader>lr";
quickfix = mkMappingOption "QuickFix [trouble]" "<leader>xq";
locList = mkMappingOption "LOCList [trouble]" "<leader>xl";
symbols = mkMappingOption "Symbols [trouble]" "<leader>xs";
};
}
```
<!-- markdownlint-disable MD013 -->
```nix
# config.nix
{
config,
lib,
options,
...
}: let
inherit (lib.modules) mkIf;
inherit (lib.nvim.binds) mkKeymap;
cfg = config.vim.plugin;
keys = cfg.mappings;
inherit (options.vim.lsp.trouble) mappings;
in {
config = mkIf cfg.enable {
vim.keymaps = [
(mkKeymap "n" keys.workspaceDiagnostics "<cmd>Trouble toggle diagnostics<CR>" {desc = mappings.workspaceDiagnostics.description;})
(mkKeymap "n" keys.documentDiagnostics "<cmd>Trouble toggle diagnostics filter.buf=0<CR>" {desc = mappings.documentDiagnostics.description;})
(mkKeymap "n" keys.lspReferences "<cmd>Trouble toggle lsp_references<CR>" {desc = mappings.lspReferences.description;})
(mkKeymap "n" keys.quickfix "<cmd>Trouble toggle quickfix<CR>" {desc = mappings.quickfix.description;})
(mkKeymap "n" keys.locList "<cmd>Trouble toggle loclist<CR>" {desc = mappings.locList.description;})
(mkKeymap "n" keys.symbols "<cmd>Trouble toggle symbols<CR>" {desc = mappings.symbols.description;})
];
};
}
```
<!-- markdownlint-enable MD013 -->
> [!TIP]
> 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.

42
docs/manual/index.md
View file

@ -1,20 +1,23 @@
# Introduction {#nvf-manual}
Version @NVF_VERSION@
Generated for nvf @NVF_VERSION@
## Preface {#ch-preface}
### What is nvf {#sec-what-is-it}
**nvf** is a highly modular, configurable, extensible and easy to use Neovim
configuration framework built and designed to be used with Nix. Boasting
flexibility, robustness and ease of use, this projecct allows you to configure a
fully featured Neovim instance with a few lines of Nix with lots of options for
advanced users as well.
[Nix]: https://nixos.org
## Try it out {#ch-try-it-out}
**nvf** is a highly modular, configurable, extensible and _easy to use_ Neovim
configuration framework built for and designed to be used with [Nix]. Boasting
flexibility, robustness and ease of use (among other positive traits), this
project allows you to configure a fully featured Neovim instance with a few
lines of Nix while leaving all kinds of doors open for integrating Lua in your
configurations _whether you are a beginner or an advanced user_.
Thanks to the portability of Nix, you can try out nvf without actually
## Try it Out {#ch-try-it-out}
Thanks to the portability of Nix, you can try out **nvf** without actually
installing it to your machine. Below are the commands you may run to try out
different configurations provided by this flake. As of v0.5, two specialized
configurations are provided:
@ -27,20 +30,27 @@ You may try out any of the provided configurations using the `nix run` command
on a system where Nix is installed.
```sh
# Add the nvf cache
$ cachix use nvf # Optional: it'll save you CPU resources and time
# Run the minimal configuration with the cache enabled
$ nix run github:notashelf/nvf#nix # Will run the default minimal configuration
```
Do keep in mind that this is **susceptible to garbage collection** meaning that
the built outputs will be removed from your Nix store once you garbage collect.
## Using Prebuilt Configs {#sec-using-prebuilt-configs}
## Using Prebuilt Configurations {#sec-using-prebuilt-configs}
<!-- markdownlint-disable MD014 -->
```bash
$ nix run github:notashelf/nvf#nix
$ nix run github:notashelf/nvf#maximal
```
<!-- markdownlint-enable MD014 -->
### Available Configurations {#sec-available-configs}
> [!NOTE]
@ -61,7 +71,7 @@ $ nix run github:notashelf/nvf#nix test.nix
```
This command will start Neovim with some opinionated plugin configurations, and
is designed specifically for Nix. the `nix` configuration lets you see how a
is designed specifically for Nix. The `nix` configuration lets you see how a
fully configured Neovim setup _might_ look like without downloading too many
packages or shell utilities.
@ -87,12 +97,16 @@ companion or fun plugins.
## Installing nvf {#ch-installation}
<!-- markdownlint-disable MD051 -->
[module installation section]: #ch-module-installation
There are multiple ways of installing nvf on your system. You may either choose
the standalone installation method, which does not depend on a module system and
may be done on any system that has the Nix package manager or the appropriate
modules for NixOS and home-manager as described in the
<!-- markdownlint-enable MD051 -->
There are multiple ways of installing **nvf** on your system. You may either
choose the standalone installation method, which does not depend on a module
system and may be done on any system that has the Nix package manager or the
appropriate modules for NixOS and Home Manager as described in the
[module installation section].
```{=include=}

7
docs/manual/installation/modules/flakes.md
View file

@ -1,7 +1,7 @@
### Prerequisites {#sec-flakes-prerequisites}
#### Prerequisites {#sec-flakes-prerequisites}
To install nvf with flakes, you must make sure the following requirements are
met.
To install **nvf** with flakes, you must make sure the following requirements
are met.
1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later
version of Nix from nixpkgs.
@ -29,5 +29,6 @@ met.
following additional flags to `nix` and `home-manager`:
```sh
# Temporarily enables "nix-command" and "flakes" experimental features.
$ nix --extra-experimental-features "nix-command flakes" <sub-commands>
```

6
docs/manual/installation/modules/home-manager.md
View file

@ -1,7 +1,7 @@
# Home-Manager Module {#ch-hm-module}
## Home Manager Module {#ch-hm-module}
The home-manager module allows us to customize the different `vim` options from
inside the home-manager configuration without having to call for the wrapper
The Home Manager module allows us to customize the different `vim` options from
inside the Home Manager configuration without having to call for the wrapper
yourself. It is the recommended way to use **nvf** alongside the NixOS module
depending on your needs.

4
docs/manual/installation/modules/nixos.md
View file

@ -1,11 +1,11 @@
# NixOS Module {#ch-nixos-module}
## NixOS Module {#ch-nixos-module}
The NixOS module allows us to customize the different `vim` options from inside
the NixOS configuration without having to call for the wrapper yourself. It is
the recommended way to use **nvf** alongside the home-manager module depending
on your needs.
## With Flakes {#sec-nixos-flakes}
### With Flakes {#sec-nixos-flakes}
```{=include=}
flakes.md

2
docs/manual/installation/standalone/home-manager.md
View file

@ -1,4 +1,4 @@
# Standalone Installation on Home-Manager {#ch-standalone-hm}
## Standalone Installation on Home-Manager {#ch-standalone-hm}
Your built Neovim configuration can be exposed as a flake output to make it
easier to share across machines, repositories and so on. Or it can be added to

2
docs/manual/installation/standalone/nixos.md
View file

@ -1,4 +1,4 @@
# Standalone Installation on NixOS {#ch-standalone-nixos}
## Standalone Installation on NixOS {#ch-standalone-nixos}
Your built Neovim configuration can be exposed as a flake output to make it
easier to share across machines, repositories and so on. Or it can be added to

35
docs/manual/quirks.md
View file

@ -5,30 +5,9 @@ be it a result of generating Lua from Nix, or the state of packaging. This page,
in turn, will list any known modules or plugins that are known to misbehave, and
possible workarounds that you may apply.
## NodeJS {#ch-quirks-nodejs}
### eslint-plugin-prettier {#sec-eslint-plugin-prettier}
When working with NodeJS, everything works as expected, but some projects have
settings that can fool nvf.
If [this plugin](https://github.com/prettier/eslint-plugin-prettier) or similar
is included, you might get a situation where your eslint configuration diagnoses
your formatting according to its own config (usually `.eslintrc.js`).
The issue there is your formatting is made via prettierd.
This results in auto-formatting relying on your prettier config, while your
eslint config diagnoses formatting
[which it's not supposed to](https://prettier.io/docs/en/comparison.html))
In the end, you get discrepancies between what your editor does and what it
wants.
Solutions are:
1. Don't add a formatting config to eslint, and separate prettier and eslint.
2. PR this repo to add an ESLint formatter and configure nvf to use it.
```{=include=}
quirks/nodejs.md
```
## Bugs & Suggestions {#ch-bugs-suggestions}
@ -36,10 +15,10 @@ Solutions are:
[discussions tab]: https://github.com/notashelf/nvf/discussions
[pull requests tab]: https://github.com/notashelf/nvf/pulls
Some quirks are not exactly quirks, but bugs in the module systeme. If you
notice any issues with nvf, or this documentation, then please consider
reporting them over at the [issue tracker]. Issues tab, in addition to the
Some quirks are not exactly quirks, but bugs in the module system. If you notice
any issues with **nvf**, or this documentation, then please consider reporting
them over at the [issue tracker]. Issues tab, in addition to the
[discussions tab] is a good place as any to request new features.
You may also consider submitting bugfixes, feature additions and upstreamed
You may also consider submitting bug fixes, feature additions and upstreamed
changes that you think are critical over at the [pull requests tab].

29
docs/manual/quirks/nodejs.md Normal file
View file

@ -0,0 +1,29 @@
## NodeJS {#ch-quirks-nodejs}
### eslint-plugin-prettier {#sec-eslint-plugin-prettier}
[eslint-plugin-prettier]: https://github.com/prettier/eslint-plugin-prettier
[not supposed to]: https://prettier.io/docs/en/comparison.html
When working with NodeJS, which is _obviously_ known for its meticulous
standards, most things are bound to work as expected but some projects, tools
and settings may fool the default configurations of tools provided by **nvf**.
If
If [eslint-plugin-prettier] or similar is included, you might get a situation
where your Eslint configuration diagnoses your formatting according to its own
config (usually `.eslintrc.js`). The issue there is your formatting is made via
prettierd.
This results in auto-formatting relying on your prettier configuration, while
your Eslint configuration diagnoses formatting "issues" while it's
[not supposed to]. In the end, you get discrepancies between what your editor
does and what it wants.
Solutions are:
1. Don't add a formatting config to Eslint, instead separate Prettier and
Eslint.
2. PR the repo in question to add an ESLint formatter, and configure **nvf** to
use it.

6
docs/manual/release-notes/rl-0.8.md
View file

@ -621,9 +621,3 @@
[JudahZF](https://github.com/JudahZF):
- Added gitFiles mapping option to telescope
[Ring-A-Ding-Ding-Baby](https://github.com/Ring-A-Ding-Ding-Baby)
- Aligned `codelldb` adapter setup with [rustaceanvim]’s built-in logic.
- Added `languages.rust.dap.backend` option to choose between `codelldb` and
`lldb-dap` adapters.

9
docs/manual/release-notes/rl-0.9.md Normal file
View file

@ -0,0 +1,9 @@
# Release 0.5 {#sec-release-0-9}
## Changelog {#sec-release-0-9-changelog}
[Ring-A-Ding-Ding-Baby](https://github.com/Ring-A-Ding-Ding-Baby):
- Aligned `codelldb` adapter setup with [rustaceanvim]’s built-in logic.
- Added `languages.rust.dap.backend` option to choose between `codelldb` and
`lldb-dap` adapters.

19
flake.nix
View file

@ -57,7 +57,7 @@
perSystem = {pkgs, ...}: {
# Provides the default formatter for 'nix fmt', which will format the
# entire tree with Alejandra. The wrapper script is necessary due to
# entire Nix source with Alejandra. The wrapper script is necessary due to
# changes to the behaviour of Nix, which now encourages wrappers for
# tree-wide formatting.
formatter = pkgs.writeShellApplication {
@ -66,11 +66,17 @@
runtimeInputs = [
pkgs.alejandra
pkgs.fd
pkgs.deno
];
text = ''
# Find Nix files in the tree and format them with Alejandra
echo "Formatting Nix files"
fd "$@" -t f -e nix -x alejandra -q '{}'
# Same for Markdown files, but with deno
echo "Formatting Markdown files"
fd "$@" -t f -e md -x deno fmt -q '{}'
'';
};
@ -81,7 +87,16 @@
# This can be initiated with `nix build .#checks.<system>.nix-fmt`
# or with `nix flake check`
nix-fmt = pkgs.runCommand "nix-fmt-check" {nativeBuildInputs = [pkgs.alejandra];} ''
alejandra --check ${self} < /dev/null | tee $out
alejandra --check ${self} < /dev/null
touch $out
'';
# Check if Markdown sources are properly formatted
# This can be initiated with `nix build .#checks.<system>.md-fmt`
# or with `nix flake check`
md-fmt = pkgs.runCommand "md-fmt-check" {nativeBuildInputs = [pkgs.deno];} ''
deno fmt --check ${self} --ext md
touch $out
'';
};
};

34
flake/develop.nix
View file

@ -1,15 +1,23 @@
{lib, ...}: {
perSystem = {
pkgs,
config,
self',
...
}: {
perSystem = {pkgs, ...}: {
# The default dev shell provides packages required to interact with
# the codebase as described by the contributing guidelines. It includes the
# formatters required, and a few additional goodies for linting work.
devShells = {
default = self'.devShells.lsp;
nvim-nix = pkgs.mkShellNoCC {packages = [config.packages.nix];};
lsp = pkgs.mkShellNoCC {
packages = with pkgs; [nil statix deadnix alejandra npins];
default = pkgs.mkShellNoCC {
packages = with pkgs; [
# Nix tooling
nil # LSP
statix # static checker
deadnix # dead code finder
# So that we can interact with plugin sources
npins
# Formatters
alejandra
deno
];
};
};
@ -18,7 +26,11 @@
# testing, but make sure to discard the changes before creating a pull
# request.
packages.dev = let
configuration = {};
configuration = {
# This is essentially the configuration that will be passed to the
# builder function. For example:
# vim.languages.nix.enable = true;
};
customNeovim = lib.nvim.neovimConfiguration {
inherit pkgs;