NotAShelf/nvf
2
1
Fork 0
mirror of https://github.com/NotAShelf/nvf.git synced 2026-02-05 11:25:52 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge branch 'main' into main

Browse source
This commit is contained in:
raf 2026-01-10 23:41:33 +03:00 • committed by GitHub
commit 7267cf3570
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
40 changed files with 1044 additions and 591 deletions
Download patch file Download diff file Expand all files Collapse all files

4
.github/PULL_REQUEST_TEMPLATE.md vendored
View file

@ -24,8 +24,8 @@ it above in your description.
--> -->
[editorconfig]: https://editorconfig.org [editorconfig]: https://editorconfig.org
[changelog]: https://github.com/NotAShelf/nvf/tree/main/docs/release-notes [changelog]: https://github.com/NotAShelf/nvf/tree/main/docs/manual/release-notes
[hacking nvf]: https://notashelf.github.io/nvf/index.xhtml#sec-guidelines [hacking nvf]: https://nvf.notashelf.dev/hacking.html#sec-guidelines
- [ ] I have updated the [changelog] as per my changes - [ ] I have updated the [changelog] as per my changes
- [ ] I have tested, and self-reviewed my code - [ ] I have tested, and self-reviewed my code

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

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

4
.github/workflows/docs-preview.yml vendored
View file

@ -3,7 +3,7 @@ name: Build and Preview Manual
on: on:
workflow_dispatch: workflow_dispatch:
pull_request_target: pull_request_target:
types: [opened, synchronize, reopened, closed] types: [opened, synchronize, reopened, labeled, unlabeled, edited]
paths: paths:
- ".github/workflows/docs-preview.yml" - ".github/workflows/docs-preview.yml"
- "modules/**" - "modules/**"
@ -73,7 +73,7 @@ jobs:
id: prelude id: prelude
run: | run: |
PR_NUMBER=${{ github.event.pull_request.number }} PR_NUMBER=${{ github.event.pull_request.number }}
URL="https://${{ github.repository_owner }}.github.io/nvf/docs-preview-${PR_NUMBER}/" URL="https:///nvf.notashelf.dev/docs-preview-${PR_NUMBER}/"
# Propagate non-interpolatable environment vars # Propagate non-interpolatable environment vars
echo "URL=$URL" >> "$GITHUB_OUTPUT" echo "URL=$URL" >> "$GITHUB_OUTPUT"

1
.github/workflows/manual.yml vendored
View file

@ -59,3 +59,4 @@ jobs:
with: with:
github_token: ${{ secrets.GITHUB_TOKEN }} github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public publish_dir: ./public
cname: nvf.notashelf.dev

6
README.md
View file

