From 9f1bd7fb35ed8c03211840f8c8332f0bbcf5fca1 Mon Sep 17 00:00:00 2001
From: NotAShelf <raf@notashelf.dev>
Date: Mon, 3 Feb 2025 14:43:59 +0300
Subject: [PATCH] docs/tips: document pure-lua/hybrid setups

---
 docs/manual/tips.md                 |  1 +
 docs/manual/tips/debugging-nvf.md   |  6 +++
 docs/manual/tips/pure-lua-config.md | 61 +++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+)
 create mode 100644 docs/manual/tips/pure-lua-config.md

diff --git a/docs/manual/tips.md b/docs/manual/tips.md
index 0d2637f1..6e6dc9c2 100644
--- a/docs/manual/tips.md
+++ b/docs/manual/tips.md
@@ -1,6 +1,7 @@
 # Helpful Tips {#ch-helpful-tips}
 
 ```{=include=} chapters
+tips/pure-lua-config.md
 tips/debugging-nvf.md
 tips/offline-docs.md
 ```
diff --git a/docs/manual/tips/debugging-nvf.md b/docs/manual/tips/debugging-nvf.md
index a642b0a7..ed0214ae 100644
--- a/docs/manual/tips/debugging-nvf.md
+++ b/docs/manual/tips/debugging-nvf.md
@@ -17,3 +17,9 @@ nvf-print-config | bat --language=lua
 ```
 
 Alternatively, `cat` or `less` may also be used.
+
+## Accessing `neovimConfig` {#sec-accessing-config}
+
+It is also possible to access the configuration for the wrapped package. The
+_built_ Neovim package will contain a `neovimConfig` attribute in its
+`passthru`.
diff --git a/docs/manual/tips/pure-lua-config.md b/docs/manual/tips/pure-lua-config.md
new file mode 100644
index 00000000..f31d4220
--- /dev/null
+++ b/docs/manual/tips/pure-lua-config.md
@@ -0,0 +1,61 @@
+# Pure Lua Configuration {#pure-lua-config}
+
+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
+method.
+
+## Custom Configuration Directory {#custom-config-dir}
+
+[Neovim 0.9]: https://github.com/neovim/neovim/pull/22128
+
+As of [Neovim 0.9], `$NVIM_APPNAME` is a variable expected by Neovim to decide
+on the configuration directory. nvf sets this variable as `"nvf"`, meaning
+`~/.config/nvf` will be regarded as _the_ configuration directory by Neovim,
+similar to how `~/.config/nvim` behaves in regular installations. This allows
+some degree[^1] of Lua configuration, backed by our low-level wrapper
+[mnw](https://github.com/Gerg-L/mnw). Creating a `lua/` directory located in
+`$NVIM_APPNAME` ("nvf" by default) and placing your configuration in, e.g.,
+`~/.config/nvf/lua/myconfig` will allow you to `require` it as a part of the Lua
+module system through nvf's module system.
+
+Let's assume your `~/.config/nvf/lua/myconfig/init.lua` consists of the
+following:
+
+```lua
+vim.keymap.set("n", " ", "<Nop>", { silent = true, remap = false })
+vim.g.mapleader = " "
+```
+
+The following Nix configuration via [](#opt-vim.luaConfigRC) will allow loading
+this
+
+```nix
+{
+  # The attribute name "myconfig-dir" here is arbitrary. It is required to be
+  # a *named* attribute by the DAG system, but the name is entirely up to you.
+  vim.luaConfigRC.myconfig-dir = ''
+    require("myconfig")
+
+    -- Any additional Lua
+  '';
+}
+```
+
+[DAG system]: https://notashelf.github.io/nvf/index.xhtml#ch-using-dags
+
+After you load your custom configuration, you may use an `init.lua` located in
+your custom configuration directory to configure Neovim exactly as you would
+without a wrapper like nvf. If you want to place your `require` call in a
+specific position (i.e., before or after options you set in nvf) the
+[DAG system] will let you place your configuration in a location of your
+choosing.
+
+[top-level DAG system]: https://notashelf.github.io/nvf/index.xhtml#ch-vim-luaconfigrc
+
+[^1]: You might sometimes face "overrides" set by nvf. Those should be very
+    rare, and almost always exclusive to `vim.globals` or `vim.options`. In such
+    a case, simply placing the `require` call for your configuration _after_
+    `optionsScript` in the [top-level DAG system] will allow you to override
+    previous options.