From 1f6d041efea8fd4f2cebf7e2b77a9d74a2ec4aee Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Tue, 28 Oct 2025 11:05:32 -0500
Subject: [PATCH 1/9] Add manage Nomad variables page

---
 website/content/commands/var/get.mdx          |  20 +---
 website/content/commands/var/init.mdx         |   7 +-
 website/content/commands/var/list.mdx         |  83 +------------
 website/content/commands/var/lock.mdx         |  15 +--
 website/content/commands/var/purge.mdx        |   7 +-
 website/content/commands/var/put.mdx          |  20 +---
 website/content/docs/concepts/variables.mdx   |  45 +++----
 .../content/docs/manage/manage-variables.mdx  |  94 +++++++++++++++
 .../docs/other-specifications/variables.mdx   |   7 +-
 .../partials/variables/get-example.mdx        |  19 +++
 .../partials/variables/init-example.mdx       |   6 +
 .../partials/variables/list-example.mdx       | 113 ++++++++++++++++++
 .../partials/variables/lock-example.mdx       |  13 ++
 .../partials/variables/purge-example.mdx      |   5 +
 .../partials/variables/put-example.mdx        |  53 ++++++++
 website/data/docs-nav-data.json               |   2 +-
 16 files changed, 336 insertions(+), 173 deletions(-)
 create mode 100644 website/content/docs/manage/manage-variables.mdx
 create mode 100644 website/content/partials/variables/get-example.mdx
 create mode 100644 website/content/partials/variables/init-example.mdx
 create mode 100644 website/content/partials/variables/list-example.mdx
 create mode 100644 website/content/partials/variables/lock-example.mdx
 create mode 100644 website/content/partials/variables/purge-example.mdx
 create mode 100644 website/content/partials/variables/put-example.mdx

diff --git a/website/content/commands/var/get.mdx b/website/content/commands/var/get.mdx
index b7de39fd4e3..0410d2d9428 100644
--- a/website/content/commands/var/get.mdx
+++ b/website/content/commands/var/get.mdx
@@ -39,25 +39,7 @@ documentation for details.
 
 ## Examples
 
-Retrieve the variable stored at path "secret/creds":
-
-```shell-session
-$ nomad var get secret/creds
-Namespace   = default
-Path        = secret/creds
-Create Time = 2022-08-23T11:14:37-04:00
-Check Index = 116
-
-Items
-passcode = my-long-passcode
-```
-
-Return only the "passcode" item from the variable stored at "secret/creds":
-
-```shell-session
-$ nomad var get -item=passcode secret/creds
-my-long-passcode
-```
+@include 'variables/get-example.mdx'
 
 ## General options
 
diff --git a/website/content/commands/var/init.mdx b/website/content/commands/var/init.mdx
index 1e7d50449ab..764cb0b2936 100644
--- a/website/content/commands/var/init.mdx
+++ b/website/content/commands/var/init.mdx
@@ -28,9 +28,4 @@ When no filename is supplied, a default filename of "spec.nv.hcl" or
 
 ## Examples
 
-Create an example variable specification:
-
-```shell-session
-$ nomad var init
-Example variable specification written to spec.nv.hcl
-```
+@include 'variables/init-example.mdx'
diff --git a/website/content/commands/var/list.mdx b/website/content/commands/var/list.mdx
index 3e206564245..a8a4b46daf3 100644
--- a/website/content/commands/var/list.mdx
+++ b/website/content/commands/var/list.mdx
@@ -52,88 +52,7 @@ documentation for details.
 
 ## Examples
 
