From f985f2de62191f1515acde0e58787045935566b5 Mon Sep 17 00:00:00 2001
From: Megan Marsh <megan@hashicorp.com>
Date: Mon, 22 Apr 2019 16:10:35 -0700
Subject: [PATCH] add docs for how to use the format strings for the isotime
 function

---
 .../guides/isotime-template-function.html.md  | 89 +++++++++++++++++++
 website/source/layouts/guides.erb             |  3 +
 2 files changed, 92 insertions(+)
 create mode 100644 website/source/guides/isotime-template-function.html.md

diff --git a/website/source/guides/isotime-template-function.html.md b/website/source/guides/isotime-template-function.html.md
new file mode 100644
index 000000000..48c084704
--- /dev/null
+++ b/website/source/guides/isotime-template-function.html.md
@@ -0,0 +1,89 @@
+---
+layout: guides
+sidebar_current: isotime-template-function
+page_title: Using the isotime template function - Guides
+description: |-
+  It can be a bit confusing to figure out how to format your isotime using the
+  golang reference date string. Here is a small guide and some examples.
+---
+
+# Using the Isotime template function with a format string
+
+The way you format isotime in golang is a bit nontraditional compared to how
+you may be used to formatting datetime strings.
+
+Full docs and examples for the golang time formatting function can be found
+[here](https://golang.org/pkg/time/#example_Time_Format)
+
+However, the formatting basics are worth describing here. From the [golang docs](https://golang.org/pkg/time/#pkg-constants):
+
+
+>These are predefined layouts for use in Time.Format and time.Parse. The
+>reference time used in the layouts is the specific time:
+>
+>Mon Jan 2 15:04:05 MST 2006
+>
+>which is Unix time 1136239445. Since MST is GMT-0700, the reference time
+>can be thought of as
+>
+>01/02 03:04:05PM '06 -0700
+>
+> To define your own format, write down what the reference time would look like
+> formatted your way; see the values of constants like ANSIC, StampMicro or
+> Kitchen for examples. The model is to demonstrate what the reference time
+> looks like so that the Format and Parse methods can apply the same
+> transformation to a general time value.
+
+
+So what does that look like in a Packer template function?
+
+``` json
+{
+	"variables":
+	{
+		"myvar": "packer-{{isotime \"2006-01-02 03:04:05\"}}"
+	},
+	"builders": [
+		{
+			"type": "null",
+			"communicator": "none"
+		}
+	],
+	"provisioners": [
+		{
+			"type": "shell-local",
+			"inline": ["echo {{ user `myvar`}}"]
+		}
+	]
+}
+```
+
+You can switch out the variables section above with the following examples to
+get different timestamps:
+
+Date only, not time:
+
+```json
+	"variables":
+	{
+		"myvar": "packer-{{isotime \"2006-01-02\"}}"
+	},
+```
+
+A timestamp down to the millisecond:
+
+```json
+	"variables":
+	{
+		"myvar": "packer-{{isotime \"Jan-_2-15:04:05.000\"}}"
+	},
+```
+
+Or just the time as it would appear on a digital clock:
+
+```json
+	"variables":
+	{
+		"myvar": "packer-{{isotime \"3:04PM\"}}"
+	},
+```
\ No newline at end of file
diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb
index 1d5653c04..d285de620 100644
--- a/website/source/layouts/guides.erb
+++ b/website/source/layouts/guides.erb
@@ -1,6 +1,9 @@
 <% wrap_layout :inner do %>
   <% content_for :sidebar do %>
     <ul class="nav docs-sidenav">
+      <li<%= sidebar_current("isotime-template-function") %>>
+        <a href="/guides/isotime-template-function.html">Isotime Template Function</a>
+      </li>
       <li<%= sidebar_current("guides-veewee-to-packer") %>>
         <a href="/guides/veewee-to-packer.html">Veewee to Packer</a>
       </li>