Updates, fixes given recent spec updates (devcontainers#66)

Co-authored-by: Samruddhi Khandale <[email protected]>

Author: Chuxel

_implementors/features-distribution.md

@@ -6,6 +6,8 @@ author: Microsoft
 index: 6
 ---
 
+**TL;DR Check out the [quick start template](https://github.com/devcontainers/feature-template) to get going on distributing your own Dev Container Features.**
+
 This specification defines a pattern where community members and organizations can author and self-publish [Dev Container 'Features'](../features). 
 
 Goals include:
@@ -85,7 +87,7 @@ Each Features's `devcontainer-feature.json` metadata file is appended into the `
 
 ## <a href="#distribution" name="distribution" class="anchor"> Distribution </a>
 
-There are several supported ways to distribute Features.  Distribution is handled by the implementing packaging tool.
+There are several supported ways to distribute Features. Distribution is handled by the implementing packaging tool such as the [Dev Container CLI](https://github.com/devcontainers/cli) or [Dev Container Publish GitHub Action](https://github.com/marketplace/actions/dev-container-publish). See the [quick start repository](https://github.com/devcontainers/feature-template) for a full working example.
 
 A user references a distributed Feature in a `devcontainer.json` as defined in ['referencing a feature'](../features#referencing-a-feature).
 

_implementors/reference.md

@@ -104,7 +104,7 @@ We recommend pre-building images with the tools you need rather than creating an
 
 We recommend using the dev container CLI to pre-build your images. Once you've built your image, you can push it to a container registry (like the [Azure Container Registry](https://learn.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) and reference it directly.
 
-#### <a href="#labels" name="labels" class="anchor"> Metadata in image labels (proposal) </a> 
+#### <a href="#labels" name="labels" class="anchor"> Metadata in image labels</a> 
 
 You can include dev container configuration and Feature metadata in prebuilt images via [image labels](https://docs.docker.com/config/labels-custom-metadata/), such that, the image and the built-in Features can be used with a devcontainer.json (image-, Dockerfile- or Docker Compose-based) that does not repeat the dev container config or Feature metadata. Other tools should be able to record the same metadata without necessarily using Features themselves.
 

_implementors/templates-distribution.md

@@ -56,7 +56,6 @@ Each sub-directory should be named such that it matches the `id` field of the `d
 
 ## <a href="#versioning" name="versioning" class="anchor">Versioning </a>
 
-
 Each Template is individually [versioned according to the semver specification](https://semver.org/). The `version` property in the respective `devcontainer-template.json` file is parsed to determine if the Template should be republished.
 
 Tooling that handles publishing Templates will not republish Templates if that exact version has already been published; however, tooling must republish major and minor versions in accordance with the semver specification.
@@ -85,14 +84,12 @@ Each Template's `devcontainer-template.json` metadata file is appended into the
 
 ## <a href="#distribution" name="distribution" class="anchor"> Distribution </a>
 
-
-There are several supported ways to distribute Templates.  Distribution is handled by the implementing packaging tool.
+There are several supported ways to distribute Templates.  Distribution is handled by the implementing packaging tool such as the **[Dev Container CLI](https://github.com/devcontainers/cli)** or **[Dev Container Publish GitHub Action](https://github.com/marketplace/actions/dev-container-publish)**.
 
 A user can add a Template in to their projects as defined by the [supporting tools](/supporting#supporting-tools-and-services).
 
 ### <a href="#oci-registry" name="oci-registry" class="anchor">OCI Registry</a>
 
-
 An OCI registry that implements the [OCI Artifact Distribution Specification](https://github.com/opencontainers/distribution-spec) serves as the primary distribution mechanism for Templates.
 
 Each packaged Template is pushed to the registry following the naming convention `<registry>/<namespace>/<id>[:version]`, where version is the major, minor, and patch version of the Template, according to the semver specification.

_implementors/templates.md

@@ -97,9 +97,11 @@ A Template's `options` property is used by a supporting tool to prompt for diffe
 
 Consider a `java` Template with the following folder structure:
 
+```
 +-- java
 |    +-- devcontainer-template.json
 |    +-- .devcontainer.json
+```
 
 Suppose the `java` Template has the following `options` parameters declared in the `devcontainer-template.json` file:
 

_includes/topnav.html

@@ -17,6 +17,9 @@ <h1>Development Containers</h1>
                 <!--<li {% if page.sectionid=='implementors' %} class="nav-item active" {% else %} class="nav-item" {% endif %}>
                     <a class="nav-link" href="{{ sorted.first.url | prepend: site.baseurl }}">Implementations</a>
                 </li>-->
+                <li {% if page.sectionid=='metadata' %} class="nav-item active" {% else %} class="nav-item" {% endif %}>
+                    <a class="nav-link" href="{{ "/implementors/json_reference" | prepend: site.baseurl }}">Metadata</a>
+                </li>
                 <li {% if page.sectionid=='implementors' %} class="nav-item active" {% else %} class="nav-item" {% endif %}>
                     <a class="nav-link" href="{{ sorted.first.url | prepend: site.baseurl }}">Specification</a>
                 </li>

index.html

@@ -27,9 +27,9 @@ <h1>Development Containers</h1>
         <div class="col-lg-7" role="navigation" aria-label="Main">
             <h2 class="header-light regular-pad">What are Development Containers?</h2>
 
-            <p>A development container allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud.</p>
+            <p>A Development Container (or Dev Container for short) allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud.</p>
 
-            <p>The Development Containers Specification seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing.</p>
+            <p>The Development Containers Specification seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing. Beyond the specification's core metadata, the spec also enables developers to quickly share and reuse container setup steps through [Dev Container Features](./features) and [Templates](./templates). </p>
 
         </div>
         <div class="col-lg-5">

overview.md

@@ -7,15 +7,17 @@ sectionid: overview
 ## <a href="#overview" name="overview" class="anchor"> What are development containers? </a>
 As containerizing production workloads becomes commonplace, more developers are using containers for scenarios beyond deployment, including continuous integration, test automation, and even full-featured coding environments.
 
-Each scenario’s needs can vary between simple single container environments to complex, orchestrated multi-container setups. Rather than attempting to create another orchestrator format, the Development Containers Specification seeks to find ways to enrich existing formats with metadata for common development specific settings, tools, and configuration.
+Each scenario’s needs can vary between simple single container environments to complex, orchestrated multi-container setups. Rather than attempting to create another orchestrator format, the Development Containers Specification (or Dev Containers Spec for short) seeks to find ways to enrich existing formats with metadata for common development specific settings, tools, and configuration.
 
 ### <a href="#metadata-format" name="metadata-format" class="anchor">  A structured metadata format </a>
 
-Like the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) before it, the first format in the specification, [`devcontainer.json`](implementors/json_reference), was born out of necessity. It is a structured JSON with Comments (jsonc) metadata format that tools can use to store any needed configuration required to develop inside of local or cloud-based containerized coding. While this metadata can be persisted in a `devcontainer.json` today, we envision that this same structured data can be embedded in images and other formats -- all while retaining a common object model for consistent processing.
+Like the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) before it, the first format in the specification, [`devcontainer.json`](implementors/json_reference), was born out of necessity. It is a structured JSON with Comments (jsonc) metadata format that tools can use to store any needed configuration required to develop inside of local or cloud-based containerized coding. 
+
+Since the spec was initally published, Dev Container metadata can now be stored in [image labels](../implementors/spec/#image-metadata) and in reusable chunks of metadata and install scripts known as [Dev Container Features](../features). We envision that this same structured data can be embedded in other formats -- all while retaining a common object model for consistent processing.
 
 ### <a href="#Development-vs-production" name="Development-vs-production" class="anchor"> Development vs production </a>
 
-A development container defines an environment in which you develop your application before you are ready to deploy. While deployment and development containers may resemble one another, you may not want to include tools in a deployment image that you use during development.
+A Development Container defines an environment in which you develop your application before you are ready to deploy. While deployment and development containers may resemble one another, you may not want to include tools in a deployment image that you use during development.
 
 <img alt="Diagram of inner and outer loop of container-based development" src="img/dev-container-stages.png"/>