-List values under the key "nomad/jobs":
-
-```shell-session
-$ nomad var list nomad/jobs
-Namespace  Path                           Last Updated
-default    nomad/jobs/example             2022-08-23T10:35:47-04:00
-default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
-default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
-default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
-```
-
-List values under the key "nomad/jobs/variable/www" in JSON format:
-
-```shell-session
-$ nomad var list -out=json -namespace="*" nomad/jobs/variable/www
-[
-  {
-    "Namespace": "default",
-    "Path": "nomad/jobs/variable/www",
-    "CreateIndex": 1457,
-    "ModifyIndex": 1457,
-    "CreateTime": 1662061225600373000,
-    "ModifyTime": 1662061225600373000
-  },
-  {
-    "Namespace": "default",
-    "Path": "nomad/jobs/variable/www/nginx",
-    "CreateIndex": 800,
-    "ModifyIndex": 1000,
-    "CreateTime": 1662061717905426000,
-    "ModifyTime": 1662062162982630000
-  }
-]
-```
-
-Perform a paginated query:
-
-```shell-session
-$ nomad var list -per-page=3
-Namespace  Path                           Last Updated
-default    nomad/jobs/example             2022-08-23T10:35:47-04:00
-default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
-default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
-Next page token: default.nomad/jobs/variable/www/nginx
-```
-
-To fetch the next page :
-
-```shell-session
-$ nomad var list -per-page=3 \
-  -page-token=default.nomad/jobs/variable/www/nginx
-Namespace  Path                 Last Updated
-default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
-```
-
-Perform a paginated query with JSON formatting:
-
-```shell-session
-$ nomad var list -out=json -namespace="*" -per-page=1 nomad/jobs/variable/www
-{
-    "Data": [
-        {
-           "Namespace": "default",
-            "Path": "nomad/jobs/variable/www",
-            "CreateIndex": 1457,
-            "ModifyIndex": 1457,
-            "CreateTime": 1662061225600373000,
-            "ModifyTime": 1662061225600373000
-        }
-    ],
-    "QueryMeta": {
-        "KnownLeader": true,
-        "LastContact": 0,
-        "LastIndex": 43,
-        "NextToken": "default.nomad/jobs/variable/www/nginx",
-        "RequestTime": 875792
-    }
-}
-```
-
-As with the tabular version, provide the `QueryMeta.NextToken` value as the
-`-page-token` value to fetch the next page.
+@include 'variables/list-example.mdx'
 
 ## General options
 
diff --git a/website/content/commands/var/lock.mdx b/website/content/commands/var/lock.mdx
index 6048d5622a6..e576da81817 100644
--- a/website/content/commands/var/lock.mdx
+++ b/website/content/commands/var/lock.mdx
@@ -74,20 +74,7 @@ taking the sum of the length in bytes of all of the unencrypted keys and values.
 
 ## Examples
 
-Attempts to acquire a lock over the variable at path "secret/creds" for a time of
-15s and executes  `nomad job run webapp.nomad.hcl` if it succeeds:
-
-```shell-session
-$ nomad var lock -ttl=15s secret/creds "nomad job run webapp.nomad.hcl"
-```
-
-The data can also be consumed from a file on disk by prefixing with the "@"
-symbol. For example, you can store a variable using a specification created with
-the `nomad var init` command.
-
-```shell-session
-$ nomad var lock secret/foo @spec.nv.json `nomad job run webapp.nomad.hcl`
-```
+@include 'variables/lock-example.mdx'
 
 ## General options
 
diff --git a/website/content/commands/var/purge.mdx b/website/content/commands/var/purge.mdx
index 39e7102b4fd..45213ea3381 100644
--- a/website/content/commands/var/purge.mdx
+++ b/website/content/commands/var/purge.mdx
@@ -33,12 +33,7 @@ documentation for details.
 
 ## Examples
 
-Purge the variable at the "secret/creds" path.
-
-```shell-session
-$ nomad var purge -y secret/creds
-Successfully purged variable "secret/creds"!
-```
+@include 'variables/purge-example.mdx'
 
 ## General options
 
diff --git a/website/content/commands/var/put.mdx b/website/content/commands/var/put.mdx
index 14c4997177e..677a2ea8293 100644
--- a/website/content/commands/var/put.mdx
+++ b/website/content/commands/var/put.mdx
@@ -83,25 +83,7 @@ taking the sum of the length in bytes of all of the unencrypted keys and values.
 
 ## Examples
 
-Writes the data to the path "secret/creds":
-
-```shell-session
-$ nomad var put secret/creds passcode=my-long-passcode
-```
-
-The data can also be consumed from a file on disk by prefixing with the "@"
-symbol. For example, you can store a variable using a specification created with
-the `nomad var init` command.
-
-```shell-session
-$ nomad var put secret/foo @spec.nv.json
-```
-
-Or it can be read from standard input using the "-" symbol:
-
-```shell-session
-$ echo "abcd1234" | nomad var put secret/foo bar=-
-```
+@include 'variables/put-examples.mdx'
 
 ## General options
 
diff --git a/website/content/docs/concepts/variables.mdx b/website/content/docs/concepts/variables.mdx
index 414651485db..089ead2a525 100644
--- a/website/content/docs/concepts/variables.mdx
+++ b/website/content/docs/concepts/variables.mdx
@@ -1,24 +1,23 @@
 ---
 layout: docs
