support extracting nu code snippets into standalone .nu files for better downstream trackability

.vuepress/config.js

@@ -6,6 +6,7 @@ import { shikiPlugin } from '@vuepress/plugin-shiki';
 import { defaultTheme } from '@vuepress/theme-default';
 import { sitemapPlugin } from '@vuepress/plugin-sitemap';
 import { docsearchPlugin } from '@vuepress/plugin-docsearch';
+import { markdownIncludePlugin } from '@vuepress/plugin-markdown-include';
 
 import {
   navbarDe,
@@ -211,6 +212,7 @@ export default defineUserConfig({
   plugins: [
     // Note: gitPlugin, backToTopPlugin, mediumZoomPlugin, and copyCodePlugin
     // are already included in defaultTheme, so we don't need to add them here
+    markdownIncludePlugin({}),
     shikiPlugin({
       themes: {
         light: 'dark-plus',

CONTRIBUTING.md

@@ -70,6 +70,8 @@ ls | where type == file | sort-by -r size | first 5
 
 The preferred form for consistency is `` ```nu ``.
 
+If the snippet is a reusable block that readers might want to source directly and track over time, save it as a sibling `.nu` file and include it inside the fence with `<!-- @include: ./example.nu -->` (see `cookbook/direnv.md` for an example).
+
 ## Translation Guide
 
 Follow the steps above for each group of translations.

cookbook/direnv.md

@@ -27,21 +27,7 @@ The direnv configuration below requires Nushell 0.104 or later.
 :::
 
 ```nu
-use std/config *
-
-# Initialize the PWD hook as an empty list if it doesn't exist
-$env.config.hooks.env_change.PWD = $env.config.hooks.env_change.PWD? | default []
-
-$env.config.hooks.env_change.PWD ++= [{||
-  if (which direnv | is-empty) {
-    # If direnv isn't installed, do nothing
-    return
-  }
-
-  direnv export json | from json | default {} | load-env
-  # If direnv changes the PATH, it will become a string and we need to re-convert it to a list
-  $env.PATH = do (env-conversions).path.from_string $env.PATH
-}]
+<!-- @include: ./direnv.nu -->
 ```
 
 As with other configuration changes, this can be made permanent by adding it to your startup [configuration](/book/configuration.md).

cookbook/direnv.nu

@@ -0,0 +1,15 @@
+use std/config *
+
+# Initialize the PWD hook as an empty list if it doesn't exist
+$env.config.hooks.env_change.PWD = $env.config.hooks.env_change.PWD? | default []
+
+$env.config.hooks.env_change.PWD ++= [{||
+  if (which direnv | is-empty) {
+    # If direnv isn't installed, do nothing
+    return
+  }
+
+  direnv export json | from json | default {} | load-env
+  # If direnv changes the PATH, it will become a string and we need to re-convert it to a list
+  $env.PATH = do (env-conversions).path.from_string $env.PATH
+}]

cookbook/ssh_agent.md

@@ -26,30 +26,7 @@ See the workarounds.
 You can work around this behavior by checking if a ssh-agent is already running on your user, and start one if none is:
 
 ```nu
-do --env {
-    let ssh_agent_file = (
-        $nu.temp-dir | path join $"ssh-agent-(whoami).nuon"
-    )
-
-    if ($ssh_agent_file | path exists) {
-        let ssh_agent_env = open ($ssh_agent_file)
-        if ($"/proc/($ssh_agent_env.SSH_AGENT_PID)" | path exists) {
-            load-env $ssh_agent_env
-            return
-        } else {
-            rm $ssh_agent_file
-        }
-    }
-
-    let ssh_agent_env = ^ssh-agent -c
-        | lines
-        | first 2
-        | parse "setenv {name} {value};"
-        | transpose --header-row
-        | into record
-    load-env $ssh_agent_env
-    $ssh_agent_env | save --force $ssh_agent_file
-}
+<!-- @include: ./ssh_agent_workaround.nu -->
 ```
 
 ### [Keychain](https://www.funtoo.org/Funtoo:Keychain)

cookbook/ssh_agent_workaround.nu

@@ -0,0 +1,24 @@
+do --env {
+    let ssh_agent_file = (
+        $nu.temp-dir | path join $"ssh-agent-(whoami).nuon"
+    )
+
+    if ($ssh_agent_file | path exists) {
+        let ssh_agent_env = open ($ssh_agent_file)
+        if ($"/proc/($ssh_agent_env.SSH_AGENT_PID)" | path exists) {
+            load-env $ssh_agent_env
+            return
+        } else {
+            rm $ssh_agent_file
+        }
+    }
+
+    let ssh_agent_env = ^ssh-agent -c
+        | lines
+        | first 2
+        | parse "setenv {name} {value};"
+        | transpose --header-row
+        | into record
+    load-env $ssh_agent_env
+    $ssh_agent_env | save --force $ssh_agent_file
+}

package.json

@@ -17,6 +17,7 @@
     "@vuepress/bundler-vite": "2.0.0-rc.26",
     "@vuepress/plugin-docsearch": "2.0.0-rc.118",
     "@vuepress/plugin-feed": "2.0.0-rc.118",
+    "@vuepress/plugin-markdown-include": "2.0.0-rc.118",
     "@vuepress/plugin-shiki": "2.0.0-rc.118",
     "@vuepress/plugin-sitemap": "2.0.0-rc.118",
     "@vuepress/theme-default": "2.0.0-rc.118",