Merge 8f1b38ee81 into c08d0a79cc

.github/README.md

@@ -48,7 +48,7 @@
 [Documentation]: #documentation
 [Help]: #help
 [Contribute]: #contributing
-[FAQ]: #faq
+[FAQ]: #frequently-asked-questions
 [Credits]: #credits
 
 **[<kbd><br> Features <br></kbd>][Features]**
@@ -56,7 +56,7 @@
 **[<kbd><br> Documentation <br></kbd>][Documentation]**
 **[<kbd><br> Help <br></kbd>][Help]**
 **[<kbd><br> Contribute <br></kbd>][Contribute]**
-**[<kbd><br> FAQ <br></kbd>][Faq]** **[<kbd><br> Credits <br></kbd>][Credits]**
+**[<kbd><br> FAQ <br></kbd>][FAQ]** **[<kbd><br> Credits <br></kbd>][Credits]**
 
 </p></div>
 
@@ -64,12 +64,21 @@
 
 ## Features
 
+[standalone]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-installation
+[NixOS module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-nixos
+[Home-Manager module]: https://notashelf.github.io/nvf/index.xhtml#ch-standalone-hm
+
+- **Simple**: One language to rule them all! Use Nix to configure everything,
+  with additional Lua Support
 - **Reproducible**: Your configuration will behave the same _anywhere_. No
   surprises, promise!
 - **Portable**: nvf depends _solely_ on your Nix store, and nothing else. No
   more global binaries! Works on all platforms, without hassle.
+  - Options to install [standalone], [NixOS module] or [Home-Manager module].
 - **Customizable**: There are _almost no defaults_ to annoy you. nvf is fully
   customizable through the Nix module system.
+- Not comfortable with a full-nix config or want to bring your Lua config? You
+  can do just that, no unnecessary restrictions.
 - **Well-documented**: Documentation is priority. You will _never_ face
   undocumented, obscure behaviour.
 - **Idiomatic**: nvf does things ✨ _the right way_ ✨ - the codebase is, and
@@ -120,7 +129,9 @@ instructions.
 
 ## Documentation
 
-The _recommended_ way of installing **nvf** is using either the NixOS or the
+### Installation
+
+The _recommended_ way of installing nvf is using either the NixOS or the
 Home-Manager module, though it is completely possible and no less supported to
 install **nvf** as a standalone package, or a flake output.
 
@@ -138,11 +149,13 @@ Please create an issue on the [issue tracker] if you find the documentation
 lacking or confusing. Any improvements to the documentation through pull
 requests are also welcome, and appreciated.
 
-## Help
+## Getting Help
 
-You can create an issue on the [issue tracker] to ask questions or report bugs.
+If you are confused, stuck or would like to ask a simple question; you may
-I am not yet on spaces like matrix or IRC, so please use the issue tracker for
+create an issue on the [issue tracker] to ask questions or report bugs.
-now.
+
+We are not not yet on spaces like matrix or IRC, so please use the issue tracker
+for now.
 
 ## Contributing
 
@@ -152,7 +165,7 @@ submitting a pull request. You can also create an issue on the [issue tracker]
 before submitting a pull request if you would like to discuss a feature or bug
 fix.
 
-## FAQ
+## Frequently Asked Questions
 
 [appropriate issue template]: https://github.com/NotAShelf/nvf/issues/new/choose
 [list of branches]: https://github.com/NotAShelf/nvf/branches
@@ -160,13 +173,15 @@ fix.
 
 **Q**: What platforms are supported?
 <br/> **A**: nvf actively supports Linux and Darwin platforms using standalone
-Nix, NixOS or Home-Manager. Please take a look at the
+Nix, NixOS or Home-Manager. Please take a look at the [nvf manual] for available
+installation instructions.
 
 **Q**: Can you add _X_?
 <br/> **A**: Maybe! It is not one of our goals to support each and every Neovim
 plugin, however, I am always open to new modules and plugin setup additions to
 **nvf**. Use the [appropriate issue template] and I will consider a module
-addition. As mentioned before, PRs adding new features are also welcome.
+addition. As mentioned before, pull requests to add new features are also
+welcome.
 
 **Q**: A plugin I need is not available in **nvf**. What to do?
 <br/> **A**: **nvf** exposes several APIs for you to be able to add your own
@@ -185,22 +200,26 @@ better prepare to breaking changes.
 
 ### Contributors
 
-Special, heart-felt thanks to
+[mnw]: https://github.com/gerg-l/mnw
 
-- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts
+nvf would not be what it is today without the awesome people below. Special,
-- [@FlafyDev](https://github.com/FlafyDev) - For getting the home-manager to
+heart-felt thanks to
-  work
+
+- [@fufexan](https://github.com/fufexan) - For the transition to flake-parts and
+  invaluable Nix assistance.
+- [@FlafyDev](https://github.com/FlafyDev) - For getting home-manager module to
+  work and Nix assistance.
 - [@n3oney](https://github.com/n3oney) - For making custom keybinds finally
-  possible
+  possible, and other module additions.
 - [@horriblename](https://github.com/horriblename) - For actively implementing
-  planned features and quality of life updates
+  planned features and quality of life updates.
 - [@Yavko](https://github.com/Yavko) - For the amazing **nvf** logo
 - [@FrothyMarrow](https://github.com/FrothyMarrow) - For seeing mistakes that I
-  could not
+  could not.
-- [@Diniamo](https://github.com/Diniamo) - For actively submitting PRs, pull
+- [@Diniamo](https://github.com/Diniamo) - For actively submitting pull
-  requests and overall assistence
+  requests, issues and assistance with maintenance of nvf.
-- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, mnw and
+- [@Gerg-l](https://github.com/gerg-l) - For the modern Neovim wrapper, [mnw],
-  occasional code improvements
+  and occasional code improvements.
 
 and everyone who has submitted issues or pull requests!
 
@@ -214,7 +233,7 @@ including:
   is originally based on.
 - [@sioodmy's](https://github.com/sioodmy)
   [dotfiles](https://github.com/sioodmy/dotfiles) that inspired the design
-  choices.
+  choices for UI and plugin defaults.
 - [@wiltaylor's](https://github.com/wiltaylor)
   [neovim-flake](https://github.com/wiltaylor/neovim-flake) for plugin and
   design ideas.
@@ -229,10 +248,11 @@ recommend checking their work out.
 ## License
 
 Following the license of the
-[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), **nvf**
+[original neovim-flake](https://github.com/jordanisaacs/neovim-flake), nvf has
-has been made available under the [**MIT License**](LICENSE). However, all
+been made available under the [**MIT License**](LICENSE). However, all assets
-assets and documentation are published under the
+and documentation are published under the
-[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE).
+[**CC BY License**](https://github.com/NotAShelf/nvf/blob/main/.github/assets/LICENSE)
+under explicit permission by the artist.
 
 <h6 align="center">Yes, this includes the logo work too. Stop taking artwork that is not yours!</h6>
 

docs/manual.nix

@@ -1,63 +1,112 @@
 {
   lib,
   stdenvNoCC,
+  fetchzip,
+  runCommandLocal,
   # build inputs
   nixos-render-docs,
   documentation-highlighter,
+  dart-sass,
   path,
   # nrd configuration
   release,
   optionsJSON,
-}:
+} @ args: let
-stdenvNoCC.mkDerivation {
+  manual-release = args.release or "unstable";
-  name = "nvf-manual";
+
-  src = builtins.path {
+  scss-reset = fetchzip {
-    path = lib.sourceFilesBySuffices ./manual [".md"];
+    url = "https://github.com/Frontend-Layers/scss-reset/archive/refs/tags/1.4.2.zip";
-    name = "nvf-manual";
+    hash = "sha256-cif5Sx8Ca5vxdw/mNAgpulLH15TwmzyJFNM7JURpoaE=";
   };
 
+  compileStylesheet = runCommandLocal "compile-nvf-stylesheet" {} ''
+    mkdir -p $out
+
+    tmpfile=$(mktemp -d)
+    trap "rm -r $tmpfile" EXIT
+
+    ln -s "${scss-reset}/build" "$tmpfile/scss-reset"
+
+    ${dart-sass}/bin/sass --load-path "$tmpfile" \
+      ${./static/style.scss} "$out/style.css"
+
+    echo "Generated styles"
+  '';
+in
+  stdenvNoCC.mkDerivation {
+    name = "nvf-manual";
+    src = builtins.path {
+      name = "nvf-manual-${manual-release}";
+      path = lib.sourceFilesBySuffices ./manual [".md" ".md.in"];
+    };
+
+    strictDependencies = true;
     nativeBuildInputs = [nixos-render-docs];
 
+    postPatch = ''
+      ln -s ${optionsJSON}/share/doc/nixos/options.json ./config-options.json
+    '';
+
     buildPhase = ''
       dest="$out/share/doc/nvf"
       mkdir -p "$(dirname "$dest")"
-    mkdir -p $dest/{highlightjs,media}
+      mkdir -p $dest/{highlightjs,script}
 
+      # Copy highlight scripts to /highlights in document root.
       cp -vt $dest/highlightjs \
         ${documentation-highlighter}/highlight.pack.js \
         ${documentation-highlighter}/LICENSE \
         ${documentation-highlighter}/mono-blue.css \
         ${documentation-highlighter}/loader.js
 
+      # Copy anchor scripts to the script directory in document root.
+      cp -vt "$dest"/script \
+        ${./static/script}/anchor-min.js \
+        ${./static/script}/anchor-use.js
+
       substituteInPlace ./options.md \
-      --subst-var-by \
+        --subst-var-by OPTIONS_JSON ./config-options.json
-        OPTIONS_JSON \
-        ${optionsJSON}/share/doc/nixos/options.json
 
       substituteInPlace ./manual.md \
-      --subst-var-by \
+        --subst-var-by NVF_VERSION ${manual-release}
-        NVF_VERSION \
-        ${release}
 
-    # copy stylesheet
+      substituteInPlace ./hacking/additional-plugins.md \
-    cp ${./static/style.css} "$dest/style.css"
+        --subst-var-by NVF_REPO "https://github.com/notashelf/nvf/blob/${manual-release}"
 
-    # copy release notes
+      # Move compiled stylesheet
+      cp -vt $dest \
+        ${compileStylesheet}/style.css
+
+      # Move release notes
       cp -vr ${./release-notes} release-notes
 
-    # generate manual from
+      # Generate final manual from a set of parameters. Explanation of the CLI flags are
+      # as follows:
+      #
+      #  1. --manpage-urls will allow you to use manual pages as they are defined in
+      #  the nixpkgs documentation.
+      #  2. --revision is the project revision as it is defined in 'release.json' in the
+      #  repository root
+      #  3. --script will inject a given Javascript file into the resulting pages inside
+      #  the <script> tag.
+      #  4. --toc-depth will determine the depth of the initial Table of Contents while
+      #  --section-toc-depth will determine the depth of per-section Table of Contents
+      #  sections.
       nixos-render-docs manual html \
         --manpage-urls ${path + "/doc/manpage-urls.json"} \
-      --revision ${lib.trivial.revisionWithDefault release} \
+        --revision ${lib.trivial.revisionWithDefault manual-release} \
-      --stylesheet style.css \
+        --stylesheet "$dest"/style.css \
-      --script highlightjs/highlight.pack.js \
+        --script ./highlightjs/highlight.pack.js \
-      --script highlightjs/loader.js \
+        --script ./highlightjs/loader.js \
+        --script script/anchor-use.js \
+        --script script/anchor-min.js \
         --toc-depth 2 \
         --section-toc-depth 1 \
         manual.md \
         "$dest/index.xhtml"
 
+        # Hydra support. Probably not necessary.
         mkdir -p $out/nix-support/
         echo "doc manual $dest index.html" >> $out/nix-support/hydra-build-products
     '';
-}
+  }

docs/manual/configuring/custom-plugins/configuring.md

@@ -1,12 +1,13 @@
 # Configuring {#sec-configuring-plugins}
 
-Just making the plugin to your Neovim configuration available might not always be enough. In that
+Just making the plugin to your Neovim configuration available might not always
-case, you can write custom lua config using either `config.vim.lazy.plugins.*.setupOpts`
+be enough. In that case, you can write custom lua config using either
-`config.vim.extraPlugins.*.setup` or `config.vim.luaConfigRC`. 
+`config.vim.lazy.plugins.*.setupOpts` `config.vim.extraPlugins.*.setup` or
+`config.vim.luaConfigRC`.
 
-The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule` and `setupOpt` can
+The first option uses an extended version of `lz.n`'s PluginSpec. `setupModule`
-be used if the plugin uses a `require('module').setup(...)` pattern. Otherwise, the `before` and
+and `setupOpt` can be used if the plugin uses a `require('module').setup(...)`
-`after` hooks should do what you need.
+pattern. Otherwise, the `before` and `after` hooks should do what you need.
 
 ```nix
 {
@@ -24,10 +25,11 @@ be used if the plugin uses a `require('module').setup(...)` pattern. Otherwise,
 }
 ```
 
-The second option uses an attribute set, which maps DAG section names to a custom type, which has
+The second option uses an attribute set, which maps DAG section names to a
-the fields `package`, `after`, `setup`. They allow you to set the package of the plugin, the
+custom type, which has the fields `package`, `after`, `setup`. They allow you to
-sections its setup code should be after (note that the `extraPlugins` option has its own DAG
+set the package of the plugin, the sections its setup code should be after (note
-scope), and the its setup code respectively. For example:
+that the `extraPlugins` option has its own DAG scope), and the its setup code
+respectively. For example:
 
 ```nix
 config.vim.extraPlugins = with pkgs.vimPlugins; {
@@ -56,13 +58,17 @@ For example:
 }
 ```
 
-:::{.note}
+<!-- deno-fmt-ignore-start -->
-If your configuration needs to be put in a specific place in the config, you
+
-can use functions from `inputs.nvf.lib.nvim.dag` to order it. Refer to
+::: {.note}
-https://github.com/nix-community/home-manager/blob/master/modules/lib/dag.nix
+One of the greatest strengths of nvf is the ability to order
+snippets of configuration via the DAG system. It will allow specifying positions
+of individual sections of configuration as needed. nvf provides helper functions
+in the extended library, usually under `inputs.nvf.lib.nvim.dag` that you may
+use.
+
+Please refer to the [DAG section](/index.xhtml#ch-dag-entries) in the nvf manual
 to find out more about the DAG system.
 :::
 
-If you successfully made your plugin work, please feel free to create a PR to
+<!-- deno-fmt-ignore-end -->
-add it to **nvf** or open an issue with your findings so that we can make it
-available for everyone easily.

docs/manual/configuring/custom-plugins/legacy-method.md

@@ -1,6 +1,6 @@
 # Legacy Method {#sec-legacy-method}
 
-Prior to version 0.5, the method of adding new plugins was adding the plugin
+Prior to version v0.5, the method of adding new plugins was adding the plugin
 package to `vim.startPlugins` and add its configuration as a DAG under one of
 `vim.configRC` or `vim.luaConfigRC`. Users who have not yet updated to 0.5, or
 prefer a more hands-on approach may use the old method where the load order of
@@ -8,13 +8,14 @@ the plugins is determined by DAGs.
 
 ## Adding plugins {#sec-adding-plugins}
 
-To add a plugin to **nvf**'s runtime, you may add it
+To add a plugin not available in nvf as a module to your configuration, you may
+add it to [](#opt-vim.startPlugins) in order to make it available to Neovim at
+runtime.
 
 ```nix
 {pkgs, ...}: {
-  # add a package from nixpkgs to startPlugins
+  # Add a Neovim plugin from Nixpkgs to the runtime.
-  vim.startPlugins = [
+  vim.startPlugins = [pkgs.vimPlugins.aerial-nvim];
-    pkgs.vimPlugins.aerial-nvim  ];
 }
 ```
 
@@ -23,7 +24,9 @@ provide configuration as a DAG using the **nvf** extended library.
 
 ```nix
 {inputs, ...}: let
-  # assuming you have an input called nvf pointing at the nvf repository
+  # This assumes you have an input called 'nvf' in your flake inputs
+  # and 'inputs' in your specialArgs. In the case you have passed 'nvf'
+  # to specialArgs, the 'inputs' prefix may be omitted.
   inherit (inputs.nvf.lib.nvim.dag) entryAnywhere;
 in {
   vim.luaConfigRC.aerial-nvim= entryAnywhere ''

docs/manual/hacking.md

@@ -1,16 +1,25 @@
 # Hacking nvf {#ch-hacking}
 
-**nvf** is designed for developers as much as it is for the end user. I would like any potential contributor
+[open issues]: https://github.com/notashelf/nvf/issues
-to be able to propagate their desired changes into the repository without the extra effort. As such, below are guides
+[new issue]: https://github.com/notashelf/nvf/issues/new
-(and guidelines) to streamline the contribution process and ensure that your valuable input seamlessly integrates
-into **nvf**'s development without leaving question marks in your head.
 
-This section is mainly directed towards those who wish to contribute code into **nvf**. If you wish to instead
+nvf is designed for the developer as much as it is designed for the end-user. We
-report a bug or discuss a potential feature implementation, first look among the
+would like for any contributor to be able to propagate their changes, or add new
-already [open issues](https://github.com/notashelf/nvf/issues) and if no matching issue exists you may open
+features to the project with minimum possible friction. As such, below are the
-a [new issue](https://github.com/notashelf/nvf/issues/new) and describe your problem/request. While creating an
+guides and guidelines written to streamline the contribution process and to
-issue, please try to include as much information as you can, ideally also include relevant context in which an issue
+ensure that your valuable input integrates into nvf's development as seamlessly
-occurs or a feature should be implemented.
+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
+feature implementation (which you do not wish to implement yourself) first look
+among the already [open issues] and if no matching issue exists you may open a
+[new issue] and describe your problem/request.
+
+While creating an issue, please try to include as much information as you can,
+ideally also include relevant context in which an issue occurs or a feature
+should be implemented. If you wish to make a contribution, but feel stuck -
+please do not be afraid to submit a pull request, we will help you get it in.
 
 ```{=include=} sections
 hacking/getting-started.md

docs/manual/hacking/additional-plugins.md

@@ -1,10 +1,9 @@
 # Adding Plugins {#sec-additional-plugins}
 
-To add a new Neovim plugin, first add the source url in the inputs section of `flake.nix`
+To add a new Neovim plugin, first add the source url in the inputs section of
-with the prefix `plugin-`
+`flake.nix` with the prefix `plugin-`
 
 ```nix
-
 {
   inputs = {
     # ...
@@ -17,13 +16,18 @@ with the prefix `plugin-`
 }
 ```
 
+Prepending `plugin-` to the name of the input will allow nvf to automatically
+discover inputs that are marked as plugins, and make them available in
+`vim.startPlugins` or other areas that require a very specific plugin type as it
+is defined in `@NVF_REPO@/lib/types/plugins.nix`
+
 The addition of the `plugin-` prefix will allow **nvf** to autodiscover the
 input from the flake inputs automatically, allowing you to refer to it in areas
 that require a very specific plugin type as defined in `lib/types/plugins.nix`
 
 You can now reference this plugin using its string name, the plugin will be
-built with the name and source URL from the flake input, allowing you to
+built with the name and source URL from the flake input, allowing you to refer
-refer to it as a **string**.
+to it as a **string**.
 
 ```nix
 config.vim.startPlugins = ["neodev-nvim"];
@@ -33,11 +37,11 @@ config.vim.startPlugins = ["neodev-nvim"];
 
 Most plugins is initialized with a call to `require('plugin').setup({...})`.
 
-We use a special function that lets you easily add support for such setup options in a modular way:
+We use a special function that lets you easily add support for such setup
-`mkPluginSetupOption`.
+options in a modular way: `mkPluginSetupOption`.
 
-Once you have added the source of the plugin as shown above, you can define the setup options like
+Once you have added the source of the plugin as shown above, you can define the
-this:
+setup options like this:
 
 ```nix
 # in modules/.../your-plugin/your-plugin.nix
@@ -86,7 +90,8 @@ require('plugin-name').setup({
 })
 ```
 
-Now users can set any of the pre-defined option field, and can also add their own fields!
+Now users can set any of the pre-defined option field, and can also add their
+own fields!
 
 ```nix
 # in user's config
@@ -110,8 +115,8 @@ As you've seen above, `toLuaObject` is used to convert our nix attrSet
 1. nix `null` converts to lua `nil`
 2. number and strings convert to their lua counterparts
 3. nix attrSet/list convert into lua tables
-4. you can write raw lua code using `lib.generators.mkLuaInline`. This
+4. you can write raw lua code using `lib.generators.mkLuaInline`. This function
-   function is part of nixpkgs.
+   is part of nixpkgs.
 
 Example:
 
@@ -127,8 +132,8 @@ vim.your-plugin.setupOpts = {
 
 ## Lazy plugins {#sec-lazy-plugins}
 
-If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it. Lazy
+If the plugin can be lazy-loaded, `vim.lazy.plugins` should be used to add it.
-plugins are managed by `lz.n`.
+Lazy plugins are managed by `lz.n`.
 
 ```nix
 # in modules/.../your-plugin/config.nix
@@ -163,6 +168,7 @@ in {
 ```
 
 This results in the following lua code:
+
 ```lua
 require('lz.n').load({
   {

docs/manual/installation.md

@@ -1,9 +1,12 @@
 # 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
+the standalone installation method, which does not depend on a module system and
-be done on any system that has the Nix package manager or the appropriate modules
+may be done on any system that has the Nix package manager or the appropriate
-for NixOS and home-manager as described in the [module installation section](#ch-module-installation)
+modules for NixOS and home-manager as described in the
+[module installation section].
 
 ```{=include=} chapters
 installation/custom-configuration.md

docs/manual/installation/custom-configuration.md

@@ -1,8 +1,9 @@
 # Standalone Installation {#ch-standalone-installation}
 
-It is possible to install **nvf** without depending on NixOS or home-manager as the parent
+It is possible to install nvf without depending on NixOS or Home-Manager as the
-module system, using the `neovimConfiguration` function exposed by **nvf** extended library.
+parent module system, using the `neovimConfiguration` function exposed in the
-It takes in the configuration as a module, and returns an attribute set as a result.
+extended library. This function will take `modules` and `extraSpecialArgs` as
+arguments, and return the following schema as a result.
 
 ```nix
 {
@@ -13,6 +14,55 @@ It takes in the configuration as a module, and returns an attribute set as a res
 }
 ```
 
+An example flake that exposes your custom Neovim configuration might look like
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    nvf.url = "github:notashelf/nvf";
+  };
+
+  outputs = {
+    self,
+    nixpkgs,
+    ...
+  } @ inputs: {
+    packages."x86_64-linux" = let
+        neovimConfigured = (inputs.nvf.lib.neovimConfiguration {
+          inherit (nixpkgs.legacyPackages."x86_64-linux") pkgs;
+          modules = [{
+              config.vim = {
+                # Enable custom theming options
+                theme.enable = true;
+
+                # Enable Treesitter
+                tree-sitter.enable = true;
+
+                # Other options will go here. Refer to the config
+                # reference in Appendix B of the nvf manual.
+                # ...
+              };
+          }];
+        });
+    in {
+      # Set the default package to the wrapped instance of Neovim.
+      # This will allow running your Neovim configuration with
+      # `nix run` and in addition, sharing your configuration with
+      # other users in case your repository is public.
+      default = neovimConfigured.neovim;
+    };
+  };
+}
+```
+
+<!-- TODO: mention the built-in flake template here when it is added -->
+
+The above setup will allow to set up nvf as a standalone flake, which you can
+build independently from your system configuration while also possibly sharing
+it with others. The next two chapters will detail specific usage of such a setup
+for a package output in the context of NixOS or Home-Manager installation.
+
 ```{=include=} chapters
 standalone/nixos.md
 standalone/home-manager.md

docs/manual/installation/modules.md

@@ -1,5 +1,9 @@
 # Module Installation {#ch-module-installation}
 
+The below chapters will describe installing nvf as NixOS and Home-Manager
+modules. Note that those methods are mutually exclusive, and will likely cause
+path collisions if used simultaneously.
+
 ```{=include=} chapters
 modules/nixos.md
 modules/home-manager.md

docs/manual/installation/modules/home-manager.md

@@ -77,7 +77,9 @@ configure **nvf**.
 ```
 
 ::: {.note}
+
 **nvf** exposes a lot of options, most of which are not referenced in the
-installation sections of the manual. You may find all avaliable options
+installation sections of the manual. You may find all available options in the
-in the [appendix](https://notashelf.github.io/nvf/options)
+[appendix](https://notashelf.github.io/nvf/options)
+
 :::

docs/manual/installation/modules/nixos.md

@@ -76,7 +76,9 @@ configure **nvf**.
 ```
 
 ::: {.note}
+
 **nvf** exposes a lot of options, most of which are not referenced in the
-installation sections of the manual. You may find all avaliable options
+installation sections of the manual. You may find all available options in the
-in the [appendix](https://notashelf.github.io/nvf/options)
+[appendix](https://notashelf.github.io/nvf/options)
+
 :::

docs/manual/installation/standalone/home-manager.md

@@ -1,12 +1,12 @@
 # Standalone Installation on Home-Manager {#ch-standalone-hm}
 
-Your built Neoevim 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
 your system packages to make it available across your system.
 
 The following is an example installation of `nvf` as a standalone package with
 the default theme enabled. You may use other options inside `config.vim` in
-`configModule`, but this example will not cover that.
+`configModule`, but this example will not cover that extensively.
 
 ```nix
 {
@@ -30,23 +30,22 @@ the default theme enabled. You may use other options inside `config.vim` in
     };
 
     customNeovim = nvf.lib.neovimConfiguration {
-      modules = [configModule];
       inherit pkgs;
+      modules = [configModule];
     };
   in {
-    # this will make the package available as a flake input
+    # This will make the package available as a flake output under 'packages'
     packages.${system}.my-neovim = customNeovim.neovim;
 
-    # this is an example home-manager configuration
+    # Example Home-Manager configuration using the configured Neovim package
-    # using the built neovim package
     homeConfigurations = {
       "your-username@your-hostname" = home-manager.lib.homeManagerConfiguration {
         # ...
         modules = [
-          ./home.nix
+          # This will make Neovim available to users using the Home-Manager
-
+          # configuration. To make the package available to all users, prefer
-          # this will make wrapped neovim available in your system packages
+          # environment.systemPackages in your NixOS configuration.
-          {environment.systemPackages = [customNeovim.neovim];}
+          {home.packages = [customNeovim.neovim];}
         ];
         # ...
       };

docs/manual/installation/standalone/nixos.md

@@ -1,12 +1,12 @@
 # Standalone Installation on NixOS {#ch-standalone-nixos}
 
-Your built Neoevim 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
 your system packages to make it available across your system.
 
 The following is an example installation of `nvf` as a standalone package with
 the default theme enabled. You may use other options inside `config.vim` in
-`configModule`, but this example will not cover that.
+`configModule`, but this example will not cover that extensively.
 
 ```nix
 {
@@ -30,21 +30,19 @@ the default theme enabled. You may use other options inside `config.vim` in
     };
 
     customNeovim = nvf.lib.neovimConfiguration {
-      modules = [configModule];
       inherit pkgs;
+      modules = [configModule];
     };
   in {
-    # this will make the package available as a flake input
+    # This will make the package available as a flake output under 'packages'
     packages.${system}.my-neovim = customNeovim.neovim;
 
-    # this is an example nixosConfiguration using the built neovim package
+    # Example nixosConfiguration using the configured Neovim package
     nixosConfigurations = {
       yourHostName = nixpkgs.lib.nixosSystem {
         # ...
         modules = [
-          ./configuration.nix # or whatever your configuration is
+          # This will make wrapped neovim available in your system packages
-
-          # this will make wrapped neovim available in your system packages
           {environment.systemPackages = [customNeovim.neovim];}
         ];
         # ...

docs/manual/manual.md

@@ -17,8 +17,8 @@ configuring.md
 hacking.md
 ```
 
-```{=include=} appendix html:into-file=//plugins.html
+```{=include=} appendix html:into-file=//quirks.html
-plugins.md
+quirks.md
 ```
 
 ```{=include=} appendix html:into-file=//options.html

docs/manual/options.md

@@ -1,8 +1,14 @@
 # Neovim Flake Configuration Options {#ch-options}
 
-Below are the options provided by nvf provided in no particular order.
+Below are the module options provided by nvf, in no particular order. Most
-They may include useful comments and warnings, or examples on how a module option
+options will include useful comments, warnings or setup tips on how a module
-is meant to be used.
+option is meant to be used as well as examples in complex cases.
+
+<!--
+In the manual, individual options may be referenced in Hyperlinks as follows:
+[](#opt-vim.*) If changing the prefix here, do keep in mind the #opt- suffix will have
+to be changed everywhere.
+-->
 
 ```{=include=} options
 id-prefix: opt-

docs/manual/plugins.md

@@ -1,16 +0,0 @@
-# Plugin specific quirks {#ch-plugins}
-
-At times, certain plugins refuse to play nicely. Be it as a result of generating
-lua from Nix, or the state of packaging. This page shall list any plugins that
-are known to misbehave, and potential workarounds.
-
-```{=include=} chapters
-plugins/nodejs.md
-```
-<!--
-If adding a new section, uncomment this part and add your page to
-plugins/<page>.md
-```{=include=} chapters
-plugins/page.md
-```
--->

docs/manual/preface.md

@@ -1,7 +1,20 @@
 # Preface {#ch-preface}
 
-If you noticed a bug caused by **nvf** then please consider reporting it over
+## What is nvf {#sec-what-is-it}
-[the issue tracker](https://github.com/notashelf/nvf/issues).
 
-Bugfixes, feature additions and upstreamed changes from your local configurations
+nvf is a highly modular, configurable, extensible and easy to use Neovim
-are always welcome in the [the pull requests tab](https://github.com/notashelf/nvf/pulls).
+configuration in Nix. Designed for flexibility and ease of use, nvf allows you
+to easily configure your fully featured Neovim instance with a few lines of Nix.
+
+## Bugs & Suggestions {#sec-bugs-suggestions}
+
+[issue tracker]: https://github.com/notashelf/nvf/issues
+[discussions tab]: https://github.com/notashelf/nvf/discussions
+[pull requests tab]: https://github.com/notashelf/nvf/pulls
+
+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
+changes that you think are critical over at the [pull requests tab].

docs/manual/quirks.md

@@ -0,0 +1,13 @@
+# Known Issues and Quirks {#ch-known-issues-quirks}
+
+At times, certain plugins and modules may refuse to play nicely with your setup,
+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.
+
+<!-- If adding a new known quirk, please create a new page in quirks/ and include
+the name of the file here.-->
+
+```{=include=} chapters
+quirks/nodejs.md
+```

docs/manual/quirks/nodejs.md

@@ -1,16 +1,22 @@
-# NodeJS {#ch-plugins-nodejs}
+# 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.
+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`).
+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-formating relying on your prettier config, while your eslint config diagnoses formatting [which it's not supposed to](https://prettier.io/docs/en/comparison.html))
+This results in auto-formating 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.
+In the end, you get discrepancies between what your editor does and what it
+wants.
 
 Solutions are:
 

docs/manual/try-it-out.md

@@ -1,25 +1,27 @@
 # 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.
+Thanks to the portability of Nix, you can try out nvf without actually
-Below are the commands you may run to try out different configurations provided by this flake. As of v0.5, three
+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:
 
-- Nix
+- **Nix** - Nix language server + simple utility plugins
-- Maximal
+- **Maximal** - Variable language servers + utility and decorative plugins
 
-You may try out any of the provided configurations using the `nix run` command on a system where Nix is installed.
+You may try out any of the provided configurations using the `nix run` command
+on a system where Nix is installed.
 
-```console
+```bash
 $ cachix use nvf                   # Optional: it'll save you CPU resources and time
 $ nix run github:notashelf/nvf#nix # will run the default minimal configuration
 ```
 
-Do keep in mind that this is **susceptible to garbage collection** meaning it will be removed from your Nix store
+Do keep in mind that this is **susceptible to garbage collection** meaning it
-once you garbage collect.
+will be removed from your Nix store once you garbage collect.
 
-## Using Prebuilt Configs {#sec-using-prebuild-configs}
+## Using Prebuilt Configs {#sec-using-prebuilt-configs}
 
-```console
+```bash
 $ nix run github:notashelf/nvf#nix
 $ nix run github:notashelf/nvf#maximal
 ```
@@ -28,12 +30,19 @@ $ nix run github:notashelf/nvf#maximal
 
 #### Nix {#sec-configs-nix}
 
-`Nix` configuration by default provides LSP/diagnostic support for Nix alongisde a set of visual and functional plugins.
+`Nix` configuration by default provides LSP/diagnostic support for Nix alongside
-By running `nix run .#`, which is the default package, you will build Neovim with this config.
+a set of visual and functional plugins. By running `nix run .#`, which is the
+default package, you will build Neovim with this config.
 
 #### Maximal {#sec-configs-maximal}
 
-`Maximal` is the ultimate configuration that will enable support for more commonly used language as well as additional
+`Maximal` is the ultimate configuration that will enable support for more
-complementary plugins. Keep in mind, however, that this will pull a lot of dependencies.
+commonly used language as well as additional complementary plugins. Keep in
+mind, however, that this will pull a lot of dependencies.
 
-You are _strongly_ recommended to use the binary cache if you would like to try the Maximal configuration.
+::: {.tip}
+
+You are _strongly_ recommended to use the binary cache if you would like to try
+the Maximal configuration.
+
+:::

docs/static/script/anchor-use.js

@@ -0,0 +1,4 @@
+document.addEventListener('DOMContentLoaded', function(event) {
+  anchors.add('h1[id]:not(div.note h1, div.warning h1, div.tip h1, div.caution h1, div.important h1), h2[id]:not(div.note h2, div.warning h2, div.tip h2, div.caution h2, div.important h2), h3[id]:not(div.note h3, div.warning h3, div.tip h3, div.caution h3, div.important h3), h4[id]:not(div.note h4, div.warning h4, div.tip h4, div.caution h4, div.important h4), h5[id]:not(div.note h5, div.warning h5, div.tip h5, div.caution h5, div.important h5), h6[id]:not(div.note h6, div.warning h6, div.tip h6, div.caution h6, div.important h6)');
+});
+

docs/static/style.scss

@@ -1,3 +1,5 @@
+@use "scss-reset/reset";
+
 :root {
 	--nmd-color0: #0a3e68;
 	--nmd-color1: #268598;
@@ -32,8 +34,6 @@ $color-blue-700: #1d4ed8;
 $color-blue-800: #1e40af;
 $color-blue-900: #1e3a8a;
 
-@use "scss-reset/reset";
-
 @mixin boxed {
 	background: $color-gray-50;
 	margin: 2rem 16px;

docs/static/tomorrow-night.min.css

@@ -4,99 +4,4 @@
   License: ~ MIT (or more permissive) [via base16-schemes-source]
   Maintainer: @highlightjs/core-team
   Version: 2021.09.0
-*/
+*/pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{color:#ccc;background:#2d2d2d}.hljs ::selection,.hljs::selection{background-color:#515151;color:#ccc}.hljs-comment{color:#999}.hljs-tag{color:#b4b7b4}.hljs-operator,.hljs-punctuation,.hljs-subst{color:#ccc}.hljs-operator{opacity:.7}.hljs-bullet,.hljs-deletion,.hljs-name,.hljs-selector-tag,.hljs-template-variable,.hljs-variable{color:#f2777a}.hljs-attr,.hljs-link,.hljs-literal,.hljs-number,.hljs-symbol,.hljs-variable.constant_{color:#f99157}.hljs-class .hljs-title,.hljs-title,.hljs-title.class_{color:#fc6}.hljs-strong{font-weight:700;color:#fc6}.hljs-addition,.hljs-code,.hljs-string,.hljs-title.class_.inherited__{color:#9c9}.hljs-built_in,.hljs-doctag,.hljs-keyword.hljs-atrule,.hljs-quote,.hljs-regexp{color:#6cc}.hljs-attribute,.hljs-function .hljs-title,.hljs-section,.hljs-title.function_,.ruby .hljs-property{color:#69c}.diff .hljs-meta,.hljs-keyword,.hljs-template-tag,.hljs-type{color:#c9c}.hljs-emphasis{color:#c9c;font-style:italic}.hljs-meta,.hljs-meta .hljs-keyword,.hljs-meta .hljs-string{color:#a3685a}.hljs-meta .hljs-keyword,.hljs-meta-keyword{font-weight:700}
-pre code.hljs {
-	display: block;
-	overflow-x: auto;
-	padding: 1em;
-}
-code.hljs {
-	padding: 3px 5px;
-}
-.hljs {
-	color: #ccc;
-	background: #2d2d2d;
-}
-.hljs ::selection,
-.hljs::selection {
-	background-color: #515151;
-	color: #ccc;
-}
-.hljs-comment {
-	color: #999;
-}
-.hljs-tag {
-	color: #b4b7b4;
-}
-.hljs-operator,
-.hljs-punctuation,
-.hljs-subst {
-	color: #ccc;
-}
-.hljs-operator {
-	opacity: 0.7;
-}
-.hljs-bullet,
-.hljs-deletion,
-.hljs-name,
-.hljs-selector-tag,
-.hljs-template-variable,
-.hljs-variable {
-	color: #f2777a;
-}
-.hljs-attr,
-.hljs-link,
-.hljs-literal,
-.hljs-number,
-.hljs-symbol,
-.hljs-variable.constant_ {
-	color: #f99157;
-}
-.hljs-class .hljs-title,
-.hljs-title,
-.hljs-title.class_ {
-	color: #fc6;
-}
-.hljs-strong {
-	font-weight: 700;
-	color: #fc6;
-}
-.hljs-addition,
-.hljs-code,
-.hljs-string,
-.hljs-title.class_.inherited__ {
-	color: #9c9;
-}
-.hljs-built_in,
-.hljs-doctag,
-.hljs-keyword.hljs-atrule,
-.hljs-quote,
-.hljs-regexp {
-	color: #6cc;
-}
-.hljs-attribute,
-.hljs-function .hljs-title,
-.hljs-section,
-.hljs-title.function_,
-.ruby .hljs-property {
-	color: #69c;
-}
-.diff .hljs-meta,
-.hljs-keyword,
-.hljs-template-tag,
-.hljs-type {
-	color: #c9c;
-}
-.hljs-emphasis {
-	color: #c9c;
-	font-style: italic;
-}
-.hljs-meta,
-.hljs-meta .hljs-keyword,
-.hljs-meta .hljs-string {
-	color: #a3685a;
-}
-.hljs-meta .hljs-keyword,
-.hljs-meta-keyword {
-	font-weight: 700;
-}

flake.nix

@@ -30,29 +30,25 @@
         };
 
         homeManagerModules = {
+          nvf = import ./flake/modules/home-manager.nix self.packages lib;
+          default = self.homeManagerModules.nvf;
           neovim-flake =
             lib.warn ''
-              homeManagerModules.neovim-flake has been deprecated.
+              'homeManagerModules.neovim-flake' has been deprecated, and will be removed
-              Plese use the homeManagerModules.nvf instead
+              in a future release. Please use 'homeManagerModules.nvf' instead.
             ''
             self.homeManagerModules.nvf;
-
-          nvf = import ./flake/modules/home-manager.nix self.packages lib;
-
-          default = self.homeManagerModules.nvf;
         };
 
         nixosModules = {
+          nvf = import ./flake/modules/nixos.nix self.packages lib;
+          default = self.nixosModules.nvf;
           neovim-flake =
             lib.warn ''
-              nixosModules.neovim-flake has been deprecated.
+              'nixosModules.neovim-flake' has been deprecated, and will be removed
-              Please use the nixosModules.nvf instead
+              in a future release. Please use 'nixosModules.nvf' instead.
             ''
             self.nixosModules.nvf;
-
-          nvf = import ./flake/modules/nixos.nix self.packages lib;
-
-          default = self.nixosModules.nvf;
         };
       };