From 1b73e78788e1931285fa6335763a0a7ad4f152e4 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 15:19:00 +0300 Subject: [PATCH 1/8] docs/manual: move v0.9 entries to the correct file; format Signed-off-by: NotAShelf Change-Id: I593bbd1dbfd60215e317360d1652588a6a6a6964 --- docs/manual/release-notes/rl-0.8.md | 6 ------ docs/manual/release-notes/rl-0.9.md | 9 +++++++++ 2 files changed, 9 insertions(+), 6 deletions(-) create mode 100644 docs/manual/release-notes/rl-0.9.md diff --git a/docs/manual/release-notes/rl-0.8.md b/docs/manual/release-notes/rl-0.8.md index fadb2e69..62f42638 100644 --- a/docs/manual/release-notes/rl-0.8.md +++ b/docs/manual/release-notes/rl-0.8.md @@ -621,9 +621,3 @@ [JudahZF](https://github.com/JudahZF): - Added gitFiles mapping option to telescope - -[Ring-A-Ding-Ding-Baby](https://github.com/Ring-A-Ding-Ding-Baby) - -- Aligned `codelldb` adapter setup with [rustaceanvim]’s built-in logic. -- Added `languages.rust.dap.backend` option to choose between `codelldb` and - `lldb-dap` adapters. diff --git a/docs/manual/release-notes/rl-0.9.md b/docs/manual/release-notes/rl-0.9.md new file mode 100644 index 00000000..c12e3558 --- /dev/null +++ b/docs/manual/release-notes/rl-0.9.md @@ -0,0 +1,9 @@ +# Release 0.5 {#sec-release-0-9} + +## Changelog {#sec-release-0-9-changelog} + +[Ring-A-Ding-Ding-Baby](https://github.com/Ring-A-Ding-Ding-Baby): + +- Aligned `codelldb` adapter setup with [rustaceanvim]’s built-in logic. +- Added `languages.rust.dap.backend` option to choose between `codelldb` and + `lldb-dap` adapters. From 858717bed77985c7bb8e356a53bb8d84060da792 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 15:19:25 +0300 Subject: [PATCH 2/8] docs/manual: fix minor typos; revamp contributing section Signed-off-by: NotAShelf Change-Id: Ibb76402cc1e759b404a5c8905109604c6a6a6964 --- docs/manual/hacking.md | 368 +++++++++++++++++++++++++++++------------ docs/manual/index.md | 29 +++- 2 files changed, 286 insertions(+), 111 deletions(-) diff --git a/docs/manual/hacking.md b/docs/manual/hacking.md index 7af0fed9..1dd5aa47 100644 --- a/docs/manual/hacking.md +++ b/docs/manual/hacking.md @@ -3,12 +3,13 @@ [open issues]: https://github.com/notashelf/nvf/issues [new issue]: https://github.com/notashelf/nvf/issues/new -nvf is designed for the developer as much as it is designed for the end-user. We -would like for any contributor to be able to propagate their changes, or add new -features to the project with minimum possible friction. As such, below are the -guides and guidelines written to streamline the contribution process and to -ensure that your valuable input integrates into nvf's development as seamlessly -as possible without leaving any question marks in your head. +**nvf** is designed for the developer as much as it is designed for the +end-user. We would like for any contributor to be able to propagate their +changes, or add new features to the project with minimum possible friction. As +such, below are the guides and guidelines written to streamline the contribution +process and to ensure that your valuable input integrates into **nvf**'s +development as seamlessly as possible without leaving any question marks in your +head. This section is directed mainly towards those who wish to contribute code into the project. If you instead wish to report a bug, or discuss a potential new @@ -23,24 +24,51 @@ please do not be afraid to submit a pull request, we will help you get it in. ## Getting Started {#sec-contrib-getting-started} -You, naturally, would like to start by forking the repository to get started. If -you are new to Git and GitHub, do have a look at GitHub's -[Fork a repo guide](https://help.github.com/articles/fork-a-repo/) for -instructions on how you can do this. Once you have a fork of **nvf**, you should -create a separate branch based on the most recent `main` branch. Give your -branch a reasonably descriptive name (e.g. `feature/debugger` or -`fix/pesky-bug`) and you are ready to work on your changes +[Fork a repo guide]: https://help.github.com/articles/fork-a-repo/ +[Contributing Guidelines]: #sec-guidelines +[Create a Pull Request]: https://help.github.com/articles/creating-a-pull-request + +To contribute to **nvf**, you'll first want to fork the repository. If you are +new to Git and GitHub, do have a look at GitHub's [Fork a repo guide] for +instructions on how you can do this. Once your fork is created, you should +create a separate branch based on the most recent `main` branch. While you _can_ +work on the main branch of your repository, it is generally preferable to use +feature branches. You should give your branch a reasonably descriptive name +(e.g. `feature/new-debugger` or `fix/pesky-bug`) and you are ready to work on +your changes! Implement your changes and commit them to the newly created branch and when you are happy with the result, and positive that it fulfills our -[Contributing Guidelines](#sec-guidelines), push the branch to GitHub and -[create a pull request](https://help.github.com/articles/creating-a-pull-request). +[Contributing Guidelines], push the branch to GitHub and [Create a Pull Request] The default pull request template available on the **nvf** repository will guide you through the rest of the process, and we'll gently nudge you in the correct direction if there are any mistakes. +Before submitting your pull request, please ensure that: + +- The code is formatted as described in the formatting section +- The commit message fits the contributing guidelines (**nvf** does not use + Conventional Commits!) +- You have updated the changelog entry and optionally updated the documentation + with important information + +None of those are reasons for a Pull Request to be closed, but it will reduce +the number of roundtrips required before we can merge your Pull Request. + +> [!IMPORTANT] +> If you do not agree with the idea of using Microsoft GitHub for contributions, +> that is perfectly understandable. Unless you refuse to have your code hosted +> on this platform, you may submit _patches_ through e-mail. +> +> You may send your patches to [@NotAShelf](https://github.com/notashelf) using +> the public e-mail located on the GitHub page. Though, please remember to +> adhere to the contributing guidelines strictly as e-mail instroduces a +> significant overhead to the communication process. + ## Guidelines {#sec-guidelines} +[discussions tab]: https://github.com/NotAShelf/nvf/discussions + If your contribution tightly follows the guidelines, then there is a good chance it will be merged without too much trouble. Some of the guidelines will be strictly enforced, others will remain as gentle nudges towards the correct @@ -48,34 +76,26 @@ direction. As we have no automated system enforcing those guidelines, please try to double check your changes before making your pull request in order to avoid "faulty" code slipping by. -If you are uncertain how these rules affect the change you would like to make -then feel free to start a discussion in the -[discussions tab](https://github.com/NotAShelf/nvf/discussions) ideally (but not -necessarily) before you start developing. +If you are not quite certain how those rules affect the change you are planning +to make, then please start a friendly discussion in the [discussions tab] before +you begin developing. This is not a requirement, but it might answer some of +your burning questions and make the contribution process easier for all parties. -### Adding Documentation {#sec-guidelines-documentation} +### Formatting {#sec-guidelines-formatting} -[Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax +[code style section]: #sec-guidelines-code-style -Almost all changes warrant updates to the documentation: at the very least, you -must update the changelog. Both the manual and module options use -[Nixpkgs Flavoured Markdown]. +There are various files within the **nvf** repository. To maintain a sense of +consistency and to avoid clashing opinions on how formatters should behave, we +are very opinionated on how those files should be formatted. -The HTML version of this manual containing both the module option descriptions -and the documentation of **nvf** (such as this page) can be generated and opened -by typing the following in a shell within a clone of the **nvf** Git repository: +- Nix files **must** be formatted with the Alejandra formatter, following some + specific tips found in [Nix style section](#nix-sec-code-style-nix). +- Markdown files **must** be formatted with the `deno fmt` command, as described + in the [Markdown style section](#sec-code-style-markdown). -```console -$ nix build .#docs-html -$ xdg-open $PWD/result/share/doc/nvf/index.html -``` - -### Formatting Code {#sec-guidelines-formatting} - -Make sure your code is formatted as described in -[code-style section](#sec-guidelines-code-style). To maintain consistency -throughout the project you are encouraged to browse through existing code and -adopt its style also in new code. +Make sure your code is formatted as described in [code style section] before +your changes are submitted. ### Formatting Commits {#sec-guidelines-commit-message-style} @@ -98,27 +118,29 @@ The commit messages should follow the component or module in the first line. A commit message ideally, but not necessarily, follow the given template from home-manager's own documentation -``` - {component}: {description} +```gitcommit +{component}: {description} - {long description} +{long description} ``` where `{component}` refers to the code component (or module) your change affects, `{description}` is a very brief description of your change, and -`{long description}` is an optional clarifying description. As a rare exception, -if there is no clear component, or your change affects many components, then the -`{component}` part is optional. See -[example commit message](#sec-guidelines-ex-commit-message) for a commit message -that fulfills these requirements. +`{long description}` is an optional clarifying description. + +[example commit message]: #sec-guidelines-ex-commit-message + +As a rare exception, if there is no clear component, or your change affects many +components, then the `{component}` part is optional. See +[example commit message] for a commit message that fulfills these requirements. #### Example Commit {#sec-guidelines-ex-commit-message} -The commit -[69f8e47e9e74c8d3d060ca22e18246b7f7d988ef](https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef) -in home-manager contains the following commit message. +[sample commit from Home Manager]: https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef -``` +The [sample commit from Home Manager] contains the following commit message. + +```gitcommit starship: allow running in Emacs if vterm is used The vterm buffer is backed by libvterm and can handle Starship prompts @@ -128,30 +150,63 @@ without issues. Similarly, if you are contributing to **nvf**, you would include the scope of the commit followed by the description: -``` +```gitcommit languages/ruby: init module -Adds a language module for Ruby, adds appropriate formatters and Treesitter grammars +Adds a language module for Ruby, adds appropriate formatters and Treesitter +grammars ``` Long description can be omitted if the change is too simple to warrant it. A minor fix in spelling or a formatting change does not warrant long description, however, a module addition or removal does as you would like to provide the -relevant context, i.e. the reasoning behind it, for your commit. +relevant context, i.e., the reasoning for your commit. -Finally, when adding a new module, say `modules/foo.nix`, we use the fixed -commit format `foo: add module`. You can, of course, still include a long -description if you wish. +For new plugin additions, the following is a good starting point: -In case of nested modules, i.e `modules/languages/java.nix` you are recommended -to contain the parent as well - for example `languages/java: some major change`. +```gitcommit +plugin: init +``` + +You can, of course, still include a long description if you wish. + +```gitcommit +neotree: init + +This adds the neo-tree plugin. +``` + +In case of nested modules, e.g., `modules/languages/java.nix` you are +recommended to contain the parent as well -- for example +`languages/java: some major change` , or if it's a new language module, +`languages/java: init` ### Code Style {#sec-guidelines-code-style} #### Treewide {#sec-code-style-treewide} -Keep lines at a reasonable width, ideally 80 characters or less. This also -applies to string literals and module descriptions and documentation. +Across the tree, you're encouraged to follow kebab-case for file names, and keep +text files (such as Markdown) to 80 characters or less. This 80 character +recommendation also applies to option descriptions and string literals inside of +Nix files. + +#### Markdown {#sec-code-style-markdown} + +Various Markdown files are used for documentation in the **nvf** repository. +Besides the README, the manual is written almost entirely in Markdown. Since +**nvf** uses a special variant of CommonMark, dubbed "Nixpkgs-flavored +CommonMark" within this repository, you are encouraged to use the `deno fmt` +command (provided by `pkgs.deno`) to format your Markdown sources. To avoid +accidentally formatting HTML or CSS files, you might want to specify the file +extension as follows: + +```bash +# Format all Markdown files within the repository +$ deno fmt --ext md **/*.md +``` + +You may also pass `--check` to the `deno fmt` command above to see if your +formatting complies with the project standards. #### Nix {#sec-code-style-nix} @@ -165,12 +220,16 @@ While Alejandra is mostly opinionated on how code looks after formatting, certain changes are done at the user's discretion based on how the original code was structured. +##### Attribute Sets + Please use one line code for attribute sets that contain only one subset. For example: + + ```nix -# parent modules should always be unfolded -# which means module = { value = ... } instead of module.value = { ... } +# Parent modules should always be unfolded. +# which means `module = { value = ... }` instead of `module.value = { ... }`. module = { value = mkEnableOption "some description" // { default = true; }; # merges can be done inline where possible @@ -190,23 +249,45 @@ module = { } ``` + + If you move a line down after the merge operator, Alejandra will automatically -unfold the whole merged attrset for you, which we **do not** want. +unfold the whole merged attribute set for you, which we **do not** want. ```nix module = { + # This is wrong! key = mkEnableOption "some description" // { default = true; # we want this to be inline - }; # ... + }; + + # ... } ``` +Though, if the right-hand side is more than a single line, it is okay to move to +a new line. For example: + +```nix +module = { + # This is okay! + key = mkEnableOption "some description" // { + default = true; + example = false; + }; + + # ... +} +``` + +##### Lists + For lists, it is mostly up to your own discretion how you want to format them, but please try to unfold lists if they contain multiple items and especially if they are to include comments. ```nix -# this is ok +# This is ok acceptableList = [ item1 # comment item2 @@ -214,14 +295,14 @@ acceptableList = [ item4 ]; -# this is not ok +# This is *not* ok listToBeAvoided = [item1 item2 /* comment */ item3 item4]; -# this is ok +# This is ok acceptableList = [item1 item2]; -# this is also ok if the list is expected to contain more elements -acceptableList= [ +# This is also ok if the list is expected to contain more elements +acceptableList = [ item1 item2 # more items if needed... @@ -244,6 +325,81 @@ 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. +## 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 + +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 HTML version of this documentation, dubbed the "nvf manual", can be +generated and opened by typing the following in a shell within a clone of the +**nvf** Git repository: + +```sh +# Build the online manual +$ nix build .#docs-html + +# Open it with a valid browser +$ xdg-open $PWD/result/share/doc/nvf/index.html +``` + +Additionally, if you are adding new links to the documentation it is **generally +recommended** that you run the package that identifies dead URLs in the +documentation: + +```sh +# Build the link checker package +$ nix build .#docs-linkcheck +``` + +You must ensure that the **HTML Documentation** builds before submitting a pull +request. + +### 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 +[](https://github.com/): + +- Added ... +- Removed ... +- Changed ... +``` + +```markdown +# Release 0.9 {#sec-release-0-9} + +## Breaking changes + +- We broke everything, please migrate! +``` + +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. + ## Keybinds {#sec-keybinds} As of 0.4, there exists an API for writing your own keybinds and a couple of @@ -252,7 +408,7 @@ useful utility functions are available in 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} +### Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings} To set a mapping, you should define it in `vim.keymaps`. @@ -273,12 +429,12 @@ An example, simple keybinding, can look like this: ``` There are many settings available in the options. Please refer to the -[documentation](./options.html#option-vim-keymaps) to see a list of them. +[documentation](/options.html#option-vim-keymaps) to see a list of them. **nvf** provides a helper function, so that you don't have to write the mapping attribute sets every time: -- `mkKeymap`, which mimics neovim's `vim.keymap.set` function +- `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: @@ -304,6 +460,8 @@ in { } ``` + + ```nix # config.nix { @@ -333,26 +491,29 @@ in { } ``` -> [!NOTE] + + +> [!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. ## Adding Plugins {#sec-additional-plugins} -There are two methods for adding new Neovim plugins to **nvf**. npins is the -faster option that should be preferred if the plugin consists of pure Lua or -Vimscript code. In which case there is no building required, and we can easily -handle the copying of plugin files. Alternative method, which is required when -plugins try to build their own libraries (e.g., in Rust or C) that need to be -built with Nix to function correctly. +**nvf** generally tries to avoid using Neovim plugins from Nixpkgs, and thus +uses one of the two alternative methods where applicable. npins is the faster +option that should be preferred if the plugin consists of pure Lua or Vimscript +code. In which case there is no building required, and we can easily handle the +copying of plugin files. Alternative method, which is required when plugins try +to build their own libraries (e.g., in Rust, C or even Assembly) that need to be +built with Nix to function correctly. In this case you must use a local overlay. ### With npins {#sec-npins-for-plugins} -npins is the standard method of adding new plugins to **nvf**. You simply need -the repository URL for the plugin, and can add it as a source to be built -automatically with one command. To add a new Neovim plugin, use `npins`. For -example: +npins is the standard, and as described above, the _faster_ method of adding new +plugins to **nvf**. You simply need the repository URL for the plugin, and you +can add it as a source to be built automatically with just one command. To add a +new Neovim plugin, use `npins`. For example: ```bash nix-shell -p npins # or nix shell nixpkgs#npins if using flakes @@ -364,16 +525,13 @@ Then run: npins add --name github -b ``` -::: {.note} - -Be sure to replace any non-alphanumeric characters with `-` for `--name`. For -example - -```bash -npins add --name lazydev-nvim github folke lazydev.nvim -b main -``` - -::: +> [!NOTE] +> Be sure to replace any non-alphanumeric characters with `-` for `--name`. For +> example +> +> ```bash +> npins add --name lazydev-nvim github folke lazydev.nvim -b main +> ``` Once the `npins` command is done, you can start referencing the plugin as a **string**. @@ -399,15 +557,21 @@ We use `buildRustPackage` to build the library from the repository root, and copy everything in the `postInstall` phase. ```nix -postInstall = '' - cp -r {lua,plugin} "$out" +{ + # ... + + postInstall = '' + cp -r {lua,plugin} "$out" - mkdir -p "$out/doc" - cp 'doc/'*'.txt' "$out/doc/" + mkdir -p "$out/doc" + cp 'doc/'*'.txt' "$out/doc/" - mkdir -p "$out/target" - mv "$out/lib" "$out/target/release" -''; + mkdir -p "$out/target" + mv "$out/lib" "$out/target/release" + ''; + + # ... +} ``` In a similar fashion, you may utilize `stdenv.mkDerivation` and other Nixpkgs @@ -503,7 +667,7 @@ own fields! } ``` -### Details of toLuaObject {#sec-details-of-toluaobject} +### Details of `toLuaObject` {#sec-details-of-toluaobject} As you've seen above, `toLuaObject` is used to convert our nix attrSet `cfg.setupOpts`, into a lua table. Here are some rules of the conversion: @@ -544,7 +708,7 @@ As you've seen above, `toLuaObject` is used to convert our nix attrSet } ``` -### Lazy plugins {#sec-lazy-plugins} +### Lazy Loading Plugins {#sec-lazy-plugins} If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it. Lazy plugins are managed by `lz.n`. diff --git a/docs/manual/index.md b/docs/manual/index.md index b07a8aca..bb2a5901 100644 --- a/docs/manual/index.md +++ b/docs/manual/index.md @@ -1,6 +1,6 @@ # Introduction {#nvf-manual} -Version @NVF_VERSION@ +Generated for nvf @NVF_VERSION@ ## Preface {#ch-preface} @@ -8,11 +8,11 @@ Version @NVF_VERSION@ **nvf** is a highly modular, configurable, extensible and easy to use Neovim configuration framework built and designed to be used with Nix. Boasting -flexibility, robustness and ease of use, this projecct allows you to configure a +flexibility, robustness and ease of use, this project 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} +## 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 @@ -27,20 +27,27 @@ You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed. ```sh +# Add the nvf cache $ cachix use nvf # Optional: it'll save you CPU resources and time + +# Run the minimal configuration with the cache enabled $ nix run github:notashelf/nvf#nix # Will run the default minimal configuration ``` Do keep in mind that this is **susceptible to garbage collection** meaning that the built outputs will be removed from your Nix store once you garbage collect. -## Using Prebuilt Configs {#sec-using-prebuilt-configs} +## Using Prebuilt Configurations {#sec-using-prebuilt-configs} + + ```bash $ nix run github:notashelf/nvf#nix $ nix run github:notashelf/nvf#maximal ``` + + ### Available Configurations {#sec-available-configs} > [!NOTE] @@ -61,7 +68,7 @@ $ nix run github:notashelf/nvf#nix test.nix ``` This command will start Neovim with some opinionated plugin configurations, and -is designed specifically for Nix. the `nix` configuration lets you see how a +is designed specifically for Nix. The `nix` configuration lets you see how a fully configured Neovim setup _might_ look like without downloading too many packages or shell utilities. @@ -87,12 +94,16 @@ companion or fun plugins. ## Installing nvf {#ch-installation} + + [module installation section]: #ch-module-installation -There are multiple ways of installing nvf on your system. You may either choose -the standalone installation method, which does not depend on a module system and -may be done on any system that has the Nix package manager or the appropriate -modules for NixOS and home-manager as described in the + + +There are multiple ways of installing **nvf** on your system. You may either +choose the standalone installation method, which does not depend on a module +system and may be done on any system that has the Nix package manager or the +appropriate modules for NixOS and Home Manager as described in the [module installation section]. ```{=include=} From c6022aeab2ddb4ef2b40e2473483a081913709ed Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 15:50:25 +0300 Subject: [PATCH 3/8] flake: document 'develop' package better Signed-off-by: NotAShelf Change-Id: Ida5b35a258dcc8ffa6fa6d653b76ddb36a6a6964 --- flake/develop.nix | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/flake/develop.nix b/flake/develop.nix index 71c13688..c05b2a9a 100644 --- a/flake/develop.nix +++ b/flake/develop.nix @@ -1,15 +1,23 @@ {lib, ...}: { - perSystem = { - pkgs, - config, - self', - ... - }: { + perSystem = {pkgs, ...}: { + # The default dev shell provides packages required to interact with + # the codebase as described by the contributing guidelines. It includes the + # formatters required, and a few additional goodies for linting work. devShells = { - default = self'.devShells.lsp; - nvim-nix = pkgs.mkShellNoCC {packages = [config.packages.nix];}; - lsp = pkgs.mkShellNoCC { - packages = with pkgs; [nil statix deadnix alejandra npins]; + default = pkgs.mkShellNoCC { + packages = with pkgs; [ + # Nix tooling + nil # LSP + statix # static checker + deadnix # dead code finder + + # So that we can interact with plugin sources + npins + + # Formatters + alejandra + deno + ]; }; }; @@ -18,7 +26,11 @@ # testing, but make sure to discard the changes before creating a pull # request. packages.dev = let - configuration = {}; + configuration = { + # This is essentially the configuration that will be passed to the + # builder function. For example: + # vim.languages.nix.enable = true; + }; customNeovim = lib.nvim.neovimConfiguration { inherit pkgs; From 20bcf9e9467b1fe0b2cd735eaaa0b7542cb82b49 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 16:10:22 +0300 Subject: [PATCH 4/8] docs: link NDG syntax documentation; revise keymaps section Signed-off-by: NotAShelf Change-Id: Ie150938b131257fbc143f338b8d9956e6a6a6964 --- docs/manual/hacking.md | 289 ++++++++++++++++++++++++----------------- 1 file changed, 171 insertions(+), 118 deletions(-) diff --git a/docs/manual/hacking.md b/docs/manual/hacking.md index 1dd5aa47..c475d6ff 100644 --- a/docs/manual/hacking.md +++ b/docs/manual/hacking.md @@ -311,24 +311,52 @@ acceptableList = [ ## Testing Changes {#sec-testing-changes} -Once you have made your changes, you will need to test them thoroughly. If it is -a module, add your module option to `configuration.nix` (located in the root of -this project) inside `neovimConfiguration`. Enable it, and then run the maximal -configuration with `nix run .#maximal -Lv` to check for build errors. If neovim -opens in the current directory without any error messages (you can check the -output of `:messages` inside neovim to see if there are any errors), then your -changes are good to go. Open your pull request, and it will be reviewed as soon -as possible. +Once you have made your changes, you will need to test them thoroughly. To make +testing easier you may either use the `configuration.nix` located in the +repository root, or use the development package located in `flake/develop.nix`. +The development package allows you to quickly bootstrap a Neovim configuration +with only the required modules, instead of the packages that consume the +`configuration.nix`, so it is generally preferable. To use it navigate to the +`develop.nix` module, and update the `configuration` set with the Neovim +configuration that you would like to test with. For example: -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. +```nix +{ + # Let's assume you are adding a new module for the Nix language. + # You will need to enable it here + configuration = { + vim.languages.nix.enable = true; + + # You can also enable other plugins that you wish to test with, for example + # none-ls: + vim.lsp.null-ls = { + enable = true; + setupOpts = { /* Your setup options here */ }; + }; + }; +``` + +You may then run this package with `nix run .#develop` and check for build or +runtime errors. If Neovim builds and opens without any errors, then your changes +are good to go. Open your pull request, and it will be reviewed as soon as +possible. + +If your changes are rather large, or if you would like to instead test with a +more complex configuration then you might use the `configuration.nix` for +testing. Make your changes, and then build either the default or `maximal` +package to test your changes. + +> [!IMPORTANT] +> `configuration.nix` is a module used to bootstrap **demo** packages and should +> generally not be changed unless migrating old APIs or updating the set of +> default plugins. Similarly, the `develop.nix` file is for reference, and +> testing configurations **should not be committed**. ## Adding Documentation {#sec-guidelines-documentation} [Nixpkgs Flavoured Markdown]: https://github.com/NixOS/nixpkgs/blob/master/doc/README.md#syntax [in-house documentation generator]: https://github.com/feel-co/ndg +[library documentation]: https://github.com/feel-co/ndg/blob/main/ndg-commonmark/docs/SYNTAX.md Almost all changes to **nvf**'s codebase warrant updates to the documentation. At the very least, you must update the relevant changelog document to describe @@ -345,7 +373,10 @@ As a general rule of thumb: 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. +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 @@ -369,7 +400,9 @@ $ nix build .#docs-linkcheck ``` You must ensure that the **HTML Documentation** builds before submitting a pull -request. +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 @@ -380,13 +413,30 @@ manual for users hoping to learn what has changed. To maintain consistency, you must follow the following format in the changelog: ```markdown -[](https://github.com/): +[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} @@ -395,108 +445,10 @@ To maintain consistency, you must follow the following format in the changelog: - We broke everything, please migrate! ``` -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. - -## 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 -{ - vim.keymaps = [ - { - key = "wq"; - mode = ["n"]; - action = ":wq"; - silent = true; - desc = "Save file and quit"; - } - ]; -} -``` - -There are many settings available in the options. Please refer to the -[documentation](/options.html#option-vim-keymaps) to see a list of them. - -**nvf** provides a helper function, so that you don't have to write the mapping -attribute sets every time: - -- `mkKeymap`, which mimics Neovim's `vim.keymap.set` function - -You can read the source code of some modules to see them in action, but the -usage should look something like this: - -```nix -# plugindefinition.nix -{lib, ...}: let - inherit (lib.options) mkEnableOption; - inherit (lib.nvim.binds) mkMappingOption; -in { - options.vim.plugin = { - enable = mkEnableOption "Enable plugin"; - - # Mappings should always be inside an attrset called mappings - mappings = { - workspaceDiagnostics = mkMappingOption "Workspace diagnostics [trouble]" "lwd"; - documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "ld"; - lspReferences = mkMappingOption "LSP References [trouble]" "lr"; - quickfix = mkMappingOption "QuickFix [trouble]" "xq"; - locList = mkMappingOption "LOCList [trouble]" "xl"; - symbols = mkMappingOption "Symbols [trouble]" "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 "Trouble toggle diagnostics" {desc = mappings.workspaceDiagnostics.description;}) - (mkKeymap "n" keys.documentDiagnostics "Trouble toggle diagnostics filter.buf=0" {desc = mappings.documentDiagnostics.description;}) - (mkKeymap "n" keys.lspReferences "Trouble toggle lsp_references" {desc = mappings.lspReferences.description;}) - (mkKeymap "n" keys.quickfix "Trouble toggle quickfix" {desc = mappings.quickfix.description;}) - (mkKeymap "n" keys.locList "Trouble toggle loclist" {desc = mappings.locList.description;}) - (mkKeymap "n" keys.symbols "Trouble toggle symbols" {desc = mappings.symbols.description;}) - ]; - }; -} -``` - - - -> [!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. +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} @@ -593,7 +545,7 @@ your package to the plugin builder (`pluginBuilders`) function manually in } ``` -### Modular setup options {#sec-modular-setup-options} +### Modular Setup Options {#sec-modular-setup-options} Most plugins is initialized with a call to `require('plugin').setup({...})`. @@ -768,3 +720,104 @@ require('lz.n').load({ A full list of options can be found in the [`vim.lazy.plugins` spec] on the rendered manual. + +## Keybinds {#sec-keybinds} + +[extended standard library]: https://github.com/NotAShelf/nvf/tree/main/lib + +As of 0.4, there exists an API for writing your own keybinds and a couple of +useful utility functions are available in the [extended standard library]. The +following section contains a general overview to how you may utilize said +functions. + +### Custom Key Mappings Support for a Plugin {#sec-custom-key-mappings} + +To set a mapping, you should define it in `vim.keymaps`. As an example, a simple +keybinding can look like this: + +```nix +{ + vim.keymaps = [ + { + key = "wq"; + mode = ["n"]; + action = ":wq"; + 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]" "lwd"; + documentDiagnostics = mkMappingOption "Document diagnostics [trouble]" "ld"; + lspReferences = mkMappingOption "LSP References [trouble]" "lr"; + quickfix = mkMappingOption "QuickFix [trouble]" "xq"; + locList = mkMappingOption "LOCList [trouble]" "xl"; + symbols = mkMappingOption "Symbols [trouble]" "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 "Trouble toggle diagnostics" {desc = mappings.workspaceDiagnostics.description;}) + (mkKeymap "n" keys.documentDiagnostics "Trouble toggle diagnostics filter.buf=0" {desc = mappings.documentDiagnostics.description;}) + (mkKeymap "n" keys.lspReferences "Trouble toggle lsp_references" {desc = mappings.lspReferences.description;}) + (mkKeymap "n" keys.quickfix "Trouble toggle quickfix" {desc = mappings.quickfix.description;}) + (mkKeymap "n" keys.locList "Trouble toggle loclist" {desc = mappings.locList.description;}) + (mkKeymap "n" keys.symbols "Trouble toggle symbols" {desc = mappings.symbols.description;}) + ]; + }; +} +``` + + + +> [!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. From a4bff9749a73cf662fbdbcc6d7a4d22ba6316200 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 16:15:43 +0300 Subject: [PATCH 5/8] flake: add a Markdown formatting check; add Deno to formatting wrapper Signed-off-by: NotAShelf Change-Id: I05593a413696ac3c6f03b2108f7ddd816a6a6964 --- flake.nix | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/flake.nix b/flake.nix index 31e8d0f1..9a7fc438 100644 --- a/flake.nix +++ b/flake.nix @@ -57,7 +57,7 @@ perSystem = {pkgs, ...}: { # Provides the default formatter for 'nix fmt', which will format the - # entire tree with Alejandra. The wrapper script is necessary due to + # entire Nix source with Alejandra. The wrapper script is necessary due to # changes to the behaviour of Nix, which now encourages wrappers for # tree-wide formatting. formatter = pkgs.writeShellApplication { @@ -66,11 +66,15 @@ runtimeInputs = [ pkgs.alejandra pkgs.fd + pkgs.deno ]; text = '' # Find Nix files in the tree and format them with Alejandra - fd "$@" -t f -e nix -x alejandra -q '{}' + fd "$@" -t f -e nix -x nixfmt -q '{}' + + # Same for Markdown files, but with deno + fd "$@" -t f -e md -x deno fmt '{}' ''; }; @@ -81,7 +85,16 @@ # This can be initiated with `nix build .#checks..nix-fmt` # or with `nix flake check` nix-fmt = pkgs.runCommand "nix-fmt-check" {nativeBuildInputs = [pkgs.alejandra];} '' - alejandra --check ${self} < /dev/null | tee $out + alejandra --check ${self} < /dev/null + touch $out + ''; + + # Check if Markdown sources are properly formatted + # This can be initiated with `nix build .#checks..md-fmt` + # or with `nix flake check` + md-fmt = pkgs.runCommand "md-fmt-check" {nativeBuildInputs = [pkgs.deno];} '' + deno fmt --check ${self} --ext md < /dev/null + touch $out ''; }; }; From 9f7da0727a01dc8b4aa1cf3a552eabd68f0e9ebb Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 16:17:03 +0300 Subject: [PATCH 6/8] ci: fix workflow id for formatting check Signed-off-by: NotAShelf Change-Id: I44b40a5e771022cb94b8e0e9405375216a6a6964 --- .github/workflows/check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 5583213e..e3a3a7ed 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -28,7 +28,7 @@ jobs: - name: Check Flake run: nix flake check - format-with-alejandra: + format-sources: name: "Check formatting" runs-on: ubuntu-latest if: "!contains(github.event.pull_request.title, '[skip ci]')" From 8a1ef233ebc8fe106ff734487e73ef604d203c2b Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 16:33:49 +0300 Subject: [PATCH 7/8] docs: fix headings; move quirks to `includes` block' Signed-off-by: NotAShelf Change-Id: Ie853fc60a60c6ff6a945dc67560639ac6a6a6964 --- docs/manual/configuring.md | 9 ++--- docs/manual/index.md | 15 ++++---- docs/manual/installation/modules/flakes.md | 7 ++-- .../installation/modules/home-manager.md | 6 ++-- docs/manual/installation/modules/nixos.md | 4 +-- .../installation/standalone/home-manager.md | 2 +- docs/manual/installation/standalone/nixos.md | 2 +- docs/manual/quirks.md | 35 ++++--------------- docs/manual/quirks/nodejs.md | 29 +++++++++++++++ 9 files changed, 61 insertions(+), 48 deletions(-) create mode 100644 docs/manual/quirks/nodejs.md diff --git a/docs/manual/configuring.md b/docs/manual/configuring.md index 99e1755f..9a1b71cf 100644 --- a/docs/manual/configuring.md +++ b/docs/manual/configuring.md @@ -3,10 +3,11 @@ [helpful tips section]: ./tips.html#ch-helpful-tips [options reference]: ./options.html -nvf allows for _very_ extensive configuration in Neovim through the Nix module -interface. The below chapters describe several of the options exposed in nvf for -your convenience. You might also be interested in the [helpful tips section] for -more advanced or unusual configuration options supported by nvf. +**nvf** allows for _very_ extensive configuration in Neovim through the Nix +module interface. The below chapters describe several of the options exposed in +nvf for your convenience. You might also be interested in the +[helpful tips section] for more advanced or unusual configuration options +supported by nvf. Note that this section does not cover module _options_. For an overview of all module options provided by nvf, please visit the [options reference] diff --git a/docs/manual/index.md b/docs/manual/index.md index bb2a5901..fec434a9 100644 --- a/docs/manual/index.md +++ b/docs/manual/index.md @@ -6,15 +6,18 @@ Generated for nvf @NVF_VERSION@ ### What is nvf {#sec-what-is-it} -**nvf** is a highly modular, configurable, extensible and easy to use Neovim -configuration framework built and designed to be used with Nix. Boasting -flexibility, robustness and ease of use, this project allows you to configure a -fully featured Neovim instance with a few lines of Nix with lots of options for -advanced users as well. +[Nix]: https://nixos.org + +**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_. ## Try it Out {#ch-try-it-out} -Thanks to the portability of Nix, you can try out nvf without actually +Thanks to the portability of Nix, you can try out **nvf** without actually installing it to your machine. Below are the commands you may run to try out different configurations provided by this flake. As of v0.5, two specialized configurations are provided: diff --git a/docs/manual/installation/modules/flakes.md b/docs/manual/installation/modules/flakes.md index 273d2b00..88b6e929 100644 --- a/docs/manual/installation/modules/flakes.md +++ b/docs/manual/installation/modules/flakes.md @@ -1,7 +1,7 @@ -### Prerequisites {#sec-flakes-prerequisites} +#### Prerequisites {#sec-flakes-prerequisites} -To install nvf with flakes, you must make sure the following requirements are -met. +To install **nvf** with flakes, you must make sure the following requirements +are met. 1. Nix 2.4 or later must be installed. You may use `nix-shell` to get a later version of Nix from nixpkgs. @@ -29,5 +29,6 @@ met. following additional flags to `nix` and `home-manager`: ```sh + # Temporarily enables "nix-command" and "flakes" experimental features. $ nix --extra-experimental-features "nix-command flakes" ``` diff --git a/docs/manual/installation/modules/home-manager.md b/docs/manual/installation/modules/home-manager.md index 37d35e2b..916208ce 100644 --- a/docs/manual/installation/modules/home-manager.md +++ b/docs/manual/installation/modules/home-manager.md @@ -1,7 +1,7 @@ -# Home-Manager Module {#ch-hm-module} +## Home Manager Module {#ch-hm-module} -The home-manager module allows us to customize the different `vim` options from -inside the home-manager configuration without having to call for the wrapper +The Home Manager module allows us to customize the different `vim` options from +inside the Home Manager configuration without having to call for the wrapper yourself. It is the recommended way to use **nvf** alongside the NixOS module depending on your needs. diff --git a/docs/manual/installation/modules/nixos.md b/docs/manual/installation/modules/nixos.md index 946905c1..0186465b 100644 --- a/docs/manual/installation/modules/nixos.md +++ b/docs/manual/installation/modules/nixos.md @@ -1,11 +1,11 @@ -# NixOS Module {#ch-nixos-module} +## NixOS Module {#ch-nixos-module} The NixOS module allows us to customize the different `vim` options from inside the NixOS configuration without having to call for the wrapper yourself. It is the recommended way to use **nvf** alongside the home-manager module depending on your needs. -## With Flakes {#sec-nixos-flakes} +### With Flakes {#sec-nixos-flakes} ```{=include=} flakes.md diff --git a/docs/manual/installation/standalone/home-manager.md b/docs/manual/installation/standalone/home-manager.md index 0c1dc025..ab604df9 100644 --- a/docs/manual/installation/standalone/home-manager.md +++ b/docs/manual/installation/standalone/home-manager.md @@ -1,4 +1,4 @@ -# Standalone Installation on Home-Manager {#ch-standalone-hm} +## Standalone Installation on Home-Manager {#ch-standalone-hm} Your built Neovim configuration can be exposed as a flake output to make it easier to share across machines, repositories and so on. Or it can be added to diff --git a/docs/manual/installation/standalone/nixos.md b/docs/manual/installation/standalone/nixos.md index 65dc9205..d5c48c66 100644 --- a/docs/manual/installation/standalone/nixos.md +++ b/docs/manual/installation/standalone/nixos.md @@ -1,4 +1,4 @@ -# Standalone Installation on NixOS {#ch-standalone-nixos} +## Standalone Installation on NixOS {#ch-standalone-nixos} Your built Neovim configuration can be exposed as a flake output to make it easier to share across machines, repositories and so on. Or it can be added to diff --git a/docs/manual/quirks.md b/docs/manual/quirks.md index 17f7abaf..056f7f5e 100644 --- a/docs/manual/quirks.md +++ b/docs/manual/quirks.md @@ -5,30 +5,9 @@ be it a result of generating Lua from Nix, or the state of packaging. This page, in turn, will list any known modules or plugins that are known to misbehave, and possible workarounds that you may apply. -## NodeJS {#ch-quirks-nodejs} - -### eslint-plugin-prettier {#sec-eslint-plugin-prettier} - -When working with NodeJS, everything works as expected, but some projects have -settings that can fool nvf. - -If [this plugin](https://github.com/prettier/eslint-plugin-prettier) or similar -is included, you might get a situation where your eslint configuration diagnoses -your formatting according to its own config (usually `.eslintrc.js`). - -The issue there is your formatting is made via prettierd. - -This results in auto-formatting relying on your prettier config, while your -eslint config diagnoses formatting -[which it's not supposed to](https://prettier.io/docs/en/comparison.html)) - -In the end, you get discrepancies between what your editor does and what it -wants. - -Solutions are: - -1. Don't add a formatting config to eslint, and separate prettier and eslint. -2. PR this repo to add an ESLint formatter and configure nvf to use it. +```{=include=} +quirks/nodejs.md +``` ## Bugs & Suggestions {#ch-bugs-suggestions} @@ -36,10 +15,10 @@ Solutions are: [discussions tab]: https://github.com/notashelf/nvf/discussions [pull requests tab]: https://github.com/notashelf/nvf/pulls -Some quirks are not exactly quirks, but bugs in the module systeme. If you -notice any issues with nvf, or this documentation, then please consider -reporting them over at the [issue tracker]. Issues tab, in addition to the +Some quirks are not exactly quirks, but bugs in the module system. If you notice +any issues with **nvf**, or this documentation, then please consider reporting +them over at the [issue tracker]. Issues tab, in addition to the [discussions tab] is a good place as any to request new features. -You may also consider submitting bugfixes, feature additions and upstreamed +You may also consider submitting bug fixes, feature additions and upstreamed changes that you think are critical over at the [pull requests tab]. diff --git a/docs/manual/quirks/nodejs.md b/docs/manual/quirks/nodejs.md new file mode 100644 index 00000000..f7031af6 --- /dev/null +++ b/docs/manual/quirks/nodejs.md @@ -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. From 797748a20ced3327ff5afaaf667697d20418c9d7 Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 18 Dec 2025 16:36:42 +0300 Subject: [PATCH 8/8] flake: use the correct formatter for Nix; suppress deno output Signed-off-by: NotAShelf Change-Id: Ic39d3a2448cd4b4f241909779f7ead596a6a6964 --- flake.nix | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/flake.nix b/flake.nix index 9a7fc438..becc838c 100644 --- a/flake.nix +++ b/flake.nix @@ -71,10 +71,12 @@ text = '' # Find Nix files in the tree and format them with Alejandra - fd "$@" -t f -e nix -x nixfmt -q '{}' + echo "Formatting Nix files" + fd "$@" -t f -e nix -x alejandra -q '{}' # Same for Markdown files, but with deno - fd "$@" -t f -e md -x deno fmt '{}' + echo "Formatting Markdown files" + fd "$@" -t f -e md -x deno fmt -q '{}' ''; }; @@ -93,7 +95,7 @@ # This can be initiated with `nix build .#checks..md-fmt` # or with `nix flake check` md-fmt = pkgs.runCommand "md-fmt-check" {nativeBuildInputs = [pkgs.deno];} '' - deno fmt --check ${self} --ext md < /dev/null + deno fmt --check ${self} --ext md touch $out ''; };