docs: fix headings; move quirks to includes block'

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: Ie853fc60a60c6ff6a945dc67560639ac6a6a6964

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
+**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
 module options provided by nvf, please visit the [options reference]

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
+[Nix]: https://nixos.org
-configuration framework built and designed to be used with Nix. Boasting
+
-flexibility, robustness and ease of use, this project allows you to configure a
+**nvf** is a highly modular, configurable, extensible and _easy to use_ Neovim
-fully featured Neovim instance with a few lines of Nix with lots of options for
+configuration framework built for and designed to be used with [Nix]. Boasting
-advanced users as well.
+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:

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
+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
    version of Nix from nixpkgs.
@@ -29,5 +29,6 @@ met.
      following additional flags to `nix` and `home-manager`:
 
      ```sh
+     # Temporarily enables "nix-command" and "flakes" experimental features.
      $ nix --extra-experimental-features "nix-command flakes" <sub-commands>
      ```

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
+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
 depending on your needs.
 

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

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

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

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}
+```{=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}
 
@@ -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
+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.
 
-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].

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.