docs: Update documentation

docs-v2/content/en/docs/environment/templating.md

@@ -6,14 +6,21 @@ featureId: templating
 aliases: [/docs/how-tos/templating]
 ---
 
-Skaffold allows for certain fields in the config to be templated with values either from environment variables, or certain special values computed by Skaffold.
+Skaffold allows for certain fields in the config to be templated via the [Go `text/template` package](https://pkg.go.dev/text/template). 
+Environment variables and certain special values computed by Skaffold (see below) are available in the templating 
+context (defined as "dot" or `.`).
+
+Go templates are quite powerful, including [control flow](https://pkg.go.dev/text/template#hdr-Actions), 
+[arguments](https://pkg.go.dev/text/template#hdr-Arguments), [pipelining](https://pkg.go.dev/text/template#hdr-Pipelines) 
+and [variables](https://pkg.go.dev/text/template#hdr-Variables). [Predefined functions](https://pkg.go.dev/text/template#hdr-Functions) 
+in the standard library are complemented in Skaffold by the  [Sprig template function library](http://masterminds.github.io/sprig/).
 
 {{% readfile file="samples/templating/env.yaml" %}}
 
 Suppose the value of the `FOO` environment variable is `v1`, the image built
 will be `gcr.io/k8s-skaffold/example:v1`.
 
-List of fields that support templating:
+#### List of fields that support templating:
 
 * `build.artifacts[].docker.buildArgs` (see [builders]({{< relref "/docs/builders" >}}))
 * `build.artifacts[].ko.{env,flags,labels,ldflags}` (see [`ko` builder]({{< relref "/docs/builders/builder-types/ko" >}}))
@@ -32,7 +39,7 @@ List of fields that support templating:
 
 _Please note, this list is not exhaustive._
 
-List of variables that are available for templating:
+#### List of variables that are available for templating:
 
 * all environment variables passed to the Skaffold process at startup
 * For the `envTemplate` tagger:
@@ -43,6 +50,18 @@ List of variables that are available for templating:
   * `IMAGE_NAME2`, `IMAGE_REPO2`, `IMAGE_TAG2`, `IMAGE_DIGEST2` - the 2nd artifact's image name, tag, and sha256 digest
   * `IMAGE_NAME2`, `IMAGE_REPON`, `IMAGE_TAGN`, `IMAGE_DIGESTN` - the Nth artifact's image name, tag, and sha256 digest
 
-### Template functions
-In addition to the [built-in template functions](https://pkg.go.dev/text/template) in Golang and the [Sprig template functions](http://masterminds.github.io/sprig/), Skaffold also provides the following:
+### Local template functions
+In addition to the functions listed above, Skaffold locally provides the following:
 - `cmd`: This allows users to use the result from external commands in template, for example `{{cmd "bash" "-c" "xxx xxx xxx"}}` can be used to execute bash script and get the result into the template.
+
+### Usage Examples
+The templating pipelines provided by Go templates can be quite comprehensive when combined with Sprig. For example:
+* The environment variable `SOURCE_DATE_EPOCH` commonly specifies a UNIX timestamp to be used in replacement of the 
+  current date and time in compiler `__DATE__` and `__TIME__` macros, so that the embedded timestamps become reproducible.
+  A numeric UNIX timestamp is less readable than a proper date, and the environment variable may not exist at all, 
+  in which case we would want to use the current date. This could be written as:
+
+  ```default now .SOURCE_DATE_EPOCH | date "2006-01-02T15:04:05-0700"``` 
+* The idiomatic seven-character abbreviated Git hash is easily accessible:
+
+  ```cmd "bash" "-c" "git rev-parse HEAD" | substr 0 7```