From 9584fe25e29fe7c6540f4cac55381e9ba25cf43d Mon Sep 17 00:00:00 2001
From: raf <raf@notashelf.dev>
Date: Sun, 5 Jan 2025 11:35:09 +0300
Subject: [PATCH] docs: add helpful tips section (#520)

---
 docs/manual/manual.md             |  1 +
 docs/manual/tips.md               |  6 ++++++
 docs/manual/tips/debugging-nvf.md | 19 +++++++++++++++++++
 docs/manual/tips/offline-docs.md  | 11 +++++++++++
 4 files changed, 37 insertions(+)
 create mode 100644 docs/manual/tips.md
 create mode 100644 docs/manual/tips/debugging-nvf.md
 create mode 100644 docs/manual/tips/offline-docs.md

diff --git a/docs/manual/manual.md b/docs/manual/manual.md
index fd7ddcd9..fd225766 100644
--- a/docs/manual/manual.md
+++ b/docs/manual/manual.md
@@ -11,6 +11,7 @@ try-it-out.md
 default-configs.md
 installation.md
 configuring.md
+tips.md
 ```
 
 ```{=include=} chapters
diff --git a/docs/manual/tips.md b/docs/manual/tips.md
new file mode 100644
index 00000000..0d2637f1
--- /dev/null
+++ b/docs/manual/tips.md
@@ -0,0 +1,6 @@
+# Helpful Tips {#ch-helpful-tips}
+
+```{=include=} chapters
+tips/debugging-nvf.md
+tips/offline-docs.md
+```
diff --git a/docs/manual/tips/debugging-nvf.md b/docs/manual/tips/debugging-nvf.md
new file mode 100644
index 00000000..a642b0a7
--- /dev/null
+++ b/docs/manual/tips/debugging-nvf.md
@@ -0,0 +1,19 @@
+# Debugging nvf {#sec-debugging-nvf}
+
+There may be instances where the your Nix configuration evaluates to invalid
+Lua, or times when you will be asked to provide your built Lua configuration for
+easier debugging by nvf maintainers. nvf provides two helpful utilities out of
+the box.
+
+**nvf-print-config** and **nvf-print-config-path** will be bundled with nvf as
+lightweight utilities to help you view or share your built configuration when
+necessary.
+
+To view your configuration with syntax highlighting, you may use the
+[bat pager](https://github.com/sharkdp/bat).
+
+```bash
+nvf-print-config | bat --language=lua
+```
+
+Alternatively, `cat` or `less` may also be used.
diff --git a/docs/manual/tips/offline-docs.md b/docs/manual/tips/offline-docs.md
new file mode 100644
index 00000000..ed11d965
--- /dev/null
+++ b/docs/manual/tips/offline-docs.md
@@ -0,0 +1,11 @@
+# Offline Documentation {#sec-offline-documentation}
+
+[https://notashelf.github.io/nvf/options.html]: https://notashelf.github.io/nvf/options.html
+
+The manpages provided by nvf contains an offline version of the option search
+normally available at [https://notashelf.github.io/nvf/options.html]. You may
+use the `man 5 nvf` command to view option documentation from the comfort of
+your terminal.
+
+Note that this is only available for NixOS and Home-Manager module
+installations.