Clarify supported buildpack/lifecycle archive types and URI schemes (#863)

* Clarify supported buildpack/lifecycle archive types and URI schemes

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>

* Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>

* Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>

* Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>

* Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>

* Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>

* Fix Vale style issues: active voice, wrap buildpacks terms, clean grammar

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>

---------

Signed-off-by: xonas1101 <aarushsingh1305@gmail.com>
Co-authored-by: Aidan Delaney <adelaney21@bloomberg.net>

Author: AidanDelaney

docs/reference/config/builder-config/index.html

@@ -926,7 +926,7 @@ <h4 id="description-string-optional"><code>description</code> <em>(string, optio
 </li>
 <li>
 <h4 id="buildpacks-list-optional"><code>buildpacks</code> <em>(list, optional)</em></h4>
-<p>A list of buildpacks, each with the following fields:</p>
+<p>A list of <code>buildpacks</code>, each with the following fields:</p>
 <ul>
 <li>
 <p><strong><code>id</code></strong> <em>(string, optional)</em><br>
@@ -944,26 +944,23 @@ <h4 id="buildpacks-list-optional"><code>buildpacks</code> <em>(list, optional)</
 </li>
 <li>
 <h4 id="order-list-required"><code>order</code> <em>(list, required)</em></h4>
-<p>A list of buildpack groups. This list determines the order in which groups of buildpacks
-will be tested during detection. Detection is a phase of the <a href="/docs/for-platform-operators/concepts/lifecycle">lifecycle</a> where
-buildpacks are tested, one group at a time, for compatibility with the provided application source code. The first
-group whose non-optional buildpacks all pass detection will be the group selected for the remainder of the build. Each
-group currently contains a single required field:</p>
+<p>A list of buildpack groups. This list determines the order in which the lifecycle tests groups of <code>buildpacks</code> during detection. Detection is a phase of the <a href="/docs/for-platform-operators/concepts/lifecycle">lifecycle</a> where the lifecycle tests each <code>buildpacks</code> group, one at a time, for compatibility with the provided app source code. The first
+group whose non-optional <code>buildpacks</code> all pass detection will be the group selected for the remainder of the build. Each group currently contains a single required field:</p>
 <ul>
 <li>
 <p><strong><code>group</code></strong> <em>(list, required)</em><br>
 A set of buildpack references. Each buildpack reference specified has the following fields:</p>
 <ul>
 <li>
 <p><strong><code>id</code></strong> <em>(string, required)</em><br>
-The identifier of a buildpack from the configuration&rsquo;s top-level <code>buildpacks</code> list. Buildpacks with the same ID may
+The identifier of a buildpack from the configuration&rsquo;s top-level <code>buildpacks</code> list. <code>Buildpacks</code> with the same ID may
 appear in multiple groups at once but never in the same group.</p>
 </li>
 <li>
 <p><strong><code>version</code></strong> <em>(string, optional, default: inferred)</em><br>
 The version of the buildpack being referred to. This field may be omitted if
 exactly one version of the buildpack
-occurs in either the top-level <code>buildpacks</code> list or those buildpacks&rsquo; dependencies.</p>
+occurs in either the top-level <code>buildpacks</code> list or in the dependencies of those <code>buildpacks</code>.</p>
 </li>
 <li>
 <p><strong><code>optional</code></strong> <em>(boolean, optional, default: <code>false</code>)</em><br>
@@ -1049,7 +1046,7 @@ <h4 id="lifecycle-optional"><code>lifecycle</code> <em>(optional)</em></h4>
 </li>
 <li>
 <h4 id="buildenv-optional"><code>build.env</code> <em>(optional)</em></h4>
-<p>The <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules">[[build.env]]</a> is used to specify <a href="https://github.com/buildpacks/spec/blob/main/platform.md#operator-defined-variables">operator-defined</a> build-time environment variables for buildpacks. Set <code>CNB_BUILD_CONFIG_DIR</code> in pack&rsquo;s environment to override the default directory (<code>/cnb/build-config/env</code>) where environment variable files are stored within the builder.</p>
+<p>The <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#environment-variable-modification-rules">[[build.env]]</a> is used to specify <a href="https://github.com/buildpacks/spec/blob/main/platform.md#operator-defined-variables">operator-defined</a> build-time environment variables for <code>buildpacks</code>. Set <code>CNB_BUILD_CONFIG_DIR</code> in pack&rsquo;s environment to override the default directory (<code>/cnb/build-config/env</code>) where environment variable files are stored within the builder.</p>
 <ul>
 <li>
 <p><strong><code>name</code></strong> <em>(string, required)</em><br>
@@ -1061,7 +1058,7 @@ <h4 id="buildenv-optional"><code>build.env</code> <em>(optional)</em></h4>
 </li>
 <li>
 <p><strong><code>suffix</code></strong> <em>(string, optional)</em><br>
-The type of action used to modify the environment variable when end-users or buildpacks define the same name/key, one of <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#default"><code>default</code></a>, <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#override"><code>override</code></a>, <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#append"><code>append</code></a>, or <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#prepend"><code>prepend</code></a>. Defaults to <code>default</code> if this field is omitted. Operator-defined environment variables take precedence over end-user or buildpack-defined environment variables.</p>
+The type of action used to modify the environment variable when end-users or <code>buildpacks</code> define the same name/key, one of <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#default"><code>default</code></a>, <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#override"><code>override</code></a>, <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#append"><code>append</code></a>, or <a href="https://github.com/buildpacks/spec/blob/main/buildpack.md#prepend"><code>prepend</code></a>. Defaults to <code>default</code> if this field is omitted. Operator-defined environment variables take precedence over end-user or buildpack-defined environment variables.</p>
 </li>
 <li>
 <p><strong><code>delim</code></strong> <em>(string, optional)</em><br>
@@ -1074,7 +1071,17 @@ <h4 id="buildenv-optional"><code>build.env</code> <em>(optional)</em></h4>
 </li>
 </ul>
 <h3 id="supported-archives">Supported archives</h3>
-<p>Currently, when specifying a URI to a buildpack or lifecycle, only <code>tar</code> or <code>tgz</code> archive types are supported.</p>
+<p>A URI to a buildpack or lifecycle can use one of the following sources:</p>
+<ul>
+<li><strong>Archives:</strong> <code>.tar</code> or <code>.tgz</code> files, either local or remote.</li>
+<li><strong>Docker images:</strong> the <code>docker://</code> URI scheme.</li>
+</ul>
+<p><strong>Examples</strong></p>
+<ul>
+<li><code>file:///path/to/buildpack.tgz</code></li>
+<li><code>https://example.com/buildpack.tar</code></li>
+<li><code>docker://example/buildpack:latest</code></li>
+</ul>