chore(templates): docs for nested templates

content/installation/server/reference/_index.md

@@ -386,6 +386,18 @@ The variable can be provided as a `duration` (i.e. `5s`, `10m`).
 This variable has a default value of `8s`.
 {{% /alert %}}
 
+### VELA_MAX_TEMPLATE_DEPTH
+
+This configuration variable is used by the [compiler component](/docs/installation/server/reference/compiler) for the server.
+
+This variable sets the maximum depth of nested templates that can be called during compilation.
+
+The variable can be provided as an `integer`.
+
+{{% alert title="Note:" color="primary" %}}
+This variable has a default value of `3`.
+{{% /alert %}}
+
 ### VELA_PORT
 
 This variable sets the port the server API responds on for HTTP requests.

content/installation/server/reference/compiler.md

@@ -42,6 +42,7 @@ The following options are used to configure the component:
 | `modification-retries` | number of times to resend failed requests to the modification endpoint          | `false`  | `5`                   | `MODIFICATION_RETRIES`<br>`VELA_MODIFICATION_RETRIES`   |
 | `modification-secret`  | authenticates communication between compiler and the modification endpoint      | `false`  | `N/A`                 | `MODIFICATION_SECRET`<br>`VELA_MODIFICATION_SECRET`     |
 | `modification-timeout` | timeout for requests sent to the modification endpoint                          | `false`  | `8s`                  | `MODIFICATION_TIMEOUT`<br>`VELA_MODIFICATION_TIMEOUT`   |
+| `max-template-depth`   | max depth for calling nested templates during compilation                       | `true`   | `3`                   | `MAX_TEMPLATE_DEPTH`<br>`VELA_MAX_TEMPLATE_DEPTH`       |
 
 _(1) this will be the latest available, tagged release of `target/vela-git` at the time the server component is released_
 

content/templates/_index.md

@@ -17,7 +17,6 @@ Templates can take the form of generalized workflows across repositories or comp
 The following YAML tags are not valid inside a template pipeline:
 
 * `stages:`
-* `templates:`
 {{% /alert %}}
 
 ## Reference documentation
@@ -327,4 +326,96 @@ stages:
         pull: always
         ruleset:
           event: [ push, pull_request ]      
-```
+```
+
+### Nested Templates
+
+As of version `0.20.0`, Vela supports templates calling templates. This can be useful for cases where a portable and repeatable process exists within a larger template. Let's take a look at an example:
+
+#### Parent Pipeline (.vela.yml)
+
+```yaml
+version: "1"
+
+templates:
+  - name: test_and_build
+    source: github.com/octocat/hello-world/.vela/test_and_build.yml
+    format: go
+    type: github
+
+# in this example, this project uses a redis service to test, whereas perhaps other projects do not
+steps:
+  - name: redis
+    image: redis:latest
+    pull: always
+    detach: true
+
+  - name: check status
+    image: redis:latest
+    pull: always
+    commands:
+      - sleep 15
+      - redis-cli -h redis ping\
+
+  # call the portable go test and build template
+  - name: test_and_build
+    template:
+      name: test_and_build
+```
+
+#### Template
+
+```yaml
+metadata:
+  template: true
+
+templates:
+  - name: tag
+    source: github.com/octocat/hello-world/.vela/tag.yml
+    format: go
+    type: github
+
+steps:
+  - name: install
+    image: golang:latest
+    pull: always
+    environment:
+      CGO_ENABLED: '0'
+      GOOS: linux
+    commands:
+      - go get ./...
+
+  - name: test
+    image: golang:latest
+    pull: always
+    environment:
+      CGO_ENABLED: '0'
+      GOOS: linux
+    commands:
+      - go test ./...
+
+  - name: build
+    image: golang:latest
+    pull: always
+    environment:
+      CGO_ENABLED: '0'
+      GOOS: linux
+    commands:
+      - go build
+
+  # in this example, the tag template is expanded within this go test_and_build template
+  - name: tag
+    # leveraging rulesets to control template call
+    ruleset:
+      event: [ tag ]
+    template:
+      name: tag
+```
+
+In the above example, the test and build template will call the tag template on tag events. This style of template composition can help organize pipeline tasks, limit redundant code, and make editing/improving pipelines an easier endeavor.
+
+The limitation on _how many_ nested templates can be called is determined by the `VELA_MAX_TEMPLATE_DEPTH` flag set by platform administrators.
+
+{{% alert title="Tip:" color="info" %}}
+Note: when using nested templates with `render_inline: true`, all templates that are called must also have `render_inline: true` in the `metadata` block.
+{{% /alert %}}