From eec20a6506a58ccbfb34fbdae81be173b2268b10 Mon Sep 17 00:00:00 2001
From: Brian Cain <bcain@hashicorp.com>
Date: Thu, 22 Jun 2017 10:27:39 -0700
Subject: [PATCH] Add information about extra box info

This commit adds a new page to vagrants docs around supplying an
`info.json` file for vagrant boxes.
---
 website/source/docs/boxes/format.html.md |  8 +++--
 website/source/docs/boxes/info.html.md   | 42 ++++++++++++++++++++++++
 website/source/layouts/docs.erb          |  1 +
 3 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 website/source/docs/boxes/info.html.md

diff --git a/website/source/docs/boxes/format.html.md b/website/source/docs/boxes/format.html.md
index 8f9111ff3..c1afd6b09 100644
--- a/website/source/docs/boxes/format.html.md
+++ b/website/source/docs/boxes/format.html.md
@@ -18,7 +18,7 @@ Box files made for Vagrant 1.0.x (the VirtualBox export `tar` files) continue
 to work with Vagrant today. When Vagrant encounters one of these old boxes,
 it automatically updates it internally to the new format.
 
-Today, there are two different components:
+Today, there are three different components:
 
 * Box File - This is a compressed (`tar`, `tar.gz`, `zip`) file that is specific
   to a single provider and can contain anything. Vagrant core does not ever
@@ -34,7 +34,11 @@ Today, there are two different components:
   metadata does not exist, a box file can still be added directly, but
   it will not support versioning and updating.
 
-Each component is covered in more detail below.
+* Box Information - This is a JSON documnent that can provide additional
+  information about the box that displays when a user runs
+  `vagrant box list -i`. More information is provided [here](/docs/boxes/info.html).
+
+The first two components are covered in more detail below.
 
 ## Box File
 
diff --git a/website/source/docs/boxes/info.html.md b/website/source/docs/boxes/info.html.md
new file mode 100644
index 000000000..c1e107f14
--- /dev/null
+++ b/website/source/docs/boxes/info.html.md
@@ -0,0 +1,42 @@
+---
+layout: "docs"
+page_title: "Box Info Format"
+sidebar_current: "boxes-info"
+description: |-
+  A box can provide additional information to the user by supplying an info.json
+  file within the box.
+---
+
+# Additional Box Information
+
+When creating a Vagrant box, you can supply additional information that might be
+relevant to the user when running `vagrant box list -i`. For example, you could
+package your box to include information about the author of the box and a
+website for users to learn more:
+
+```
+brian@localghost % vagrant box list -i
+hashicorp/precise64     (virtualbox, 1.0.0)
+  - author: brian
+  - homepage: https://www.vagrantup.com
+```
+
+## Box Info
+
+To accomplish this, you simply need to include a file named `info.json` when
+creating a [base box](/docs/boxes/base.html) which is a JSON document containing
+any and all relevant information that will be displayed to the user when the
+`-i` option is used with `vagrant box list`.
+
+```json
+{
+ "author": "brian",
+ "homepage": "https://example.com"
+}
+```
+
+There are no special keys or values in `info.json`, and Vagrant will print each
+key and value on its own line.
+
+The [Box File Format](/docs/boxes/format.html) provides more information about what
+else goes into a Vagrant box.
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
index 0da62fc7e..5eb6eb757 100644
--- a/website/source/layouts/docs.erb
+++ b/website/source/layouts/docs.erb
@@ -80,6 +80,7 @@
           <li<%= sidebar_current("boxes-versioning") %>><a href="/docs/boxes/versioning.html">Box Versioning</a></li>
           <li<%= sidebar_current("boxes-base") %>><a href="/docs/boxes/base.html">Creating a Base Box</a></li>
           <li<%= sidebar_current("boxes-format") %>><a href="/docs/boxes/format.html">Box File Format</a></li>
+          <li<%= sidebar_current("boxes-info") %>><a href="/docs/boxes/info.html">Box Info Format</a></li>
         </ul>
       </li>