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 @@ >Box Versioning >Creating a Base Box >Box File Format + >Box Info Format