docs: YAMLifying some more function docs, improving the doc template

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

12 files changed, 1501 insertions, 15 deletions

diff --git a/docs-src/content/functions/aws.yml b/docs-src/content/functions/aws.yml
new file mode 100644
index 00000000..53d6c470
--- /dev/null
+++ b/docs-src/content/functions/aws.yml
@@ -0,0 +1,98 @@
+ns: aws
+preamble: |
+  The functions in the `aws` namespace interface with various Amazon Web Services
+  APIs to make it possible for a template to render differently based on the AWS
+  environment and metadata.
+
+  ### Configuring AWS
+
+  A number of environment variables can be used to control how gomplate communicates
+  with AWS APIs. A few are documented here for convenience. See [the `aws-sdk-go` documentation](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html)
+  for details.
+
+  | Environment Variable | Description |
+  | -------------------- | ----------- |
+  | `AWS_TIMEOUT` | _(Default `500`)_ Adjusts timeout for API requests, in milliseconds. Not part of the AWS SDK. |
+  | `AWS_PROFILE` | Profile name the SDK should use when loading shared config from the configuration files. If not provided `default` will be used as the profile name. |
+  | `AWS_REGION` | Specifies where to send requests. See [this list](https://docs.aws.amazon.com/general/latest/gr/rande.html). Note that the region must be set for AWS functions to work correctly, either through this variable, or a configuration profile. |
+funcs:
+  - name: aws.EC2Meta
+    alias: ec2meta
+    description: |
+      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 `aws.EC2Dynamic`.
+
+      For times when running outside EC2, or when the metadata API can't be reached, a `default` value can be provided.
+    pipeline: false
+    arguments:
+      - name: key
+        required: true
+        description: the metadata key to query
+      - name: default
+        required: false
+        description: the default value
+    examples:
+      - |
+        $ echo '{{aws.EC2Meta "instance-id"}}' | gomplate
+        i-12345678
+  - name: aws.EC2Dynamic
+    alias: ec2dynamic
+    description: |
+      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 `aws.EC2Meta`.
+
+      For times when running outside EC2, or when the metadata API can't be reached, a `default` value can be provided.
+    pipeline: false
+    arguments:
+      - name: key
+        required: true
+        description: the dynamic metadata key to query
+      - name: default
+        required: false
+        description: the default value
+    examples:
+      - |
+        $ echo '{{ (aws.EC2Dynamic "instance-identity/document" | json).region }}' | gomplate
+        us-east-1
+  - name: aws.EC2Region
+    alias: ec2region
+    description: |
+      Queries AWS to get the region. An optional default can be provided, or returns
+      `unknown` if it can't be determined for some reason.
+    pipeline: false
+    arguments:
+      - name: default
+        required: false
+        description: the default value
+    rawExamples:
+      - |
+        _In EC2_
+        ```console
+        $ echo '{{ aws.EC2Region }}' | ./gomplate
+        us-east-1
+        ```
+        _Not in EC2_
+        ```console
+        $ echo '{{ aws.EC2Region }}' | ./gomplate
+        unknown
+        $ echo '{{ aws.EC2Region "foo" }}' | ./gomplate
+        foo
+        ```
+  - name: aws.EC2Tag
+    alias: ec2tag
+    description: |
+      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.
+    pipeline: false
+    arguments:
+      - name: tag
+        required: true
+        description: the tag to query
+      - name: default
+        required: false
+        description: the default value
+    examples:
+      - |
+        $ echo 'This server is in the {{ aws.EC2Tag "Account" }} account.' | ./gomplate
+        foo
+      - |
+        $ echo 'I am a {{ aws.EC2Tag "classification" "meat popsicle" }}.' | ./gomplate
+        I am a meat popsicle.
diff --git a/docs-src/content/functions/base64.yml b/docs-src/content/functions/base64.yml
new file mode 100644
index 00000000..1f278ddc
--- /dev/null
+++ b/docs-src/content/functions/base64.yml
@@ -0,0 +1,35 @@
+ns: base64
+preamble: ''
+funcs:
+  - name: base64.Encode
+    description: |
+      Encode data as a Base64 string. Specifically, this uses the standard Base64 encoding as defined in [RFC4648 §4](https://tools.ietf.org/html/rfc4648#section-4) (and _not_ the URL-safe encoding).
+    pipeline: false
+    arguments:
+      - name: input
+        required: true
+        description: The data to encode. Can be a string, a byte array, or a buffer. Other types will be converted to strings first.
+    examples:
+      - |
+        $ gomplate -i '{{ base64.Encode "hello world" }}'
+        aGVsbG8gd29ybGQ=
+      - |
+        $ gomplate -i '{{ "hello world" | base64.Encode }}'
+        aGVsbG8gd29ybGQ=
+  - name: base64.Decode
+    description: |
+      Decode a Base64 string. This supports both standard ([RFC4648 §4](https://tools.ietf.org/html/rfc4648#section-4)) and URL-safe ([RFC4648 §5](https://tools.ietf.org/html/rfc4648#section-5)) encodings.
+
+      This implementation outputs the data as a string, so it may not be appropriate for decoding binary data. If this functionality is desired, [file an issue](https://github.com/hairyhenderson/gomplate/issues/new).
+    pipeline: false
+    arguments:
+      - name: input
+        required: true
+        description: The base64 string to decode
+    examples:
+      - |
+        $ gomplate -i '{{ base64.Decode "aGVsbG8gd29ybGQ=" }}'
+        hello world
+      - |
+        $ gomplate -i '{{ "aGVsbG8gd29ybGQ=" | base64.Decode }}'
+        hello world
diff --git a/docs-src/content/functions/crypto.yml b/docs-src/content/functions/crypto.yml
new file mode 100644
index 00000000..1f91418d
--- /dev/null
+++ b/docs-src/content/functions/crypto.yml
@@ -0,0 +1,98 @@
+ns: crypto
+preamble: |
+  A set of crypto-related functions to be able to perform hashing and (simple!) encryption operations with `gomplate`.
+
+  _Note: These functions are mostly wrappers of existing functions in the Go standard library. The authors of gomplate are not cryptographic experts, however, and so can not guarantee correctness of implementation. It is recommended to have your resident security experts inspect gomplate's code before using gomplate for critical security infrastructure!_
+funcs:
+  - name: crypto.Bcrypt
+    description: |
+      Uses the [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) password hashing algorithm to generate the hash of a given string. Wraps the [`golang.org/x/crypto/brypt`](https://godoc.org/golang.org/x/crypto/bcrypt) package.
+    pipeline: true
+    arguments:
+      - name: cost
+        required: false
+        description: the cost, as a number from `4` to `31` - defaults to `10`
+      - name: input
+        required: true
+        description: the input to hash, usually a password
+    examples:
+      - |
+        $ gomplate -i '{{ "foo" | crypto.Bcrypt }}'
+        $2a$10$jO8nKZ1etGkKK7I3.vPti.fYDAiBqwazQZLUhaFoMN7MaLhTP0SLy
+      - |
+        $ gomplate -i '{{ crypto.Bcrypt 4 "foo" }}
+        $2a$04$zjba3N38sjyYsw0Y7IRCme1H4gD0MJxH8Ixai0/sgsrf7s1MFUK1C
+  - name: crypto.PBKDF2
+    description: |
+      Run the Password-Based Key Derivation Function #2 as defined in
+      [RFC 8018 (PKCS #5 v2.1)](https://tools.ietf.org/html/rfc8018#section-5.2).
+
+      This function outputs the binary result as a hexadecimal string.
+    pipeline: false
+    arguments:
+      - name: password
+        required: true
+        description: the password to use to derive the key
+      - name: salt
+        required: true
+        description: the salt
+      - name: iter
+        required: true
+        description: iteration count
+      - name: keylen
+        required: true
+        description: desired length of derived key
+      - name: hashfunc
+        required: false
+        description: the hash function to use - must be one of the allowed functions (either in the SHA-1 or SHA-2 sets). Defaults to `SHA-1`
+    examples:
+      - |
+        $ gomplate -i '{{ crypto.PBKDF2 "foo" "bar" 1024 8 }}'
+        32c4907c3c80792b
+  - rawName: '`crypto.SHA1`, `crypto.SHA224`, `crypto.SHA256`, `crypto.SHA384`, `crypto.SHA512`, `crypto.SHA512_224`, `crypto.SHA512_256`'
+    description: |
+      Compute a checksum with a SHA-1 or SHA-2 algorithm as defined in [RFC 3174](https://tools.ietf.org/html/rfc3174) (SHA-1) and [FIPS 180-4](http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf) (SHA-2).
+
+      These functions output the binary result as a hexadecimal string.
+
+      _Note: SHA-1 is cryptographically broken and should not be used for secure applications._
+    pipeline: false
+    rawUsage: |
+      ```
+      crypto.SHA1 input
+      crypto.SHA224 input
+      crypto.SHA256 input
+      crypto.SHA384 input
+      crypto.SHA512 input
+      crypto.SHA512_224 input
+      crypto.SHA512_256 input
+      ```
+    arguments:
+      - name: input
+        required: true
+        description: the data to hash - can be binary data or text
+    examples:
+      - |
+        $ gomplate -i '{{ crypto.SHA1 "foo" }}'
+        f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
+      - |
+        $ gomplate -i '{{ crypto.SHA512 "bar" }}'
+        cc06808cbbee0510331aa97974132e8dc296aeb795be229d064bae784b0a87a5cf4281d82e8c99271b75db2148f08a026c1a60ed9cabdb8cac6d24242dac4063
+  - name: crypto.WPAPSK
+    description: |
+      This is really an alias to [`crypto.PBKDF2`](#crypto.PBKDF2) with the
+      values necessary to convert ASCII passphrases to the WPA pre-shared keys for use with WiFi networks.
+
+      This can be used, for example, to help generate a configuration for [wpa_supplicant](http://w1.fi/wpa_supplicant/).
+    pipeline: false
+    arguments:
+      - name: ssid
+        required: true
+        description: the WiFi SSID (network name) - must be less than 32 characters
+      - name: password
+        required: true
+        description: the password - must be between 8 and 63 characters
+    examples:
+      - |
+        $ PW=abcd1234 gomplate -i '{{ crypto.WPAPSK "mynet" (getenv "PW") }}'
+        2c201d66f01237d17d4a7788051191f31706844ac3ffe7547a66c902f2900d34
diff --git a/docs-src/content/functions/data.yml b/docs-src/content/functions/data.yml
new file mode 100644
index 00000000..a512c078
--- /dev/null
+++ b/docs-src/content/functions/data.yml
@@ -0,0 +1,479 @@
+ns: data
+preamble: |
+  A collection of functions that retrieve, parse, and convert structured data.
+funcs:
+  - name: datasource
+    alias: ds
+    description: |
+      Parses a given datasource (provided by the [`--datasource/-d`](#--datasource-d) argument or [`defineDatasource`](#definedatasource)).
+
+      If the `alias` is undefined, but is a valid URL, `datasource` will dynamically read from that URL.
+
+      See [Datasources](../../datasources) for (much!) more information.
+    pipeline: false
+    arguments:
+      - name: alias
+        required: true
+        description: the datasource alias (or a URL for dynamic use)
+      - name: subpath
+        required: false
+        description: the subpath to use, if supported by the datasource
+    rawExamples:
+      - |
+        _`person.json`:_
+        ```json
+        { "name": "Dave" }
+        ```
+
+        ```console
+        $ gomplate -d person.json -i 'Hello {{ (datasource "person").name }}'
+        Hello Dave
+        ```
+  - name: datasourceExists
+    description: |
+      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
+      a template to be rendered differently whether or not a given datasource was
+      defined.
+
+      Note: this does _not_ verify if the datasource is reachable.
+
+      Useful when used in an `if`/`else` block.
+    pipeline: false
+    arguments:
+      - name: alias
+        required: true
+        description: the datasource alias
+    examples:
+      - |
+        $ echo '{{if (datasourceExists "test")}}{{datasource "test"}}{{else}}no worries{{end}}' | gomplate
+        no worries
+  - name: datasourceReachable
+    description: |
+      Tests whether or not a given datasource is defined and reachable, where the definition of "reachable" differs by datasource, but generally means the data is able to be read successfully.
+
+      Useful when used in an `if`/`else` block.
+    pipeline: false
+    arguments:
+      - name: alias
+        required: true
+        description: the datasource alias
+    examples:
+      - |
+        $ gomplate -i '{{if (datasourceReachable "test")}}{{datasource "test"}}{{else}}no worries{{end}}' -d test=https://bogus.example.com/wontwork.json
+        no worries
+  - name: defineDatasource
+    description: |
+      Define a datasource alias with target URL inside the template. Overridden by the [`--datasource/-d`](#--datasource-d) flag.
+
+      Note: once a datasource is defined, it can not be redefined (i.e. if this function is called twice with the same alias, only the first applies).
+
+      This function can provide a good way to set a default datasource when sharing templates.
+
+      See [Datasources](../../datasources) for (much!) more information.
+    pipeline: false
+    arguments:
+      - name: alias
+        required: true
+        description: the datasource alias
+      - name: url
+        required: true
+        description: the datasource's URL
+    rawExamples:
+      - |
+        _`person.json`:_
+        ```json
+        { "name": "Dave" }
+        ```
+
+        ```console
+        $ gomplate -i '{{ defineDatasource "person" "person.json" }}Hello {{ (ds "person").name }}'
+        Hello Dave
+        $ FOO='{"name": "Daisy"}' gomplate -d person=env:///FOO -i '{{ defineDatasource "person" "person.json" }}Hello {{ (ds "person").name }}'
+        Hello Daisy
+        ```
+  - name: include
+    description: |
+      Includes the content of a given datasource (provided by the [`--datasource/-d`](../usage/#datasource-d) argument).
+
+      This is similar to [`datasource`](#datasource), except that the data is not parsed. There is no restriction on the type of data included, except that it should be textual.
+    pipeline: false
+    arguments:
+      - name: alias
+        required: true
+        description: the datasource alias, as provided by [`--datasource/-d`](../usage/#datasource-d)
+      - name: subpath
+        required: false
+        description: the subpath to use, if supported by the datasource
+    rawExamples:
+      - |
+        _`person.json`:_
+        ```json
+        { "name": "Dave" }
+        ```
+
+        _`input.tmpl`:_
+        ```go
+        {
+          "people": [
+            {{ include "person" }}
+          ]
+        }
+        ```
+
+        ```console
+        $ gomplate -d person.json -f input.tmpl
+        {
+          "people": [
+            { "name": "Dave" }
+          ]
+        }
+        ```
+  - name: data.JSON
+    alias: json
+    description: |
+      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.
+
+      #### Encrypted JSON support (EJSON)
+
+      If the input is in the [EJSON](https://github.com/Shopify/ejson) format (i.e. has a `_public_key` field), this function will attempt to decrypt the document first. A private key must be provided by one of these methods:
+
+      - set the `EJSON_KEY` environment variable to the private key's value
+      - set the `EJSON_KEY_FILE` environment variable to the path to a file containing the private key
+      - set the `EJSON_KEYDIR` environment variable to the path to a directory containing private keys (filename must be the public key), just like [`ejson decrypt`'s `--keydir`](https://github.com/Shopify/ejson/blob/master/man/man1/ejson.1.ronn) flag. Defaults to `/opt/ejson/keys`.
+    pipeline: true
+    arguments:
+      - name: in
+        required: true
+        description: the input string
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        Hello {{ (getenv "FOO" | json).hello }}
+        ```
+
+        ```console
+        $ export FOO='{"hello":"world"}'
+        $ gomplate < input.tmpl
+        Hello world
+        ```
+  - name: data.JSONArray
+    alias: jsonArray
+    description: |
+      Converts a JSON string into a slice. Only works for JSON Arrays.
+    pipeline: true
+    arguments:
+      - name: in
+        required: true
+        description: the input string
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        Hello {{ index (getenv "FOO" | jsonArray) 1 }}
+        ```
+
+        ```console
+        $ export FOO='[ "you", "world" ]'
+        $ gomplate < input.tmpl
+        Hello world
+        ```
+  - name: data.YAML
+    alias: yaml
+    description: |
+      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.
+    pipeline: true
+    arguments:
+      - name: in
+        required: true
+        description: the input string
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        Hello {{ (getenv "FOO" | yaml).hello }}
+        ```
+
+        ```console
+        $ export FOO='hello: world'
+        $ gomplate < input.tmpl
+        Hello world
+        ```
+  - name: data.YAMLArray
+    alias: yamlArray
+    description: |
+      Converts a YAML string into a slice. Only works for YAML Arrays.
+    pipeline: true
+    arguments:
+      - name: in
+        required: true
+        description: the input string
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        Hello {{ index (getenv "FOO" | yamlArray) 1 }}
+        ```
+
+        ```console
+        $ export FOO='[ "you", "world" ]'
+        $ gomplate < input.tmpl
+        Hello world
+        ```
+  - name: data.TOML
+    alias: toml
+    description: |
+      Converts a [TOML](https://github.com/toml-lang/toml) document into an object.
+      This can be used to access properties of TOML documents.
+
+      Compatible with [TOML v0.4.0](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md).
+    pipeline: true
+    arguments:
+      - name: input
+        required: true
+        description: the TOML document to parse
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        {{ $t := `[data]
+        hello = "world"` -}}
+        Hello {{ (toml $t).hello }}
+        ```
+
+        ```console
+        $ gomplate -f input.tmpl
+        Hello world
+        ```
+  - name: data.CSV
+    alias: csv
+    description: |
+      Converts a CSV-format string into a 2-dimensional string array.
+
+      By default, the [RFC 4180](https://tools.ietf.org/html/rfc4180) format is
+      supported, but any single-character delimiter can be specified.
+    pipeline: true
+    arguments:
+      - name: delim
+        required: false
+        description: the (single-character!) field delimiter, defaults to `","`
+      - name: input
+        required: true
+        description: the CSV-format string to parse
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        {{ $c := `C,32
+        Go,25
+        COBOL,357` -}}
+        {{ range ($c | csv) -}}
+        {{ index . 0 }} has {{ index . 1 }} keywords.
+        {{ end }}
+        ```
+
+        ```console
+        $ gomplate < input.tmpl
+        C has 32 keywords.
+        Go has 25 keywords.
+        COBOL has 357 keywords.
+        ```
+  - name: data.CSVByRow
+    alias: csvByRow
+    description: |
+      Converts a CSV-format string into a slice of maps.
+
+      By default, the [RFC 4180](https://tools.ietf.org/html/rfc4180) format is
+      supported, but any single-character delimiter can be specified.
+
+      Also by default, the first line of the string will be assumed to be the header,
+      but this can be overridden by providing an explicit header, or auto-indexing
+      can be used.
+    pipeline: true
+    arguments:
+      - name: delim
+        required: false
+        description: the (single-character!) field delimiter, defaults to `","`
+      - name: header
+        required: false
+        description: comma-separated list of column names, set to `""` to get auto-named columns (A-Z), defaults to using the first line of `input`
+      - name: input
+        required: true
+        description: the CSV-format string to parse
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        {{ $c := `lang,keywords
+        C,32
+        Go,25
+        COBOL,357` -}}
+        {{ range ($c | csvByRow) -}}
+        {{ .lang }} has {{ .keywords }} keywords.
+        {{ end }}
+        ```
+
+        ```console
+        $ gomplate < input.tmpl
+        C has 32 keywords.
+        Go has 25 keywords.
+        COBOL has 357 keywords.
+        ```
+  - name: data.CSVByColumn
+    alias: csvByColumn
+    description: |
+      Like [`csvByRow`](#csvByRow), except that the data is presented as a columnar
+      (column-oriented) map.
+    pipeline: true
+    arguments:
+      - name: delim
+        required: false
+        description: the (single-character!) field delimiter, defaults to `","`
+      - name: header
+        required: false
+        description: comma-separated list of column names, set to `""` to get auto-named columns (A-Z), defaults to using the first line of `input`
+      - name: input
+        required: true
+        description: the CSV-format string to parse
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        {{ $c := `C;32
+        Go;25
+        COBOL;357` -}}
+        {{ $langs := ($c | csvByColumn ";" "lang,keywords").lang -}}
+        {{ range $langs }}{{ . }}
+        {{ end -}}
+        ```
+
+        ```console
+        $ gomplate < input.tmpl
+        C
+        Go
+        COBOL
+        ```
+  - name: data.ToJSON
+    alias: toJSON
+    description: |
+      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`.
+    pipeline: true
+    arguments:
+      - name: obj
+        required: true
+        description: the object to marshal
+    rawExamples:
+      - |
+        _This is obviously contrived - `json` is used to create an object._
+
+        _`input.tmpl`:_
+        ```
+        {{ (`{"foo":{"hello":"world"}}` | json).foo | toJSON }}
+        ```
+
+        ```console
+        $ gomplate < input.tmpl
+        {"hello":"world"}
+        ```
+  - name: data.ToJSONPretty
+    alias: toJSONPretty
+    description: |
+      Converts an object to a pretty-printed (or _indented_) JSON document.
+      Input objects may be the result of functions like `data.JSON`, `data.YAML`,
+      `data.JSONArray`, or `data.YAMLArray` functions, or they could be provided
+      by a [`datasource`](../general/datasource).
+
+      The indent string must be provided as an argument.
+    pipeline: true
+    arguments:
+      - name: indent
+        required: true
+        description: the string to use for indentation
+      - name: obj
+        required: true
+        description: the object to marshal
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```
+        {{ `{"hello":"world"}` | data.JSON | data.ToJSONPretty "  " }}
+        ```
+
+        ```console
+        $ gomplate < input.tmpl
+        {
+          "hello": "world"
+        }
+        ```
+  - name: data.ToYAML
+    alias: toYAML
+    description: |
+      Converts an object to a YAML document. Input objects may be the result of
+      `data.JSON`, `data.YAML`, `data.JSONArray`, or `data.YAMLArray` functions,
+      or they could be provided by a [`datasource`](../general/datasource).
+    pipeline: true
+    arguments:
+      - name: obj
+        required: true
+        description: the object to marshal
+    rawExamples:
+      - |
+        _This is obviously contrived - `data.JSON` is used to create an object._
+
+        _`input.tmpl`:_
+        ```
+        {{ (`{"foo":{"hello":"world"}}` | data.JSON).foo | data.ToYAML }}
+        ```
+
+        ```console
+        $ gomplate < input.tmpl
+        hello: world
+        ```
+  - name: data.ToTOML
+    alias: toTOML
+    description: |
+      Converts an object to a [TOML](https://github.com/toml-lang/toml) document.
+    pipeline: true
+    arguments:
+      - name: obj
+        required: true
+        description: the object to marshal as a TOML document
+    examples:
+      - |
+        $ gomplate -i '{{ `{"foo":"bar"}` | data.JSON | data.ToTOML }}'
+        foo = "bar"
+  - name: data.ToCSV
+    alias: toCSV
+    description: |
+      Converts an object to a CSV document. The input object must be a 2-dimensional
+      array of strings (a `[][]string`). Objects produced by [`data.CSVByRow`](#conv-csvbyrow)
+      and [`data.CSVByColumn`](#conv-csvbycolumn) cannot yet be converted back to CSV documents.
+
+      **Note:** With the exception that a custom delimiter can be used, `data.ToCSV`
+      outputs according to the [RFC 4180](https://tools.ietf.org/html/rfc4180) format,
+      which means that line terminators are `CRLF` (Windows format, or `\r\n`). If
+      you require `LF` (UNIX format, or `\n`), the output can be piped through
+      [`strings.ReplaceAll`](../strings/#strings-replaceall) to replace `"\r\n"` with `"\n"`.
+    pipeline: true
+    arguments:
+      - name: delim
+        required: false
+        description: the (single-character!) field delimiter, defaults to `","`
+      - name: input
+        required: true
+        description: the object to convert to a CSV
+    rawExamples:
+      - |
+        _`input.tmpl`:_
+        ```go
+        {{ $rows := (jsonArray `[["first","second"],["1","2"],["3","4"]]`) -}}
+        {{ data.ToCSV ";" $rows }}
+        ```
+
+        ```console
+        $ gomplate -f input.tmpl
+        first,second
+        1,2
+        3,4
+        ```
diff --git a/docs-src/content/functions/env.yml b/docs-src/content/functions/env.yml
new file mode 100644
index 00000000..65f5ad2b
--- /dev/null
+++ b/docs-src/content/functions/env.yml
@@ -0,0 +1,67 @@
+ns: env
+preamble: |
+  [12-factor]: https://12factor.net
+  [Docker Secrets]: https://docs.docker.com/engine/swarm/secrets/#build-support-for-docker-secrets-into-your-images
+funcs:
+  - name: env.Getenv
+    alias: getenv
+    description: |
+      Exposes the [os.Getenv](https://golang.org/pkg/os/#Getenv) function.
+
+      Retrieves the value of the environment variable named by the key. If the
+      variable is unset, but the same variable ending in `_FILE` is set, the contents
+      of the file will be returned. Otherwise the provided default (or an empty
+      string) is returned.
+
+      This is a more forgiving alternative to using `.Env`, since missing keys will
+      return an empty string, instead of panicking.
+
+      The `_FILE` fallback is especially useful for use with [12-factor][]-style
+      applications configurable only by environment variables, and especially in
+      conjunction with features like [Docker Secrets][].
+    pipeline: false
+    arguments:
+      - name: var
+        required: true
+        description: the environment variable name
+      - name: default
+        required: false
+        description: the default
+    examples:
+      - |
+        $ gomplate -i 'Hello, {{env.Getenv "USER"}}'
+        Hello, hairyhenderson
+        $ gomplate -i 'Hey, {{getenv "FIRSTNAME" "you"}}!'
+        Hey, you!
+      - |
+        $ echo "safe" > /tmp/mysecret
+        $ export SECRET_FILE=/tmp/mysecret
+        $ gomplate -i 'Your secret is {{getenv "SECRET"}}'
+        Your secret is safe
+  - name: env.ExpandEnv
+    description: |
+      Exposes the [os.ExpandEnv](https://golang.org/pkg/os/#ExpandEnv) function.
+
+      Replaces `${var}` or `$var` in the input string according to the values of the
+      current environment variables. References to undefined variables are replaced by the empty string.
+
+      Like [`env.Getenv`](#env-getenv), the `_FILE` variant of a variable is used.
+    pipeline: false
+    arguments:
+      - name: input
+        required: true
+        description: the input
+    examples:
+      - |
+        $ gomplate -i '{{env.ExpandEnv "Hello $USER"}}'
+        Hello, hairyhenderson
+        $ gomplate -i 'Hey, {{env.ExpandEnv "Hey, ${FIRSTNAME}!"}}'
+        Hey, you!
+      - |
+        $ echo "safe" > /tmp/mysecret
+        $ export SECRET_FILE=/tmp/mysecret
+        $ gomplate -i '{{env.ExpandEnv "Your secret is $SECRET"}}'
+        Your secret is safe
+      - |
+        $ gomplate -i '{{env.ExpandEnv (file.Read "foo")}}
+        contents of file "foo"...
diff --git a/docs-src/content/functions/func_doc.md.tmpl b/docs-src/content/functions/func_doc.md.tmpl
index c70a6ade..c66b0d09 100644
--- a/docs-src/content/functions/func_doc.md.tmpl
+++ b/docs-src/content/functions/func_doc.md.tmpl
@@ -1,3 +1,19 @@
+{{ define "argName" }}{{ if not .required }}[{{ .name }}]{{else}}{{ .name }}{{end}}{{ end }}
+
+{{- define "usage" }}### Usage
+{{- $arguments := index . "arguments" | default slice }}
+{{ if has . "rawUsage" }}{{ .rawUsage | strings.TrimSpace }}{{ else }}
+```go
+{{ .name }}{{ range $a := $arguments }} {{template "argName" $a }}{{end}}
+```
+{{- if (index . "pipeline" | default false) }}
+```go
+{{ $last := (sub (len $arguments) 1) -}}
+{{ (index $arguments $last).name }} | {{ .name }}{{ range $i, $a := $arguments }}{{if not (eq $i $last)}} {{template "argName" $a }}{{end}}{{end}}
+```
+{{- end }}{{ end -}}
+{{ end -}}
+
 {{ $data := ds "data" -}}
 ---
 title: {{ index $data "title" | default (print $data.ns " functions") }}
@@ -9,8 +25,8 @@ menu:
 {{ $data.preamble -}}
 
 {{ range $_, $f := $data.funcs }}
-## `{{ $f.name }}`{{ if has $f "deprecated" }} _(deprecated)_
-**Deprecation Notice:** {{ $f.deprecated }}{{ end }}
+## {{ if has $f "rawName" }}{{ $f.rawName }}{{ else }}`{{ $f.name }}`{{ if has $f "deprecated" }} _(deprecated)_
+**Deprecation Notice:** {{ $f.deprecated }}{{ end }}{{ end }}
 {{ if has $f "alias" }}
 **Alias:** `{{$f.alias}}`
 {{ end }}
@@ -19,17 +35,9 @@ menu:
 {{ $f.description }}
 {{ end -}}
 
+{{ template "usage" $f }}
+
 {{ if has $f "arguments" -}}
-### Usage
-```go
-{{ $f.name }} {{ range $f.arguments -}} {{ if not .required }}[{{ .name }}]{{else}}{{ .name }}{{end}} {{end}}
-```
-{{ if has $f "pipeline" }}{{ if $f.pipeline }}
-```go
-{{ $last := (sub (len $f.arguments) 1) -}}
-{{ (index $f.arguments $last).name }} | {{ $f.name }} {{ range $i, $a := $f.arguments -}} {{if not (eq $i $last)}}{{ if not $a.required }}[{{ .name }}]{{else}}{{ .name }}{{end}}{{end}} {{end}}
-```
-{{ end }}{{ end }}
 ### Arguments
 
 | name | description |
diff --git a/docs-src/content/functions/math.yml b/docs-src/content/functions/math.yml
index da9033a8..385b53d0 100644
--- a/docs-src/content/functions/math.yml
+++ b/docs-src/content/functions/math.yml
@@ -55,7 +55,7 @@ funcs:
     arguments:
       - name: num
         required: true
-        description: The input number. Will be converted to a `float64`, or `0` if not convertable
+        description: The input number. Will be converted to a `float64`, or `0` if not convertible
     examples:
       - |
         $ gomplate -i '{{ range (slice 5.1 42 "3.14" "0xFF" "NaN" "Inf" "-0") }}ceil {{ printf "%#v" . }} = {{ math.Ceil . }}{{"\n"}}{{ end }}'
diff --git a/docs-src/content/functions/net.yml b/docs-src/content/functions/net.yml
new file mode 100644
index 00000000..5f01cc2b
--- /dev/null
+++ b/docs-src/content/functions/net.yml
@@ -0,0 +1,119 @@
+ns: net
+preamble: ''
+funcs:
+  - name: net.LookupIP
+    description: |
+      Resolve an IPv4 address for a given host name. When multiple IP addresses
+      are resolved, the first one is returned.
+    pipeline: true
+    arguments:
+      - name: name
+        required: true
+        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
+    examples:
+      - |
+        $ gomplate -i '{{ net.LookupIP "example.com" }}'
+        93.184.216.34
+  - name: net.LookupIPs
+    description: |
+      Resolve all IPv4 addresses for a given host name. Returns an array of strings.
+    pipeline: true
+    arguments:
+      - name: name
+        required: true
+        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
+    examples:
+      - |
+        $ gomplate -i '{{ join (net.LookupIPs "twitter.com") "," }}'
+        104.244.42.65,104.244.42.193
+  - name: net.LookupCNAME
+    description: |
+      Resolve the canonical name for a given host name. This does a DNS lookup for the
+      `CNAME` record type. If no `CNAME` is present, a canonical form of the given name
+      is returned -- e.g. `net.LookupCNAME "localhost"` will return `"localhost."`.
+    pipeline: true
+    arguments:
+      - name: name
+        required: true
+        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
+    examples:
+      - |
+        $ gomplate -i '{{ net.LookupCNAME "www.amazon.com" }}'
+        d3ag4hukkh62yn.cloudfront.net.
+  - name: net.LookupSRV
+    description: |
+      Resolve a DNS [`SRV` service record](https://en.wikipedia.org/wiki/SRV_record).
+      This implementation supports the canonical [RFC2782](https://tools.ietf.org/html/rfc2782)
+      form (i.e. `_Service._Proto.Name`), but other forms are also supported, such as
+      those served by [Consul's DNS interface](https://www.consul.io/docs/agent/dns.html#standard-lookup).
+
+      When multiple records are returned, this function returns the first.
+
+      A [`net.SRV`](https://golang.org/pkg/net/#SRV) data structure is returned. The
+      following properties are available:
+      - `Target` - _(string)_ the hostname where the service can be reached
+      - `Port` - _(uint16)_ the service's port
+      - `Priority`, `Weight` - see [RFC2782](https://tools.ietf.org/html/rfc2782) for details
+    pipeline: true
+    arguments:
+      - name: name
+        required: true
+        description: The service name to look up
+    examples:
+      - |
+        $ gomplate -i '{{ net.LookupSRV "_sip._udp.sip.voice.google.com" | toJSONPretty "  " }}'
+        {
+          "Port": 5060,
+          "Priority": 10,
+          "Target": "sip-anycast-1.voice.google.com.",
+          "Weight": 1
+        }
+  - name: net.LookupSRVs
+    description: |
+      Resolve a DNS [`SRV` service record](https://en.wikipedia.org/wiki/SRV_record).
+      This implementation supports the canonical [RFC2782](https://tools.ietf.org/html/rfc2782)
+      form (i.e. `_Service._Proto.Name`), but other forms are also supported, such as
+      those served by [Consul's DNS interface](https://www.consul.io/docs/agent/dns.html#standard-lookup).
+
+      This function returns all available SRV records.
+
+      An array of [`net.SRV`](https://golang.org/pkg/net/#SRV) data structures is
+      returned. For each element, the following properties are available:
+      - `Target` - _(string)_ the hostname where the service can be reached
+      - `Port` - _(uint16)_ the service's port
+      - `Priority`, `Weight` - see [RFC2782](https://tools.ietf.org/html/rfc2782) for details
+    pipeline: true
+    arguments:
+      - name: name
+        required: true
+        description: The hostname to look up. This can be a simple hostname, or a fully-qualified domain name.
+    rawExamples:
+      - |
+        _input.tmpl:_
+        ```
+        {{ range (net.LookupSRVs "_sip._udp.sip.voice.google.com") -}}
+        priority={{.Priority}}/port={{.Port}}
+        {{- end }}
+        ```
+
+        ```console
+        $ gomplate -f input.tmpl
+        priority=10/port=5060
+        priority=20/port=5060
+        ```
+  - name: net.LookupTXT
+    description: |
+      Resolve a DNS [`TXT` record](https://en.wikipedia.org/wiki/SRV_record).
+
+      This function returns all available TXT records as an array of strings.
+    pipeline: true
+    arguments:
+      - name: name
+        required: true
+        description: The host name to look up
+    examples:
+      - |
+        $ gomplate -i '{{net.LookupTXT "example.com" | data.ToJSONPretty "  " }}'
+        [
+          "v=spf1 -all"
+        ]
diff --git a/docs-src/content/functions/path.yml b/docs-src/content/functions/path.yml
index 4be76854..8c1d26ca 100644
--- a/docs-src/content/functions/path.yml
+++ b/docs-src/content/functions/path.yml
@@ -113,7 +113,7 @@ funcs:
     description: |
       Splits path immediately following the final slash, separating it into a directory and file name component.
 
-      The function returns an array with two values, the first being the diretory, and the second the file.
+      The function returns an array with two values, the first being the directory, and the second the file.
 
       A wrapper for Go's [`path.Split`](https://golang.org/pkg/path/#Split) function.
     pipeline: true
diff --git a/docs-src/content/functions/sockaddr.yml b/docs-src/content/functions/sockaddr.yml
new file mode 100644
index 00000000..f50af477
--- /dev/null
+++ b/docs-src/content/functions/sockaddr.yml
@@ -0,0 +1,327 @@
+ns: sockaddr
+preamble: |
+  This namespace wraps the [`github.com/hashicorp/go-sockaddr`](https://github.com/hashicorp/go-sockaddr)
+  package, which makes it easy to discover information about a system's network
+  interfaces.
+
+  These functions are _partly_ documented here for convenience, but the canonical
+  documentation is at https://godoc.org/github.com/hashicorp/go-sockaddr.
+
+  Aside from some convenience functions, the general method of working with these
+  functions is through a _pipeline_. There are _source_ functions, which select
+  interfaces ([`IfAddr`](https://godoc.org/github.com/hashicorp/go-sockaddr#IfAddr)),
+  and there are functions to further filter, refine, and finally to select
+  the specific attributes you're interested in.
+
+  To demonstrate how this can be used, here's an example that lists all of the IPv4 addresses available on the system:
+
+  ```console
+  $ gomplate -i '{{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") -}}
+  {{ . | sockaddr.Attr "address" }}
+  {{end}}'
+  127.0.0.1
+  10.0.0.8
+  132.79.79.79
+  ```
+
+  [RFC 1918]: http://tools.ietf.org/html/rfc1918
+  [RFC 6890]: http://tools.ietf.org/html/rfc6890
+funcs:
+  - name: sockaddr.GetAllInterfaces
+    description: |
+      Iterates over all available network interfaces and finds all available IP
+      addresses on each interface and converts them to `sockaddr.IPAddrs`, and returning
+      the result as an array of `IfAddr`.
+
+      Should be piped through a further function to refine and extract attributes.
+  - name: sockaddr.GetDefaultInterfaces
+    description: |
+      Returns `IfAddrs` of the addresses attached to the default route.
+
+      Should be piped through a further function to refine and extract attributes.
+  - name: sockaddr.GetPrivateInterfaces
+    description: |
+      Returns an array of `IfAddr`s containing every IP that matches
+      [RFC 6890][], is attached to the interface with
+      the default route, and is a forwardable IP address.
+
+      **Note:** [RFC 6890][] is a more exhaustive version of [RFC 1918][]
+      because it spans IPv4 and IPv6, however it does permit the inclusion of likely
+      undesired addresses such as multicast, therefore our definition of a "private"
+      address also excludes non-forwardable IP addresses (as defined by the IETF).
+
+      Should be piped through a further function to refine and extract attributes.
+  - name: sockaddr.GetPublicInterfaces
+    description: |
+      Returns an array of `IfAddr`s that do not match [RFC 6890][],
+      are attached to the default route, and are forwardable.
+
+      Should be piped through a further function to refine and extract attributes.
+  - name: sockaddr.Sort
+    description: |
+      Returns an array of `IfAddr`s sorted based on the given selector. Multiple sort
+      clauses can be passed in as a comma-delimited list without whitespace.
+
+      ### Selectors
+
+      The valid selectors are:
+
+      | selector | sorts by... |
+      |----------|-------------|
+      | `address` | the network address |
+      | `default` | whether or not the `IfAddr` has a default route |
+      | `name` | the interface name |
+      | `port` | the port, if included in the `IfAddr` |
+      | `size` | the size of the network mask, smaller mask (larger number of hosts per network) to largest (e.g. a /24 sorts before a /32) |
+      | `type` | the type of the `IfAddr`. Order is Unix, IPv4, then IPv6 |
+
+      Each of these selectors sort _ascending_, but a _descending_ sort may be chosen
+      by prefixing the selector with a `-` (e.g. `-address`). You may prefix with a `+`
+      to make explicit that the sort is ascending.
+
+      `IfAddr`s that are not comparable will be at the end of the list and in a
+      non-deterministic order.
+    pipeline: true
+    arguments:
+      - name: selector
+        required: true
+        description: which selector to use (see above for values)
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s to sort
+    rawExamples:
+      - |
+        To sort first by interface name, then by address (descending):
+        ```console
+        $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Sort "name,-address" }}'
+        ```
+  - name: sockaddr.Exclude
+    description: |
+      Returns an array of `IfAddr`s filtered by interfaces that do not match the given
+      selector's value.
+
+      ### Selectors
+
+      The valid selectors are:
+
+      | selector | excludes by... |
+      |----------|-------------|
+      | `address` | the network address |
+      | `flag` | the specified flags (see below) |
+      | `name` | the interface name |
+      | `network` | being part of the given IP network (in net/mask format) |
+      | `port` | the port, if included in the `IfAddr` |
+      | `rfc` | being included in networks defined by the given RFC. See [the source code](https://github.com/hashicorp/go-sockaddr/blob/master/rfc.go#L38) for a list of valid RFCs |
+      | `size` | the size of the network mask, as number of bits (e.g. `"24"` for a /24) |
+      | `type` | the type of the `IfAddr`. `unix`, `ipv4`, or `ipv6` |
+
+      #### supported flags
+
+      These flags are supported by the `flag` selector:
+      `broadcast`, `down`, `forwardable`, `global unicast`, `interface-local multicast`,
+      `link-local multicast`, `link-local unicast`, `loopback`, `multicast`, `point-to-point`,
+      `unspecified`, `up`
+    pipeline: true
+    arguments:
+      - name: selector
+        required: true
+        description: which selector to use (see above for values)
+      - name: value
+        required: true
+        description: the selector value to exclude
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s to consider
+    rawExamples:
+      - |
+        To exclude all IPv6 interfaces:
+        ```console
+        $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Exclude "type" "ipv6" }}'
+        ```
+  - name: sockaddr.Include
+    description: |
+      Returns an array of `IfAddr`s filtered by interfaces that match the given
+      selector's value.
+
+      This is the inverse of `sockaddr.Exclude`. See [`sockaddr.Exclude`](#sockaddr.Exclude) for details.
+    pipeline: true
+    arguments:
+      - name: selector
+        required: true
+        description: which selector to use (see above for values)
+      - name: value
+        required: true
+        description: the selector value to include
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s to consider
+  - name: sockaddr.Attr
+    description: |
+      Returns the named attribute as a string.
+    pipeline: true
+    arguments:
+      - name: selector
+        required: true
+        description: the attribute to return
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s to inspect
+    examples:
+      - |
+        $ gomplate -i '{{ range (sockaddr.GetAllInterfaces | sockaddr.Include "type" "ipv4") }}{{ . | sockaddr.Attr "name" }} {{end}}'
+        lo0 en0
+  - name: sockaddr.Join
+    description: |
+      Selects the given attribute from each `IfAddr` in the source array, and joins
+      the results with the given separator.
+    pipeline: true
+    arguments:
+      - name: selector
+        required: true
+        description: the attribute to select
+      - name: separator
+        required: true
+        description: the separator
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s to join
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Join "name" "," }}'
+        lo0,lo0,lo0,en0,en0
+  - name: sockaddr.Limit
+    description: |
+      Returns a slice of `IfAddr`s based on the specified limit.
+    pipeline: true
+    arguments:
+      - name: limit
+        required: true
+        description: the maximum number of `IfAddrs`
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Join "name" "|" }}'
+        lo0|lo0
+  - name: sockaddr.Offset
+    description: |
+      Returns a slice of `IfAddr`s based on the specified offset.
+    pipeline: true
+    arguments:
+      - name: offset
+        required: true
+        description: the offset
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Limit 2 | sockaddr.Offset 1 | sockaddr.Attr "address" }}'
+        ::1
+  - name: sockaddr.Unique
+    description: |
+      Creates a unique array of `IfAddr`s based on the matching selector. Assumes the input has
+      already been sorted.
+    pipeline: true
+    arguments:
+      - name: selector
+        required: true
+        description: the attribute to select
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Unique "name" | sockaddr.Join "name" ", " }}'
+        lo0, en0
+  - name: sockaddr.Math
+    description: |
+      Applies a math operation to each `IfAddr` in the input. Any failure will result in zero results.
+
+      See [the source code](https://github.com/hashicorp/go-sockaddr/blob/master/ifaddrs.go#L725)
+      for details.
+    pipeline: true
+    arguments:
+      - name: selector
+        required: true
+        description: the attribute to operate on
+      - name: operation
+        required: true
+        description: the operation
+      - name: <array-of-IfAddrs>
+        required: true
+        description: the array of `IfAddr`s
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetAllInterfaces | sockaddr.Math "address" "+5" | sockaddr.Attr "address" }}'
+        127.0.0.6
+  - name: sockaddr.GetPrivateIP
+    description: |
+      Returns a string with a single IP address that is part of [RFC 6890][] and has a
+      default route. If the system can't determine its IP address or find an [RFC 6890][]
+      IP address, an empty string will be returned instead.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetPrivateIP }}'
+        10.0.0.28
+  - name: sockaddr.GetPrivateIPs
+    description: |
+      Returns a space-separated string with all IP addresses that are part of [RFC 6890][]
+      (regardless of whether or not there is a default route, unlike `GetPublicIP`).
+      If the system can't find any [RFC 6890][] IP addresses, an empty string will be
+      returned instead.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetPrivateIPs }}'
+        10.0.0.28 192.168.0.1
+  - name: sockaddr.GetPublicIP
+    description: |
+      Returns a string with a single IP address that is NOT part of [RFC 6890][] and
+      has a default route. If the system can't determine its IP address or find a
+      non-[RFC 6890][] IP address, an empty string will be returned instead.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetPublicIP }}'
+        8.1.2.3
+  - name: sockaddr.GetPublicIPs
+    description: |
+      Returns a space-separated string with all IP addresses that are NOT part of
+      [RFC 6890][] (regardless of whether or not there is a default route, unlike
+      `GetPublicIP`). If the system can't find any non-[RFC 6890][] IP addresses, an
+      empty string will be returned instead.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetPublicIPs }}'
+        8.1.2.3 8.2.3.4
+  - name: sockaddr.GetInterfaceIP
+    description: |
+      Returns a string with a single IP address sorted by the size of the network
+      (i.e. IP addresses with a smaller netmask, larger network size, are sorted first).
+    pipeline: false
+    arguments:
+      - name: name
+        required: true
+        description: the interface name
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetInterfaceIP "en0" }}'
+        10.0.0.28
+  - name: sockaddr.GetInterfaceIPs
+    description: |
+      Returns a string with all IPs, sorted by the size of the network (i.e. IP
+      addresses with a smaller netmask, larger network size, are sorted first), on a
+      named interface.
+    pipeline: false
+    arguments:
+      - name: name
+        required: true
+        description: the interface name
+    examples:
+      - |
+        $ gomplate -i '{{ sockaddr.GetInterfaceIPs "en0" }}'
+        10.0.0.28 fe80::1f9a:5582:4b41:bd18
diff --git a/docs-src/content/functions/strings.yml b/docs-src/content/functions/strings.yml
index bbb9a572..9dbc886f 100644
--- a/docs-src/content/functions/strings.yml
+++ b/docs-src/content/functions/strings.yml
@@ -257,7 +257,7 @@ funcs:
     description: |
       Surrounds an input string with a single-quote (apostrophe) character (`'`). If the input is not a string, converts first.
 
-      `'` characters in the input are first escaped in the YAML-style (by repetition: `''`).<!-- ' -->
+      `'` characters in the input are first escaped in the YAML-style (by repetition: `''`).
     pipeline: true
     arguments:
       - name: in
diff --git a/docs-src/content/functions/time.yml b/docs-src/content/functions/time.yml
new file mode 100644
index 00000000..b208f432
--- /dev/null
+++ b/docs-src/content/functions/time.yml
@@ -0,0 +1,255 @@
+ns: time
+preamble: |
+  This namespace wraps Go's [`time` package](https://golang.org/pkg/time/), and a
+  few of the functions return a `time.Time` value. All of the
+  [`time.Time` functions](https://golang.org/pkg/time/#Time) can then be used to
+  convert, adjust, or format the time in your template.
+
+  ### Reference time
+
+  An important difference between this and many other time/date utilities is how
+  parsing and formatting is accomplished. Instead of relying solely on pre-defined
+  formats, or having a complex system of variables, formatting is accomplished by
+  declaring an example of the layout you wish to display.
+
+  This uses a _reference time_, which is:
+
+  ```
+  Mon Jan 2 15:04:05 -0700 MST 2006
+  ```
+
+  ### Constants
+
+  #### format layouts
+
+  Some pre-defined layouts have been provided for convenience:
+
+  | layout name | value |
+  |-------------|-------|
+  | `time.ANSIC`       | `"Mon Jan _2 15:04:05 2006"` |
+  | `time.UnixDate`    | `"Mon Jan _2 15:04:05 MST 2006"` |
+  | `time.RubyDate`    | `"Mon Jan 02 15:04:05 -0700 2006"` |
+  | `time.RFC822`      | `"02 Jan 06 15:04 MST"` |
+  | `time.RFC822Z`     | `"02 Jan 06 15:04 -0700"` // RFC822 with numeric zone |
+  | `time.RFC850`      | `"Monday, 02-Jan-06 15:04:05 MST"` |
+  | `time.RFC1123`     | `"Mon, 02 Jan 2006 15:04:05 MST"` |
+  | `time.RFC1123Z`    | `"Mon, 02 Jan 2006 15:04:05 -0700"` // RFC1123 with numeric zone |
+  | `time.RFC3339`     | `"2006-01-02T15:04:05Z07:00"` |
+  | `time.RFC3339Nano` | `"2006-01-02T15:04:05.999999999Z07:00"` |
+  | `time.Kitchen`     | `"3:04PM"` |
+  | `time.Stamp`      | `"Jan _2 15:04:05"` |
+  | `time.StampMilli` | `"Jan _2 15:04:05.000" `|
+  | `time.StampMicro` | `"Jan _2 15:04:05.000000"` |
+  | `time.StampNano`  | `"Jan _2 15:04:05.000000000"` |
+
+  See below for examples of how these layouts can be used.
+
+  #### durations
+
+  Some operations (such as [`Time.Add`](https://golang.org/pkg/time/#Time.Add) and
+  [`Time.Round`](https://golang.org/pkg/time/#Time.Round)) require a
+  [`Duration`](https://golang.org/pkg/time/#Duration) value. These can be created
+  conveniently with the following functions:
+
+  - `time.Nanosecond`
+  - `time.Microsecond`
+  - `time.Millisecond`
+  - `time.Second`
+  - `time.Minute`
+  - `time.Hour`
+
+  For example:
+
+  ```console
+  $ gomplate -i '{{ (time.Now).Format time.Kitchen }}
+  {{ ((time.Now).Add (time.Hour 2)).Format time.Kitchen }}'
+  9:05AM
+  11:05AM
+  ```
+
+  For other durations, such as `2h10m`, [`time.ParseDuration`](#time-parseduration) can be used.
+funcs:
+  - name: time.Now
+    description: |
+      Returns the current local time, as a `time.Time`. This wraps [`time.Now`](https://golang.org/pkg/time/#Now).
+
+      Usually, further functions are called using the value returned by `Now`.
+    pipeline: false
+    rawExamples:
+      - |
+        Usage with [`UTC`](https://golang.org/pkg/time/#Time.UTC) and [`Format`](https://golang.org/pkg/time/#Time.Format):
+        ```console
+        $ gomplate -i '{{ (time.Now).UTC.Format "Day 2 of month 1 in year 2006 (timezone MST)" }}'
+        Day 14 of month 10 in year 2017 (timezone UTC)
+        ```
+      - |
+        Usage with [`AddDate`](https://golang.org/pkg/time/#Time.AddDate):
+        ```console
+        $ date
+        Sat Oct 14 09:57:02 EDT 2017
+        $ gomplate -i '{{ ((time.Now).AddDate 0 1 0).Format "Mon Jan 2 15:04:05 MST 2006" }}'
+        Tue Nov 14 09:57:02 EST 2017
+        ```
+
+        _(notice how the TZ adjusted for daylight savings!)_
+  - name: time.Parse
+    description: |
+      Parses a timestamp defined by the given layout. This wraps [`time.Parse`](https://golang.org/pkg/time/#Parse).
+
+      A number of pre-defined layouts are provided as constants, defined
+      [here](https://golang.org/pkg/time/#pkg-constants).
+
+      Just like [`time.Now`](#time-now), this is usually used in conjunction with
+      other functions.
+
+      _Note: In the absence of a time zone indicator, `time.Parse` returns a time in UTC._
+    pipeline: true
+    arguments:
+      - name: layout
+        required: true
+        description: The layout string to parse with
+      - name: timestamp
+        required: true
+        description: The timestamp to parse
+    rawExamples:
+      - |
+        Usage with [`Format`](https://golang.org/pkg/time/#Time.Format):
+        ```console
+        $ gomplate -i '{{ (time.Parse "2006-01-02" "1993-10-23").Format "Monday January 2, 2006 MST" }}'
+        Saturday October 23, 1993 UTC
+        ```
+  - name: time.ParseDuration
+    description: |
+      Parses a duration string. This wraps [`time.ParseDuration`](https://golang.org/pkg/time/#ParseDuration).
+
+      A duration string is a possibly signed sequence of decimal numbers, each with
+      optional fraction and a unit suffix, such as `300ms`, `-1.5h` or `2h45m`. Valid
+      time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`.
+    pipeline: true
+    arguments:
+      - name: duration
+        required: true
+        description: The duration string to parse
+    examples:
+      - |
+        $ gomplate -i '{{ (time.Now).Format time.Kitchen }}
+        {{ ((time.Now).Add (time.ParseDuration "2h30m")).Format time.Kitchen }}'
+        12:43AM
+        3:13AM
+  - name: time.ParseLocal
+    description: |
+      Same as [`time.Parse`](#time-parse), except that in the absence of a time zone
+      indicator, the timestamp wil be parsed in the local timezone.
+    pipeline: true
+    arguments:
+      - name: layout
+        required: true
+        description: The layout string to parse with
+      - name: timestamp
+        required: true
+        description: The timestamp to parse
+    rawExamples:
+      - |
+        Usage with [`Format`](https://golang.org/pkg/time/#Time.Format):
+        ```console
+        $ bin/gomplate -i '{{ (time.ParseLocal time.Kitchen "6:00AM").Format "15:04 MST" }}'
+        06:00 EST
+        ```
+  - name: time.ParseInLocation
+    description: |
+      Same as [`time.Parse`](#time-parse), except that the time is parsed in the given location's time zone.
+
+      This wraps [`time.ParseInLocation`](https://golang.org/pkg/time/#ParseInLocation).
+    pipeline: true
+    arguments:
+      - name: layout
+        required: true
+        description: The layout string to parse with
+      - name: location
+        required: true
+        description: The location to parse in
+      - name: timestamp
+        required: true
+        description: The timestamp to parse
+    rawExamples:
+      - |
+        Usage with [`Format`](https://golang.org/pkg/time/#Time.Format):
+        ```console
+        $ gomplate -i '{{ (time.ParseInLocation time.Kitchen "Africa/Luanda" "6:00AM").Format "15:04 MST" }}'
+        06:00 LMT
+        ```
+  - name: time.Since
+    description: |
+      Returns the time elapsed since a given time. This wraps [`time.Since`](https://golang.org/pkg/time/#Since).
+
+      It is shorthand for `time.Now.Sub t`.
+    pipeline: true
+    arguments:
+      - name: t
+        required: true
+        description: the `Time` to calculate since
+    examples:
+      - |
+        $ gomplate -i '{{ $t := time.Parse time.RFC3339 "1970-01-01T00:00:00Z" }}time since the epoch:{{ time.Since $t }}'
+        time since the epoch:423365h0m24.353828924s
+  - name: time.Unix
+    description: |
+      Returns the local `Time` corresponding to the given Unix time, in seconds since
+      January 1, 1970 UTC. Note that fractional seconds can be used to denote
+      milliseconds, but must be specified as a string, not a floating point number.
+    pipeline: true
+    arguments:
+      - name: time
+        required: true
+        description: the time to parse
+    rawExamples:
+      - |
+        _with whole seconds:_
+        ```console
+        $ gomplate -i '{{ (time.Unix 42).UTC.Format time.Stamp}}'
+        Jan  1, 00:00:42
+        ```
+
+        _with fractional seconds:_
+        ```console
+        $ gomplate -i '{{ (time.Unix "123456.789").UTC.Format time.StampMilli}}'
+        Jan  2 10:17:36.789
+        ```
+  - name: time.Until
+    description: |
+      Returns the duration until a given time. This wraps [`time.Until`](https://golang.org/pkg/time/#Until).
+
+      It is shorthand for `$t.Sub time.Now`.
+    pipeline: true
+    arguments:
+      - name: t
+        required: true
+        description: the `Time` to calculate until
+    rawExamples:
+      - |
+        ```console
+        $ gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ time.Until $t }} to go...'
+        only 14922h56m46.578625891s to go...
+        ```
+
+        Or, less precise:
+        ```console
+        $ bin/gomplate -i '{{ $t := time.Parse time.RFC3339 "2020-01-01T00:00:00Z" }}only {{ (time.Until $t).Round (time.Hour 1) }} to go...'
+        only 14923h0m0s to go...
+        ```
+  - name: time.ZoneName
+    description: |
+      Return the local system's time zone's name.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{time.ZoneName}}'
+        EDT
+  - name: time.ZoneOffset
+    description: |
+      Return the local system's time zone offset, in seconds east of UTC.
+    pipeline: false
+    examples:
+      - |
+        $ gomplate -i '{{time.ZoneOffset}}'
+        -14400