Edit pass for consistency (devcontainers#307)

* Formatting

* Update _implementors/features.md

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

* Add Slack link

* Update _implementors/spec.md

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

---------

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

Author: 3 people

_implementors/contributing.md

@@ -6,7 +6,7 @@ author: Microsoft
 index: 9
 ---
 
-We're excited for your contributions to the Dev Container Specification! This document outlines how you can get involved. 
+We're excited for your contributions to the Dev Container Specification! This document outlines how you can get involved. We also welcome you to join our [community Slack channel](https://aka.ms/dev-container-community).
 
 ## <a href="#contribution-approaches" name="contribution-approaches" class="anchor"> Contribution approaches </a>
 

_implementors/features-distribution.md

@@ -8,7 +8,7 @@ index: 6
 
 **TL;DR Check out the [quick start repository](https://github.com/devcontainers/feature-template) to get started 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). 
+This specification defines a pattern where community members and organizations can author and self-publish [Dev Container Features](../features). 
 
 Goals include:
 
@@ -89,7 +89,7 @@ Each Features's `devcontainer-feature.json` metadata file is appended into the `
 
 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).
+A user references a distributed Feature in a `devcontainer.json` as defined in ['referencing a Feature'](../features#referencing-a-feature).
 
 ### <a href="#oci-registry" name="oci-registry" class="anchor"> OCI Registry </a>
 
@@ -151,7 +151,7 @@ Additional constraints exists when including local Features in a project:
 
 * The project must have a `.devcontainer/` folder at the root of the [**project workspace folder**](/implementors/spec/#project-workspace-folder).
 
-* A local Feature's source code **must** be contained within a sub-folder of the `.devcontainer/ folder`.
+* A local Feature's source code **must** be contained within a sub-folder of the `.devcontainer/` folder.
 
 * The sub-folder name **must** match the Feature's `id` field.
 

_implementors/features.md

@@ -6,13 +6,13 @@ author: Microsoft
 index: 5
 ---
 
-Development container "Features" are self-contained, shareable units of installation code and development container configuration. The name comes from the idea that referencing one of them allows you to quickly and easily add more tooling, runtime, or library "Features" into your development container for you or your collaborators to use.
+**Development Container Features** are self-contained, shareable units of installation code and development container configuration. The name comes from the idea that referencing one of them allows you to quickly and easily add more tooling, runtime, or library "features" into your development container for you or your collaborators to use.
 
 Feature metadata is captured by a `devcontainer-feature.json` file in the root folder of the feature.
 
 > **Note:** While Features may be installed on top of any base image, the implementation of a Feature might restrict it to a subset of possible base images. For example, some Features may be authored to work with a certain Linux distro (e.g. debian-based images that use the `apt` package manager).
 > 
-> This section covers details on the Features specification. If you are looking for summarized information on creating your own Features, check out the [quick start](https://github.com/devcontainers/feature-starter) and [core Features](https://github.com/devcontainers/features) repositories.
+> This page covers details on the Features specification. If you are looking for summarized information on creating your own Features, check out the [quick start](https://github.com/devcontainers/feature-starter) and [core Features](https://github.com/devcontainers/features) repositories.
 
 ## <a href="#folder-structure" name="folder-structure" class="anchor"> Folder Structure </a>
 
@@ -72,15 +72,15 @@ The following lifecycle hooks may be declared as properties of `devcontainer-fea
 | `postAttachCommand` | [string, array, object](/implementors/json_reference#formatting-string-vs-array-properties) |
 {: .table .table-bordered .table-responsive}
 
-#### Behavior
+#### <a href="#behavior" name="behavior" class="anchor"> Behavior </a>
 
 Each property mirrors the behavior of the matching property in [`devcontainer.json`](/implementors/json_reference#Lifecycle-scripts), including the behavior that commands are executed from the context of the [project workspace folder](/implementors/spec/#project-workspace-folder).
 
 For each lifecycle hook (in [Feature installation order](/implementors/features/#installation-order)), each command contributed by a Feature is executed in sequence (blocking the next command from executing). Commands provided by Features are always executed _before_ any user-provided lifecycle commands (i.e: in the `devcontainer.json`).
 
 If a Feature provides a given command with the [object syntax](/implementors/json_reference#formatting-string-vs-array-properties), all commands within that group are executed in parallel, but still blocking commands from subsequent Features and/or the `devcontainer.json`.
 
-> NOTE: These properties are stored within [image metadata](/implementors/spec/#merge-logic).
+> **Note**: These properties are stored within [image metadata](/implementors/spec/#merge-logic).
 
 ### <a href="#options-property" name="options-property" class="anchor"> The `options` property </a>
 
@@ -117,11 +117,11 @@ Feature scripts run as the `root` user and sometimes need to know which user acc
 
 Additionally, the home folders of the two users are passed to the Feature scripts as `_REMOTE_USER_HOME` and `_CONTAINER_USER_HOME` environment variables.
 
-The container user can be set with `containerUser` in the devcontainer.json and image metadata, `user` in the docker-compose.yml, `USER` in the Dockerfile, and can be passed down from the base image.
+The container user can be set with `containerUser` in the `devcontainer.json` and image metadata, `user` in the `docker-compose.yml`, `USER` in the Dockerfile, and can be passed down from the base image.
 
 ### <a href="#dev-container-id" name="dev-container-id" class="anchor"> Dev Container ID </a>
 
-An identifier will be referred to as `${devcontainerId}` in the devcontainer.json and the Feature metadata and that will be replaced with the dev container's id. It should only be used in parts of the configuration and metadata that is not used for building the image because that would otherwise prevent pre-building the image at a time when the dev container's id is not known yet. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in the Feature metadata are: `entrypoint`, `mounts`, `customizations`.
+An identifier will be referred to as `${devcontainerId}` in the `devcontainer.json` and the Feature metadata and that will be replaced with the dev container's id. It should only be used in parts of the configuration and metadata that is not used for building the image because that would otherwise prevent pre-building the image at a time when the dev container's id is not known yet. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in the Feature metadata are: `entrypoint`, `mounts`, `customizations`.
 
 Implementations can choose how to compute this identifier. They must ensure that it is unique among other dev containers on the same Docker host and that it is stable across rebuilds of dev containers. The identifier must only contain alphanumeric characters. We describe a way to do this below.
 
@@ -218,7 +218,7 @@ As a shorthand, the value of the `features` property can be provided as a single
 }
 ```
 
-### <a href="#referencing-a-feature" name="referencing-a-feature" class="anchor"> Referencing a feature </a>
+### <a href="#referencing-a-feature" name="referencing-a-feature" class="anchor"> Referencing a Feature </a>
 
 The `id` format specified dicates how a supporting tool will locate and download a given feature. `id` is one of the following:
 
@@ -251,7 +251,7 @@ If the Feature is included in a folder as part of the repository that contains `
 
 ## <a href="#release" name="release" class="anchor"> Release </a>
 
-_For information on distributing Features, see [the dev container Features distribution page](../features-distribution)._
+_For information on distributing Features, see the [Features distribution page](../features-distribution)._
 
 ## <a href="#execution" name="execution" class="anchor"> Execution </a>
 
@@ -313,11 +313,11 @@ After `overrideFeatureInstallOrder` is resolved, any remaining Features that dec
 
 ### <a href="#option-resolution" name="option-resolution" class="anchor"> Option Resolution </a>
 
-A Feature's 'options' - specified as the value of a single Feature key/value pair in the user's `devcontainer.json` - are passed to the Feature as environment variables.
+A Feature's `options` - specified as the value of a single Feature key/value pair in the user's `devcontainer.json` - are passed to the Feature as environment variables.
 
 A supporting tool will parse the `options` object provided by the user.  If a value is provided for a Feature, it will be emitted to a file named `devcontainer-features.env` following the format `<OPTION_NAME>=<value>`.  
 
-To ensure a option that is valid as an environment variable, the follow substitutions are performed.
+To ensure a option that is valid as an environment variable, the follow substitutions are performed:
 
 ```javascript
 (str: string) => str

_implementors/reference.md

@@ -6,18 +6,18 @@ author: Microsoft
 index: 2
 ---
 
-The reference implementation for the specification is available through a [development container CLI](https://github.com/devcontainers/cli). This CLI can take a devcontainer.json and create and configure a dev container from it.
+The reference implementation for the specification is available through a [development container CLI](https://github.com/devcontainers/cli). This CLI can take a `devcontainer.json` and create and configure a dev container from it.
 
-## <a href="#what-is-CLI" name="what-is-CLI" class="anchor"> What is the dev container CLI? </a>
-When tools like VS Code and Codespaces detect a devcontainer.json file in a user's project, they use a CLI to configure a dev container. We've now opened up this CLI as a reference implementation so that individual users and other tools can read in devcontainer.json metadata and create dev containers from it.
+## <a href="#what-is-CLI" name="what-is-CLI" class="anchor"> What is the Dev Container CLI? </a>
+When tools like VS Code and Codespaces detect a `devcontainer.json` file in a user's project, they use a CLI to configure a dev container. We've now opened up this CLI as a reference implementation so that individual users and other tools can read in `devcontainer.json` metadata and create dev containers from it.
 
 This CLI can either be used directly or integrated into product experiences, similar to how it's integrated with Dev Containers and Codespaces today. It currently supports both a simple single container option and integrates with [Docker Compose](https://docs.docker.com/compose/) for multi-container scenarios.
 
-The CLI is available for review in a new [devcontainers/cli](https://github.com/devcontainers/cli) repository, and you can read more about its development in [this issue](https://github.com/devcontainers/spec/issues/9) in the spec repo.
+The CLI is available in the [devcontainers/cli](https://github.com/devcontainers/cli) repository.
 
 ## <a href="#try-it" name="try-it" class="anchor"> How can I try it? </a>
 
-We'd love for you to try out the dev container CLI and let us know what you think. You can quickly try it out in just a few simple steps, either by installing its npm package or building the CLI repo from sources.
+We'd love for you to try out the Dev Container CLI and let us know what you think. You can quickly try it out in just a few simple steps, either by installing its npm package or building the CLI repo from sources.
 
 You may learn more about building from sources in the [CLI repo's README](https://github.com/devcontainers/cli#try-it-out). On this page, we'll focus on using the npm package.
 
@@ -97,7 +97,7 @@ Hello, VS Code Remote - Containers!
 {"outcome":"success"}
 ```
 
-Congrats, you've just run the dev container CLI and seen it in action!
+Congrats, you've just run the Dev Container CLI and seen it in action!
 
 These steps are also provided in the CLI repo's [README](https://github.com/devcontainers/cli/blob/main/README.md). You may also review frequently asked questions [here](https://github.com/devcontainers/spec/issues/31).
 
@@ -110,13 +110,15 @@ We recommend using the [Dev Container CLI](#npm-install) (or other spec supporti
 devcontainer build --workspace-folder . --push true --image-name <my_image_name>:<optional_image_version>
 ```
 
+You can also check out our [in-depth guide on prebuilds](/_posts/2023-08-22-prebuild.md).
+
 #### <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/). This makes the image self-contained since these settings are automatically picked up when the image is referenced - whether directly, in a `FROM` in a referenced Dockerfile, or in a Docker Compose file. This helps prevent your Dev Container config and image contents from getting out of sync, and allows you to push updates of the same configuration to multiple repositories through a simple image reference.
 
-This metadata label is **automatically added** when you pre-build using the [Dev Container CLI](#npm-install) (or other spec supporting utilities like the [GitHub Action](https://github.com/marketplace/actions/devcontainers-ci) or [Azure DevOps task](https://marketplace.visualstudio.com/items?itemName=devcontainers.ci)) and includes settings from devcontainer.json and any referenced Dev Container Features.
+This metadata label is **automatically added** when you pre-build using the [Dev Container CLI](#npm-install) (or other spec supporting utilities like the [GitHub Action](https://github.com/marketplace/actions/devcontainers-ci) or [Azure DevOps task](https://marketplace.visualstudio.com/items?itemName=devcontainers.ci)) and includes settings from `devcontainer.json` and any referenced Dev Container Features.
 
-This allows you to have a separate **more complex** devcontainer.json you use to pre-build your image, and then a dramatically **simplified one** in one or more repositories. The contents of the image will be merged with this simplified devcontainer.json content at the time you create the container (see the [the spec](/implementors/spec/#merge-logic) for info on merge logic). But at its simplest, you can just reference the image directly in devcontainer.json for the settings to take effect:
+This allows you to have a separate **more complex** `devcontainer.json` you use to pre-build your image, and then a dramatically **simplified one** in one or more repositories. The contents of the image will be merged with this simplified devcontainer.json content at the time you create the container (see the [the spec](/implementors/spec/#merge-logic) for info on merge logic). But at its simplest, you can just reference the image directly in `devcontainer.json` for the settings to take effect:
 
 ```json
 {
@@ -138,7 +140,7 @@ See the [Dev Container metadata reference](../json_reference) for information on
 
 ### <a href="#domainnames" name="domainnames" class="anchor"> Domain Names </a> 
 
-If you are behind a firewall that needs to allow specific domains used by the dev container CLI, here's the list of hostnames you should allow communication to go through:
+If you are behind a firewall that needs to allow specific domains used by the Dev Container CLI, here's the list of hostnames you should allow communication to go through:
 
 * `containers.dev` - The [homepage](https://containers.dev/) for everything about dev containers. It includes all official and community-supported [Features](https://containers.dev/features) and [Templates](https://containers.dev/templates).
 * `ghcr.io`, `*.azurecr.io`, `mcr.microsoft.com` - [OCI registries](https://containers.dev/implementors/features-distribution/#oci-registry) like [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry), [Azure Container Registry](azure.microsoft.com/en-us/products/container-registry), and [Microsoft Container Registry](https://mcr.microsoft.com/en-us/catalog?search=dev%20container) serves as the primary distribution mechanism for dev container resources.