FCCEUD-79 Updates to pantheon2.yml file configuration descriptions (#630)

* fcceud-79 updates to pantheon2.yml file configuration  descriptions

* fcceud-79 updates following tech review

* variants definitionand example

* fcceud-79 updates following review input and suggestions

* emarcusRH-fcceud-79 Various clarifications and other edits.

Co-authored-by: emarcusRH <[email protected]>

Author: stoobie

pantheon-bundle/src/main/resources/SLING-INF/content/docs/modules/con_pantheon_yaml_file.adoc

@@ -5,9 +5,8 @@
 The configuration file, named `pantheon2.yml`, resides in the root directory of your documentation repository. You use this file to designate a Git repository as a source that {ProductShortName} can use to import content. This configuration file provides the information necessary for {ProductShortName} to interact with files in the repository.
 
 ////
-// Keeping this section because the status of the Uploader tool is not clear. It might be relevant in the future.
+Keeping this section because the status of the Uploader tool is not clear. It might be relevant in the future.
 The configuration file enables you to perform the following actions:
-
 * Import content from a Git repository into {ProductShortName}
 * Upload {ContentTerm} into {ProductShortName} using the Uploader tool
 ////
@@ -16,18 +15,55 @@ The configuration file enables you to import content from a Git repository into
 
 The {ProductShortName} configuration file defines the following parameters:
 
-* `server` The URL of the {ProductShortName} server.
-* `repositories` A multi-valued structure with the following child members:
+`server`:: (Required) The URL of the {ProductShortName} server.
+`repository`:: (Required) The name of the repository. It is recommended not to include spaces in the repository name.
+`variants`:: (Required) Separate sets of output built on the same set of files and differentiated by these values: `name`, `path`, and `canonical`. Modules and assemblies can have variants to differentiate how they are used, and what output is created.
 +
-** `name` (optional) A unique ID that displays in URLs on the {ProductShortName} site when you view modules and assemblies.
+** `name` (Optional) A unique ID that is displayed in URLs on the {ProductShortName} site when you view modules and assemblies. If no value is provided for `name`, this field is defined as *DEFAULT*.
 +
 For example, if you specify `name: rhel_docs`, and one of your files is named [filename]`foo.adoc`, the module's URL in {ProductShortName} is:
-`\http://<_{ProductShortName}__url>/content/repositories/**rhel_docs**/entities/modules/getting_started/foo.adoc.preview`
-** `modules` (optional) Patterns for modules that show up in the search results on {ProductShortName}.
-** `resources` (optional) Image files, legal information, or other content that is not a complete module or assembly.
-** `attributes` (optional) A path to the repository-wide attributes file. Provide this value if your documents relies on the attributes file.
-+
-NOTE: You must define the values for `server` and `repository`.
+`\https://<_{ProductShortName}__url>/content/repositories/*repository*/entities/modules/getting_started/foo.adoc.preview`
+** `path` (Optional) The path containing resource files, such as `attributes.adoc`.
+** `canonical` (Required) The primary variant of content. If a search engine sees multiple variants of the same piece of content (HTML page or a group of pages) it needs to know what the primary or original one is to establish ranking. Declaring a piece of content as `canonical` tells the search engine to treat that piece of content as the canonical variant. The canonical declaration is transformed into HTML meta data. Possible values: `*true*` or `*false*`.
+
+`assemblies`:: (optional) The path to assemblies in the repository that should be uploaded. The path can include specific files or a pattern, such as `*.adoc` to include only `.adoc` files, or `**` to include all files.
+`modules`:: Path to modules in the repository that should be uploaded.
+`resources`:: (optional) Attributes, image files, snippets, legal information, or other content that is not a complete module or assembly.
+
+[NOTE]
+====
+File paths can indicate specific files, or file patterns. For example:
+
+* This will upload everything inside `assemblies/`: `assemblies/**`
+* This will only upload `.adoc` files inside `assemblies/`: `assemblies/*.adoc`
+====
+
+.Examples of variants:
+
+** Document level - _Installing RHV using the command line_; _Installing RHV using the Administration Portal_.
+** Module level - The same module is published in multiple Red Hat documents, such as _Red Hat Decision Manager_, _Red Hat Process Automation Manager_.
+
+.Example YAML file with multiple variants
+[source,yaml,options="nowrap",subs="attributes+,+quotes"]
+----
+server: https://pantheon.corp.redhat.com
+repository: rhel-docs
+variants:
+  - name: rhel9
+    path: rhel-9/common-content/attributes.adoc
+    canonical: true
+  - name: rhel8
+    path: rhel-8/common-content/attributes.adoc
+    canonical: false
+assemblies:
+  - rhel/assemblies/*.adoc
+modules:
+  - rhel/modules/*.adoc
+resources:
+  - images/*.png
+----
+
+In the above example, the assemblies and modules for both rhel9 and rhel8 variants are in the same directories, `rhel/assemblies/` and `rhel/modules/`. Depending on the value of their attributes, {ProductShortName} creates the separate variants.
 
 .Example {ProductShortName} configuration file
 [source,yaml,options="nowrap",subs="attributes+,+quotes"]