@ -65,9 +65,9 @@
## Features ## Features
[standalone]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-installation [standalone]: https://nvf.notashelf.dev/#ch-standalone-installation
[NixOS module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-nixos [NixOS module]: https://nvf.notashelf.dev/#ch-standalone-nixos
[Home-Manager module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-hm [Home-Manager module]: https://nvf.notashelf.dev/#ch-standalone-hm
[release notes]: https://notashelf.github.io/nvf/release-notes.html [release notes]: https://notashelf.github.io/nvf/release-notes.html
[discussions tab]: https://github.com/notashelf/nvf/discussions [discussions tab]: https://github.com/notashelf/nvf/discussions
[FAQ section]: #frequently-asked-questions [FAQ section]: #frequently-asked-questions

1
configuration.nix
View file

@ -214,7 +214,6 @@ isMaximal: {
}; };
notes = { notes = {
obsidian.enable = false; # FIXME: neovim fails to build if obsidian is enabled
neorg.enable = false; neorg.enable = false;
orgmode.enable = false; orgmode.enable = false;
mind-nvim.enable = isMaximal; mind-nvim.enable = isMaximal;

9
docs/manual/configuring.md
View file

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

614
docs/manual/hacking.md
View file

@ -3,12 +3,13 @@
[open issues]: https://github.com/notashelf/nvf/issues [open issues]: https://github.com/notashelf/nvf/issues
[new issue]: https://github.com/notashelf/nvf/issues/new [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 **nvf** is designed for the developer as much as it is designed for the
would like for any contributor to be able to propagate their changes, or add new end-user. We would like for any contributor to be able to propagate their
features to the project with minimum possible friction. As such, below are the changes, or add new features to the project with minimum possible friction. As
guides and guidelines written to streamline the contribution process and to such, below are the guides and guidelines written to streamline the contribution
ensure that your valuable input integrates into nvf's development as seamlessly process and to ensure that your valuable input integrates into **nvf**'s
as possible without leaving any question marks in your head. 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 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 the project. If you instead wish to report a bug, or discuss a potential new
@ -23,24 +24,52 @@ please do not be afraid to submit a pull request, we will help you get it in.
## Getting Started {#sec-contrib-getting-started} ## Getting Started {#sec-contrib-getting-started}
You, naturally, would like to start by forking the repository to get started. If [Fork a repo guide]: https://help.github.com/articles/fork-a-repo/
you are new to Git and GitHub, do have a look at GitHub's [Contributing Guidelines]: #sec-guidelines
[Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for [Create a Pull Request]: https://help.github.com/articles/creating-a-pull-request
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 To contribute to **nvf**, you'll first want to fork the repository. If you are
branch a reasonably descriptive name (e.g. `feature/debugger` or new to Git and GitHub, do have a look at GitHub's [Fork a repo guide] for
`fix/pesky-bug`) and you are ready to work on your changes 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 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 are happy with the result, and positive that it fulfills our
[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and [Contributing Guidelines], push the branch to GitHub and [Create a Pull Request]
[create a pull request](https://help.github.com/articles/creating-a-pull-request).
The default pull request template available on the **nvf** repository will guide 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 you through the rest of the process, and we'll gently nudge you in the correct
direction if there are any mistakes. 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", or rather, the back-and-forth 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 introduces a
> significant overhead to the communication process.
## Guidelines {#sec-guidelines} ## Guidelines {#sec-guidelines}
[discussions tab]: https://github.com/NotAShelf/nvf/discussions
If your contribution tightly follows the guidelines, then there is a good chance 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 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 strictly enforced, others will remain as gentle nudges towards the correct
@ -48,34 +77,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 to double check your changes before making your pull request in order to avoid
"faulty" code slipping by. "faulty" code slipping by.
If you are uncertain how these rules affect the change you would like to make If you are not quite certain how those rules affect the change you are planning
then feel free to start a discussion in the to make, then please start a friendly discussion in the [discussions tab] before
[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not you begin developing. This is not a requirement, but it might answer some of
necessarily) before you start developing. 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 There are various files within the **nvf** repository. To maintain a sense of
must update the changelog. Both the manual and module options use consistency and to avoid clashing opinions on how formatters should behave, we
[Nixpkgs Flavoured Markdown]. are very opinionated on how those files should be formatted.
The HTML version of this manual containing both the module option descriptions - Nix files **must** be formatted with the Alejandra formatter, following some
and the documentation of **nvf** (such as this page) can be generated and opened specific tips found in [Nix style section](#nix-sec-code-style-nix).
by typing the following in a shell within a clone of the **nvf** Git repository: - Markdown files **must** be formatted with the `deno fmt` command, as described
in the [Markdown style section](#sec-code-style-markdown).
```console Make sure your code is formatted as described in [code style section] before
$ nix build .#docs-html your changes are submitted.
$ 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.
### Formatting Commits {#sec-guidelines-commit-message-style} ### Formatting Commits {#sec-guidelines-commit-message-style}
@ -98,27 +119,29 @@ The commit messages should follow the
component or module in the first line. A commit message ideally, but not component or module in the first line. A commit message ideally, but not
necessarily, follow the given template from home-manager's own documentation necessarily, follow the given template from home-manager's own documentation
``` ```gitcommit
{component}: {description} {component}: {description}
{long description} {long description}
``` ```
where `{component}` refers to the code component (or module) your change where `{component}` refers to the code component (or module) your change
affects, `{description}` is a very brief description of your change, and affects, `{description}` is a very brief description of your change, and
`{long description}` is an optional clarifying description. As a rare exception, `{long description}` is an optional clarifying description.
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
[example commit message](#sec-guidelines-ex-commit-message) for a commit message
that fulfills these requirements. 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} #### Example Commit {#sec-guidelines-ex-commit-message}
The commit [sample commit from Home Manager]: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef
[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef)
in home-manager contains the following commit message.
``` The [sample commit from Home Manager] contains the following commit message.
```gitcommit
starship: allow running in Emacs if vterm is used starship: allow running in Emacs if vterm is used
The vterm buffer is backed by libvterm and can handle Starship prompts The vterm buffer is backed by libvterm and can handle Starship prompts
@ -128,30 +151,63 @@ without issues.
Similarly, if you are contributing to **nvf**, you would include the scope of Similarly, if you are contributing to **nvf**, you would include the scope of
the commit followed by the description: the commit followed by the description:
``` ```gitcommit
languages/ruby: init module 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 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, 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 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 For new plugin additions, the following is a good starting point:
commit format `foo: add module`. You can, of course, still include a long
description if you wish.
In case of nested modules, i.e `modules/languages/java.nix` you are recommended ```gitcommit
to contain the parent as well - for example `languages/java: some major change`. 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} ### Code Style {#sec-guidelines-code-style}
#### Treewide {#sec-code-style-treewide} #### Treewide {#sec-code-style-treewide}
Keep lines at a reasonable width, ideally 80 characters or less. This also Across the tree, you're encouraged to follow kebab-case for file names, and keep
applies to string literals and module descriptions and documentation. 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} #### Nix {#sec-code-style-nix}
@ -165,12 +221,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 certain changes are done at the user's discretion based on how the original code
was structured. was structured.
##### Attribute Sets
Please use one line code for attribute sets that contain only one subset. For Please use one line code for attribute sets that contain only one subset. For
example: example:
<!-- markdownlint-disable MD013 -->
```nix ```nix
# parent modules should always be unfolded # Parent modules should always be unfolded.
# which means module = { value = ... } instead of module.value = { ... } # which means `module = { value = ... }` instead of `module.value = { ... }`.
module = { module = {
value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible
@ -190,23 +250,45 @@ module = {
} }
``` ```
<!-- markdownlint-enable MD013 -->
If you move a line down after the merge operator, Alejandra will automatically 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 ```nix
module = { module = {
# This is wrong!
key = mkEnableOption "some description" // { key = mkEnableOption "some description" // {
default = true; # we want this to be inline 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, 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 but please try to unfold lists if they contain multiple items and especially if
they are to include comments. they are to include comments.
```nix ```nix
# this is ok # This is ok
acceptableList = [ acceptableList = [
item1 # comment item1 # comment
item2 item2
@ -214,14 +296,14 @@ acceptableList = [
item4 item4
]; ];
# this is not ok # This is *not* ok
listToBeAvoided = [item1 item2 /* comment */ item3 item4]; listToBeAvoided = [item1 item2 /* comment */ item3 item4];
# this is ok # This is ok
acceptableList = [item1 item2]; acceptableList = [item1 item2];
# this is also ok if the list is expected to contain more elements # This is also ok if the list is expected to contain more elements
acceptableList= [ acceptableList = [
item1 item1
item2 item2
# more items if needed... # more items if needed...
@ -230,129 +312,161 @@ acceptableList= [
## Testing Changes {#sec-testing-changes} ## Testing Changes {#sec-testing-changes}
Once you have made your changes, you will need to test them thoroughly. If it is Once you have made your changes, you will need to test them thoroughly. To make
a module, add your module option to `configuration.nix` (located in the root of testing easier you may either use the `configuration.nix` located in the
this project) inside `neovimConfiguration`. Enable it, and then run the maximal repository root, or use the development package located in `flake/develop.nix`.
configuration with `nix run .#maximal -Lv` to check for build errors. If neovim The development package allows you to quickly bootstrap a Neovim configuration
opens in the current directory without any error messages (you can check the with only the required modules, instead of the packages that consume the
output of `:messages` inside neovim to see if there are any errors), then your `configuration.nix`, so it is generally preferable. To use it navigate to the
changes are good to go. Open your pull request, and it will be reviewed as soon `develop.nix` module, and update the `configuration` set with the Neovim
as possible. configuration that you would like to test with. For example:
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:
```nix ```nix
{ {
vim.keymaps = [ # Let's assume you are adding a new module for the Nix language.
{ # You will need to enable it here
key = "<leader>wq"; configuration = {
mode = ["n"]; vim.languages.nix.enable = true;
action = ":wq<CR>";
silent = true;
desc = "Save file and quit";
}
];
}
```
There are many settings available in the options. Please refer to the # You can also enable other plugins that you wish to test with, for example
[documentation](./options.html#option-vim-keymaps) to see a list of them. # none-ls:
vim.lsp.null-ls = {
**nvf** provides a helper function, so that you don't have to write the mapping enable = true;
attribute sets every time: setupOpts = { /* Your setup options here */ };
- `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";
}; };
}
```
```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] You may then run this package with `nix run .#develop` and check for build or
> If you have come across a plugin that has an API that doesn't seem to easily runtime errors. If Neovim builds and opens without any errors, then your changes
> allow custom keybindings, don't be scared to implement a draft PR. We'll help are good to go. Open your pull request, and it will be reviewed as soon as
> you get it done. 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/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} ## Adding Plugins {#sec-additional-plugins}
There are two methods for adding new Neovim plugins to **nvf**. npins is the **nvf** generally tries to avoid using Neovim plugins from Nixpkgs, and thus
faster option that should be preferred if the plugin consists of pure Lua or uses one of the two alternative methods where applicable. npins is the faster
Vimscript code. In which case there is no building required, and we can easily option that should be preferred if the plugin consists of pure Lua or Vimscript
handle the copying of plugin files. Alternative method, which is required when code. In which case there is no building required, and we can easily handle the
plugins try to build their own libraries (e.g., in Rust or C) that need to be copying of plugin files. Alternative method, which is required when plugins try
built with Nix to function correctly. 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} ### With npins {#sec-npins-for-plugins}
npins is the standard method of adding new plugins to **nvf**. You simply need npins is the standard, and as described above, the _faster_ method of adding new
the repository URL for the plugin, and can add it as a source to be built plugins to **nvf**. You simply need the repository URL for the plugin, and you
automatically with one command. To add a new Neovim plugin, use `npins`. For can add it as a source to be built automatically with just one command. To add a
example: new Neovim plugin, use `npins`. For example:
```bash ```bash
nix-shell -p npins # or nix shell nixpkgs#npins if using flakes nix-shell -p npins # or nix shell nixpkgs#npins if using flakes
@ -364,16 +478,13 @@ Then run:
npins add --name <plugin name> github <owner> <repo> -b <branch> npins add --name <plugin name> github <owner> <repo> -b <branch>
``` ```
::: {.note} > [!NOTE]
> Be sure to replace any non-alphanumeric characters with `-` for `--name`. For
Be sure to replace any non-alphanumeric characters with `-` for `--name`. For > example
example >
> ```bash
```bash > npins add --name lazydev-nvim github folke lazydev.nvim -b main
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 Once the `npins` command is done, you can start referencing the plugin as a
**string**. **string**.
@ -399,15 +510,21 @@ We use `buildRustPackage` to build the library from the repository root, and
copy everything in the `postInstall` phase. copy everything in the `postInstall` phase.
```nix ```nix
postInstall = '' {
cp -r {lua,plugin} "$out" # ...
mkdir -p "$out/doc" postInstall = ''
cp 'doc/'*'.txt' "$out/doc/" cp -r {lua,plugin} "$out"
mkdir -p "$out/target" mkdir -p "$out/doc"
mv "$out/lib" "$out/target/release" 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 In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs
@ -429,7 +546,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({...})`. Most plugins is initialized with a call to `require('plugin').setup({...})`.
@ -503,7 +620,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 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: `cfg.setupOpts`, into a lua table. Here are some rules of the conversion:
@ -544,7 +661,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. If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it.
Lazy plugins are managed by `lz.n`. Lazy plugins are managed by `lz.n`.
@ -604,3 +721,104 @@ require('lz.n').load({
A full list of options can be found in the [`vim.lazy.plugins` spec] on the A full list of options can be found in the [`vim.lazy.plugins` spec] on the
rendered manual. 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} # Introduction {#nvf-manual}
Version @NVF_VERSION@ Generated for nvf @NVF_VERSION@
## Preface {#ch-preface} ## Preface {#ch-preface}
### What is nvf {#sec-what-is-it} ### What is nvf {#sec-what-is-it}
**nvf** is a highly modular, configurable, extensible and easy to use Neovim [Nix]: https://nixos.org
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.
## 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 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 different configurations provided by this flake. As of v0.5, two specialized
configurations are provided: 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. on a system where Nix is installed.
```sh ```sh
# Add the nvf cache
$ cachix use nvf # Optional: it'll save you CPU resources and time $ 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 $ 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 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. 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 ```bash
$ nix run github:notashelf/nvf#nix $ nix run github:notashelf/nvf#nix
$ nix run github:notashelf/nvf#maximal $ nix run github:notashelf/nvf#maximal
``` ```
<!-- markdownlint-enable MD014 -->
### Available Configurations {#sec-available-configs} ### Available Configurations {#sec-available-configs}
> [!NOTE] > [!NOTE]
@ -61,7 +71,7 @@ $ nix run github:notashelf/nvf#nix test.nix
``` ```
This command will start Neovim with some opinionated plugin configurations, and 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 fully configured Neovim setup _might_ look like without downloading too many
packages or shell utilities. packages or shell utilities.
@ -87,12 +97,16 @@ companion or fun plugins.
## Installing nvf {#ch-installation} ## Installing nvf {#ch-installation}
<!-- markdownlint-disable MD051 -->
[module installation section]: #ch-module-installation [module installation section]: #ch-module-installation
There are multiple ways of installing nvf on your system. You may either choose <!-- markdownlint-enable MD051 -->
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 There are multiple ways of installing **nvf** on your system. You may either
modules for NixOS and home-manager as described in the 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]. [module installation section].
```{=include=} ```{=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 To install **nvf** with flakes, you must make sure the following requirements
met. are met.
1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later 1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later
version of Nix from nixpkgs. version of Nix from nixpkgs.
@ -29,5 +29,6 @@ met.
following additional flags to `nix` and `home-manager`: following additional flags to `nix` and `home-manager`:
```sh ```sh
# Temporarily enables "nix-command" and "flakes" experimental features.
$ nix --extra-experimental-features "nix-command flakes" <sub-commands> $ nix --extra-experimental-features "nix-command flakes" <sub-commands>
``` ```

19
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 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 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 yourself. It is the recommended way to use **nvf** alongside the NixOS module
depending on your needs. depending on your needs.
@ -19,20 +19,13 @@ To use **nvf** with flakes, we first need to add the input to our `flake.nix`.
# flake.nix # flake.nix
{ {
inputs = { inputs = {
# Optional, if you intend to follow nvf's obsidian-nvim input # nvf works best with and only directly supports flakes
# you must also add it as a flake input.
obsidian-nvim.url = "github:epwalsh/obsidian.nvim";
# Required, nvf works best and only directly supports flakes
nvf = { nvf = {
url = "github:NotAShelf/nvf"; url = "github:NotAShelf/nvf";
# You can override the input nixpkgs to follow your system's # You can override the input nixpkgs to follow your system's
# instance of nixpkgs. This is safe to do as nvf does not depend # instance of nixpkgs. This is safe to do as nvf does not depend
# on a binary cache. # on a binary cache.
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
# Optionally, you can also override individual plugins
# for example:
inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs
}; };
# ... # ...
@ -44,8 +37,8 @@ Followed by importing the home-manager module somewhere in your configuration.
```nix ```nix
{ {
# Assuming "nvf" is in your inputs and inputs is in the argument set. # Assuming nvf is in your inputs and inputs is in the argument set.
# See example installation below # See example installation below.
imports = [ inputs.nvf.homeManagerModules.default ]; imports = [ inputs.nvf.homeManagerModules.default ];
} }
``` ```

18
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 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 NixOS configuration without having to call for the wrapper yourself. It is
the recommended way to use **nvf** alongside the home-manager module depending the recommended way to use **nvf** alongside the home-manager module depending
on your needs. on your needs.
## With Flakes {#sec-nixos-flakes} ### With Flakes {#sec-nixos-flakes}
```{=include=} ```{=include=}
flakes.md flakes.md
@ -19,20 +19,13 @@ To use **nvf** with flakes, we first need to add the input to our `flake.nix`.
# flake.nix # flake.nix
{ {
inputs = { inputs = {
# Optional, if you intend to follow nvf's obsidian-nvim input # nvf works best with and only directly supports flakes
# you must also add it as a flake input.
obsidian-nvim.url = "github:epwalsh/obsidian.nvim";
# Required, nvf works best and only directly supports flakes
nvf = { nvf = {
url = "github:NotAShelf/nvf"; url = "github:NotAShelf/nvf";
# You can override the input nixpkgs to follow your system's # You can override the input nixpkgs to follow your system's
# instance of nixpkgs. This is safe to do as nvf does not depend # instance of nixpkgs. This is safe to do as nvf does not depend
# on a binary cache. # on a binary cache.
inputs.nixpkgs.follows = "nixpkgs"; inputs.nixpkgs.follows = "nixpkgs";
# Optionally, you can also override individual plugins
# for example:
inputs.obsidian-nvim.follows = "obsidian-nvim"; # <- this will use the obsidian-nvim from your inputs
}; };
# ... # ...
@ -44,8 +37,8 @@ Followed by importing the NixOS module somewhere in your configuration.
```nix ```nix
{ {
# assuming nvf is in your inputs and inputs is in the argset # Assuming nvf is in your inputs and inputs is in the argument set.
# see example below # See example below.
imports = [ inputs.nvf.nixosModules.default ]; imports = [ inputs.nvf.nixosModules.default ];
} }
``` ```
@ -79,7 +72,6 @@ configure **nvf**.
{ {
programs.nvf = { programs.nvf = {
enable = true; enable = true;
# Your settings need to go into the settings attribute set # Your settings need to go into the settings attribute set
# most settings are documented in the appendix # most settings are documented in the appendix
settings = { settings = {

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 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 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 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 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 in turn, will list any known modules or plugins that are known to misbehave, and
possible workarounds that you may apply. possible workarounds that you may apply.
## NodeJS {#ch-quirks-nodejs} ```{=include=}
quirks/nodejs.md
### 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.
## Bugs & Suggestions {#ch-bugs-suggestions} ## Bugs & Suggestions {#ch-bugs-suggestions}
@ -36,10 +15,10 @@ Solutions are:
[discussions tab]: https://github.com/notashelf/nvf/discussions [discussions tab]: https://github.com/notashelf/nvf/discussions
[pull requests tab]: https://github.com/notashelf/nvf/pulls [pull requests tab]: https://github.com/notashelf/nvf/pulls
Some quirks are not exactly quirks, but bugs in the module systeme. If you Some quirks are not exactly quirks, but bugs in the module system. If you notice
notice any issues with nvf, or this documentation, then please consider any issues with **nvf**, or this documentation, then please consider reporting
reporting them over at the [issue tracker]. Issues tab, in addition to the them over at the [issue tracker]. Issues tab, in addition to the
[discussions tab] is a good place as any to request new features. [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]. 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): [JudahZF](https://github.com/JudahZF):
- Added gitFiles mapping option to telescope - 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.

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

@ -1,8 +1,126 @@
# Release 0.9 {#sec-release-0-9} # Release 0.9 {#sec-release-0-9}
## Breaking changes
- Nixpkgs has merged a fully incompatible rewrite of
`vimPlugins.nvim-treesitter`. Namely, it changes from the frozen `master`
branch to the new main branch. This change removes incremental selections, so
it is no longer available.
- [obsidian.nvim] now uses a maintained fork which has removed the `dir`
setting. Use `workspaces` instead:
```nix
{
workspaces = [
{
name = "any-string";
path = "~/old/dir/path/value";
}
];
}
```
Some other settings and commands are now deprecated but are still supported.
- The `setupOpts.mappings` options were also removed. Use the built-in
Neovim settings (nvf's {option}`vim.keymaps`)
## Changelog {#sec-release-0-9-changelog} ## Changelog {#sec-release-0-9-changelog}
[taylrfnt](https://github.com/taylrfnt)
- Introduce a `darwinModule` option for Darwin users. The ergonomics of
importing a `nixosModule` into a Darwin flake were less than ideal, and when
users fork and update npins, they are prone to encountering errors like the
following:
```shell
(class: "nixos") cannot be imported into a module
evaluation that expects class "darwin".
```
[suimong](https://github.com/suimong): [suimong](https://github.com/suimong):
- Fix `vim.tabline.nvimBufferline` where `setupOpts.options.hover` requires `vim.opt.mousemoveevent` to be set. - Fix `vim.tabline.nvimBufferline` where `setupOpts.options.hover` requires
`vim.opt.mousemoveevent` to be set.
[thamenato](https://github.com/thamenato):
- Attempt to adapt nvim-treesitter to (breaking) Nixpkgs changes. Some
treesitter grammars were changed to prefer `grammarPlugins` over
`builtGrammars`.
[jfeo](https://github.com/jfeo):
[ccc.nvim]: https://github.com/uga-rosa/ccc.nvim
- Added [ccc.nvim] option {option}`vim.utility.ccc.setupOpts` with the existing
hard-coded options as default values.
[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.
[Libadoxon](https://github.com/Libadoxon):
- `toggleterm` open map now also works when in terminal mode
[jtliang24](https://github.com/jtliang24):
- Updated nix language plugin to use pkgs.nixfmt instead of pkgs.nixfmt-rfc-style
[alfarel](https://github.com/alfarelcynthesis):
[obsidian.nvim]: https://github.com/obsidian-nvim/obsidian.nvim
[blink.cmp]: https://cmp.saghen.dev/
[snacks.nvim]: https://github.com/folke/snacks.nvim
[mini.nvim]: https://nvim-mini.org/mini.nvim/
[telescope.nvim]: https://github.com/nvim-telescope/telescope.nvim
[fzf-lua]: https://github.com/ibhagwan/fzf-lua
[render-markdown.nvim]: https://github.com/MeanderingProgrammer/render-markdown.nvim
[markview.nvim]: https://github.com/OXY2DEV/markview.nvim
[which-key.nvim]: https://github.com/folke/which-key.nvim
- Upgrade [obsidian.nvim] to use a maintained fork, instead of the unmaintained
upstream.
- Various upstream improvements:
- Support [blink.cmp] and completion plugin autodetection.
- Support various pickers for prompts, including [snacks.nvim]'s
`snacks.picker`, [mini.nvim]'s `mini.pick`, [telescope.nvim], and
[fzf-lua].
- Merge commands like `ObsidianBacklinks` into `Obisidian backlinks`. The
old format is still supported by default.
- Some `setupOpts` options have changed:
- `disable_frontmatter` -> `frontmatter.enabled` (and inverted), still
supported.
- `note_frontmatter_func` -> `frontmatter.func`, still supported.
- `statusline` module is now deprecated in favour of `footer`, still
supported.
- `dir` is no longer supported, use `workspaces`:
```nix
{
workspaces = [
{
name = "any-string";
path = "~/old/dir/path/value";
}
];
}
```
- `use_advanced_uri` -> `open.use_advanced_uri`.
- Mappings are now expected to be set using the built-in Neovim APIs,
managed by `vim.keymaps` in nvf, instead of `mappings` options.
- Some option defaults have changed.
- And more.
- Automatically configure an enabled picker in the order mentioned above, if
any are enabled.
- Add integration with `snacks.image` for rendering workspace/vault assets.
- Detect if [render-markdown.nvim] or [markview.nvim] are enabled and disable
the `ui` module if so. It should work without this, but `render-markdown`'s
{command}`:healthcheck` doesn't know that.
- Remove [which-key.nvim] `<leader>o` `+Notes` description which did not
actually correspond to any keybinds.

28
flake.lock generated
View file

@ -53,7 +53,9 @@
}, },
"ndg": { "ndg": {
"inputs": { "inputs": {
"nixpkgs": "nixpkgs" "nixpkgs": [
"nixpkgs"
]
}, },
"locked": { "locked": {
"lastModified": 1765720983, "lastModified": 1765720983,
@ -71,27 +73,11 @@
}, },
"nixpkgs": { "nixpkgs": {
"locked": { "locked": {
"lastModified": 1764242076, "lastModified": 1767364772,
"narHash": "sha256-sKoIWfnijJ0+9e4wRvIgm/HgE27bzwQxcEmo2J/gNpI=", "narHash": "sha256-fFUnEYMla8b7UKjijLnMe+oVFOz6HjijGGNS1l7dYaQ=",
"owner": "NixOS",
"repo": "nixpkgs",
"rev": "2fad6eac6077f03fe109c4d4eb171cf96791faa4",
"type": "github"
},
"original": {
"owner": "NixOS",
"ref": "nixos-unstable",
"repo": "nixpkgs",
"type": "github"
}
},
"nixpkgs_2": {
"locked": {
"lastModified": 1764081664,
"narHash": "sha256-sUoHmPr/EwXzRMpv1u/kH+dXuvJEyyF2Q7muE+t0EU4=",
"owner": "nixos", "owner": "nixos",
"repo": "nixpkgs", "repo": "nixpkgs",
"rev": "dc205f7b4fdb04c8b7877b43edb7b73be7730081", "rev": "16c7794d0a28b5a37904d55bcca36003b9109aaa",
"type": "github" "type": "github"
}, },
"original": { "original": {
@ -107,7 +93,7 @@
"flake-parts": "flake-parts", "flake-parts": "flake-parts",
"mnw": "mnw", "mnw": "mnw",
"ndg": "ndg", "ndg": "ndg",
"nixpkgs": "nixpkgs_2", "nixpkgs": "nixpkgs",
"systems": "systems" "systems": "systems"
} }
}, },

29
flake.nix
View file

@ -53,11 +53,16 @@
'' ''
self.nixosModules.nvf; self.nixosModules.nvf;
}; };
darwinModules = {
nvf = import ./flake/modules/nixos.nix {inherit lib inputs;};
default = self.darwinModules.nvf;
};
}; };
perSystem = {pkgs, ...}: { perSystem = {pkgs, ...}: {
# Provides the default formatter for 'nix fmt', which will format the # 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 # changes to the behaviour of Nix, which now encourages wrappers for
# tree-wide formatting. # tree-wide formatting.
formatter = pkgs.writeShellApplication { formatter = pkgs.writeShellApplication {
@ -66,11 +71,17 @@
runtimeInputs = [ runtimeInputs = [
pkgs.alejandra pkgs.alejandra
pkgs.fd pkgs.fd
pkgs.deno
]; ];
text = '' text = ''
# Find Nix files in the tree and format them with Alejandra # Find Nix files in the tree and format them with Alejandra
echo "Formatting Nix files"
fd "$@" -t f -e nix -x alejandra -q '{}' 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 +92,16 @@
# This can be initiated with `nix build .#checks.<system>.nix-fmt` # This can be initiated with `nix build .#checks.<system>.nix-fmt`
# or with `nix flake check` # or with `nix flake check`
nix-fmt = pkgs.runCommand "nix-fmt-check" {nativeBuildInputs = [pkgs.alejandra];} '' 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
''; '';
}; };
}; };
@ -107,6 +127,9 @@
mnw.url = "github:Gerg-L/mnw"; mnw.url = "github:Gerg-L/mnw";
# Alternative documentation generator # Alternative documentation generator
ndg.url = "github:feel-co/ndg"; ndg = {
url = "github:feel-co/ndg";
inputs.nixpkgs.follows = "nixpkgs";
};
}; };
} }

34
flake/develop.nix
View file

@ -1,15 +1,23 @@
{lib, ...}: { {lib, ...}: {
perSystem = { perSystem = {pkgs, ...}: {
pkgs, # The default dev shell provides packages required to interact with
config, # the codebase as described by the contributing guidelines. It includes the
self', # formatters required, and a few additional goodies for linting work.
...
}: {
devShells = { devShells = {
default = self'.devShells.lsp; default = pkgs.mkShellNoCC {
nvim-nix = pkgs.mkShellNoCC {packages = [config.packages.nix];}; packages = with pkgs; [
lsp = pkgs.mkShellNoCC { # Nix tooling
packages = with pkgs; [nil statix deadnix alejandra npins]; 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 # testing, but make sure to discard the changes before creating a pull
# request. # request.
packages.dev = let 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 { customNeovim = lib.nvim.neovimConfiguration {
inherit pkgs; inherit pkgs;

2
lib/types/languages.nix
View file

@ -30,7 +30,7 @@
mkGrammarOption = pkgs: grammar: mkGrammarOption = pkgs: grammar:
mkPackageOption pkgs ["${grammar} treesitter"] { mkPackageOption pkgs ["${grammar} treesitter"] {
default = ["vimPlugins" "nvim-treesitter" "builtGrammars" grammar]; default = ["vimPlugins" "nvim-treesitter" "grammarPlugins" grammar];
}; };
in { in {
inherit diagnostics diagnosticSubmodule mkGrammarOption; inherit diagnostics diagnosticSubmodule mkGrammarOption;

34
modules/extra/deprecations.nix
View file

@ -308,5 +308,39 @@ in {
]) ])
# Migrated via batchRenameOptions. Further batch renames must be below this line. # Migrated via batchRenameOptions. Further batch renames must be below this line.
renamedVimOpts renamedVimOpts
# 2026-01-06
[
(mkRemovedOptionModule ["vim" "treesitter" "highlight" "disable"] ''
Treesitter highlighting is now handled by Neovim natively, and it does not have a disable option.
'')
(mkRemovedOptionModule ["vim" "treesitter" "highlight" "additionalVimRegexHighlighting"] ''
Treesitter highlighting is now handled by Neovim natively, and it does not have a additionalVimRegexHighlighting option.
'')
(mkRemovedOptionModule ["vim" "treesitter" "indent" "disable"] ''
Treesitter indentation is now handled differently, and it does not have a disable option.
'')
(mkRemovedOptionModule ["vim" "treesitter" "incrementalSelection" "enable"] ''
Incremental selection configuration has been removed from nvim-treesitter.
'')
(mkRemovedOptionModule ["vim" "treesitter" "incrementalSelection" "disable"] ''
Incremental selection configuration has been removed from nvim-treesitter.
'')
(mkRemovedOptionModule ["vim" "treesitter" "mappings" "incrementalSelection" "init"] ''
Incremental selection configuration has been removed from nvim-treesitter.
'')
(mkRemovedOptionModule ["vim" "treesitter" "mappings" "incrementalSelection" "incrementByNode"] ''
Incremental selection configuration has been removed from nvim-treesitter.
'')
(
mkRemovedOptionModule ["vim" "treesitter" "mappings" "incrementalSelection" "incrementByScope"]
''
Incremental selection configuration has been removed from nvim-treesitter.
''
)
(mkRemovedOptionModule ["vim" "treesitter" "mappings" "incrementalSelection" "decrementByNode"] ''
Incremental selection configuration has been removed from nvim-treesitter.
'')
]
]; ];
} }

2
modules/plugins/languages/csharp.nix
View file

@ -178,7 +178,7 @@ in {
treesitter = { treesitter = {
enable = mkEnableOption "C# treesitter" // {default = config.vim.languages.enableTreesitter;}; enable = mkEnableOption "C# treesitter" // {default = config.vim.languages.enableTreesitter;};
package = mkGrammarOption pkgs "c-sharp"; package = mkGrammarOption pkgs "c_sharp";
}; };
lsp = { lsp = {

2
modules/plugins/languages/markdown.nix
View file

@ -64,7 +64,7 @@ in {
description = "Enable Markdown treesitter"; description = "Enable Markdown treesitter";
}; };
mdPackage = mkGrammarOption pkgs "markdown"; mdPackage = mkGrammarOption pkgs "markdown";
mdInlinePackage = mkGrammarOption pkgs "markdown-inline"; mdInlinePackage = mkGrammarOption pkgs "markdown_inline";
}; };
lsp = { lsp = {

2
modules/plugins/languages/nix.nix
View file

@ -41,7 +41,7 @@
}; };
nixfmt = { nixfmt = {
command = getExe pkgs.nixfmt-rfc-style; command = getExe pkgs.nixfmt;
}; };
}; };

2
modules/plugins/languages/python.nix
View file

@ -228,7 +228,7 @@ in {
package = mkOption { package = mkOption {
description = "Python treesitter grammar to use"; description = "Python treesitter grammar to use";
type = package; type = package;
default = pkgs.vimPlugins.nvim-treesitter.builtGrammars.python; default = pkgs.vimPlugins.nvim-treesitter.grammarPlugins.python;
}; };
}; };

2
modules/plugins/languages/sql.nix
View file

@ -66,7 +66,7 @@ in {
package = mkOption { package = mkOption {
type = package; type = package;
default = pkgs.vimPlugins.nvim-treesitter.builtGrammars.sql; default = pkgs.vimPlugins.nvim-treesitter.grammarPlugins.sql;
description = "SQL treesitter grammar to use"; description = "SQL treesitter grammar to use";
}; };
}; };

57
modules/plugins/notes/obsidian/config.nix
View file

@ -3,9 +3,9 @@
lib, lib,
... ...
}: let }: let
inherit (lib.modules) mkIf; inherit (lib.modules) mkIf mkMerge;
inherit (lib.generators) mkLuaInline;
inherit (lib.nvim.dag) entryAnywhere; inherit (lib.nvim.dag) entryAnywhere;
inherit (lib.nvim.binds) pushDownDefault;
inherit (lib.nvim.lua) toLuaObject; inherit (lib.nvim.lua) toLuaObject;
cfg = config.vim.notes.obsidian; cfg = config.vim.notes.obsidian;
@ -18,13 +18,58 @@ in {
"tabular" "tabular"
]; ];
binds.whichKey.register = pushDownDefault {
"<leader>o" = "+Notes";
};
pluginRC.obsidian = entryAnywhere '' pluginRC.obsidian = entryAnywhere ''
require("obsidian").setup(${toLuaObject cfg.setupOpts}) require("obsidian").setup(${toLuaObject cfg.setupOpts})
''; '';
notes.obsidian.setupOpts = let
# may not be defined
snacks-picker.enable = config.vim.utility.snacks-nvim.setupOpts.picker.enabled or false;
mini-pick = config.vim.mini.pick;
inherit (config.vim) telescope fzf-lua;
inherit (config.vim.languages.markdown.extensions) render-markdown-nvim markview-nvim;
in
mkMerge [
# Don't set option unless we have a useful setting for it.
(mkIf (snacks-picker.enable || mini-pick.enable || telescope.enable || fzf-lua.enable) {
# It doesn't detect/choose this.
# Some pickers and completion plugins don't get detected correctly by the checkhealth, but they all work.
# Values taken from the [config's](https://github.com/obsidian-nvim/obsidian.nvim/blob/main/lua/obsidian/config/init.lua) valid ones.
picker.name =
if snacks-picker.enable
then "snacks.pick"
else if mini-pick.enable
then "mini.pick"
else if telescope.enable
then "telescope.nvim"
else if fzf-lua.enable
then "fzf-lua"
# NOTE: Shouldn't happen with the if-guard.
else null;
})
# Should be disabled automatically, but still shows up in render-markdown's checkhealth.
# This is also useful in that it will conflict with a user explicitly enabling it
# without mkForce, which is probably a copy paste issue and a sign to look at
# whether this option is useful.
(mkIf (render-markdown-nvim.enable || markview-nvim.enable) {ui.enable = false;})
];
# Resolve markdown image paths in the vault.
# Only actually used by snacks if image.enabled is set to true and
# required programs are supplied and `attachments.img_folder` is correct.
# From https://github.com/obsidian-nvim/obsidian.nvim/wiki/Images,
# which notes the API might change.
utility.snacks-nvim.setupOpts = mkIf config.vim.utility.snacks-nvim.enable {
image.resolve = mkLuaInline ''
function(path, src)
if require("obsidian.api").path_is_note(path) then
return require("obsidian.api").resolve_image_path(src)
end
end
'';
};
}; };
}; };
} }

81
modules/plugins/notes/obsidian/obsidian.nix
View file

@ -1,14 +1,7 @@
{ {lib, ...}: let
config, inherit (lib.options) mkEnableOption;
lib, inherit (lib.modules) mkRenamedOptionModule mkRemovedOptionModule;
...
}: let
inherit (lib.options) mkEnableOption mkOption;
inherit (lib.types) bool str nullOr;
inherit (lib.modules) mkRenamedOptionModule;
inherit (lib.nvim.types) mkPluginSetupOption; inherit (lib.nvim.types) mkPluginSetupOption;
autocompleteCfg = config.vim.autocomplete;
in { in {
imports = let imports = let
renamedSetupOption = oldPath: newPath: renamedSetupOption = oldPath: newPath:
@ -16,38 +9,60 @@ in {
(["vim" "notes" "obsidian"] ++ oldPath) (["vim" "notes" "obsidian"] ++ oldPath)
(["vim" "notes" "obsidian" "setupOpts"] ++ newPath); (["vim" "notes" "obsidian" "setupOpts"] ++ newPath);
in [ in [
(renamedSetupOption ["dir"] ["dir"]) (
mkRemovedOptionModule ["vim" "notes" "obsidian" "dir"]
''
`obsidian.nvim` has migrated to the `setupOpts.workspaces` option to support multiple vaults with a single interface.
To continue using a single vault, set:
```nix
{
notes.obsidian.setupOpts.workspaces = [
{
name = "any-string";
path = "~/old/dir/path/value";
}
];
}
```
See the [wiki](https://github.com/obsidian-nvim/obsidian.nvim/wiki/Workspace#vault-based-workspaces) for more information.
''
)
(renamedSetupOption ["daily-notes" "folder"] ["daily_notes" "folder"]) (renamedSetupOption ["daily-notes" "folder"] ["daily_notes" "folder"])
(renamedSetupOption ["daily-notes" "date-format"] ["daily_notes" "date_format"]) (renamedSetupOption ["daily-notes" "date-format"] ["daily_notes" "date_format"])
(renamedSetupOption ["completion"] ["completion"]) (renamedSetupOption ["completion"] ["completion"])
]; ];
options.vim.notes = { options.vim.notes = {
obsidian = { obsidian = {
enable = mkEnableOption "complementary neovim plugins for Obsidian editor"; enable =
mkEnableOption ""
// {
description = ''
Whether to enable plugins to complement the Obsidian markdown editor [obsidian.nvim].
setupOpts = mkPluginSetupOption "Obsidian.nvim" { Enables [vim-markdown] which automatically folds markdown headings inside and outside of workspaces/vaults.
daily_notes = { Set {option}`vim.globals.vim_markdown_folding_disable = 1;` to disable automatic folding,
folder = mkOption { or {option}`vim.globals.vim_markdown_folding_level = <heading-level-int>;` to set the default fold level for new buffers.
type = nullOr str;
default = null; nvf will choose one of `snacks.picker`, `mini.pick`, `telescope`, or `fzf-lua` as the `obsidian.nvim` picker based on whether they are enabled, in that order.
description = "Directory in which daily notes should be created";
}; You can enable one of them with one of the following:
date_format = mkOption {
type = nullOr str; - {option}`vim.utility.snacks-nvim.setupOpts.picker.enabled` and {option}`vim.utility.snacks-nvim.enable`
default = null; - {option}`vim.mini.pick.enable`
description = "Date format used for creating daily notes"; - {option}`vim.telescope.enable`
}; - {option}`vim.fzf-lua.enable`
{option}`vim.notes.obsidian.setupOpts.ui.enable` is automatically disabled if `render-markdown.nvim` or `markview.nvim` are enabled.
[vim-markdown]: https://github.com/preservim/vim-markdown?tab=readme-ov-file#options
'';
}; };
completion = { setupOpts = mkPluginSetupOption "obsidian.nvim" {};
nvim_cmp = mkOption {
# If using nvim-cmp, otherwise set to false
type = bool;
description = "If using nvim-cmp, otherwise set to false";
default = autocompleteCfg.nvim-cmp.enable || autocompleteCfg.blink-cmp.enable;
};
};
};
}; };
}; };
} }

2
modules/plugins/notes/orgmode/config.nix
View file

@ -21,7 +21,7 @@ in {
pluginRC.orgmode = entryAnywhere '' pluginRC.orgmode = entryAnywhere ''
-- Treesitter configuration -- Treesitter configuration
require('nvim-treesitter.configs').setup { require('nvim-treesitter.config').setup {
-- If TS highlights are not enabled at all, or disabled via `disable` prop, -- If TS highlights are not enabled at all, or disabled via `disable` prop,
-- highlighting will fallback to default Vim syntax highlighting -- highlighting will fallback to default Vim syntax highlighting

15
modules/plugins/terminal/toggleterm/config.nix
View file

@ -17,9 +17,20 @@ in {
vim = { vim = {
lazy.plugins.toggleterm-nvim = { lazy.plugins.toggleterm-nvim = {
package = "toggleterm-nvim"; package = "toggleterm-nvim";
cmd = ["ToggleTerm" "ToggleTermSendCurrentLine" "ToggleTermSendVisualLines" "ToggleTermSendVisualSelection" "ToggleTermSetName" "ToggleTermToggleAll"]; cmd = [
"ToggleTerm"
"ToggleTermSendCurrentLine"
"ToggleTermSendVisualLines"
"ToggleTermSendVisualSelection"
"ToggleTermSetName"
"ToggleTermToggleAll"
];
keys = keys =
[(mkKeymap "n" cfg.mappings.open "<Cmd>execute v:count . \"ToggleTerm\"<CR>" {desc = "Toggle terminal";})] [
(mkKeymap ["n" "t"] cfg.mappings.open "<Cmd>execute v:count . \"ToggleTerm\"<CR>" {
desc = "Toggle terminal";
})
]
++ optional cfg.lazygit.enable { ++ optional cfg.lazygit.enable {
key = cfg.lazygit.mappings.open; key = cfg.lazygit.mappings.open;
mode = "n"; mode = "n";

106
modules/plugins/treesitter/config.nix
View file

@ -1,19 +1,13 @@
{ {
config, config,
lib, lib,
options,
... ...
}: let }: let
inherit (lib.modules) mkIf mkMerge; inherit (lib.modules) mkIf;
inherit (lib.lists) optionals; inherit (lib.lists) optionals;
inherit (lib.nvim.binds) mkSetBinding addDescriptionsToMappings; inherit (lib.nvim.dag) entryAfter;
inherit (lib.nvim.lua) toLuaObject;
inherit (lib.nvim.dag) entryBefore entryAfter;
cfg = config.vim.treesitter; cfg = config.vim.treesitter;
mappingDefinitions = options.vim.treesitter.mappings;
mappings = addDescriptionsToMappings cfg.mappings mappingDefinitions;
in { in {
config = mkIf cfg.enable { config = mkIf cfg.enable {
vim = { vim = {
@ -27,68 +21,46 @@ in {
treesitter.grammars = optionals cfg.addDefaultGrammars cfg.defaultGrammars; treesitter.grammars = optionals cfg.addDefaultGrammars cfg.defaultGrammars;
maps = { pluginRC.treesitter-autocommands = entryAfter ["basic"] ''
# HACK: Using mkSetLuaBinding and putting the lua code does not work for some reason: It just selects the whole file. vim.api.nvim_create_augroup("nvf_treesitter", { clear = true })
# This works though, and if it ain't broke, don't fix it.
normal = mkSetBinding mappings.incrementalSelection.init ":lua require('nvim-treesitter.incremental_selection').init_selection()<CR>";
visualOnly = mkMerge [ ${lib.optionalString cfg.highlight.enable ''
(mkSetBinding mappings.incrementalSelection.incrementByNode "<cmd>lua require('nvim-treesitter.incremental_selection').node_incremental()<CR>") -- Enable treesitter highlighting for all filetypes
(mkSetBinding mappings.incrementalSelection.incrementByScope "<cmd>lua require('nvim-treesitter.incremental_selection').scope_incremental()<CR>") vim.api.nvim_create_autocmd("FileType", {
(mkSetBinding mappings.incrementalSelection.decrementByNode "<cmd>lua require('nvim-treesitter.incremental_selection').node_decremental()<CR>") group = "nvf_treesitter",
]; pattern = "*",
}; callback = function()
pcall(vim.treesitter.start)
end,
})
''}
# For some reason treesitter highlighting does not work on start if this is set before syntax on ${lib.optionalString cfg.indent.enable ''
pluginRC.treesitter-fold = mkIf cfg.fold (entryBefore ["basic"] '' -- Enable treesitter highlighting for all filetypes
-- This is required by treesitter-context to handle folds vim.api.nvim_create_autocmd("FileType", {
vim.o.foldmethod = "expr" group = "nvf_treesitter",
vim.o.foldexpr = "nvim_treesitter#foldexpr()" pattern = "*",
callback = function()
vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()"
end,
})
''}
-- This is optional, but is set rather as a sane default. ${lib.optionalString cfg.fold ''
-- If unset, opened files will be folded by automatically as -- Enable treesitter folding for all filetypes
-- the files are opened vim.api.nvim_create_autocmd("FileType", {
vim.o.foldenable = false group = "nvf_treesitter",
''); pattern = "*",
callback = function()
pluginRC.treesitter = entryAfter ["basic"] '' vim.wo[0][0].foldmethod = "expr"
require('nvim-treesitter.configs').setup { vim.wo[0][0].foldexpr = "v:lua.vim.treesitter.foldexpr()"
-- Disable imperative treesitter options that would attempt to fetch -- This is optional, but is set rather as a sane default.
-- grammars into the read-only Nix store. To add additional grammars here -- If unset, opened files will be folded by automatically as
-- you must use the `config.vim.treesitter.grammars` option. -- the files are opened
auto_install = false, vim.o.foldenable = false
sync_install = false, end,
ensure_installed = {}, })
''}
-- Indentation module for Treesitter
indent = {
enable = ${toLuaObject cfg.indent.enable},
disable = ${toLuaObject cfg.indent.disable},
},
-- Highlight module for Treesitter
highlight = {
enable = ${toLuaObject cfg.highlight.enable},
disable = ${toLuaObject cfg.highlight.disable},
additional_vim_regex_highlighting = ${toLuaObject cfg.highlight.additionalVimRegexHighlighting},
},
-- Indentation module for Treesitter
-- Keymaps are set to false here as they are
-- handled by `vim.maps` entries calling lua
-- functions achieving the same functionality.
incremental_selection = {
enable = ${toLuaObject cfg.incrementalSelection.enable},
disable = ${toLuaObject cfg.incrementalSelection.disable},
keymaps = {
init_selection = false,
node_incremental = false,
scope_incremental = false,
node_decremental = false,
},
},
}
''; '';
}; };
}; };

121
modules/plugins/treesitter/treesitter.nix
View file

@ -3,21 +3,12 @@
lib, lib,
... ...
}: let }: let
inherit (lib.options) mkOption mkEnableOption literalMD literalExpression; inherit (lib.options) mkOption mkEnableOption literalExpression;
inherit (lib.types) listOf package str either bool; inherit (lib.types) listOf package bool;
inherit (lib.nvim.binds) mkMappingOption;
inherit (lib.nvim.types) luaInline;
in { in {
options.vim.treesitter = { options.vim.treesitter = {
enable = mkEnableOption "treesitter, also enabled automatically through language options"; enable = mkEnableOption "treesitter, also enabled automatically through language options";
mappings.incrementalSelection = {
init = mkMappingOption "Init selection [treesitter]" "gnn";
incrementByNode = mkMappingOption "Increment selection by node [treesitter]" "grn";
incrementByScope = mkMappingOption "Increment selection by scope [treesitter]" "grc";
decrementByNode = mkMappingOption "Decrement selection by node [treesitter]" "grm";
};
fold = mkEnableOption "fold with treesitter"; fold = mkEnableOption "fold with treesitter";
autotagHtml = mkEnableOption "autoclose and rename html tag"; autotagHtml = mkEnableOption "autoclose and rename html tag";
@ -25,14 +16,14 @@ in {
type = listOf package; type = listOf package;
default = []; default = [];
example = literalExpression '' example = literalExpression ''
with pkgs.vimPlugins.nvim-treesitter.builtGrammars; [ with pkgs.vimPlugins.nvim-treesitter.grammarPlugins; [
regex regex
kdl kdl
]; ];
''; '';
description = '' description = ''
List of treesitter grammars to install. For grammars to be installed properly, List of treesitter grammars to install. For grammars to be installed properly,
you must use grammars from `pkgs.vimPlugins.nvim-treesitter.builtGrammars`. you must use grammars from `pkgs.vimPlugins.nvim-treesitter.parsers` or `pkgs.vimPlugins.nvim-treesitter.grammarPlugins`.
You can use `pkgs.vimPlugins.nvim-treesitter.allGrammars` to install all grammars. You can use `pkgs.vimPlugins.nvim-treesitter.allGrammars` to install all grammars.
For languages already supported by nvf, you may use For languages already supported by nvf, you may use
@ -56,7 +47,7 @@ in {
internal = true; internal = true;
readOnly = true; readOnly = true;
type = listOf package; type = listOf package;
default = with pkgs.vimPlugins.nvim-treesitter.builtGrammars; [c lua vim vimdoc query]; default = with pkgs.vimPlugins.nvim-treesitter.grammarPlugins; [c lua vim vimdoc query];
description = '' description = ''
A list of treesitter grammars that will be installed by default A list of treesitter grammars that will be installed by default
if treesitter has been enabled and {option}`vim.treeesitter.addDefaultGrammars` if treesitter has been enabled and {option}`vim.treeesitter.addDefaultGrammars`
@ -73,105 +64,7 @@ in {
''; '';
}; };
indent = { indent = {enable = mkEnableOption "indentation with treesitter" // {default = true;};};
enable = mkEnableOption "indentation with treesitter" // {default = true;}; highlight = {enable = mkEnableOption "highlighting with treesitter" // {default = true;};};
disable = mkOption {
type = either (listOf str) luaInline;
default = [];
example = literalExpression ''["c" "rust"]'';
description = ''
List of treesitter grammars to disable indentation for.
This option can be either a list, in which case it will be
converted to a Lua table containing grammars to disable
indentation for, or a string containing a **lua function**
that will be read as is.
::: {.warning}
A comma will be added at the end of your function, so you
do not need to add it yourself. Doing so will cause in
syntax errors within your Neovim configuration.
:::
'';
};
};
highlight = {
enable = mkEnableOption "highlighting with treesitter" // {default = true;};
disable = mkOption {
type = either (listOf str) luaInline;
default = [];
example = literalMD ''
```lua
-- Disable slow treesitter highlight for large files
function(lang, buf)
local max_filesize = 1000 * 1024 -- 1MB
local ok, stats = pcall(vim.uv.fs_stat, vim.api.nvim_buf_get_name(buf))
if ok and stats and stats.size > max_filesize then
return true
end
end
```
'';
description = ''
List of treesitter grammars to disable highlighting for.
This option can be either a list, in which case it will be
converted to a Lua table containing grammars to disable
highlighting for, or a string containing a **lua function**
that will be read as is.
::: {.warning}
A comma will be added at the end of your function, so you
do not need to add it yourself. Doing so will cause in
syntax errors within your Neovim configuration.
:::
'';
};
additionalVimRegexHighlighting = mkOption {
type = either bool (listOf str);
default = false;
description = ''
Takes either a boolean or a list of languages.
Setting this to true will run `:h syntax` and tree-sitter at the same time.
You may this to `true` if you depend on 'syntax' being enabled (like for
indentation).
::: {.note}
Using this option may slow down your editor, and you may see some duplicate
highlights.
:::
'';
};
};
incrementalSelection = {
enable = mkEnableOption "incremental selection with treesitter" // {default = true;};
disable = mkOption {
type = either (listOf str) luaInline;
default = [];
example = literalExpression ''["c" "rust" ]'';
description = ''
List of treesitter grammars to disable incremental selection
for.
This option can be either a list, in which case it will be
converted to a Lua table containing grammars to disable
indentation for, or a string containing a **lua function**
that will be read as is.
::: {.warning}
A comma will be added at the end of your function, so you
do not need to add it yourself. Doing so will cause in
syntax errors within your Neovim configuration.
:::
'';
};
};
}; };
} }

2
modules/plugins/treesitter/ts-textobjects/config.nix
View file

@ -16,7 +16,7 @@ in {
# set up treesitter-textobjects after Treesitter, whose config we're adding to. # set up treesitter-textobjects after Treesitter, whose config we're adding to.
pluginRC.treesitter-textobjects = entryAfter ["treesitter"] '' pluginRC.treesitter-textobjects = entryAfter ["treesitter"] ''
require("nvim-treesitter.configs").setup({textobjects = ${toLuaObject cfg.setupOpts}}) require("nvim-treesitter.config").setup({textobjects = ${toLuaObject cfg.setupOpts}})
''; '';
}; };
}; };

2
modules/plugins/ui/noice/config.nix
View file

@ -12,7 +12,7 @@
cfg = config.vim.ui.noice; cfg = config.vim.ui.noice;
tscfg = config.vim.treesitter; tscfg = config.vim.treesitter;
defaultGrammars = with pkgs.vimPlugins.nvim-treesitter.builtGrammars; [vim regex lua bash markdown]; defaultGrammars = with pkgs.vimPlugins.nvim-treesitter.grammarPlugins; [vim regex lua bash markdown];
in { in {
config = mkIf cfg.enable { config = mkIf cfg.enable {
vim = { vim = {

140
modules/plugins/utility/ccc/ccc.nix
View file

@ -1,10 +1,148 @@
{lib, ...}: let {lib, ...}: let
inherit (lib.options) mkEnableOption; inherit (lib.options) mkOption mkEnableOption;
inherit (lib.types) anything attrsOf listOf enum;
inherit (lib.nvim.binds) mkMappingOption; inherit (lib.nvim.binds) mkMappingOption;
inherit (lib.nvim.types) mkPluginSetupOption luaInline;
inherit (lib.generators) mkLuaInline;
in { in {
options.vim.utility.ccc = { options.vim.utility.ccc = {
enable = mkEnableOption "ccc color picker for neovim"; enable = mkEnableOption "ccc color picker for neovim";
setupOpts = mkPluginSetupOption "ccc.nvim" {
highlighter = mkOption {
type = attrsOf anything;
default = {
auto_enable = true;
max_byte = 2 * 1024 * 1024; # 2mb
lsp = true;
filetypes = mkLuaInline "colorPickerFts";
};
description = ''
Settings for the highlighter. See {command}`:help ccc` for options.
'';
};
pickers = mkOption {
type = listOf luaInline;
default = map mkLuaInline [
"ccc.picker.hex"
"ccc.picker.css_rgb"
"ccc.picker.css_hsl"
"ccc.picker.ansi_escape { meaning1 = \"bold\", }"
];
description = ''
List of formats that can be detected by {command}`:CccPick` to be
activated.
Must be inline lua references to `ccc.picker`, for example
`mkLuaInline "ccc.picker.hex"`. See {command}`:help ccc` for options.
'';
};
alpha_show = mkOption {
type = enum [
"show"
"hide"
"auto"
];
default = "hide";
description = ''
This option determines whether the alpha slider is displayed when the
UI is opened. "show" and "hide" mean as they are. "auto" makes the
slider appear only when the alpha value can be picked up.
'';
};
recognize = mkOption {
type = attrsOf anything;
default = {
output = true;
};
description = ''
Settings for recognizing the color format. See {command}`:help ccc` for options.
'';
};
inputs = mkOption {
type = listOf luaInline;
default = map mkLuaInline ["ccc.input.hsl"];
description = ''
List of color systems to be activated. Must be inline lua references to
`ccc.input`, for example `mkLuaInline "ccc.input.rgb"`. See
{command}`:help ccc` for options.
The toggle input mode action toggles in this order. The first one is
the default used at the first startup. Once activated, it will keep the
previous input mode.
'';
};
outputs = mkOption {
type = listOf luaInline;
default = map mkLuaInline [
"ccc.output.css_hsl"
"ccc.output.css_rgb"
"ccc.output.hex"
];
description = ''
List of output formats to be activated. Must be inline Lua references to
`ccc.output`, for example `mkLuaInline "ccc.output.rgb"`. See
{command}`:help ccc` for options.
The toggle output mode action toggles in this order. The first one is
the default used at the first startup. Once activated, it will keep the
previous output mode.
'';
};
convert = mkOption {
type = listOf (listOf luaInline);
default = map (map mkLuaInline) [
[
"ccc.picker.hex"
"ccc.output.css_hsl"
]
[
"ccc.picker.css_rgb"
"ccc.output.css_hsl"
]
[
"ccc.picker.css_hsl"
"ccc.output.hex"
]
];
description = ''
Specify the correspondence between picker and output. Must be a list of
two-element lists defining picker/output pairs as inline Lua references,
for example:
```nix
map (map mkLuaInline) [
["ccc.picker.hex", "ccc.output.css_rgb"]
["ccc.picker.css_rgb", "ccc.output.hex"]
];
```
See {command}`:help ccc` for options.
'';
};
mappings = mkOption {
type = attrsOf luaInline;
default = {
"q" = mkLuaInline "ccc.mapping.quit";
"L" = mkLuaInline "ccc.mapping.increase10";
"H" = mkLuaInline "ccc.mapping.decrease10";
};
description = ''
The mappings are set in the UI of ccc. The table where lhs is key and
rhs is value. To disable all default mappings, use
{option}`vim.utility.ccc.setupOpts.disable_default_mappings`. To
disable only some of the default mappings, set `ccc.mapping.none`.
'';
};
};
mappings = { mappings = {
quit = mkMappingOption "Cancel and close the UI without replace or insert" "<Esc>"; quit = mkMappingOption "Cancel and close the UI without replace or insert" "<Esc>";
increase10 = mkMappingOption "Increase the value times delta of the slider" "<L>"; increase10 = mkMappingOption "Increase the value times delta of the slider" "<L>";

37
modules/plugins/utility/ccc/config.nix
View file

@ -5,7 +5,7 @@
}: let }: let
inherit (lib.modules) mkIf; inherit (lib.modules) mkIf;
inherit (lib.nvim.dag) entryAnywhere; inherit (lib.nvim.dag) entryAnywhere;
inherit (lib.nvim.lua) toLuaObject;
cfg = config.vim.utility.ccc; cfg = config.vim.utility.ccc;
in { in {
config = mkIf cfg.enable { config = mkIf cfg.enable {
@ -13,40 +13,7 @@ in {
vim.pluginRC.ccc = entryAnywhere '' vim.pluginRC.ccc = entryAnywhere ''
local ccc = require("ccc") local ccc = require("ccc")
ccc.setup { ccc.setup(${toLuaObject cfg.setupOpts})
highlighter = {
auto_enable = true,
max_byte = 2 * 1024 * 1024, -- 2mb
lsp = true,
filetypes = colorPickerFts,
},
pickers = {
ccc.picker.hex,
ccc.picker.css_rgb,
ccc.picker.css_hsl,
ccc.picker.ansi_escape {
meaning1 = "bright", -- whether the 1 means bright or yellow
},
},
alpha_show = "hide", -- needed when highlighter.lsp is set to true
recognize = { output = true }, -- automatically recognize color format under cursor
inputs = { ccc.input.hsl },
outputs = {
ccc.output.css_hsl,
ccc.output.css_rgb,
ccc.output.hex,
},
convert = {
{ ccc.picker.hex, ccc.output.css_hsl },
{ ccc.picker.css_rgb, ccc.output.css_hsl },
{ ccc.picker.css_hsl, ccc.output.hex },
},
mappings = {
["q"] = ccc.mapping.quit,
["L"] = ccc.mapping.increase10,
["H"] = ccc.mapping.decrease10,
},
}
''; '';
}; };
} }

15
modules/wrapper/build/config.nix
View file

@ -46,6 +46,21 @@
# Disable failing require check hook checks # Disable failing require check hook checks
doCheck = false; doCheck = false;
}; };
# Checkhealth fails to get the plugin's commit and therefore to
# show the rest of the useful diagnostics if not built like this.
obsidian-nvim = pkgs.vimUtils.buildVimPlugin {
# If set to `"obsidian-nvim"`, this breaks like `buildPlug` and `noBuildPlug`.
name = "obsidian.nvim";
src = getPin "obsidian-nvim";
nvimSkipModules = [
"minimal"
# require picker plugins
"obsidian.picker._telescope"
"obsidian.picker._snacks"
"obsidian.picker._fzf"
"obsidian.picker._mini"
];
};
# Get plugins built from source from self.packages # Get plugins built from source from self.packages
# If adding a new plugin to be built from source, it must also be inherited # If adding a new plugin to be built from source, it must also be inherited

21
npins/sources.json
View file

@ -285,9 +285,9 @@
}, },
"branch": "main", "branch": "main",
"submodules": false, "submodules": false,
"revision": "38db66c4e20032821bd166f7012291fe99f1e8f3", "revision": "b3bb0d73079643d4a5b0d8b621cde619a73bc91a",
"url": "https://github.com/olimorris/codecompanion.nvim/archive/38db66c4e20032821bd166f7012291fe99f1e8f3.tar.gz", "url": "https://github.com/olimorris/codecompanion.nvim/archive/b3bb0d73079643d4a5b0d8b621cde619a73bc91a.tar.gz",
"hash": "1iqqgcj7vdsif0fj0pf6ifn3nh05aznk2gnas7l3lg8b5g103vb8" "hash": "0jzldi9h98hci5ij1qnb4283hmh14irnprp5zg6mnfs9l6m8z3mq"
}, },
"codewindow-nvim": { "codewindow-nvim": {
"type": "Git", "type": "Git",
@ -2108,17 +2108,20 @@
"hash": "1qbyh8r2gbaw2n0mm7qwi4y8r9ywyz37q35vlxjzy879ba8dlnlm" "hash": "1qbyh8r2gbaw2n0mm7qwi4y8r9ywyz37q35vlxjzy879ba8dlnlm"
}, },
"obsidian-nvim": { "obsidian-nvim": {
"type": "Git", "type": "GitRelease",
"repository": { "repository": {
"type": "GitHub", "type": "GitHub",
"owner": "epwalsh", "owner": "obsidian-nvim",
"repo": "obsidian.nvim" "repo": "obsidian.nvim"
}, },
"branch": "main", "pre_releases": false,
"version_upper_bound": null,
"release_prefix": null,
"submodules": false, "submodules": false,
"revision": "14e0427bef6c55da0d63f9a313fd9941be3a2479", "version": "v3.15.3",
"url": "https://github.com/epwalsh/obsidian.nvim/archive/14e0427bef6c55da0d63f9a313fd9941be3a2479.tar.gz", "revision": "3121b4b52a167949c4126254272346d363cc92b6",
"hash": "15ycmhn48ryaqzch6w3w6llq2qgmjx8xwkb9dn0075z60dybpflr" "url": "https://api.github.com/repos/obsidian-nvim/obsidian.nvim/tarball/v3.15.3",
"hash": "0m6lwqb2y19xrs11hj818ja36z5ql34xk81x393b20jwnd0bar5l"
}, },
"oil-git-status.nvim": { "oil-git-status.nvim": {
"type": "Git", "type": "Git",