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.