Adding docs for nested templates

Signed-off-by: Dave Henderson <dhenderson@gmail.com>

2 files changed, 89 insertions, 0 deletions

diff --git a/docs/content/syntax.md b/docs/content/syntax.md
index fe1640a7..453d61d0 100644
--- a/docs/content/syntax.md
+++ b/docs/content/syntax.md
@@ -137,6 +137,53 @@ Templates rendered by gomplate always have a _default_ context. In future, gompl
 context may expand (_watch this space!_), but currently, it contains one item: the
 system's environment variables, available as [`.Env`](#env).
 
+## Nested templates
+
+Gomplate supports nested templates, using Go's `template` action. These can be
+defined in-line with the `define` action, or external data can be used with the
+[`--template`/`-t`](../usage/#template-t) flag.
+
+Note that nested templates do _not_ have access to gomplate's default
+[context](#the-context) (though it can be explicitly provided to the `template`
+action).
+
+### In-line templates
+
+To define a nested template in-line, you can use the `define` action.
+
+```
+{{ define "T1" -}}
+Hello {{ . }}!
+{{- end -}}
+
+{{ template "T1" "World" }}
+{{ template "T1" }}
+{{ template "T1" "everybody" }}
+```
+
+This renders as:
+
+```
+Hello World!
+Hello <no value>!
+Hello everybody!
+```
+
+### External templates
+
+To define a nested template from an external source such as a file, use the
+[`--template`/`-t`](../usage/#template-t) flag.
+
+_hello.t:_
+```
+Hello {{ . }}!
+```
+
+```
+$ gomplate -t hello=hello.t -i '{{ template "hello" "World" }} {{ template "hello" .Env.USER }}"
+Hello World! Hello hairyhenderson!
+```
+
 ## `.Env`
 
 You can easily access environment variables with `.Env`, but there's a catch:
diff --git a/docs/content/usage.md b/docs/content/usage.md
index 9b9abb65..7e2dcdef 100644
--- a/docs/content/usage.md
+++ b/docs/content/usage.md
@@ -82,6 +82,48 @@ A few different forms are valid:
 Sometimes it's necessary to override the default template delimiters (`{{`/`}}`).
 Use `--left-delim`/`--right-delim` or set `$GOMPLATE_LEFT_DELIM`/`$GOMPLATE_RIGHT_DELIM`.
 
+### `--template`/`-t`
+
+Add a nested template that can be referenced by the main input template(s) with the [`template`](https://golang.org/pkg/text/template/#hdr-Actions) built-in. Specify multiple times to add multiple template references.
+
+A few different forms are valid:
+
+- `--template mytemplate.t`
+  - References a file `mytemplate.t` in the current working directory.
+  - It will be available as a template named `mytemplate.t`:
+    ```console
+    $ gomplate --template helloworld.tmpl -i 'here are the contents of the template: [ {{ template "helloworld.tmpl" }} ]'
+    here are the contents of the template: [ hello, world! ]
+    ```
+- `--template path/to/mytemplate.t`
+  - References a file `mytemplate.t` in the path `path/to/`.
+  - It will be available as a template named `path/to/mytemplate.t`:
+    ```console
+    $ gomplate --template foo/bar/helloworld.tmpl -i 'here are the contents of the template: [ {{ template "foo/bar/helloworld.tmpl" }} ]'
+    here are the contents of the template: [ hello, world! ]
+    ```
+- `--template path/to/`
+  - Makes available all files in the path `path/to/`.
+  - Any files within this path can be referenced:
+    ```console
+    $ gomplate --template foo/bar/ -i 'here are the contents of the template: [ {{ template "foo/bar/helloworld.tmpl" }} ]'
+    here are the contents of the template: [ hello, world! ]
+    ```
+- `--template alias=path/to/mytemplate.t`
+  - References a file `mytemplate.t` in the path `path/to/`
+  - It will be available as a template named `alias`:
+    ```console
+    $ gomplate --template t=foo/bar/helloworld.tmpl -i 'here are the contents of the template: [ {{ template "t" }} ]'
+    here are the contents of the template: [ hello, world! ]
+    ```
+- `--template alias=path/to/`
+  - Makes available all files in the path `path/to/`.
+  - Any files within this path can be referenced, with the path replaced with `alias`:
+    ```console
+    $ gomplate --template dir=foo/bar/ -i 'here are the contents of the template: [ {{ template "dir/helloworld.tmpl" }} ]'
+    here are the contents of the template: [ hello, world! ]
+    ```
+
 ## Post-template command execution
 
 Gomplate can launch other commands when template execution is successful. Simply