docs: name templates

www/content/archive.md

@@ -14,17 +14,7 @@ Here is a commented `archive` section with all fields specified:
 ```yml
 # .goreleaser.yml
 archive:
-  # You can change the name of the archive.
-  # This is parsed with the Go template engine and the following variables
-  # are available:
-  # - ProjectName
-  # - Binary (Name of the binary if the packaging format is binary)
-  # - Tag
-  # - Version (Git tag without `v` prefix)
-  # - Os
-  # - Arch
-  # - Arm (ARM version)
-  # - Env (environment variables)
+  # Archive name template.
   # Defaults:
   # - if format is `tar.gz` or `zip`:
   #   - `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
@@ -73,21 +63,7 @@ archive:
     - design/*.png
 ```
 
-## Passing environment variables to name_template
-
-You can do that by using `{{ .Env.VARIABLE_NAME }}` in the template, for
-example:
-
-```yaml
-archive:
-  name_template: '{{.ProjectName}}-{{.Version}}-{{.Env.GOVERSION_NR}}'
-```
-
-Then you can run:
-
-```console
-GOVERSION_NR=$(go version | awk '{print $3;}') goreleaser
-```
+> Learn more about the [name template engine](/templates).
 
 ## Packaging only the binaries
 

www/content/build.md

@@ -19,14 +19,7 @@ builds:
     # Default is `.`.
     main: ./cmd/main.go
 
-    # Name of the binary.
-    # This is parsed with the Go template engine and the following variables
-    # are available:
-    # - Date
-    # - Commit
-    # - Tag
-    # - Version (Git tag without `v` prefix)
-    # Date format is `2006-01-02_15:04:05`.
+    # Name template for the binary final name.
     # Default is the name of the project directory.
     binary: program
 
@@ -37,51 +30,18 @@ builds:
       - dev
 
     # Custom asmflags templates.
-    # These are parsed with the Go template engine and the following variables
-    # are available:
-    # - Date
-    # - Commit
-    # - Tag
-    # - Version (Git tag without `v` prefix)
-    # - Env (environment variables)
-    # Date format is `2006-01-02_15:04:05`.
-    # You can use the `time` function instead of `Date`, for example:
-    # `time "2006-01-02"` too if you need custom formats
-    #
     # Default is empty.
     asmflags:
       - -D mysymbol
       - all=-trimpath={{.Env.GOPATH}}
 
     # Custom gcflags templates.
-    # These are parsed with the Go template engine and the following variables
-    # are available:
-    # - Date
-    # - Commit
-    # - Tag
-    # - Version (Git tag without `v` prefix)
-    # - Env (environment variables)
-    # Date format is `2006-01-02_15:04:05`.
-    # You can use the `time` function instead of `Date`, for example:
-    # `time "2006-01-02"` too if you need custom formats
-    #
     # Default is empty.
     gcflags:
       - all=-trimpath={{.Env.GOPATH}}
       - ./dontoptimizeme=-N
 
     # Custom ldflags templates.
-    # These are parsed with the Go template engine and the following variables
-    # are available:
-    # - Date
-    # - Commit
-    # - Tag
-    # - Version (Git tag without `v` prefix)
-    # - Env (environment variables)
-    # Date format is `2006-01-02_15:04:05`.
-    # You can use the `time` function instead of `Date`, for example:
-    # `time "2006-01-02"` too if you need custom formats
-    #
     # Default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}`.
     ldflags:
      - -s -w -X main.build={{.Version}}
@@ -131,6 +91,8 @@ builds:
       post: ./script.sh
 ```
 
+> Learn more about the [name template engine](/templates).
+
 ## Passing environment variables to ldflags
 
 You can do that by using `{{ .Env.VARIABLE_NAME }}` in the template, for

www/content/checksum.md

@@ -14,12 +14,8 @@ The `checksum` section allows customizations of the filename:
 # .goreleaser.yml
 checksum:
   # You can change the name of the checksums file.
-  # This is parsed with the Go template engine and the following variables
-  # are available:
-  # - ProjectName
-  # - Tag
-  # - Version (Git tag without `v` prefix)
-  # - Env (environment variables)
   # Default is `{{ .ProjectName }}_{{ .Version }}_checksums.txt`.
   name_template: "{{ .ProjectName }}_checksums.txt"
 ```
+
+> Learn more about the [name template engine](/templates).

www/content/docker.md

@@ -61,13 +61,6 @@ dockers:
     # Path to the Dockerfile (from the project root).
     dockerfile: Dockerfile
     # Template of the docker tag. Defaults to `{{ .Version }}`.
-    # Other allowed fields are:
-    # - `.Commint`
-    # - `.Tag`
-    # - `.Major`
-    # - `.Minor`
-    # - `.Patch`
-    # - `.Env.VARIABLE_NAME`
     tag_templates:
     - "{{ .Tag }}"
     - "{{ .Tag }}-{{ .Env.GO_VERSION }}"
@@ -79,27 +72,12 @@ dockers:
     - config.yml
 ```
 
+> Learn more about the [name template engine](/templates).
+
 These settings should allow you to generate multiple Docker images,
 for example, using multiple `FROM` statements,
 as well as generate one image for each binary in your project.
 
-## Passing environment variables to tag_template
-
-You can do that by using `{{ .Env.VARIABLE_NAME }}` in the template, for
-example:
-
-```yaml
-dockers:
-  -
-    tag_template: "{{ .Tag }}-{{ .Env.GOVERSION_NR }}"
-```
-
-Then you can run:
-
-```console
-GOVERSION_NR=$(go version | awk '{print $3}') goreleaser
-```
-
 ## Keeping docker images updated for current major
 
 Some users might want to when version to push docker tags `:v1`, `:v1.6`,

www/content/homebrew.md

@@ -18,7 +18,7 @@ for more details.
 ```yml
 # .goreleaser.yml
 brew:
-  # Name of the recipe
+  # Name template of the recipe
   # Default to project name
   name: myproject
 
@@ -88,6 +88,8 @@ brew:
     ...
 ```
 
+> Learn more about the [name template engine](/templates).
+
 By defining the `brew` section, GoReleaser will take care of publishing the
 Homebrew tap.
 Assuming that the current tag is `v1.2.3`, the above configuration will generate a

www/content/nfpm.md

@@ -14,15 +14,6 @@ Available options:
 # .goreleaser.yml
 nfpm:
   # You can change the name of the package.
-  # This is parsed with the Go template engine and the following variables
-  # are available:
-  # - ProjectName
-  # - Tag
-  # - Version (Git tag without `v` prefix)
-  # - Os
-  # - Arch
-  # - Arm (ARM version)
-  # - Env (environment variables)
   # Default: `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
   name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
 
@@ -141,6 +132,8 @@ nfpm:
         preinstall: "scripts/preinstall-rpm.sh"
 ```
 
+> Learn more about the [name template engine](/templates).
+
 Note that GoReleaser will not install `rpmbuild` or any dependencies for you.
 As for now, `rpmbuild` is recommended if you want to generate rpm packages.
 You can install it with `apt-get install rpm` or `brew install rpm`.

www/content/put.md

@@ -1,5 +1,5 @@
 ---
-title: Put
+title: HTTP Put
 series: customization
 hideFromIndex: true
 weight: 120

www/content/release.md

@@ -29,14 +29,6 @@ release:
   prerelease: true
 
   # You can change the name of the GitHub release.
-  # This is parsed with the Go template engine and the following variables
-  # are available:
-  # - ProjectName
-  # - Tag
-  # - Version (Git tag without `v` prefix)
-  # - Env (environment variables)
-  # There is also a template function "time" that takes a Go time format
-  # string to insert a formated timestamp into the release name.
   # Default is ``
   name_template: "{{.ProjectName}}-v{{.Version}} {{.Env.USER}}"
 
@@ -46,6 +38,8 @@ release:
   disable: true
 ```
 
+> Learn more about the [name template engine](/templates).
+
 ## Customize the changelog
 
 You can customize how the changelog is generated using the

www/content/s3.md

@@ -27,14 +27,7 @@ s3:
     # AWS Region to use.
     # Defaults is us-east-1
     region: us-east-1
-    # path inside the bucket.
-    # This is parsed with the Go template engine and the following variables
-    # are available:
-    # - ProjectName
-    # - Tag
-    # - Version (Git tag without `v` prefix)
-    # There is also a template function "time" that takes a Go time format
-    # string to insert a formated timestamp into the release name.
+    # Template for the path/name inside the bucket.
     # Default is `{{ .ProjectName }}/{{ .Tag }}`
     folder: "foo/bar/{{.Version}}"
     # Set a custom profile to use for this s3 config. If you have multiple
@@ -48,6 +41,8 @@ s3:
     endpoint: "http://minio.foo.com"
 ```
 
+> Learn more about the [name template engine](/templates).
+
 ## Authentication
 
 GoReleaser will authenticate using the [same methods defined by aws-cli][auth].

www/content/snapcraft.md

@@ -20,15 +20,6 @@ Available options:
 # .goreleaser.yml
 snapcraft:
   # You can change the name of the package.
-  # This is parsed with the Go template engine and the following variables
-  # are available:
-  # - ProjectName
-  # - Tag
-  # - Version (Git tag without `v` prefix)
-  # - Os
-  # - Arch
-  # - Arm (ARM version)
-  # - Env (environment variables)
   # Default: `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
   name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
 
@@ -97,5 +88,7 @@ snapcraft:
       args: --foo
 ```
 
+> Learn more about the [name template engine](/templates).
+
 Note that GoReleaser will not install `snapcraft` nor any of its dependencies
 for you.

www/content/snapshots.md

@@ -14,10 +14,8 @@ and also with the `snapshot` customization section:
 # .goreleaser.yml
 snapshot:
   # Allows you to change the name of the generated snapshot
-  # releases. The following variables are available:
-  # - Commit
-  # - Tag
-  # - Timestamp
   # Default is `SNAPSHOT-{{.Commit}}`.
   name_template: SNAPSHOT-{{.Commit}}
 ```
+
+> Learn more about the [name template engine](/templates).

www/content/templates.md

@@ -0,0 +1,65 @@
+---
+title: Name Templates
+series: customization
+hideFromIndex: true
+weight: 25
+---
+
+Several fields in GoReleaser's config file support templating.
+
+Those fields are often suffixed with `_template`, but sometimes they may not
+be. The documentation of each section should explicit in which fields
+templating is available.
+
+On fields that support templating, this fields are always available:
+
+| Key | Description |
+|:-:|:-:|
+| `.ProjectName` | the project name |
+| `.Version` | the version being released (`v` prefix stripped) |
+| `.Tag` | the current git tag |
+| `.Commit` | the git commit hash |
+| `.Major` | the major part of the version |
+| `.Minor` | the minor part of the version |
+| `.Patch` | the patch part of the version |
+| `.Env` | a map with system's environment variables |
+| `.Date` | current UTC date in RFC3339 format |
+| `.Timestamp` | current UTC time in Unix format |
+
+On fields that are related to a single artifact (e.g., the binary name), you
+may have some extra fields:
+
+| Key | Description |
+|:-:|:-:|
+| `.Os` | `GOOS` (usually allow replacements) |
+| `.Arch` | `GOARCH` (usually allow replacements) |
+| `.Arm` | `GOARM` (usually allow replacements) |
+| `.Binary ` | Binary name |
+
+On all fields, you have these available functions:
+
+| Usage | Description |
+|:-:|:-:|
+| `time "01/02/2006"` | current UTC time in the specified format |
+
+With all those fields, you may be able to compose the name of your artifacts
+pretty much the way you want:
+
+```yaml
+example_template: '{{ .ProjectName }}_{{ .Env.USER }}_{{ time "2006" }}'
+```
+
+For example, if you want to add the go version to some artifact:
+
+```yaml
+foo_template: 'foo_{{ .Env.GOVERSION }}'
+```
+
+And then you can run:
+
+```console
+GOVERSION_NR=$(go version | awk '{print $3;}') goreleaser
+```
+
+> Note that those are hypothetical examples and the fields `foo_template` and
+> `example_template` are not valid GoReleaser configurations.

www/themes/hugo-apex-theme

@@ -1 +1 @@
-Subproject commit cb87b6b1368824d743a5d31d824eaecd2351b783
+Subproject commit 7a952e65f3dcdc1023f35a7faf83b7b70de4631a