feat: add docs for new render inline option (#291)

content/reference/yaml/metadata.md

@@ -19,10 +19,11 @@ metadata:
 
 ## Tags
 
-| Tag        | Required | Type | Description                                   |
-|------------|----------|------|-----------------------------------------------|
-| `template` | Y        | bool | Enables compiling the pipeline as a template. |
-| `clone`    | N        | bool | Enables injecting the default clone process.  |
+| Tag             | Required | Type | Description                                                        |
+|-----------------|----------|------|--------------------------------------------------------------------|
+| `template`      | Y        | bool | Enables compiling the pipeline as a template.                      |
+| `clone`         | N        | bool | Enables injecting the default clone process.                       |
+| `render_inline` | N        | bool | Enables rendering without explicitly calling within the pipeline.  |
 
 ### Usage
 
@@ -60,3 +61,15 @@ metadata:
   # configuration specified is used during compile phase.
   environment: [ steps, services, secrets ]
 ```
+
+#### The `render_inline:` tag
+
+```yaml
+---
+metadata:
+  # By default, the below is populated into every pipeline with
+  # false. But, when set to "true" a user can render a template 
+  # in the resulting pipeline without referencing it in stages
+  # or steps. 
+  render_inline: false
+```

content/templates/_index.md

@@ -41,7 +41,7 @@ By default, templates utilize the Go template language unless otherwise specifie
 
 Let's take a look at a basic template:
 
-{{% alert color="tip" %}}
+{{% alert title="Tip:" color="info" %}}
 For this example we will call it `build.yml` but the YAML does not have a required name.
 {{% /alert %}}
 
@@ -86,7 +86,7 @@ It is recommended users read the [Starlark Spec](https://github.com/bazelbuild/s
 
 Let's take a look at a basic template:
 
-{{% alert color="tip" %}}
+{{% alert title="Tip:" color="info" %}}
 For this example we will call it `build.star` but the file does not have a required name.
 {{% /alert %}}
 
@@ -130,12 +130,11 @@ steps:
 As of `0.9.0` Vela allows using Starlark and Go templates directly in the `.vela.yml` 
 given you select the desired template language in the pipeline settings `https://vela.company.com/<org>/<repo>/settings`.
 
-**NOTE:** When starlark is chosen in the pipeline settings, Vela will look for any of the following files for the pipeline instructions
+**NOTE:** When Starlark is chosen in the pipeline settings, Vela will look for any of the following files for the pipeline instructions
 `.vela.yml`, `.vela.py` or `.vela.star`
 
 #### Example `.vela.yml` using Golang
 ```yaml
-
 version: "1"
 
 # The trailing dash trims any whitespace to the right of the closing }} tag. See
@@ -182,3 +181,123 @@ def stage(word):
       ]
   }
 ```
+
+### Rendering inline directly in `.vela.yml`
+
+Rendering a template inline gives you the power of:
+
+ - using an external template without the need of having to specify using that directly in the pipeline 
+ - merging templates into an existing pipeline without needing to be expanded
+
+{{% alert title="Warning:" color="warning" %}}
+You **can not** mix stages and steps pipelines in a single render. They must be all of one type. 
+{{% /alert %}}
+
+Using this feat unlocks powerful pipelines that allow you to use templates with:
+
+- stages
+- steps
+- services
+- secrets
+
+To use this feature all you need to do is add `render_inline: true` in the metadata block of your pipeline and you can start compiling templates without the need of the stages and steps blocks. This feature does work with both Go templates and Starlark. 
+
+#### Basic
+
+This example is for injecting a stages into an external calling pipeline.
+
+{{% alert title="Tip:" color="info" %}}
+The same pattern can be used with steps workflows.
+{{% /alert %}}
+
+```yaml
+metadata:
+  template: true
+
+stages:
+  test:
+    steps:
+      - name: Test
+        commands:
+          - go test ./...
+        image: {{ .image }}
+        pull: always
+        ruleset:
+          event: [ push, pull_request ]
+  build:
+    steps:
+      - name: Build
+        commands:
+          - go build
+        image: {{ .image }}
+        pull: always
+        ruleset:
+          event: [ push, pull_request ]
+```
+
+The caller of this template could look like:
+
+```yaml
+version: "1"
+metadata:
+  render_inline: true
+
+templates:
+  - name: go
+    source: github.com/octocat/hello-world/.vela/build.yml
+    format: go
+    type: github
+    vars:
+      image: golang:latest
+```
+
+#### Advanced
+
+This example is for combing stages from an external template into the calling pipeline.
+
+{{% alert title="Tip:" color="info" %}}
+The same pattern can be used with steps workflows.
+{{% /alert %}}
+
+```yaml
+metadata:
+  template: true
+
+stages:
+  test:
+    steps:
+      - name: Test
+        commands:
+          - go test ./...
+        image: {{ .image }}
+        pull: always
+        ruleset:
+          event: [ push, pull_request ]
+```
+
+The caller of this template could look like:
+
+```yaml
+version: "1"
+metadata:
+  render_inline: true
+
+templates:
+  - name: go
+    source: github.com/octocat/hello-world/.vela/build.yml
+    format: go
+    type: github
+    vars:
+      image: golang:latest
+
+stages:
+  build:
+    steps:
+      - name: Build
+        commands:
+          - go build
+        image: {{ .image }}
+        pull: always
+        ruleset:
+          event: [ push, pull_request ]      
+```

content/templates/tutorials/go/conditional.md

@@ -27,7 +27,7 @@ From [Go template Conditional](https://golang.org/pkg/text/template/#hdr-Actions
 > string of length zero.
 > Dot is unaffected.
 
-{{% alert color="tip" %}}
+{{% alert title="Tip:" color="info" %}}
 For information on if/else statements see [conditional docs](https://golang.org/pkg/text/template/#hdr-Actions)
 {{% /alert %}}
 

content/templates/tutorials/go/loops_maps.md

@@ -28,7 +28,7 @@ From [Go template range](https://golang.org/pkg/text/template/#hdr-Actions):
 > keys are of basic type with a defined order, the elements will be
 > visited in sorted key order.
 
-{{% alert color="tip" %}}
+{{% alert title="Tip:" color="info" %}}
 For information on range/else statements see [conditional docs](https://golang.org/pkg/text/template/#hdr-Actions)
 {{% /alert %}}
 

content/templates/tutorials/go/loops_slice.md

@@ -28,7 +28,7 @@ From [Go template range](https://golang.org/pkg/text/template/#hdr-Actions):
 > keys are of basic type with a defined order, the elements will be
 > visited in sorted key order.
 
-{{% alert color="tip" %}}
+{{% alert title="Tip:" color="info" %}}
 For information on range/else statements see [conditional docs](https://golang.org/pkg/text/template/#hdr-Actions)
 {{% /alert %}}
 

content/templates/tutorials/go/mulitline.md

@@ -24,7 +24,7 @@ From [YAML Spec Scalars](https://yaml.org/spec/1.2/spec.html):
   // ||  ||__
 ```
 
-{{% alert color="tip" %}}
+{{% alert title="Tip:" color="info" %}}
 For information on more types of scalars read the [spec information](https://yaml.org/spec/1.2/spec.html#id2760844)
 {{% /alert %}}
 

content/templates/tutorials/starlark/conditional.md

@@ -17,7 +17,7 @@ From [Starlark Conditional Expressions](https://github.com/google/starlark-go/bl
 "yes" if enabled else "no"
 ```
 
-{{% alert color="tip" %}}
+{{% alert title="Tip:" color="info" %}}
 For information on if/else statements see [conditional docs](https://github.com/google/starlark-go/blob/master/doc/spec.md#conditional-expressions)
 {{% /alert %}}