summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/.gitignore2
-rw-r--r--docs/_config.yml1
-rw-r--r--docs/config.toml51
-rw-r--r--docs/content/functions.md (renamed from docs/index.md)374
-rw-r--r--docs/content/index.md29
-rw-r--r--docs/content/installing.md81
-rw-r--r--docs/content/syntax.md15
-rw-r--r--docs/content/usage.md60
8 files changed, 306 insertions, 307 deletions
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..7b822970
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,2 @@
+themes/
+public/
diff --git a/docs/_config.yml b/docs/_config.yml
deleted file mode 100644
index c4192631..00000000
--- a/docs/_config.yml
+++ /dev/null
@@ -1 +0,0 @@
-theme: jekyll-theme-cayman \ No newline at end of file
diff --git a/docs/config.toml b/docs/config.toml
new file mode 100644
index 00000000..f1484cc9
--- /dev/null
+++ b/docs/config.toml
@@ -0,0 +1,51 @@
+baseURL = "/"
+languageCode = "en-us"
+title = "gomplate documentation"
+
+theme = "hugo-material-docs"
+
+
+[params]
+ author = "hairyhenderson"
+ description = "gomplate documentation"
+ copyright = "Released under the MIT license"
+ provider = "GitHub"
+ repo_url = "https://github.com/hairyhenderson/gomplate"
+ googleAnalytics = "UA-82637990-1"
+
+[params.palette]
+ primary = "indigo"
+
+[social]
+ twitter = "hairyhenderson"
+ github = "hairyhenderson"
+
+[[menu.main]]
+ name = "About"
+ url = "/"
+ weight = 1
+ pre = ""
+
+[[menu.main]]
+ name = "Installing"
+ url = "installing/"
+ weight = 10
+ pre = ""
+
+[[menu.main]]
+ name = "Usage"
+ url = "usage/"
+ weight = 11
+ pre = ""
+
+[[menu.main]]
+ name = "Syntax"
+ url = "syntax/"
+ weight = 12
+ pre = ""
+
+[[menu.main]]
+ name = "Built-in Functions"
+ url = "functions/"
+ weight = 13
+ pre = ""
diff --git a/docs/index.md b/docs/content/functions.md
index f0cd5879..72836f36 100644
--- a/docs/index.md
+++ b/docs/content/functions.md
@@ -1,227 +1,18 @@
-# gomplate
-
-A [Go template](https://golang.org/pkg/text/template/)-based CLI tool. `gomplate` can be used as an alternative to
-[`envsubst`](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html) but also supports
-additional template datasources such as: JSON, YAML, AWS EC2 metadata, and
-[Hashicorp Vault](https://https://www.vaultproject.io/) secrets.
-
-I really like `envsubst` for use as a super-minimalist template processor. But its simplicity is also its biggest flaw: it's all-or-nothing with shell-like variables.
-
-Gomplate is an alternative that will let you process templates which also include shell-like variables. Also there are some useful built-in functions that can be used to make templates even more expressive.
-
-!-- TOC depthFrom:2 depthTo:4 withLinks:1 updateOnSave:1 orderedList:0 -->
-
-- [Installing](#installing)
- - [macOS with homebrew](#macos-with-homebrew)
- - [Alpine Linux](#alpine-linux)
- - [use with Docker](#use-with-docker)
- - [manual install](#manual-install)
- - [install with `go get`](#install-with-go-get)
-- [Usage](#usage)
- - [Commandline Arguments](#commandline-arguments)
- - [`--file`/`-f`, `--in`/`-i`, and `--out`/`-o`](#-file-f-in-i-and-out-o)
- - [`--datasource`/`-d`](#-datasource-d)
- - [Overriding the template delimiters](#overriding-the-template-delimiters)
-- [Syntax](#syntax)
- - [About `.Env`](#about-env)
- - [Built-in functions](#built-in-functions)
- - [`contains`](#contains)
- - [`getenv`](#getenv)
- - [`hasPrefix`](#hasprefix)
- - [`hasSuffix`](#hassuffix)
- - [`bool`](#bool)
- - [`slice`](#slice)
- - [`split`](#split)
- - [`splitN`](#splitn)
- - [`replaceAll`](#replaceall)
- - [`title`](#title)
- - [`toLower`](#tolower)
- - [`toUpper`](#toupper)
- - [`trim`](#trim)
- - [`urlParse`](#urlparse)
- - [`has`](#has)
- - [`join`](#join)
- - [`indent`](#indent)
- - [`json`](#json)
- - [`jsonArray`](#jsonarray)
- - [`yaml`](#yaml)
- - [`yamlArray`](#yamlarray)
- - [`toJSON`](#tojson)
- - [`toJSONPretty`](#tojsonpretty)
- - [`toYAML`](#toyaml)
- - [`datasource`](#datasource)
- - [`datasourceExists`](#datasourceexists)
- - [`ds`](#ds)
- - [`ec2meta`](#ec2meta)
- - [`ec2dynamic`](#ec2dynamic)
- - [`ec2region`](#ec2region)
- - [`ec2tag`](#ec2tag)
- - [Some more complex examples](#some-more-complex-examples)
- - [Variable assignment and `if`/`else`](#variable-assignment-and-ifelse)
-- [License](#license)
-
-<!-- /TOC -->
-
-## Installing
-
-### macOS with homebrew
-
-The simplest method for macOS is to use homebrew:
-
-```console
-$ brew tap hairyhenderson/tap
-$ brew install gomplate
-...
-```
-
-### Alpine Linux
-
-Currently, `gomplate` is available in the `community` repository for the `edge` release.
-
-```console
-$ echo "http://dl-cdn.alpinelinux.org/alpine/edge/community/" >> /etc/apk/repositories
-$ apk update
-$ apk add gomplate
-...
-```
-
-_Note: the Alpine version of gomplate may lag behind the latest release of gomplate._
-
-### use with Docker
-
-A simple way to get started is with the Docker image.
-
-```console
-$ docker run hairyhenderson/gomplate --version
-```
-
-Of course, there are some drawbacks - any files to be used for [datasources][]
-must be mounted and any environment variables to be used must be passed through:
-
-```console
-$ echo 'My voice is my {{.Env.THING}}. {{(datasource "vault").value}}' \
- | docker run -e THING=passport -v /home/me/.vault-token:/root/.vault-token hairyhenderson/gomplate -d vault=vault:///secret/sneakers
-My voice is my passport. Verify me.
-```
-
-It can be pretty awkward to always type `docker run hairyhenderson/gomplate`,
-so this can be made simpler with a shell alias:
-
-```console
-$ alias gomplate=docker run hairyhenderson/gomplate
-$ gomplate --version
-gomplate version 1.2.3
-```
-
-### manual install
-
-1. Get the latest `gomplate` for your platform from the [releases](https://github.com/hairyhenderson/gomplate/releases) page
-2. Store the downloaded binary somewhere in your path as `gomplate` (or `gomplate.exe`
- on Windows)
-3. Make sure it's executable (on Linux/macOS)
-3. Test it out with `gomplate --help`!
-
-In other words:
-
-```console
-$ curl -o /usr/local/bin/gomplate -sSL https://github.com/hairyhenderson/gomplate/releases/download/<version>/gomplate_<os>-<arch>
-$ chmod 755 /usr/local/bin/gomplate
-$ gomplate --help
-...
-```
-
-### install with `go get`
-
-If you're a Go user already, sometimes it's faster to just use `go get` to install `gomplate`:
-
-```console
-$ go get github.com/hairyhenderson/gomplate
-$ gomplate --help
-...
-```
-
-_Please report any bugs found in the [issue tracker](https://github.com/hairyhenderson/gomplate/issues/)._
-
-## Usage
-
-The usual and most basic usage of `gomplate` is to just replace environment variables. All environment variables are available by referencing `.Env` (or `getenv`) in the template.
-
-The template is read from standard in, and written to standard out.
-
-Use it like this:
-
-```console
-$ echo "Hello, {{.Env.USER}}" | gomplate
-Hello, hairyhenderson
-```
-
-### Commandline Arguments
-
-#### `--file`/`-f`, `--in`/`-i`, and `--out`/`-o`
-
-By default, `gomplate` will read from `Stdin` and write to `Stdout`. This behaviour can be changed.
-
-- Use `--file`/`-f` to use a specific input template file. The special value `-` means `Stdin`.
-- Use `--out`/`-o` to save output to file. The special value `-` means `Stdout`.
-- Use `--in`/`-i` if you want to set the input template right on the commandline. This overrides `--file`. Because of shell command line lengths, it's probably not a good idea to use a very long value with this argument.
-
-##### Multiple inputs
-
-You can specify multiple `--file` and `--out` arguments. The same number of each much be given. This allows `gomplate` to process multiple templates _slightly_ faster than invoking `gomplate` multiple times in a row.
-
-##### `--input-dir` and `--output-dir`
-
-For processing multiple templates in a directory you can use `--input-dir` and `--output-dir` together. In this case all files in input directory will be processed as templates and the resulting files stored in `--output-dir`. The output directory will be created if it does not exist and the directory structure of the input directory will be preserved.
-
-Example:
-
-```bash
- # Process all files in directory "templates" with the datasource given
- # and store the files with the same directory structure in "config"
-gomplate --input-dir=templates --output-dir=config --datasource config=config.yaml
-```
-
-#### `--datasource`/`-d`
-
-Add a data source in `name=URL` form. Specify multiple times to add multiple sources. The data can then be used by the [`datasource`](#datasource) function.
-
-A few different forms are valid:
-- `mydata=file:///tmp/my/file.json`
- - Create a data source named `mydata` which is read from `/tmp/my/file.json`. This form is valid for any file in any path.
-- `mydata=file.json`
- - Create a data source named `mydata` which is read from `file.json` (in the current working directory). This form is only valid for files in the current directory.
-- `mydata.json`
- - This form infers the name from the file name (without extension). Only valid for files in the current directory.
-
-#### Overriding the template delimiters
-
-Sometimes it's necessary to override the default template delimiters (`{{`/`}}`).
-Use `--left-delim`/`--right-delim` or set `$GOMPLATE_LEFT_DELIM`/`$GOMPLATE_RIGHT_DELIM`.
-
-## Syntax
-
-### About `.Env`
-
-You can easily access environment variables with `.Env`, but there's a catch:
-if you try to reference an environment variable that doesn't exist, parsing
-will fail and `gomplate` will exit with an error condition.
-
-Sometimes, this behaviour is desired; if the output is unusable without certain strings, this is a sure way to know that variables are missing!
-
-If you want different behaviour, try `getenv` (below).
-
-### Built-in functions
+---
+title: Built-in functions
+weight: 0
+---
In addition to all of the functions and operators that the [Go template](https://golang.org/pkg/text/template/)
language provides (`if`, `else`, `eq`, `and`, `or`, `range`, etc...), there are
some additional functions baked in to `gomplate`:
-#### `contains`
+## `contains`
Contains reports whether the second string is contained within the first. Equivalent to
[strings.Contains](https://golang.org/pkg/strings#Contains)
-##### Example
+### Example
_`input.tmpl`:_
```
@@ -235,7 +26,7 @@ $ FOO=bar gomplate < input.tmpl
no
```
-#### `getenv`
+## `getenv`
Exposes the [os.Getenv](https://golang.org/pkg/os/#Getenv) function.
@@ -244,7 +35,7 @@ return an empty string.
An optional default value can be given as well.
-##### Example
+#### Example
```console
$ gomplate -i 'Hello, {{getenv "USER"}}'
@@ -253,12 +44,12 @@ $ gomplate -i 'Hey, {{getenv "FIRSTNAME" "you"}}!'
Hey, you!
```
-#### `hasPrefix`
+## `hasPrefix`
Tests whether the string begins with a certain substring. Equivalent to
[strings.HasPrefix](https://golang.org/pkg/strings#HasPrefix)
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -272,12 +63,12 @@ $ URL=https://example.com gomplate < input.tmpl
foo
```
-#### `hasSuffix`
+## `hasSuffix`
Tests whether the string ends with a certain substring. Equivalent to
[strings.HasSuffix](https://golang.org/pkg/strings#HasSuffix)
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -289,11 +80,11 @@ $ URL=http://example.com gomplate < input.tmpl
http://example.com:80
```
-#### `bool`
+## `bool`
Converts a true-ish string to a boolean. Can be used to simplify conditional statements based on environment variables or other text input.
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -307,11 +98,11 @@ $ FOO=true gomplate < input.tmpl
foo
```
-#### `slice`
+## `slice`
Creates a slice. Useful when needing to `range` over a bunch of variables.
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -327,12 +118,12 @@ Hello, Lisa
Hello, Maggie
```
-#### `split`
+## `split`
Creates a slice by splitting a string on a given delimiter. Equivalent to
[strings.Split](https://golang.org/pkg/strings#Split)
-##### Example
+#### Example
```console
$ gomplate -i '{{range split "Bart,Lisa,Maggie" ","}}Hello, {{.}}{{end}}'
@@ -341,75 +132,75 @@ Hello, Lisa
Hello, Maggie
```
-#### `splitN`
+## `splitN`
Creates a slice by splitting a string on a given delimiter. The count determines
the number of substrings to return. Equivalent to [strings.SplitN](https://golang.org/pkg/strings#SplitN)
-##### Example
+#### Example
```console
$ gomplate -i '{{ range splitN "foo:bar:baz" ":" 2 }}{{.}}{{end}}'
foo
bar:baz
```
-#### `replaceAll`
+## `replaceAll`
Replaces all occurrences of a given string with another.
-##### Example
+#### Example
```console
$ gomplate -i '{{ replaceAll "." "-" "172.21.1.42" }}'
172-21-1-42
```
-##### Example (with pipeline)
+#### Example (with pipeline)
```console
$ gomplate -i '{{ "172.21.1.42" | replaceAll "." "-" }}'
172-21-1-42
```
-#### `title`
+## `title`
Convert to title-case. Equivalent to [strings.Title](https://golang.org/pkg/strings/#Title)
-##### Example
+#### Example
```console
$ echo '{{title "hello, world!"}}' | gomplate
Hello, World!
```
-#### `toLower`
+## `toLower`
Convert to lower-case. Equivalent to [strings.ToLower](https://golang.org/pkg/strings/#ToLower)
-##### Example
+#### Example
```console
$ echo '{{toLower "HELLO, WORLD!"}}' | gomplate
hello, world!
```
-#### `toUpper`
+## `toUpper`
Convert to upper-case. Equivalent to [strings.ToUpper](https://golang.org/pkg/strings/#ToUpper)
-##### Example
+#### Example
```console
$ echo '{{toUpper "hello, world!"}}' | gomplate
HELLO, WORLD!
```
-#### `trim`
+## `trim`
Trims a string by removing the given characters from the beginning and end of
the string. Equivalent to [strings.Trim](https://golang.org/pkg/strings/#Trim)
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -421,11 +212,11 @@ $ FOO=" world " | gomplate < input.tmpl
Hello, world!
```
-#### `urlParse`
+## `urlParse`
Parses a string as a URL for later use. Equivalent to [url.Parse](https://golang.org/pkg/net/url/#Parse)
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -442,11 +233,11 @@ The host is example.com:443
The path is /foo/bar
```
-#### `has`
+## `has`
Has reports whether or not a given object has a property with the given key. Can be used with `if` to prevent the template from trying to access a non-existent property in an object.
-##### Example
+#### Example
_Let's say we're using a Vault datasource..._
@@ -475,11 +266,11 @@ $ gomplate -d vault:///secret/foo < input.tmpl
The secret is 'foo: bar'
```
-#### `join`
+## `join`
Concatenates the elements of an array to create a string. The separator string sep is placed between elements in the resulting string.
-##### Example
+#### Example
_`input.tmpl`_
```
@@ -492,11 +283,11 @@ $ gomplate -f input.tmpl
1-2-3
```
-#### `indent`
+## `indent`
Indents a given string with the given indentation pattern. If the input string has multiple lines, each line will be indented.
-##### Example
+#### Example
This function can be especially useful when adding YAML snippets into other YAML documents, where indentation is important:
@@ -513,11 +304,11 @@ foo:
baz: 2
```
-#### `json`
+## `json`
Converts a JSON string into an object. Only works for JSON Objects (not Arrays or other valid JSON types). This can be used to access properties of JSON objects.
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -530,11 +321,11 @@ $ gomplate < input.tmpl
Hello world
```
-#### `jsonArray`
+## `jsonArray`
Converts a JSON string into a slice. Only works for JSON Arrays.
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -547,11 +338,11 @@ $ gomplate < input.tmpl
Hello world
```
-#### `yaml`
+## `yaml`
Converts a YAML string into an object. Only works for YAML Objects (not Arrays or other valid YAML types). This can be used to access properties of YAML objects.
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -564,11 +355,11 @@ $ gomplate < input.tmpl
Hello world
```
-#### `yamlArray`
+## `yamlArray`
Converts a YAML string into a slice. Only works for YAML Arrays.
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -581,11 +372,11 @@ $ gomplate < input.tmpl
Hello world
```
-#### `toJSON`
+## `toJSON`
Converts an object to a JSON document. Input objects may be the result of `json`, `yaml`, `jsonArray`, or `yamlArray` functions, or they could be provided by a `datasource`.
-##### Example
+#### Example
_This is obviously contrived - `json` is used to create an object._
@@ -599,13 +390,13 @@ $ gomplate < input.tmpl
{"hello":"world"}
```
-#### `toJSONPretty`
+## `toJSONPretty`
Converts an object to a pretty-printed (or _indented_) JSON document. Input objects may be the result of `json`, `yaml`, `jsonArray`, or `yamlArray` functions, or they could be provided by a `datasource`.
The indent string must be provided as an argument.
-##### Example
+#### Example
_`input.tmpl`:_
```
@@ -619,11 +410,11 @@ $ gomplate < input.tmpl
}
```
-#### `toYAML`
+## `toYAML`
Converts an object to a YAML document. Input objects may be the result of `json`, `yaml`, `jsonArray`, or `yamlArray` functions, or they could be provided by a `datasource`.
-##### Example
+#### Example
_This is obviously contrived - `json` is used to create an object._
@@ -638,7 +429,7 @@ hello: world
```
-#### `datasource`
+## `datasource`
Parses a given datasource (provided by the [`--datasource/-d`](#--datasource-d) argument).
@@ -646,9 +437,9 @@ Currently, `file://`, `http://`, `https://`, and `vault://` URLs are supported.
Currently-supported formats are JSON and YAML.
-##### Examples
+#### Examples
-###### Basic usage
+##### Basic usage
_`person.json`:_
```json
@@ -667,7 +458,7 @@ $ gomplate -d person.json < input.tmpl
Hello Dave
```
-###### Usage with HTTP data
+##### Usage with HTTP data
```console
$ echo 'Hello there, {{(datasource "foo").headers.Host}}...' | gomplate -d foo=https://httpbin.org/get
@@ -681,7 +472,7 @@ $ gomplate -d foo=https://httpbin.org/get -H 'foo=Foo: bar' -i '{{(datasource "f
bar
```
-###### Usage with Vault data
+##### Usage with Vault data
The special `vault://` URL scheme can be used to retrieve data from [Hashicorp
Vault](https://vaultproject.io). To use this, you must put the Vault server's
@@ -730,7 +521,7 @@ $ echo 'db_password={{(datasource "vault" "db/pass").value}}' \
db_password=prodsecret
```
-#### `datasourceExists`
+## `datasourceExists`
Tests whether or not a given datasource was defined on the commandline (with the
[`--datasource/-d`](#--datasource-d) argument). This is intended mainly to allow
@@ -746,42 +537,42 @@ $ echo '{{if (datasourceExists "test")}}{{datasource "test"}}{{else}}no worries{
no worries
```
-#### `ds`
+## `ds`
Alias to [`datasource`](#datasource)
-#### `ec2meta`
+## `ec2meta`
Queries AWS [EC2 Instance Metadata](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) for information. This only retrieves data in the `meta-data` path -- for data in the `dynamic` path use `ec2dynamic`.
This only works when running `gomplate` on an EC2 instance. If the EC2 instance metadata API isn't available, the tool will timeout and fail.
-##### Example
+#### Example
```console
$ echo '{{ec2meta "instance-id"}}' | gomplate
i-12345678
```
-#### `ec2dynamic`
+## `ec2dynamic`
Queries AWS [EC2 Instance Dynamic Metadata](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) for information. This only retrieves data in the `dynamic` path -- for data in the `meta-data` path use `ec2meta`.
This only works when running `gomplate` on an EC2 instance. If the EC2 instance metadata API isn't available, the tool will timeout and fail.
-##### Example
+#### Example
```console
$ echo '{{ (ec2dynamic "instance-identity/document" | json).region }}' | ./gomplate
us-east-1
```
-#### `ec2region`
+## `ec2region`
Queries AWS to get the region. An optional default can be provided, or returns
`unknown` if it can't be determined for some reason.
-##### Example
+#### Example
_In EC2_
```console
@@ -796,12 +587,12 @@ $ echo '{{ ec2region "foo" }}' | ./gomplate
foo
```
-#### `ec2tag`
+## `ec2tag`
Queries the AWS EC2 API to find the value of the given [user-defined tag](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html). An optional default
can be provided.
-##### Example
+#### Example
```console
$ echo 'This server is in the {{ ec2tag "Account" }} account.' | ./gomplate
@@ -809,32 +600,3 @@ foo
$ echo 'I am a {{ ec2tag "classification" "meat popsicle" }}.' | ./gomplate
I am a meat popsicle.
```
-
-### Some more complex examples
-
-#### Variable assignment and `if`/`else`
-
-_`input.tmpl`:_
-```
-{{ $u := getenv "USER" }}
-{{ if eq $u "root" -}}
-You are root!
-{{- else -}}
-You are not root :(
-{{- end}}
-```
-
-```console
-$ gomplate < input.tmpl
-You are not root :(
-$ sudo gomplate < input.tmpl
-You are root!
-```
-
-## License
-
-[The MIT License](http://opensource.org/licenses/MIT)
-
-Copyright (c) 2016-2017 Dave Henderson
-
-[![Analytics](https://ga-beacon.appspot.com/UA-82637990-1/gomplate/docs/README.md?pixel)](https://github.com/igrigorik/ga-beacon)
diff --git a/docs/content/index.md b/docs/content/index.md
new file mode 100644
index 00000000..2ad6fee6
--- /dev/null
+++ b/docs/content/index.md
@@ -0,0 +1,29 @@
+---
+title: gomplate
+type: index
+weight: 0
+---
+
+A [Go template](https://golang.org/pkg/text/template/)-based CLI tool. `gomplate` can be used as an alternative to
+[`envsubst`](https://www.gnu.org/software/gettext/manual/html_node/envsubst-Invocation.html) but also supports
+additional template datasources such as: JSON, YAML, AWS EC2 metadata, and
+[Hashicorp Vault](https://www.vaultproject.io/) secrets.
+
+I really like `envsubst` for use as a super-minimalist template processor. But its simplicity is also its biggest flaw: it's all-or-nothing with shell-like variables.
+
+Gomplate is an alternative that will let you process templates which also include shell-like variables. Also there are some useful built-in functions that can be used to make templates even more expressive.
+
+
+_Please report any bugs found in the [issue tracker](https://github.com/hairyhenderson/gomplate/issues/)._
+
+{{< note title="Note" >}}
+This documentation is still in the process of being migrated out of the
+[README](https://github.com/hairyhenderson/gomplate/tree/master/README.md), so
+expect some inconsistencies! If you want to help, [PRs and issues are welcome!](https://github.com/hairyhenderson/gomplate/issues/new)
+{{< /note >}}
+
+## License
+
+[The MIT License](http://opensource.org/licenses/MIT)
+
+Copyright (c) 2016-2017 Dave Henderson
diff --git a/docs/content/installing.md b/docs/content/installing.md
new file mode 100644
index 00000000..5f064cae
--- /dev/null
+++ b/docs/content/installing.md
@@ -0,0 +1,81 @@
+---
+title: Installing
+weight: 10
+---
+# Installing
+
+## macOS with homebrew
+
+The simplest method for macOS is to use homebrew:
+
+```console
+$ brew tap hairyhenderson/tap
+$ brew install gomplate
+...
+```
+
+## Alpine Linux
+
+Currently, `gomplate` is available in the `community` repository for the `edge` release.
+
+```console
+$ echo "http://dl-cdn.alpinelinux.org/alpine/edge/community/" >> /etc/apk/repositories
+$ apk update
+$ apk add gomplate
+...
+```
+
+_Note: the Alpine version of gomplate may lag behind the latest release of gomplate._
+
+## use with Docker
+
+A simple way to get started is with the Docker image.
+
+```console
+$ docker run hairyhenderson/gomplate --version
+```
+
+Of course, there are some drawbacks - any files to be used for [datasources][]
+must be mounted and any environment variables to be used must be passed through:
+
+```console
+$ echo 'My voice is my {{.Env.THING}}. {{(datasource "vault").value}}' \
+ | docker run -e THING=passport -v /home/me/.vault-token:/root/.vault-token hairyhenderson/gomplate -d vault=vault:///secret/sneakers
+My voice is my passport. Verify me.
+```
+
+It can be pretty awkward to always type `docker run hairyhenderson/gomplate`,
+so this can be made simpler with a shell alias:
+
+```console
+$ alias gomplate=docker run hairyhenderson/gomplate
+$ gomplate --version
+gomplate version 1.2.3
+```
+
+## manual install
+
+1. Get the latest `gomplate` for your platform from the [releases](https://github.com/hairyhenderson/gomplate/releases) page
+2. Store the downloaded binary somewhere in your path as `gomplate` (or `gomplate.exe`
+ on Windows)
+3. Make sure it's executable (on Linux/macOS)
+3. Test it out with `gomplate --help`!
+
+In other words:
+
+```console
+$ curl -o /usr/local/bin/gomplate -sSL https://github.com/hairyhenderson/gomplate/releases/download/<version>/gomplate_<os>-<arch>
+$ chmod 755 /usr/local/bin/gomplate
+$ gomplate --help
+...
+```
+
+## install with `go get`
+
+If you're a Go user already, sometimes it's faster to just use `go get` to install `gomplate`:
+
+```console
+$ go get github.com/hairyhenderson/gomplate
+$ gomplate --help
+...
+```
diff --git a/docs/content/syntax.md b/docs/content/syntax.md
new file mode 100644
index 00000000..0b092087
--- /dev/null
+++ b/docs/content/syntax.md
@@ -0,0 +1,15 @@
+---
+title: Syntax
+weight: 0
+---
+
+## About `.Env`
+
+You can easily access environment variables with `.Env`, but there's a catch:
+if you try to reference an environment variable that doesn't exist, parsing
+will fail and `gomplate` will exit with an error condition.
+
+Sometimes, this behaviour is desired; if the output is unusable without certain
+strings, this is a sure way to know that variables are missing!
+
+If you want different behaviour, try [`getenv`](../functions/#getenv).
diff --git a/docs/content/usage.md b/docs/content/usage.md
new file mode 100644
index 00000000..2296a7b8
--- /dev/null
+++ b/docs/content/usage.md
@@ -0,0 +1,60 @@
+---
+title: Usage
+weight: 0
+---
+
+The simplest usage of `gomplate` is to just replace environment
+variables. All environment variables are available by referencing [`.Env`](../syntax/#about-env)
+(or [`getenv`](../functions/#getenv)) in the template.
+
+The template is read from standard in, and written to standard out.
+
+Use it like this:
+
+```console
+$ echo "Hello, {{.Env.USER}}" | gomplate
+Hello, hairyhenderson
+```
+
+# Commandline Arguments
+
+## `--file`/`-f`, `--in`/`-i`, and `--out`/`-o`
+
+By default, `gomplate` will read from `Stdin` and write to `Stdout`. This behaviour can be changed.
+
+- Use `--file`/`-f` to use a specific input template file. The special value `-` means `Stdin`.
+- Use `--out`/`-o` to save output to file. The special value `-` means `Stdout`.
+- Use `--in`/`-i` if you want to set the input template right on the commandline. This overrides `--file`. Because of shell command line lengths, it's probably not a good idea to use a very long value with this argument.
+
+### Multiple inputs
+
+You can specify multiple `--file` and `--out` arguments. The same number of each much be given. This allows `gomplate` to process multiple templates _slightly_ faster than invoking `gomplate` multiple times in a row.
+
+### `--input-dir` and `--output-dir`
+
+For processing multiple templates in a directory you can use `--input-dir` and `--output-dir` together. In this case all files in input directory will be processed as templates and the resulting files stored in `--output-dir`. The output directory will be created if it does not exist and the directory structure of the input directory will be preserved.
+
+Example:
+
+```bash
+ # Process all files in directory "templates" with the datasource given
+ # and store the files with the same directory structure in "config"
+gomplate --input-dir=templates --output-dir=config --datasource config=config.yaml
+```
+
+## `--datasource`/`-d`
+
+Add a data source in `name=URL` form. Specify multiple times to add multiple sources. The data can then be used by the [`datasource`](#datasource) function.
+
+A few different forms are valid:
+- `mydata=file:///tmp/my/file.json`
+ - Create a data source named `mydata` which is read from `/tmp/my/file.json`. This form is valid for any file in any path.
+- `mydata=file.json`
+ - Create a data source named `mydata` which is read from `file.json` (in the current working directory). This form is only valid for files in the current directory.
+- `mydata.json`
+ - This form infers the name from the file name (without extension). Only valid for files in the current directory.
+
+## Overriding the template delimiters
+
+Sometimes it's necessary to override the default template delimiters (`{{`/`}}`).
+Use `--left-delim`/`--right-delim` or set `$GOMPLATE_LEFT_DELIM`/`$GOMPLATE_RIGHT_DELIM`.
generated by cgit v1.2.3 (git 2.25.1) at 2026-02-12 12:23:11 +0000