-page_title: Nomad Variables
+page_title: Nomad variables
 description: Nomad's variables feature lets you store and use encrypted configuration data in your job specifications. Learn how Access Control List (ACL) policies restrict access to variables within a namespace, how a job task's workload identity grants access to variables, and how locking a variable blocks access to that variable.
 ---
 
-# Nomad Variables
+# Nomad variables
 
 This page contains conceptual information about the Nomad variables feature,
 which lets you store and use encrypted configuration data in your job
 specifications. Learn how Access Control List (ACL) policies restrict access to variables within a namespace, how a job task's workload identity grants access to variables, and how locking a variable blocks access to that variable.
 
-Most Nomad workloads need access to config values or secrets. Nomad has a
-`template` block to [provide such configuration to tasks](/nomad/docs/job-specification/template#nomad-variables),
-but prior to Nomad 1.4 has left the role of storing that configuration to
-external services such as [HashiCorp Consul] and [HashiCorp Vault].
+## Introduction
 
-Nomad variables provide the option to store configuration at file-like paths
-directly in Nomad's state store. [Access these variables](/nomad/docs/job-specification/template#nomad-variables) directly from
-your task templates. The contents of these variables are encrypted
-and replicated between servers via raft. Access to variables is controlled by
+Most Nomad workloads need access to configuration values or secrets. Nomad has a
+`template` block to [provide such configuration to
+tasks](/nomad/docs/job-specification/template#nomad-variables). Nomad variables
+provide the option to store configuration at file-like paths
+directly in Nomad's state store. Access these variables directly from
+your task templates. Nomad encrypts and replicates the contents of these variables between servers via Raft. Access to variables is controlled by
 ACL policies, and tasks have implicit ACL policies that allow them to access
 their own variables. You can create, read, update, or delete variables via the
 command line, the Nomad API, or in the Nomad web UI.
@@ -26,25 +25,27 @@ command line, the Nomad API, or in the Nomad web UI.
 Note that the variables feature is intended for small pieces of configuration
 data needed by workloads. Because writing to the Nomad state store uses
 resources needed by Nomad, it is not well-suited for large or fast-changing
-data. For example, do not store batch job results as variables - these should be
+data. For example, do not store batch job results as variables. These should be
 stored in an external database. Variables are also not intended to be a full
 replacement for HashiCorp Vault. Unlike Vault, Nomad stores the root encryption
-key on the servers. See [Key Management][] for details.
+key on the servers. Refer to [Key Management][] for details.
 
-## ACL for Variables
+## Policies
 
 Every variable belongs to a specific Nomad namespace. ACL policies can restrict
 access to variables within a namespace on a per-path basis, using a list of
-`path` blocks, located under `namespace.variables`. See the [ACL policy
-specification] docs for details about the syntax and structure of an ACL policy.
+`path` blocks, located under `namespace.variables`. Refer to the [ACL policy
+specification] for details about the syntax and structure of an ACL policy.
 
-Path definitions may also include wildcard symbols, also called globs, allowing
+Path definitions may also include a wildcard symbol that allows
 a single path policy definition to apply to a set of paths within that
-namespace. For example, the policy below allows full access to variables at all
-paths in the "dev" namespace that are prefixed with "project/" (including child
-paths) but only read access to paths prefixed with "system/". Note that the glob
+namespace.
+
+In the following example, the policy allows full access to variables at all
+paths in the `dev` namespace that are prefixed with `project/`, including child
+paths, but only read access to paths prefixed with `system/`. Note that the wildcard
 can match an empty string and all other characters. This policy grants read
-access to paths prefixed with "system/" but not a path named "system" (without a
+access to paths prefixed with `system/` but not a path named `system` (without a
 trailing slash).
 
 ```hcl
@@ -76,7 +77,7 @@ The available capabilities for variables are as follows:
 | list       | List the metadata but not contents of variables at this path.                                                         |
 | destroy    | Delete variables at this path.                                                                                        |
 
-## Task Access to Variables
+## Task access to variables
 
 Tasks can access variables with the [`template`] block or using the [Task API].
 The [workload identity] for each task grants it automatic read and list access to
@@ -210,7 +211,7 @@ and no renew or release calls were made, the variable will remain locked for at
 least the lock delay duration, to avoid a possible split-brain situation, where
 there are two holders at the same time.
 
-### Leader election backed by Nomad Variable Locks
+### Leader election backed by Nomad variable locks
 
 For some applications, like HDFS or the Nomad Autoscaler, it is necessary to
 have multiple instances running to ensure redundancy in case of a failure, but
diff --git a/website/content/docs/manage/manage-variables.mdx b/website/content/docs/manage/manage-variables.mdx
new file mode 100644
index 00000000000..6a400f325d1
--- /dev/null
+++ b/website/content/docs/manage/manage-variables.mdx
@@ -0,0 +1,94 @@
+---
+layout: docs
+page_title: Create and update Nomad variables
+description: |-
+  Use the Nomad CLI or API to create, store, and update Nomad variables.
+---
+
+# Create and update Nomad variables
+
+This page describes the processes for interacting with Nomad variables. Use the
+[`nomad var` command reference](/nomad/commands/var) or the [Vars HTTP
+API](/nomad/api-docs/variables) to manage Nomad variables.
+
+## Background
+
+Nomad variables provide the option to securely store configuration at
+file-like paths directly in Nomad's state store. For complete documentation on
+the Nomad variables feature and related concepts, refer to the following:
+
+- [Nomad variables concepts](/nomad/docs/concepts/variables)
+- [Nomad variable specification](/nomad/docs/other-specifications/variables)
+- [Key management]: /nomad/docs/manage/key-management
+- [Workload identity]: /nomad/docs/concepts/workload-identity
+
+Nomad scopes a Nomad variable to a namespace. You may control access to Nomad
+variables with ACL policies.
+
+## Generate a Nomad variable specification
+
+Use the [`nomad var init` command](/nomad/commands/var/init) to generate a Nomad
+variable specification that you can customize.
+
+@include 'variables/init-example.mdx'
+
+## Add and update Nomad variables
+
+Use the [`nomad var put` command](/nomad/commands/var/put) to create and update
+Nomad variables. Supply variable items by including a Nomad variable
+specification file, a series of key-value pairs, or both. Refer to the [`nomad
+var put` command reference](/nomad/commands/var/put) for details on formatting
+keys and values. Values that you supply as command line arguments supersede
+values provided in any variable specification piped into the command or loaded
+from file.
+
+You may also use  the `nomad var put` command to overwrite all items in a
+variable. To avoid conflicting with other writes that may have happened since
+you last read the variable, you must use the `-check-index` flag and set it to
+the last modified index.
+
+@include 'variables/put-example.mdx'
+
+## Delete Nomad variables
+
+Use the [`nomad var purge` command](/nomad/commands/var/purge) to permanently
+delete an existing variable.
+
+@include 'variables/purge-example.mdx'
+
+## Query Nomad variables
+
+### Get
+
+Use the [`nomad var get` command](/nomad/commands/var/get) to fetch the contents of an existing variable.
+
+@include 'variables/get-example.mdx'
+
+### List
+
+Use the [`nomad var list` command](/nomad/commands/var/list) to fetch a list of
+variable paths accessible to you.
+
+@include 'variables/list-example.mdx'
+
+## Lock access to a Nomad variable
+
+The [`nomad var lock` command](/nomad/commands/var/lock) provides a mechanism
+for distributed locking. Nomad creates a lock in the given variable, and only
+when held, invokes the specified child process.
+
+@include 'variables/lock-example.mdx'
+
+## Next steps
+
+Refer to the following Nomad variables tutorials for in-depth learning:
+
+- [Create and update Nomad
+  variables](/nomad/tutorials/variables/variables-create) contains advanced
+  examples for updating Nomad variables.
+- [Configure access control for Nomad
+  variables](/nomad/tutorials/variables/variables-acls) shows how to configure
+  ACL policies for Nomad variables.
+
+To learn how to access Nomad variables in your job specification, refer to the
+[Use Nomad variables in tasks](/nomad/docs/job-declare/nomad-variables) guide.
diff --git a/website/content/docs/other-specifications/variables.mdx b/website/content/docs/other-specifications/variables.mdx
index 7d3e5853d0a..f6366ce61c3 100644
--- a/website/content/docs/other-specifications/variables.mdx
+++ b/website/content/docs/other-specifications/variables.mdx
@@ -9,8 +9,8 @@ description: |-
 
 [Nomad variables][nv] let you store and use encrypted configuration data in your
 job specifications. Specify variables as HCL files and submit them with the
-[`nomad var put` command][var-put. Unlike [job specifications][jobspecs], Nomad
-Variables specifications do not support HCL2 features like functions.
+[`nomad var put` command][var-put]. Unlike [job specifications][jobspecs], Nomad
+variables specifications do not support HCL2 features like functions.
 
 This example is a variable specification generated by [`nomad var init` command][var-init].
 
@@ -59,8 +59,7 @@ $ nomad var put -in hcl some/path @spec.nv.hcl
 - `items` `(object: <required>)` - Object of keys and values to set. Must be
   strings.
 
-Refer to the [Restrictions section][var-restrict] in the command reference for
-details on `path` and `items` name restrictions.
+Refer to the [`nomad var put` restrictions section][var-restrict] for details on `path` and `items` name restrictions.
 
 ## Resources
 
diff --git a/website/content/partials/variables/get-example.mdx b/website/content/partials/variables/get-example.mdx
new file mode 100644
index 00000000000..78c2e1bd043
--- /dev/null
+++ b/website/content/partials/variables/get-example.mdx
@@ -0,0 +1,19 @@
+This example retrieves the variable stored at path `secret/foo`.
+
+```shell-session
+$ nomad var get secret/foo
+Namespace   = default
+Path        = secret/foo
+Create Time = 2025-11-23T11:14:37-04:00
+Check Index = 116
+
+Items
+passcode = my-long-passcode
+```
+
+Return only the `passcode` item from the variable stored at `secret/foo`.
+
+```shell-session
+$ nomad var get -item=passcode secret/foo
+my-long-passcode
+```
diff --git a/website/content/partials/variables/init-example.mdx b/website/content/partials/variables/init-example.mdx
new file mode 100644
index 00000000000..b40a5dcfb66
--- /dev/null
+++ b/website/content/partials/variables/init-example.mdx
@@ -0,0 +1,6 @@
+Generate an example variable specification in the current directory.
+
+```shell-session
+$ nomad var init
+Example variable specification written to spec.nv.hcl
+```
diff --git a/website/content/partials/variables/list-example.mdx b/website/content/partials/variables/list-example.mdx
new file mode 100644
index 00000000000..65c3213d7ac
--- /dev/null
+++ b/website/content/partials/variables/list-example.mdx
@@ -0,0 +1,113 @@
+List the variables in the namespace `prod`.
+
+```shell-session
+$ nomad var list -namespace prod
+Namespace  Path                     Last Updated
+prod       project/another-example  2025-09-19T11:21:56-04:00
+prod       project/example          2025-09-19T11:29:03-04:00
+```
+
+List the variables in namespace `prod` that match the prefix filter `project/ex`.
+
+```shell-session
+$ nomad var list -namespace prod project/ex
+Namespace  Path             Last Updated
+prod       project/example  2025-09-19T11:29:03-04:00
+```
+
+Use the wildcard namespace indicator (`*`) to list all the variables you have
+access to. For many shells, the `*` character is significant, so you might need
+to wrap it in double (`"`) or single (`'`) quotation marks.
+
+```shell-session
+$ nomad var list -namespace '*'
+Namespace  Path                     Last Updated
+dev        another-project/example  2022-09-19T11:29:54-04:00
+dev        project/example          2022-09-19T11:29:54-04:00
+dev        system/config            2022-09-19T11:29:54-04:00
+prod       project/another-example  2022-09-19T11:21:56-04:00
+prod       project/example          2022-09-19T11:29:03-04:00
+```
+
+List values under the key `nomad/jobs`.
+
+```shell-session
+$ nomad var list nomad/jobs
+Namespace  Path                           Last Updated
+default    nomad/jobs/example             2022-08-23T10:35:47-04:00
+default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
+default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
+default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
+```
+
+List values under the key `nomad/jobs/variable/www` in JSON format.
+
+```shell-session
+$ nomad var list -out=json -namespace="*" nomad/jobs/variable/www
+[
+  {
+    "Namespace": "default",
+    "Path": "nomad/jobs/variable/www",
+    "CreateIndex": 1457,
+    "ModifyIndex": 1457,
+    "CreateTime": 1662061225600373000,
+    "ModifyTime": 1662061225600373000
+  },
+  {
+    "Namespace": "default",
+    "Path": "nomad/jobs/variable/www/nginx",
+    "CreateIndex": 800,
+    "ModifyIndex": 1000,
+    "CreateTime": 1662061717905426000,
+    "ModifyTime": 1662062162982630000
+  }
+]
+```
+
+Perform a paginated query.
+
+```shell-session
+$ nomad var list -per-page=3
+Namespace  Path                           Last Updated
+default    nomad/jobs/example             2022-08-23T10:35:47-04:00
+default    nomad/jobs/variable            2022-08-23T10:24:45-04:00
+default    nomad/jobs/variable/www        2022-08-23T10:24:45-04:00
+Next page token: default.nomad/jobs/variable/www/nginx
+```
+
+To fetch the next page, include the next page token.
+
+```shell-session
+$ nomad var list -per-page=3 \
+  -page-token=default.nomad/jobs/variable/www/nginx
+Namespace  Path                 Last Updated
+default    nomad/jobs/variable/www/nginx  2022-08-23T10:24:46-04:00
+```
+
+Perform a paginated query with JSON formatting.
+
+```shell-session
+$ nomad var list -out=json -namespace="*" -per-page=1 nomad/jobs/variable/www
+{
+    "Data": [
+        {
+           "Namespace": "default",
+            "Path": "nomad/jobs/variable/www",
+            "CreateIndex": 1457,
+            "ModifyIndex": 1457,
+            "CreateTime": 1662061225600373000,
+            "ModifyTime": 1662061225600373000
+        }
+    ],
+    "QueryMeta": {
+        "KnownLeader": true,
+        "LastContact": 0,
+        "LastIndex": 43,
+        "NextToken": "default.nomad/jobs/variable/www/nginx",
+        "RequestTime": 875792
+    }
+}
+```
+
+As with the tabular version, provide the `QueryMeta.NextToken` value as the
+`-page-token` value to fetch the next page.
diff --git a/website/content/partials/variables/lock-example.mdx b/website/content/partials/variables/lock-example.mdx
new file mode 100644
index 00000000000..f5de5b84c58
--- /dev/null
+++ b/website/content/partials/variables/lock-example.mdx
@@ -0,0 +1,13 @@
+Lock the variable at path `secret/foo` for a time of
+fifteen seconds. Execute `nomad job run webapp.nomad.hcl` if the lock succeeds.
+
+```shell-session
+$ nomad var lock -ttl=15s secret/foo "nomad job run webapp.nomad.hcl"
+```
+
+You may also pass in file, prefixed with the "@" symbol. This example store and
+locks the variables in the `spec.nv.json` file. Execute `nomad job run webapp.nomad.hcl` if the lock succeeds.
+
+```shell-session
+$ nomad var lock secret/foo @spec.nv.json `nomad job run webapp.nomad.hcl`
+```
diff --git a/website/content/partials/variables/purge-example.mdx b/website/content/partials/variables/purge-example.mdx
new file mode 100644
index 00000000000..0bfd80b4fb0
--- /dev/null
+++ b/website/content/partials/variables/purge-example.mdx
@@ -0,0 +1,5 @@
+Purge all the variables at the `secret/foo` path.
+
+```shell-session
+$ nomad var purge secret/foo
+```
diff --git a/website/content/partials/variables/put-example.mdx b/website/content/partials/variables/put-example.mdx
new file mode 100644
index 00000000000..988740fecd6
--- /dev/null
+++ b/website/content/partials/variables/put-example.mdx
@@ -0,0 +1,53 @@
+
+This example writes the Nomad variables `passcode=my-long-passcode` and
+`user=me` to the path `secret/foo`. The variables are scoped to the `prod`
+namespace.
+
+```shell-session
+$ nomad var put -namespace prod secret/foo passcode=my-long-passcode user=me
+```
+
+This example uses a Nomad variable specification file, prefixed with the "@"
+symbol.
+
+```shell-session
+$ nomad var put -namespace prod secret/foo @spec.nv.json
+```
+
+Use a hyphen ("-") to instruct the command to read the variable value from
+standard input. The `-out` option displays the command's output.
+
+```shell-session
+$ echo "abcd1234" | nomad var put -namespace prod -out secret/foo bar=-
+Namespace   = prod
+Path        = secret/foo
+Create Time = 2025-11-19T11:21:56-04:00
+Check Index = 28
+
+Items
+bar = abcd1234
+```
+
+This example updates the `bar` value in the `secret/foo` path and outputs the
+updated variable in JSON format. You must include the `check-index` value when
+you update a Nomad variable.
+
+```shell-session
+$ nomad var put -namespace prod -out json -check-index 28 secret/foo bar=efgh5678
+```
+
+Output is similar to this snippet.
+
+```json
+{
+  "Namespace": "prod",
+  "Path": "secret/foo",
+  "CreateIndex": 28,
+  "ModifyIndex": 39,
+  "CreateTime": 1663600883130070567,
+  "ModifyTime": 1663601343585644939,
+  "Items": {
+    "bar": "efgh5678",
+  }
+}
+```
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index 4327e55c23c..e98703ee327 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -325,7 +325,7 @@
       },
       {
         "title": "Nomad variables",
-        "href": "https://developer.hashicorp.com/nomad/tutorials/variables/variables-create"
+        "path": "manage/manage-variables"
       },
       {
         "title": "Recovery",

From c2bcd6b72b3c9c2382e14d13be3891c1a6644383 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Tue, 28 Oct 2025 11:32:00 -0500
Subject: [PATCH 2/9] fix include name

---
 website/content/commands/var/put.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/commands/var/put.mdx b/website/content/commands/var/put.mdx
index 677a2ea8293..7b829fe20e3 100644
--- a/website/content/commands/var/put.mdx
+++ b/website/content/commands/var/put.mdx
@@ -83,7 +83,7 @@ taking the sum of the length in bytes of all of the unencrypted keys and values.
 
 ## Examples
 
-@include 'variables/put-examples.mdx'
+@include 'variables/put-example.mdx'
 
 ## General options
 

From ad5c7bc910a24b78210c6c85989745f3552f4bdc Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Tue, 28 Oct 2025 11:43:40 -0500
Subject: [PATCH 3/9] fix links in background section

---
 website/content/docs/manage/manage-variables.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/manage/manage-variables.mdx b/website/content/docs/manage/manage-variables.mdx
index 6a400f325d1..e54d5128760 100644
--- a/website/content/docs/manage/manage-variables.mdx
+++ b/website/content/docs/manage/manage-variables.mdx
@@ -19,8 +19,8 @@ the Nomad variables feature and related concepts, refer to the following:
 
 - [Nomad variables concepts](/nomad/docs/concepts/variables)
 - [Nomad variable specification](/nomad/docs/other-specifications/variables)
-- [Key management]: /nomad/docs/manage/key-management
-- [Workload identity]: /nomad/docs/concepts/workload-identity
+- [Key management]: (/nomad/docs/manage/key-management)
+- [Workload identity]: (/nomad/docs/concepts/workload-identity)
 
 Nomad scopes a Nomad variable to a namespace. You may control access to Nomad
 variables with ACL policies.

From 6cc6939b46d491d9deb6bd4ad74989ddf32ebeee Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Tue, 28 Oct 2025 11:46:00 -0500
Subject: [PATCH 4/9] fix content check

---
 website/content/docs/manage/manage-variables.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/manage/manage-variables.mdx b/website/content/docs/manage/manage-variables.mdx
index e54d5128760..f055fa6c5ee 100644
--- a/website/content/docs/manage/manage-variables.mdx
+++ b/website/content/docs/manage/manage-variables.mdx
@@ -19,8 +19,8 @@ the Nomad variables feature and related concepts, refer to the following:
 
 - [Nomad variables concepts](/nomad/docs/concepts/variables)
 - [Nomad variable specification](/nomad/docs/other-specifications/variables)
-- [Key management]: (/nomad/docs/manage/key-management)
-- [Workload identity]: (/nomad/docs/concepts/workload-identity)
+- [Key management](/nomad/docs/manage/key-management)
+- [Workload identity](/nomad/docs/concepts/workload-identity)
 
 Nomad scopes a Nomad variable to a namespace. You may control access to Nomad
 variables with ACL policies.

From 200cb88962acab5eb97227cdddec41d510c8dc35 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Thu, 30 Oct 2025 06:49:24 -0500
Subject: [PATCH 5/9] Apply suggestion from @boruszak

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
---
 website/content/docs/manage/manage-variables.mdx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/website/content/docs/manage/manage-variables.mdx b/website/content/docs/manage/manage-variables.mdx
index f055fa6c5ee..0287ef8a520 100644
--- a/website/content/docs/manage/manage-variables.mdx
+++ b/website/content/docs/manage/manage-variables.mdx
@@ -90,5 +90,4 @@ Refer to the following Nomad variables tutorials for in-depth learning:
   variables](/nomad/tutorials/variables/variables-acls) shows how to configure
   ACL policies for Nomad variables.
 
-To learn how to access Nomad variables in your job specification, refer to the
-[Use Nomad variables in tasks](/nomad/docs/job-declare/nomad-variables) guide.
+To learn how to access Nomad variables in your job specification, refer to [Use Nomad variables in tasks](/nomad/docs/job-declare/nomad-variables).

From 3ceff8dcbc4f2fb7247c387885dd3967a7ad6905 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Thu, 30 Oct 2025 06:49:38 -0500
Subject: [PATCH 6/9] Apply suggestion from @boruszak

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
---
 website/content/docs/concepts/variables.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/website/content/docs/concepts/variables.mdx b/website/content/docs/concepts/variables.mdx
index 089ead2a525..170253c5e38 100644
--- a/website/content/docs/concepts/variables.mdx
+++ b/website/content/docs/concepts/variables.mdx
@@ -13,11 +13,11 @@ specifications. Learn how Access Control List (ACL) policies restrict access to
 ## Introduction
 
 Most Nomad workloads need access to configuration values or secrets. Nomad has a
-`template` block to [provide such configuration to
+`template` block to [provide these values to
 tasks](/nomad/docs/job-specification/template#nomad-variables). Nomad variables
 provide the option to store configuration at file-like paths
-directly in Nomad's state store. Access these variables directly from
-your task templates. Nomad encrypts and replicates the contents of these variables between servers via Raft. Access to variables is controlled by
+directly in Nomad's state store so that you can access these variables directly from
+your task templates. Nomad encrypts and replicates the contents of these variables between servers with Raft communication. Access to variables is controlled by
 ACL policies, and tasks have implicit ACL policies that allow them to access
 their own variables. You can create, read, update, or delete variables via the
 command line, the Nomad API, or in the Nomad web UI.

From 51bfaa2c6e432986311c8e8866e0e0778a7d36f0 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Thu, 30 Oct 2025 06:50:03 -0500
Subject: [PATCH 7/9] Apply suggestion from @boruszak

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
---
 website/content/docs/manage/manage-variables.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/content/docs/manage/manage-variables.mdx b/website/content/docs/manage/manage-variables.mdx
index 0287ef8a520..a77ea2aab74 100644
--- a/website/content/docs/manage/manage-variables.mdx
+++ b/website/content/docs/manage/manage-variables.mdx
@@ -22,8 +22,8 @@ the Nomad variables feature and related concepts, refer to the following:
 - [Key management](/nomad/docs/manage/key-management)
 - [Workload identity](/nomad/docs/concepts/workload-identity)
 
-Nomad scopes a Nomad variable to a namespace. You may control access to Nomad
-variables with ACL policies.
+Nomad scopes a Nomad variable to a namespace and allows access to Nomad
+variables according to ACL policies.
 
 ## Generate a Nomad variable specification
 

From 9ad9063be5f6cea137ee92115d9fb8a9537f6967 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Thu, 30 Oct 2025 06:50:14 -0500
Subject: [PATCH 8/9] Apply suggestion from @boruszak

Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
---
 website/content/partials/variables/put-example.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/content/partials/variables/put-example.mdx b/website/content/partials/variables/put-example.mdx
index 988740fecd6..96467a45315 100644
--- a/website/content/partials/variables/put-example.mdx
+++ b/website/content/partials/variables/put-example.mdx
@@ -14,7 +14,7 @@ symbol.
 $ nomad var put -namespace prod secret/foo @spec.nv.json
 ```
 
-Use a hyphen ("-") to instruct the command to read the variable value from
+Use a hyphen (`-`) to instruct the command to read the variable value from
 standard input. The `-out` option displays the command's output.
 
 ```shell-session

From ff5b29d5806ec7f9d901b5f3ffebb090f15498c2 Mon Sep 17 00:00:00 2001
From: Aimee Ukasick <aimee.ukasick@hashicorp.com>
Date: Thu, 30 Oct 2025 07:11:44 -0500
Subject: [PATCH 9/9] Revert file name back to variables.mdx

---
 .../content/docs/manage/{manage-variables.mdx => variables.mdx} | 0
 website/data/docs-nav-data.json                                 | 2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename website/content/docs/manage/{manage-variables.mdx => variables.mdx} (100%)

diff --git a/website/content/docs/manage/manage-variables.mdx b/website/content/docs/manage/variables.mdx
similarity index 100%
rename from website/content/docs/manage/manage-variables.mdx
rename to website/content/docs/manage/variables.mdx
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index e98703ee327..1315d93b090 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -325,7 +325,7 @@
       },
       {
         "title": "Nomad variables",
-        "path": "manage/manage-variables"
+        "path": "manage/variables"
       },
       {
         "title": "Recovery",