docs/tips: distinguish pure and impure installation methods for raw lua

.github/README.md

@@ -50,6 +50,7 @@
 [Contribute]: #contributing
 [FAQ]: #frequently-asked-questions
 [Credits]: #credits
+[License]: #license
 
 **[<kbd><br> Features <br></kbd>][Features]**
 **[<kbd><br> Get Started <br></kbd>][Get Started]**
@@ -70,6 +71,7 @@
 [release notes]: https://notashelf.github.io/nvf/release-notes.html
 [discussions tab]: https://github.com/notashelf/nvf/discussions
 [FAQ section]: #frequently-asked-questions
+[DAG]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
 
 - **Simple**: One language to rule them all! Use Nix to configure everything,
   with optional Lua support for robust configurability!
@@ -87,7 +89,10 @@
   - nvf exposes everything you need to avoid a vendor lock-in. Which means you
     can add new modules, plugins and so on without relying on us adding a module
     for them! Though, of course, feel free to request them.
-  - Use plugins from anywhere.
+  - Use plugins from anywhere. Inputs, npins, nixpkgs... You name it.
+  - nvf allows _ordering configuration bits_ using [DAG] (_Directed acyclic
+    graph_)s. It has never been easier to construct an editor configuration
+    deterministically!
 - **Well-documented**: Documentation is priority. You will _never_ face
   undocumented, obscure behaviour.
   - Changes, breaking or otherwise, will be communicated in the [release notes]

docs/manual/tips/pure-lua-config.md

@@ -3,10 +3,71 @@
 We recognize that you might not always want to configure your setup purely in
 Nix, sometimes doing things in Lua is simply the "superior" option. In such a
 case you might want to configure your Neovim instance using Lua, and nothing but
-Lua. It is also possible to mix Lua and Nix configurations through the following
+Lua. It is also possible to mix Lua and Nix configurations.
-method.
 
-## Custom Configuration Directory {#sec-custom-config-dir}
+Pure Lua or hybrid Lua/Nix configurations can be achieved in two different ways.
+_Purely_, by modifying Neovim's runtime directory or _impurely_ by placing Lua
+configuration in a directory found in `$HOME`. For your convenience, this
+section will document both methods as they can be used.
+
+## Pure Runtime Directory {#sec-pure-nvf-runtime}
+
+As of 0.6, nvf allows you to modify Neovim's runtime path to suit your needs.
+One of the ways the new runtime option is to add a configuration **located
+relative to your `flake.nix`**, which must be version controlled in pure flakes
+manner.
+
+```nix
+{
+  # Let us assume we are in the repository root, i.e., the same directory as the
+  # flake.nix. For the sake of the argument, we will assume that the Neovim lua
+  # configuration is in a nvim/ directory relative to flake.nix.
+  vim = {
+    additionalRuntimeDirectories = [
+      # This will be added to Neovim's runtime paths. Conceptually, this behaves
+      # very similarly to ~/.config/nvim but you may not place a top-level
+      # init.lua to be able to require it directly.
+      ./nvim
+    ];
+  };
+}
+```
+
+This will add the `nvim` directory, or rather, the _store path_ that will be
+realised after your flake gets copied to the Nix store, to Neovim's runtime
+directory. You may now create a `lua/myconfig` directory within this nvim
+directory, and call it with [](#opt-vim.luaConfigRC).
+
+```nix
+{pkgs, ...}: {
+  vim = {
+    additionalRuntimeDirectories = [
+      # You can list more than one file here.
+      ./nvim-custom-1
+
+      # To make sure list items are ordered, use lib.mkBefore or lib.mkAfter
+      # Simply placing list items in a given order will **not** ensure that
+      # this list  will be deterministic.
+      ./nvim-custom-2
+    ];
+
+    startPlugins = [pkgs.vimPlugins.gitsigns];
+
+    # Neovim supports in-line syntax highlighting for multi-line strings.
+    # Simply place the filetype in a /* comment */ before the line.
+    luaConfigRC.myconfig = /* lua */ ''
+      -- Call the Lua module from ./nvim/lua/myconfig
+      require("myconfig")
+
+      -- Any additional Lua configuration that you might want *after* your own
+      -- configuration. For example, a plugin setup call.
+      require('gitsigns').setup({})
+    '';
+  };
+}
+```
+
+## Impure Absolute Directory {#sec-impure-absolute-dir}
 
 [Neovim 0.9]: https://github.com/neovim/neovim/pull/22128