docs: update templates for starlark and go (#201)

content/templates/_index.md

@@ -8,3 +8,117 @@ menu:
   main:
     weight: 405
 ---
+
+A template is a pipeline with one to many defined steps that can be sourced into another pipeline. Templates can live in any repository in a [source control system](/docs/concepts/infrastructure/server/source/) and are expanded at compile time to create the final executable pipeline.
+
+Templates can take the form of generalized workflows across repositories or complex workflows like matrices in a single build.
+
+{{% alert color="warning" %}}
+The following YAML tags are not valid inside a template pipeline:
+
+* `services:`
+* `secrets:`
+* `stages:`
+* `templates:`
+{{% /alert %}}
+
+## Template Engines
+
+### Format
+
+By default, templates utilize the Go template language unless otherwise specified. You may opt to specify the `format` key to switch the template language to one of the following:
+
+* `format: go`
+* `format: golang`
+* `format: ""`
+* `format: starlark`
+
+### Go Template
+
+[Go Templates](https://golang.org/pkg/text/template/) is the default formatter for building out template pipelines. We extend Go's built-in template functions by utilizing the [sprig library](http://masterminds.github.io/sprig/) in the engine to allow for more options on top of the Go template syntax.
+
+Let's take a look at a basic template:
+
+{{% alert color="tip" %}}
+For this example we will call it `build.yml` but the YAML does not have a required name.
+{{% /alert %}}
+
+```yaml
+metadata:
+  template: true
+
+steps:
+  - name: Test and Build
+    commands:
+      - go test ./...
+      - go build
+    image: {{ .image }}
+    pull: always
+    ruleset:
+      event: [ push, pull_request ]
+```
+
+The caller of this template could look like:
+
+```yaml
+version: "1"
+templates:
+  - name: go
+    source: github.com/octocat/hello-world/.vela/build.yml
+    format: go
+    type: github
+
+steps:
+  - name: sample
+    template:
+      name: go
+      vars:
+        image: golang:latest
+```
+
+### Starlark
+
+[Starlark](https://github.com/bazelbuild/starlark) is a configuration language that was designed for the [Bazel build system](https://bazel.build/). The language is a [Python](https://www.python.org/) dialect that exists for advanced configuration management that can require complex structures. The language is dynamically typed and allows for all sorts of language-esque primitives to make writing large configuration files more manageable.
+
+It is recommended users read the [Starlark Spec](https://github.com/bazelbuild/starlark/blob/master/spec.md) to understand the syntax differences between Python and Starlark. Python IDE tools are compatible with Starlark to assist users in writing their `.star` or `.py` template pipelines.
+
+Let's take a look at a basic template:
+
+{{% alert color="tip" %}}
+For this example we will call it `build.star` but the file does not have a required name.
+{{% /alert %}}
+
+```python
+def main(ctx):
+  return {
+    'version': '1',
+    'steps': [
+      {
+        'name': 'build',
+        'image': ctx["vars"]["image"],
+        'commands': [
+          'go build',
+          'go test',
+        ]
+      },
+    ],
+}
+```
+
+The caller of this template could look like:
+
+```yaml
+version: "1"
+templates:
+  - name: starlark
+    source: github.com/octocat/hello-world/.vela/build.star
+    format: starlark
+    type: github
+
+steps:
+  - name: sample
+    template:
+      name: starlark
+      vars:
+        image: golang:latest
+```

content/templates/tutorials/_index.md

@@ -4,3 +4,9 @@ linkTitle: "Tutorials"
 description: >
   Learn how to write your own templates for Vela.
 ---
+
+{{% alert title="Note:" color="primary" %}}
+Pipeline templates are an advanced way to write pipelines. We strongly recommend you have a grasp on the following concepts before continuing:
+
+* [Steps](/docs/concepts/pipeline/steps/)
+{{% /alert %}}

content/templates/tutorials/go/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Go"
+linkTitle: "Go"
+description: >
+  See examples on how to write Go templates.
+---

content/templates/tutorials/conditional.md → content/templates/tutorials/go/conditional.md

@@ -2,7 +2,7 @@
 title: "Conditionals"
 linkTitle: "Conditionals"
 description: >
-  Learn how to write a Vela template with conditionals.
+  Example Go template with conditionals.
 ---
 
 {{% alert color="note" %}}
@@ -39,7 +39,7 @@ Let's take a look at using a conditional with a variable in a template:
 metadata:
   template: true
 
-{{$br := .branch}}
+{{$br := vela "BUILD_BRANCH"}}
 
 steps:
 
@@ -76,12 +76,11 @@ templates:
 
 steps:
   - name: golang
-    template:  
+    template:
       name: sample
       vars:
         image: golang:latest
         pull_policy: "pull: always"
-        branch: master
 ```
 
 Which means the compiled pipeline for execution on a worker is:

content/templates/tutorials/loops_maps.md → content/templates/tutorials/go/loops_maps.md

@@ -2,7 +2,7 @@
 title: "Loops with Maps"
 linkTitle: "Loops with Maps"
 description: >
-  Learn how to write a Vela template with loops and maps.
+  Example Go template with loops and maps.
 ---
 
 {{% alert color="note" %}}
@@ -77,7 +77,7 @@ templates:
 
 steps:
   - name: golang
-    template:  
+    template:
       name: sample
       vars:
         pull_policy: "pull: always"

content/templates/tutorials/loops_slice.md → content/templates/tutorials/go/loops_slice.md

@@ -2,7 +2,7 @@
 title: "Loops with Slices"
 linkTitle: "Loops with Slices"
 description: >
-  Learn how to write a Vela template with loops and slices.
+  Example Go template with loops and slices.
 ---
 
 {{% alert color="note" %}}

content/templates/tutorials/mulitline.md → content/templates/tutorials/go/mulitline.md

@@ -2,7 +2,7 @@
 title: "Multiline"
 linkTitle: "Multiline"
 description: >
-  Learn how to write a Vela template that passes multiline strings.
+  Example Go template with multiline strings.
 ---
 
 {{% alert color="note" %}}

content/templates/tutorials/go/vars_platform.md

@@ -0,0 +1,72 @@
+---
+title: "Platform Vars"
+linkTitle: "Platform Vars"
+description: >
+  Example Go template with platform vars.
+---
+
+{{% alert color="note" %}}
+We recommend reviewing [Go Templates documentation](https://golang.org/pkg/text/template/) before attempting to create a template.
+
+If you're new to YAML we also recommend reviewing the [YAML 1.2 spec](https://yaml.org/spec/1.2/spec.html) for validation on syntax.
+{{% /alert %}}
+
+## Overview
+
+Platform variables can be referenced with the following syntax:
+
+`{{ vela "<environment variable>" }}`
+
+## Examples
+
+- `{{ vela "VELA_FULL_REPO_NAME" }}` equates to the `VELA_FULL_REPO_NAME` environment variable
+- `{{ vela "FULL_REPO_NAME" }}` equates to the `VELA_REPO_NAME` environment variable
+- `{{ vela "VELA_BUILD_NUMBER" }}` equates to the `VELA_BUILD_NUMBER` environment variable
+- `{{ vela "VELA_ADDR" }}` equates to the `VELA_ADDR` environment variable
+
+## Sample
+
+Let's take a look at using a platform variable in a template:
+
+```yaml
+metadata:
+  template: true
+
+steps:
+  - name: test
+    commands:
+      - echo {{ vela "VELA_REPO_FULL_NAME" }}
+    image: alpine
+    pull: always
+    ruleset:
+      event: [ push, pull_request ]
+```
+
+The caller of this template could look like:
+
+```yaml
+version: "1"
+templates:
+  - name: sample
+    source: github.com/<org>/<repo>/path/to/file/<template>.yml
+    type: github
+
+steps:
+  - name: sample
+    template:
+      name: echo
+```
+
+Which means the compiled pipeline for execution on a worker is:
+
+```yaml
+version: "1"
+steps:
+  - name: sample_echo
+    commands:
+      - echo github/octocat
+    image: alpine
+    pull: always
+    ruleset:
+      event: [ push, pull_request ]
+```

content/templates/tutorials/starlark/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Starlark"
+linkTitle: "Starlark"
+description: >
+  See examples on how to write Starlark templates.
+---