From 4d6e4a9a8aa8c09e095b24f6368486613a14e845 Mon Sep 17 00:00:00 2001
From: ysthakur <45539777+ysthakur@users.noreply.github.com>
Date: Tue, 10 Jun 2025 05:59:26 -0400
Subject: [PATCH] Move Zoxide completer to cookbook

---
 .vuepress/configs/sidebar/en.ts |  1 +
 book/custom_completions.md      | 23 ------------
 cookbook/custom_completers.md   | 62 +++++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 23 deletions(-)
 create mode 100644 cookbook/custom_completers.md

diff --git a/.vuepress/configs/sidebar/en.ts b/.vuepress/configs/sidebar/en.ts
index b67eb896095..37cbc475ec3 100644
--- a/.vuepress/configs/sidebar/en.ts
+++ b/.vuepress/configs/sidebar/en.ts
@@ -154,6 +154,7 @@ export const sidebarEn: SidebarConfig = {
         '/cookbook/parsing',
         '/cookbook/foreign_shell_scripts',
         '/cookbook/pattern_matching',
+        '/cookbook/custom_completers',
         '/cookbook/external_completers',
         '/cookbook/modules',
         '/cookbook/files',
diff --git a/book/custom_completions.md b/book/custom_completions.md
index 465f943e376..cc40f5082da 100644
--- a/book/custom_completions.md
+++ b/book/custom_completions.md
@@ -69,29 +69,6 @@ cat                 rat                 bat
 
 Because we made matching case-insensitive, Nushell will find the substring "a" in all of the completion suggestions. Additionally, because we set `sort: false`, the completions will be left in their original order. This is useful if your completions are already sorted in a particular order unrelated to their text (e.g. by date).
 
-## Another Practical Example - Zoxide Path Completions
-
-[Zoxide](https://github.com/ajeetdsouza/zoxide) allows easily jumping between visited folders in the system. It's possible to autocomplete matching folders with this completer:
-
-```nu
-def "nu-complete zoxide path" [context: string] {
-    let parts = $context | split row " " | skip 1
-    {
-      options: {
-        sort: false,
-        completion_algorithm: prefix,
-        positional: false,
-        case_sensitive: false,
-      },
-      completions: (zoxide query --list --exclude $env.PWD -- ...$parts | lines),
-    }
-  }
-
-def --env --wrapped z [...rest: string@"nu-complete zoxide path"] {
-  __zoxide_z ...$rest
-}
-```
-
 ## Modules and Custom Completions
 
 Since completion commands aren't meant to be called directly, it's common to define them in modules.
diff --git a/cookbook/custom_completers.md b/cookbook/custom_completers.md
new file mode 100644
index 00000000000..dd87393037b
--- /dev/null
+++ b/cookbook/custom_completers.md
@@ -0,0 +1,62 @@
+---
+title: Custom Completers
+---
+
+# Custom Completers
+
+## Zoxide Path Completions
+
+[Zoxide](https://github.com/ajeetdsouza/zoxide) allows easily jumping between visited folders in the system. It's possible to autocomplete matching folders with this completer:
+
+```nu
+def "nu-complete zoxide path" [context: string] {
+    let parts = $context | split row " " | skip 1
+    {
+      options: {
+        sort: false,
+        completion_algorithm: substring,
+        case_sensitive: false,
+      },
+      completions: (^zoxide query --list --exclude $env.PWD -- ...$parts | lines),
+    }
+  }
+
+def --env --wrapped z [...rest: string@"nu-complete zoxide path"] {
+  __zoxide_z ...$rest
+}
+```
+
+Do note that the above completer probably won't work with multiple keywords because each completion suggestion is a full path. Something like `z nu <TAB>` might provide `/home/user/nushell` as a suggestion, and if you select this suggestion, your commandline will be replaced with `z nu /home/user/nushell` rather than `z /home/user/nushell`. Running `z nu /home/user/nushell` will now fail.
+
+Below is a more convoluted completer that provides odd-looking suggestions but does work with multiple keywords.
+
+```nu
+def "nu-complete zoxide path" [context: string] {
+    let parts = $context | str trim --left | split row " " | skip 1 | each { str downcase }
+    let completions = (
+        ^zoxide query --list --exclude $env.PWD -- ...$parts
+            | lines
+            | each { |dir|
+                if ($parts | length) <= 1 {
+                    $dir
+                } else {
+                    let dir_lower = $dir | str downcase
+                    let rem_start = $parts | drop 1 | reduce --fold 0 { |part, rem_start|
+                        ($dir_lower | str index-of --range $rem_start.. $part) + ($part | str length)
+                    }
+                    {
+                        value: ($dir | str substring $rem_start..),
+                        description: $dir
+                    }
+                }
+            })
+    {
+        options: {
+            sort: false,
+            completion_algorithm: substring,
+            case_sensitive: false,
+        },
+        completions: $completions,
+    }
+}
+```