[HPR-763] Update HCL variable documentation (#12058)

* Update HCL variable documentation

* Add supported arguments section for variables
* Add inpage links to key variable arguments
* Reorder content to cluster assignment documentation together
* Split variable definitions into two sub-sections

Co-authored-by: Lucas Bajolet <105649352+lbajolet-hashicorp@users.noreply.github.com>

website/content/docs/templates/hcl_templates/variables.mdx

@@ -79,33 +79,32 @@ name for the variable, which must be unique among all variables in the same
 build. This name is used to assign a value to the variable from outside and to
 reference the variable's value from within the build.
 
-The `variable` block can optionally include a `type` argument to specify what
-value types are accepted for the variable, as described in the following
-section.
 
-The `variable` declaration can also include a `default` argument. If present,
+## Arguments
-the variable is considered to be _optional_ and the default value will be used
-if no value is set when calling the build or running Packer. The `default`
-argument requires a literal value and cannot reference other objects in the
-configuration.
 
-## Using Input Variable Values
+Packer defines the following arguments for variable declarations:
 
-Within the build that declared a variable, its value can be accessed from
+* [`default`][inpage-default] - A default value which then makes the variable optional.
-within [expressions](/docs/templates/hcl_templates/expressions) as `var.<NAME>`, where `<NAME>`
+* [`type`][inpage-type] - This argument specifies what value types are accepted for the variable.
-matches the label given in the declaration block:
+* [`description`][inpage-description] - This specifies the input variable's documentation.
+* [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints.
+* [`sensitive`][inpage-sensitive] -  This causes string-values from that variable to be obfuscated from Packer's output.
 
-```hcl
-source "googlecompute" "debian"  {
-    zone = var.gcp_zone
-    tags = var.gcp_debian_tags
-}
-```
 
-The value assigned to a variable can be accessed only from expressions within
-the folder where it was declared.
 
-## Type Constraints
+### Default values
+
+[inpage-default]: #default-values
+
+The variable declaration can also include a `default` argument. If present,
+the variable is considered to be _optional_ and the default value will be used
+if no value is set when calling the module or running Terraform. The `default`
+argument requires a literal value and cannot reference other objects in the
+configuration.
+
+
+### Type Constraints
+[inpage-type]: #type-constraints
 
 The `type` argument in a `variable` block allows you to restrict the [type of
 value](/docs/templates/hcl_templates/expressions#types-and-values) that will be accepted as the value
@@ -146,7 +145,9 @@ variable [from env vars](#environment-variables) or [from the command
 line](#variables-on-the-command-line), the variable will always be interpreted
 as a string.
 
-## Input Variable Documentation
+### Input Variable Documentation
+
+[inpage-description]: #input-variable-documentation
 
 Because the input variables of a build are part of its user interface, you can
 briefly describe the purpose of each variable using the optional `description`
@@ -165,12 +166,32 @@ documentation about the build, and so it should be written from the perspective
 of the user of the build rather than its maintainer. For commentary for build
 maintainers, use comments.
 
+`@include 'from-1.5/variables/custom-validation.mdx'`
+
+`@include 'from-1.5/variables/sensitive.mdx'`
+
+
+## Using Input Variable Values
+
+Within the build that declared a variable, its value can be accessed from
+within [expressions](/docs/templates/hcl_templates/expressions) as `var.<NAME>`, where `<NAME>`
+matches the label given in the declaration block:
+
+```hcl
+source "googlecompute" "debian"  {
+    zone = var.gcp_zone
+    tags = var.gcp_debian_tags
+}
+```
+
+The value assigned to a variable can be accessed only from expressions within
+the folder where it was declared.
+
+
 `@include 'from-1.5/variables/assignment.mdx'`
 
 The following sections describe these options in more detail.
 
-`@include 'from-1.5/variables/custom-validation.mdx'`
-
 ### Variables on the Command Line
 
 To specify individual variables on the command line, use the `-var` option when
@@ -189,11 +210,11 @@ you at least set a default type instead of using empty blocks; this helps the
 HCL parser understand what is being set. Otherwise, the interpreter will assume
 that any variable set on the command line is a string.
 
-### Variable Definitions (`.pkrvars.hcl` and `.auto.pkrvars.hcl`) Files
+### Standard Variable Definitions Files
 
 To set lots of variables, it is more convenient to specify their values in a
-_variable definitions file_ (with a filename ending in either `.pkrvars.hcl` or
+_variable definitions file_ with a filename ending in either `.pkrvars.hcl` or
-`.pkrvars.json`) and then specify that file on the command line with
+`.pkrvars.json` and then specify that file on the command line with
 `-var-file`:
 
 ```shell-session
@@ -201,7 +222,7 @@ $ packer build -var-file="testing.pkrvars.hcl"
 ```
 
 A variable definitions file uses the same basic syntax as Packer language
-files, but consists only of variable name assignments:
+files, but consists only of variable name and its assigned values:
 
 ```hcl
 image_id = "ami-abc123"
@@ -211,7 +232,13 @@ availability_zone_names = [
 ]
 ```
 
-Packer also automatically loads a number of variable definitions files if they
+~> **Important**: Unlike legacy JSON templates the input variables within a variable definitions file must be declared 
+via a variables block within a standard HCL2 template file `*.pkr.hcl` before it can be assigned a value. 
+Failure to do so will result in an unknown variable error during Packer's runtime.
+
+### Auto-loaded Variable Definitions Files
+
+Packer also has the ability automatically load one or more variable definitions files if they
 are present:
 
 - Any files with names ending in `.auto.pkrvars.hcl` or `.auto.pkrvars.json`.
@@ -226,6 +253,11 @@ with the root object properties corresponding to variable names:
 }
 ```
 
+~> **Important**: Unlike legacy JSON templates the input variables within a variable definitions file must be declared 
+via a variables block within a standard HCL2 template file `*.pkr.hcl` before it can be assigned a value. 
+Failure to do so will result in an unknown variable error during Packer's runtime.
+
+
 ### Environment Variables
 
 As a fallback for the other ways of defining variables, Packer searches the
@@ -307,4 +339,3 @@ other variables: the last value found overrides the previous values.
 |     `-var bar=yz` argument     | error, "bar undeclared" |  error, "bar undeclared"  |
 |    `export PKR_VAR_bar=yz`     |            -            |             -             |
 
-`@include 'from-1.5/variables/sensitive.mdx'`

website/content/partials/from-1.5/variables/assignment.mdx

@@ -1,8 +1,7 @@
-## Assigning Values to build Variables
+## Assigning Values to input Variables
 
 Once a variable is declared in your configuration, you can set it:
 
 - Individually, with the `-var foo=bar` command line option.
-- In variable definitions (`.pkrvars.hcl` and `.auto.pkrvars.hcl`) files,
+- In variable definitions files, either specified on the command line with the `-var-files values.pkrvars.hcl` or automatically loaded (`*.auto.pkrvars.hcl`).
-  either specified on the command line or automatically loaded.
 - As environment variables, for example: `PKR_VAR_foo=bar`

website/content/partials/from-1.5/variables/custom-validation.mdx

@@ -1,4 +1,6 @@
-## Custom Validation Rules
+### Custom Validation Rules
+
+[inpage-validation]: #custom-validation-rules
 
 In addition to Type Constraints, you can specify arbitrary custom validation
 rules for a particular variable using one or more `validation` block nested

website/content/partials/from-1.5/variables/sensitive.mdx

@@ -1,4 +1,7 @@
-## A variable can be sensitive
+### Suppressing Sensitive Variables
+
+[inpage-sensitive]: #suppressing-sensitive-variables
+
 
 When a variable is sensitive all string-values from that variable will be
 obfuscated from Packer's output :