Merge pull request #8708 from briancain/add-box-info-docs

Add information about extra box info

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
 

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.

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>