Merge branch 'main' into 5765-private-profile

.devcontainer/test-custom-devcontainer/devcontainer.json

@@ -11,6 +11,12 @@
 		"sissel.shopify-liquid"
 	],
 
+	"hostRequirements": {
+	   "cpus": 8,
+	   "memory": "8gb",
+	   "storage": "32gb" 
+	},
+		
 	// Use 'forwardPorts' to make a list of ports inside the container available locally.
 	"forwardPorts": [5000],
 

.github/actions-scripts/enterprise-server-issue-templates/release-issue.md

@@ -18,11 +18,8 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng
     ```
     script/update-enterprise-dates.js
     ```
-- [ ] Create REST files based on previous version. For example `script/enterprise-server-releases/create-rest-files.js --oldVersion enterprise-server@3.2 --newVersion enterprise-server@3.3`:
+- [ ] Create REST files based on previous version. Copy the latest GHES version of the dereferenced file from `lib/rest/static/dereferenced` to a new file in the same directory for the new GHES release. Ex, `cp lib/rest/static/dereferenced/ghes-3.4.deref.json lib/rest/static/dereferenced/ghes-3.5.deref.json`. Then run `script/rest/updated-files.js --decorate-only` and check in the resulting files.
 
-  ```
-  script/enterprise-server-releases/create-rest-files.js --oldVersion <PLAN@RELEASE> --newVersion <PLAN@RELEASE>
-  ```
 - [ ] Create GraphQL files based on previous version:
 
   ```

.github/workflows/azure-preview-env-deploy.yml

@@ -59,6 +59,7 @@ jobs:
       IS_INTERNAL_BUILD: ${{ github.repository == 'github/docs-internal' }}
       # This may also run in forked repositories, not just 'github/docs'
       IS_PUBLIC_BUILD: ${{ github.repository != 'github/docs-internal' }}
+      NONPROD_REGISTRY_USERNAME: ${{ fromJSON('["ghdocs", "ghdocsinternal"]')[github.repository == 'github/docs-internal'] }}
 
     steps:
       - name: 'Az CLI login'
@@ -70,7 +71,7 @@ jobs:
         uses: azure/docker-login@81744f9799e7eaa418697cb168452a2882ae844a
         with:
           login-server: ${{ secrets.NONPROD_REGISTRY_SERVER }}
-          username: ${{ secrets.NONPROD_REGISTRY_USERNAME }}
+          username: ${{ env.NONPROD_REGISTRY_USERNAME }}
           password: ${{ secrets.NONPROD_REGISTRY_PASSWORD }}
 
       - name: Set up Docker Buildx
@@ -205,7 +206,7 @@ jobs:
           parameters: appName="${{ env.APP_NAME }}"
             containerImage="${{ env.DOCKER_IMAGE }}"
             dockerRegistryUrl="${{ secrets.NONPROD_REGISTRY_SERVER }}"
-            dockerRegistryUsername="${{ secrets.NONPROD_REGISTRY_USERNAME }}"
+            dockerRegistryUsername="${{ env.NONPROD_REGISTRY_USERNAME }}"
             dockerRegistryPassword="${{ secrets.NONPROD_REGISTRY_PASSWORD }}"
           # this shows warnings in the github actions console, because the flag is passed through a validation run,
           # but it *is* functional during the actual execution

.github/workflows/check-broken-links-github-github.yml

@@ -51,6 +51,8 @@ jobs:
         run: npm ci
 
       - name: Run broken github/github link check
+        env:
+          WAF_TOKEN: ${{ secrets.WAF_TOKEN }}
         run: |
           script/check-github-github-links.js > broken_github_github_links.md
 

.github/workflows/codeql.yml

@@ -31,8 +31,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@ec3a7ce113134d7a93b817d10a8272cb61118579
-      - uses: github/codeql-action/init@1a927e9307bc11970b2c679922ebc4d03a5bd980
+      - uses: github/codeql-action/init@1ed1437484560351c5be56cf73a48a279d116b78
         with:
           languages: javascript # comma separated list of values from {go, python, javascript, java, cpp, csharp} (not YET ruby, sorry!)
-      - uses: github/codeql-action/analyze@1a927e9307bc11970b2c679922ebc4d03a5bd980
+      - uses: github/codeql-action/analyze@1ed1437484560351c5be56cf73a48a279d116b78
         continue-on-error: true

.github/workflows/enterprise-dates.yml

@@ -55,7 +55,7 @@ jobs:
 
       - name: Create pull request
         id: create-pull-request
-        uses: peter-evans/create-pull-request@f22a7da129c901513876a2380e2dae9f8e145330
+        uses: peter-evans/create-pull-request@bd72e1b7922d417764d27d30768117ad7da78a0e
         env:
           # Disable pre-commit hooks; they don't play nicely here
           HUSKY: '0'

.github/workflows/main-preview-docker-cache.yml

@@ -26,6 +26,7 @@ jobs:
     env:
       ENABLE_EARLY_ACCESS: ${{ github.repository == 'github/docs-internal' }}
       DOCKER_IMAGE_CACHE_REF: ${{ secrets.NONPROD_REGISTRY_SERVER }}/${{ github.repository }}:main-preview
+      NONPROD_REGISTRY_USERNAME: ${{ fromJSON('["ghdocs", "ghdocsinternal"]')[github.repository == 'github/docs-internal'] }}
 
     steps:
       - name: 'Az CLI login'
@@ -37,7 +38,7 @@ jobs:
         uses: azure/docker-login@81744f9799e7eaa418697cb168452a2882ae844a
         with:
           login-server: ${{ secrets.NONPROD_REGISTRY_SERVER }}
-          username: ${{ secrets.NONPROD_REGISTRY_USERNAME }}
+          username: ${{ env.NONPROD_REGISTRY_USERNAME }}
           password: ${{ secrets.NONPROD_REGISTRY_PASSWORD }}
 
       - name: Set up Docker Buildx

.github/workflows/needs-sme-stale-check.yaml

@@ -14,7 +14,7 @@ permissions:
 
 jobs:
   stale_needs-sme:
-    if: ${{ github.repository == 'github/docs'' }}
+    if: ${{ github.repository == 'github/docs' }}
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/needs-sme-workflow.yml

@@ -15,7 +15,7 @@ permissions:
   pull-requests: write
 
 jobs:
-  add-comment:
+  add-issue-comment:
     if: ${{ github.repository == 'github/docs' && (github.event.label.name == 'needs SME' && github.event_name == 'issues' || github.event_name == 'pull_request_target') }}
     runs-on: ubuntu-latest
     steps:
@@ -24,8 +24,13 @@ jobs:
           issue-number: ${{ github.event.issue.number }}
           body: |
             Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:
+
+  add-pr-comment:
+    if: ${{ github.repository == 'github/docs' && github.event.label.name == 'needs SME' }}
+    runs-on: ubuntu-latest
+    steps:
       - uses: peter-evans/create-or-update-comment@a35cf36e5301d70b76f316e867e7788a55a31dae
         with:
-          issue-number: ${{ github.event.pull_request_target.number }}
+          issue-number: ${{ github.event.pull_request.number }}
           body: |
             Thanks for opening a pull request! We've triaged this issue for technical review by a subject matter expert :eyes:

.github/workflows/remove-unused-assets.yml

@@ -44,7 +44,7 @@ jobs:
       - name: Remove script results file
         run: rm ./results.md
       - name: Create pull request
-        uses: peter-evans/create-pull-request@f22a7da129c901513876a2380e2dae9f8e145330
+        uses: peter-evans/create-pull-request@bd72e1b7922d417764d27d30768117ad7da78a0e
         env:
           # Disable pre-commit hooks; they don't play nicely here
           HUSKY: '0'

.github/workflows/repo-sync.yml

@@ -120,7 +120,7 @@ jobs:
           github_token: ${{ secrets.OCTOMERGER_PAT_WITH_REPO_AND_WORKFLOW_SCOPE }}
 
       - name: Create pull request
-        uses: repo-sync/pull-request@65194d8015be7624d231796ddee1cd52a5023cb3
+        uses: repo-sync/pull-request@9152b1c4aeeab247ba2ce12c5d7e693d287bf1b9
         env:
           GITHUB_TOKEN: ${{ secrets.OCTOMERGER_PAT_WITH_REPO_AND_WORKFLOW_SCOPE }}
         with:

.github/workflows/triage-unallowed-internal-changes.yml

@@ -74,7 +74,7 @@ jobs:
         run: $GITHUB_WORKSPACE/.github/actions-scripts/enterprise-search-label.js
 
       - name: Fail if unallowed changes were made outside of the Search Sync label added
-        if: false == steps.labelExists.outputs.versionToSync && false == contains(github.event.pull_request.labels.*.name, 'deprecate-lunr-index')
+        if: false == steps.labelExists.outputs.versionToSync && false == contains(github.event.pull_request.labels.*.name, 'deprecate-lunr-index') && !contains(github.event.pull_request.labels.*.name, 'skip-index-check')
         run: |
           echo "Search indices are updated automatically every 4 hours. Please revert any changes you have made to the search indexes before you merge this PR. If you need to update the search indices directly after you merge your PR, you can manually run the search sync workflow: Sync search indexes. See the docs/contributing/search.md for more details. If you have any other questions, please ping us in #docs-engineering."
           exit 1

.github/workflows/update-graphql-files.yml

@@ -48,7 +48,7 @@ jobs:
           script/graphql/update-files.js
       - name: Create pull request
         id: create-pull-request
-        uses: peter-evans/create-pull-request@f22a7da129c901513876a2380e2dae9f8e145330
+        uses: peter-evans/create-pull-request@bd72e1b7922d417764d27d30768117ad7da78a0e
         env:
           # Disable pre-commit hooks; they don't play nicely here
           HUSKY: '0'

.gitignore

@@ -1,6 +1,7 @@
 .search-cache
 .DS_Store
 .env
+.vscode/settings.json
 /node_modules/
 npm-debug.log
 coverage/

components/Search.tsx

@@ -218,7 +218,11 @@ export function Search({
       <div className="position-relative z-2">
         <form role="search" className="width-full d-flex" noValidate onSubmit={onFormSubmit}>
           <label className="text-normal width-full">
-            <span className="visually-hidden">{t`placeholder`}</span>
+            <span
+              className="visually-hidden"
+              aria-label={t`label`}
+              aria-describedby={t`description`}
+            >{t`placeholder`}</span>
             <input
               data-testid="site-search-input"
               ref={inputRef}
@@ -237,13 +241,15 @@ export function Search({
               )}
               type="search"
               placeholder={t`placeholder`}
-              autoComplete="off"
+              autoComplete={localQuery ? 'on' : 'off'}
               autoCorrect="off"
               autoCapitalize="off"
               spellCheck="false"
               maxLength={512}
               onChange={onSearch}
               value={localQuery}
+              aria-label={t`label`}
+              aria-describedby={t`description`}
             />
           </label>
           <button className="d-none" type="submit" title="Submit the search query." hidden />
@@ -393,7 +399,12 @@ function ShowSearchResults({
             You're searching the <strong>{searchVersion}</strong> version.
           </p>
           <div className="float-right mr-4">
-            <p className={cx(styles.selectWording, 'f6 d-inline-block')}>Select version:</p>
+            <p
+              aria-describedby={`You're searching the ${searchVersion} version`}
+              className={cx(styles.selectWording, 'f6 d-inline-block')}
+            >
+              Select version:
+            </p>
             <DropdownMenu
               placeholder={searchVersion}
               items={searchVersions}

components/landing/CodeExamples.tsx

@@ -22,7 +22,8 @@ export const CodeExamples = () => {
   const isSearching = !!search
   let searchResults: typeof productCodeExamples = []
   if (isSearching) {
-    const matchReg = new RegExp(search, 'i')
+    // The following replace method escapes special characters in regular expression creation.
+    const matchReg = new RegExp(search.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&'), 'i')
     searchResults = productCodeExamples.filter((example) => {
       const searchableStr = `${example.tags.join(' ')} ${example.title} ${example.description}`
       return matchReg.test(searchableStr)

components/landing/ProductArticlesList.tsx

@@ -57,7 +57,7 @@ const ProductTreeNodeList = ({ treeNode }: { treeNode: ProductTreeNode }) => {
                 }}
               >
                 <Link className="d-block width-full" href={childNode.href}>
-                  {childNode.page.title}
+                  {childNode.renderedFullTitle}
                   {childNode.page.documentType === 'mapTopic' ? (
                     <small className="color-fg-muted d-inline-block">
                       &nbsp;&bull; {childNode.childPages.length} articles

components/lib/get-rest-code-samples.ts

@@ -0,0 +1,142 @@
+import { parseTemplate } from 'url-template'
+import { stringify } from 'javascript-stringify'
+
+import type { CodeSample, Operation } from '../rest/types'
+
+/*
+  Generates a curl example
+
+  For example: 
+  curl \
+  -X POST \
+  -H "Accept: application/vnd.github.v3+json" \
+  https://{hostname}/api/v3/repos/OWNER/REPO/deployments \
+  -d '{"ref":"topic-branch","payload":"{ \"deploy\": \"migrate\" }","description":"Deploy request from hubot"}'
+*/
+export function getShellExample(operation: Operation, codeSample: CodeSample) {
+  // This allows us to display custom media types like application/sarif+json
+  const defaultAcceptHeader = codeSample?.response?.contentType?.includes('+json')
+    ? codeSample.response.contentType
+    : 'application/vnd.github.v3+json'
+
+  const requestPath = codeSample?.request?.parameters
+    ? parseTemplate(operation.requestPath).expand(codeSample.request.parameters)
+    : operation.requestPath
+
+  let requestBodyParams = ''
+  if (codeSample?.request?.bodyParameters) {
+    requestBodyParams = `-d '${JSON.stringify(codeSample.request.bodyParameters)}'`
+
+    // If the content type is application/x-www-form-urlencoded the format of
+    // the shell example is --data-urlencode param1=value1 --data-urlencode param2=value2
+    // For example, this operation:
+    // https://docs.github.com/en/enterprise/rest/reference/enterprise-admin#enable-or-disable-maintenance-mode
+    if (codeSample.request.contentType === 'application/x-www-form-urlencoded') {
+      requestBodyParams = ''
+      const paramNames = Object.keys(codeSample.request.bodyParameters)
+      paramNames.forEach((elem) => {
+        requestBodyParams = `${requestBodyParams} --data-urlencode ${elem}=${codeSample.request.bodyParameters[elem]}`
+      })
+    }
+  }
+
+  const args = [
+    operation.verb !== 'get' && `-X ${operation.verb.toUpperCase()}`,
+    `-H "Accept: ${defaultAcceptHeader}"`,
+    `${operation.serverUrl}${requestPath}`,
+    requestBodyParams,
+  ].filter(Boolean)
+  return `curl \\\n  ${args.join(' \\\n  ')}`
+}
+
+/*
+  Generates a GitHub CLI example
+
+  For example:
+   gh api \
+    -X POST \
+    -H "Accept: application/vnd.github.v3+json" \
+    /repos/OWNER/REPO/deployments \
+    -fref,topic-branch=0,payload,{ "deploy": "migrate" }=1,description,Deploy request from hubot=2
+*/
+export function getGHExample(operation: Operation, codeSample: CodeSample) {
+  const defaultAcceptHeader = codeSample?.response?.contentType?.includes('+json')
+    ? codeSample.response.contentType
+    : 'application/vnd.github.v3+json'
+  const hostname = operation.serverUrl !== 'https://api.github.com' ? '--hostname HOSTNAME' : ''
+
+  const requestPath = codeSample?.request?.parameters
+    ? parseTemplate(operation.requestPath).expand(codeSample.request.parameters)
+    : operation.requestPath
+
+  let requestBodyParams = ''
+  if (codeSample?.request?.bodyParameters) {
+    const bodyParamValues = Object.values(codeSample.request.bodyParameters)
+    // GitHub CLI does not support sending Objects and arrays using the -F or
+    // -f flags. That support may be added in the future. It is possible to
+    // use gh api --input to take a JSON object from standard input
+    // constructed by jq and piped to gh api. However, we'll hold off on adding
+    // that complexity for now.
+    if (bodyParamValues.some((elem) => typeof elem === 'object')) {
+      return undefined
+    }
+    requestBodyParams = Object.keys(codeSample.request.bodyParameters)
+      .map((key) => {
+        if (typeof codeSample.request.bodyParameters[key] === 'string') {
+          return `-f ${key}='${codeSample.request.bodyParameters[key]}'`
+        } else {
+          return `-F ${key}=${codeSample.request.bodyParameters[key]}`
+        }
+      })
+      .join(' ')
+  }
+  const args = [
+    operation.verb !== 'get' && `--method ${operation.verb.toUpperCase()}`,
+    `-H "Accept: ${defaultAcceptHeader}"`,
+    hostname,
+    requestPath,
+    requestBodyParams,
+  ].filter(Boolean)
+  return `gh api \\\n  ${args.join(' \\\n  ')}`
+}
+
+/*
+  Generates an octokit.js example
+
+  For example:
+  await octokit.request('POST /repos/{owner}/{repo}/deployments'{
+    "owner": "OWNER",
+    "repo": "REPO",
+    "ref": "topic-branch",
+    "payload": "{ \"deploy\": \"migrate\" }",
+    "description": "Deploy request from hubot"
+  })
+
+*/
+export function getJSExample(operation: Operation, codeSample: CodeSample) {
+  const parameters = codeSample.request
+    ? { ...codeSample.request.parameters, ...codeSample.request.bodyParameters }
+    : {}
+
+  let queryParameters = ''
+
+  // Add query parameters to the request path for POST and PUT operations in
+  // URL template format e.g. 'POST /repos/{owner}/{repo}/releases/{release_id}/assets{?name,label}'
+  if (operation.verb === 'post' || operation.verb === 'put') {
+    const queryParms = operation.parameters
+      .filter((param) => {
+        return param.in === 'query'
+      })
+      .map((param) => {
+        return param.name
+      })
+
+    if (queryParms.length > 0) {
+      queryParameters = `{?${queryParms.join(',')}}`
+    }
+  }
+
+  return `await octokit.request('${operation.verb.toUpperCase()} ${
+    operation.requestPath
+  }${queryParameters}', ${stringify(parameters, null, 2)})`
+}

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/dotnet.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your project',
-  shortTitle: 'C# Codespaces',
+  title: 'Add a dev container configuration to your repository',
+  shortTitle: 'C# codespaces',
   topics: ['Codespaces', 'Developer', 'Organization'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-dotnet-project-for-codespaces',
   codeLanguageId: 'dotnet',
   intro: dedent`
-  This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **C# (.NET)** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **C# (.NET)** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
  `,
   prerequisites: dedent`
     - You should have an existing C# (.NET) project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/2percentsilk/python-quickstart.
-    - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+    - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,17 +27,19 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-            If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+            If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including .NET. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
         You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
-
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace.
+        
+        On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -43,11 +47,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-       The default codespaces container comes with the latest .NET version and common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces comes with the latest .NET version and common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           ![Codespaces: Add Development Container Configuration Files... in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -70,7 +74,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-      Adding the C# (.NET) dev container template adds a \`.devcontainer\` folder to the root of your project's repository with the following files:
+      Adding the C# (.NET) dev container template adds a \`.devcontainer\` directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -96,7 +100,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfil\`e** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This file only contains one build argument, which is the .NET Core version that we want to use.
       `,
@@ -140,7 +144,7 @@ const article: PlaygroundArticleT = {
         highlight: 29,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like \`dotnet restore\`, you can do that here.
+      **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, like \`dotnet restore\`, after your codespace is created.
       `,
     },
     {
@@ -160,7 +164,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -171,7 +175,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
         1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
 
@@ -182,7 +186,7 @@ const article: PlaygroundArticleT = {
            \`\`\`json{:copy}
            "extensions": [
                "ms-dotnettools.csharp",
-               "streetsidesoftware.code-spell-checker",
+               "streetsidesoftware.code-spell-checker"
              ],
            \`\`\`
          

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/java.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your project',
-  shortTitle: 'Add a dev container to your project',
+  title: 'Add a dev container configuration to your repository',
+  shortTitle: 'Java codespaces',
   topics: ['Codespaces', 'Developer', 'Organization', 'Java'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-java-project-for-codespaces',
   codeLanguageId: 'java',
   intro: dedent`
-  This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **Java** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **Java** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
   `,
   prerequisites: dedent`
   - You should have an existing Java project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/microsoft/vscode-remote-try-java
-  - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+  - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,15 +27,17 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-           If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+           If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Java, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
         
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace. 
+        
+        On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -41,11 +45,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-        The default codespaces container comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces comes with the latest Java version, package managers (Maven, Gradle), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           !["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -65,7 +69,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-        Adding the Java dev container template adds a .devcontainer folder to the root of your project's repository with the following files:
+        Adding the Java dev container template adds a .devcontainer directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -91,7 +95,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This file only contains one build argument, which is the Java version that is passed into the Dockerfile.
       `,
@@ -135,7 +139,7 @@ const article: PlaygroundArticleT = {
         highlight: 34,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
+        **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.
       `,
     },
     {
@@ -155,7 +159,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -166,7 +170,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
         1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
 
@@ -179,7 +183,7 @@ const article: PlaygroundArticleT = {
            "forwardPorts": [4000],
            \`\`\`
          
-           For more information on \`devcontainer.json\` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) on the Visual Studio Code docs.
+           For more information about \`devcontainer.json\` properties, see the Visual Studio Code documentation: "[devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference)."
 
         4. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**. 
           ![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/nodejs.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your project',
-  shortTitle: 'Node.js Codespaces',
+  title: 'Add a dev container configuration to your repository',
+  shortTitle: 'Node.js codespaces',
   topics: ['Codespaces', 'Developer', 'Organization', 'Node', 'JavaScript'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-nodejs-project-for-codespaces',
   codeLanguageId: 'nodejs',
   intro: dedent`
-  This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **JavaScript**, **Node.js**, or **TypeScript** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **Node.js** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
   `,
   prerequisites: dedent`
     - You should have an existing JavaScript, Node.js, or TypeScript project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/microsoft/vscode-remote-try-node
-    - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+    - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,17 +27,17 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-           If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+           If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Node.js, JavaScript, Typescript, nvm, npm, and yarn. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
         You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
 
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch, Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace. On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -43,11 +45,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-        The default codespaces container will support running Node.js projects like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node) out of the box. By setting up a custom container you can customize the tools and scripts that run as part of codespace creation and ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces supports running Node.js projects like [vscode-remote-try-node](https://github.com/microsoft/vscode-remote-try-node) out of the box. However, we recommend that you configure your own dev container to include all of the tools and scripts your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           !["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -67,7 +69,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-        Adding the Node.js dev container template adds a \`.devcontainer\` folder to the root of your project's repository with the following files:
+        Adding the Node.js dev container template adds a \`.devcontainer\` directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -93,7 +95,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This file only contains one build argument, which is the node variant we want to use that is passed into the Dockerfile.
       `,
@@ -137,7 +139,7 @@ const article: PlaygroundArticleT = {
         highlight: 25,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, you can do that here.
+        **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, after your codespace is created.
       `,
     },
     {
@@ -157,7 +159,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -168,7 +170,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install npm when your codespace launches and make a list of ports inside the container available locally.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install npm when your codespace launches and make a list of ports inside the container available locally.
 
         1. In the Explorer, select the \`devcontainer.json\` file from the tree to open it. You might have to expand the \`.devcontainer\` folder to see it.
           ![devcontainer.json file in the Explorer](/assets/images/help/codespaces/devcontainers-options.png)
@@ -178,7 +180,7 @@ const article: PlaygroundArticleT = {
             "postCreateCommand": "npm install",
             "forwardPorts": [4000],
             \`\`\`
-            For more information on \`devcontainer.json\` properties, see the [devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference) in the Visual Studio Code docs.
+            For more information about \`devcontainer.json\` properties, see the Visual Studio Code documentation: "[devcontainer.json reference](https://code.visualstudio.com/docs/remote/devcontainerjson-reference)."
 
         1. Access the command palette (\`Shift + Command + P\`/ \`Ctrl + Shift + P\`), then start typing "rebuild". Select **Codespaces: Rebuild Container**. 
             ![Rebuild container option](/assets/images/help/codespaces/codespaces-rebuild.png)

components/playground/content/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces/python.tsx

@@ -2,8 +2,8 @@ import dedent from 'ts-dedent'
 import { PlaygroundArticleT } from 'components/playground/types'
 
 const article: PlaygroundArticleT = {
-  title: 'Add a dev container to your repository',
-  shortTitle: 'Python Codespaces',
+  title: 'Add a dev container configuration to your repository',
+  shortTitle: 'Python codespaces',
   topics: ['Codespaces', 'Developer', 'Organization', 'Python'],
   type: 'tutorial',
   slug: '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-project-for-codespaces',
@@ -11,11 +11,13 @@ const article: PlaygroundArticleT = {
     '/codespaces/setting-up-your-project-for-codespaces/setting-up-your-python-project-for-codespaces',
   codeLanguageId: 'py',
   intro: dedent`
-    This guide shows you how to add a [dev container](/codespaces/setting-up-your-project-for-codespaces/configuring-codespaces-for-your-project) to define the Codespaces configuration for your **Python** project. For other project languages, click the language button to the right.
+  This guide shows you how to add a dev container configuration to your repository to define the GitHub Codespaces development environment for your **Python** codebase. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers)." 
+  
+  If you want to add a dev container configuration for another programming language, click the language button to the right.
   `,
   prerequisites: dedent`
     - You should have an existing Python project in a repository on GitHub.com. If you don't have a project, you can try this tutorial with the following example: https://github.com/2percentsilk/python-quickstart.
-    - Codespaces must be enabled for your organization. For more information, see "[Enabling Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
+    - GitHub Codespaces must be enabled for your organization. For more information, see "[Enabling GitHub Codespaces for your organization](/codespaces/managing-codespaces-for-your-organization/enabling-codespaces-for-your-organization)."
   `,
   contentBlocks: [
     {
@@ -25,17 +27,19 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 1: Open your project in a codespace',
       content: dedent`
-        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **New codespace**.
+        1. Under the repository name, use the **Code** drop-down menu, and in the **Codespaces** tab, click **Create codespace on BRANCH**.
 
             ![New codespace button](/assets/images/help/codespaces/new-codespace-button.png)
 
-            If you don’t see this option, Codespaces isn't available for your project. See [Access to Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
+            If you don’t see this option, GitHub Codespaces isn't available for your project. See [Access to GitHub Codespaces](/codespaces/developing-in-codespaces/creating-a-codespace#access-to-codespaces) for more information.
 
         When you create a codespace, your project is created on a remote VM that is dedicated to you. By default, the container for your codespace has many languages and runtimes including Python, pip, and Miniconda. It also includes a common set of tools like git, wget, rsync, openssh, and nano.
 
         You can customize your codespace by adjusting the amount of vCPUs and RAM, [adding dotfiles to personalize your environment](/codespaces/setting-up-your-codespace/personalizing-codespaces-for-your-account), or by modifying the tools and scripts installed.
 
-        Codespaces uses a file called \`devcontainer.json\` to store configurations. On launch Codespaces uses the file to install any tools, dependencies, or other set up that might be needed for the project. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
+        GitHub Codespaces uses a file called \`devcontainer.json\` to configure the development container that you use when you work in a codespace. Each repository can contain one or more  \`devcontainer.json\` files, to give you exactly the development environment you need to work on your code in a codespace. 
+        
+        On launch, GitHub Codespaces uses a \`devcontainer.json\` file, and any dependent files that make up the dev container configuration, to install tools and runtimes, and perform other setup tasks that the project requires. For more information, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)."
       `,
     },
     {
@@ -43,11 +47,11 @@ const article: PlaygroundArticleT = {
         id: '0',
       },
       type: 'default',
-      title: 'Step 2: Add a dev container to your codespace from a template',
+      title: 'Step 2: Add a dev container configuration to your repository from a template',
       content: dedent`
-        The default codespaces container comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you set up a custom container to define the tools and scripts that your project needs. This will ensure a fully reproducible environment for all Codespaces users in your repository.
+        The default development container, or "dev container," for GitHub Codespaces comes with the latest Python version, package managers (pip, Miniconda), and other common tools preinstalled. However, we recommend that you configure your own dev container to include all of the tools and scripts that your project needs. This will ensure a fully reproducible environment for all GitHub Codespaces users in your repository.
 
-        To set up your project with a custom container, you will need to use a \`devcontainer.json\` file to define the environment. In Codespaces you can add this either from a template or you can create your own. For more information on dev containers, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
+        To set up your repository to use a custom dev container, you will need to create one or more \`devcontainer.json\` files. You can add these either from a template, in Visual Studio Code, or you can write your own. For more information on dev container configurations, see "[Introduction to dev containers](/codespaces/setting-up-your-codespace/configuring-codespaces-for-your-project)".
 
         1. Access the Command Palette (\`Shift + Command + P\` / \`Ctrl + Shift + P\`), then start typing "dev container". Select **Codespaces: Add Development Container Configuration Files...**.
           !["Codespaces: Add Development Container Configuration Files..." in the command palette](/assets/images/help/codespaces/add-prebuilt-container-command.png)
@@ -69,7 +73,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Anatomy of your dev container',
       content: dedent`
-        Adding the Python dev container template adds a .devcontainer folder to the root of your project's repository with the following files:
+        Adding the Python dev container template adds a .devcontainer directory to the root of your project's repository with the following files:
 
         - \`devcontainer.json\`
         - Dockerfile
@@ -95,7 +99,7 @@ const article: PlaygroundArticleT = {
       },
       content: dedent`
         **\`build\`** - The build properties.
-          - **\`dockerfile\`** - In the build object, dockerfile is a reference to the Dockerfile that was also added from the template.
+          - **\`dockerfile\`** - In the \`build\` object, \`dockerfile\` contains the path to the Dockerfile that was also added from the template.
           - **\`args\`**
             - **\`VARIANT\`**: This is the node variant we want to use that is passed into the Dockerfile.
       `,
@@ -139,7 +143,7 @@ const article: PlaygroundArticleT = {
         highlight: 41,
       },
       content: dedent`
-        **\`postCreateCommand\`** - If you want to run anything after you land in your codespace that’s not defined in the Dockerfile, like pip3 install -r requirements, you can do that here.
+        **\`postCreateCommand\`** - Use this to run commands that aren't defined in the Dockerfile, like \`pip3 install -r requirements\`, after your codespace is created.
       `,
     },
     {
@@ -159,7 +163,7 @@ const article: PlaygroundArticleT = {
       type: 'sub-section',
       title: 'Dockerfile',
       content: dedent`
-        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our Dockerfile.
+        You can use the Dockerfile to add additional container layers to specify OS packages, node versions, or global packages we want included in our container.
       `,
     },
     {
@@ -170,7 +174,7 @@ const article: PlaygroundArticleT = {
       type: 'default',
       title: 'Step 3: Modify your devcontainer.json file',
       content: dedent`
-        With your dev container added and a basic understanding of what everything does, you can now make changes to configure it for your environment. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
+        With your dev container configuration added and a basic understanding of what everything does, you can now make changes to customize your environment further. In this example, you'll add properties to install extensions and your project dependencies when your codespace launches.
 
         1. In the Explorer, expand the \`.devcontainer\` folder and select the \`devcontainer.json\` file from the tree to open it.
 
@@ -182,7 +186,7 @@ const article: PlaygroundArticleT = {
            "extensions": [
                "ms-python.python",
                "cstrap.flask-snippets",
-               "streetsidesoftware.code-spell-checker",
+               "streetsidesoftware.code-spell-checker"
              ],
            \`\`\`
 
@@ -271,7 +275,7 @@ const article: PlaygroundArticleT = {
       
         // Add the IDs of extensions you want installed when the container is created.
         "extensions": [
-          "ms-python.python",
+          "ms-python.python"
         ],
       
         // Use 'forwardPorts' to make a list of ports inside the container available locally.

components/rest/CodeBlock.tsx

@@ -1,15 +1,13 @@
 import cx from 'classnames'
 import { CheckIcon, CopyIcon } from '@primer/octicons-react'
 import { Tooltip } from '@primer/react'
-
 import useClipboard from 'components/hooks/useClipboard'
-
 import styles from './CodeBlock.module.scss'
+import type { ReactNode } from 'react'
 
 type Props = {
   verb?: string
-  // Only Code samples should have a copy icon - if there's a headingLang it's a code sample
-  headingLang?: string
+  headingLang?: ReactNode | string
   codeBlock: string
   highlight?: string
 }
@@ -20,20 +18,12 @@ export function CodeBlock({ verb, headingLang, codeBlock, highlight }: Props) {
   })
 
   return (
-    <div className={headingLang && 'code-extra'}>
+    <div className={headingLang ? 'code-extra' : undefined}>
+      {/* Only Code samples should have a copy icon
+          If there's a headingLang it's a code sample */}
       {headingLang && (
         <header className="d-flex flex-justify-between flex-items-center p-2 text-small rounded-top-1 border">
-          {headingLang === 'JavaScript' ? (
-            <span>
-              {headingLang} (
-              <a className="text-underline" href="https://github.com/octokit/core.js#readme">
-                @octokit/core.js
-              </a>
-              )
-            </span>
-          ) : (
-            `${headingLang}`
-          )}
+          {headingLang}
           <Tooltip direction="w" aria-label={isCopied ? 'Copied!' : 'Copy to clipboard'}>
             <button className="js-btn-copy btn-octicon" onClick={() => setCopied()}>
               {isCopied ? <CheckIcon /> : <CopyIcon />}
@@ -44,10 +34,13 @@ export function CodeBlock({ verb, headingLang, codeBlock, highlight }: Props) {
       <pre className={cx(styles.codeBlock, 'rounded-1 border')} data-highlight={highlight}>
         <code>
           {verb && (
-            <span className="color-bg-accent-emphasis color-fg-on-emphasis rounded-1 text-uppercase p-1">
-              {verb}
-            </span>
-          )}{' '}
+            <>
+              <span className="color-bg-accent-emphasis color-fg-on-emphasis rounded-1 text-uppercase p-1">
+                {verb}
+              </span>
+              <> </>
+            </>
+          )}
           {codeBlock}
         </code>
       </pre>

components/rest/PreviewsRow.tsx

@@ -1,14 +1,12 @@
-import { xGitHub } from './types'
 import { useTranslation } from 'components/hooks/useTranslation'
 
 type Props = {
   slug: string
-  xGitHub: xGitHub
+  numPreviews: number
 }
 
-export function PreviewsRow({ slug, xGitHub }: Props) {
+export function PreviewsRow({ slug, numPreviews }: Props) {
   const { t } = useTranslation('products')
-  const hasPreviews = xGitHub.previews && xGitHub.previews.length > 0
 
   return (
     <tr>
@@ -21,9 +19,9 @@ export function PreviewsRow({ slug, xGitHub }: Props) {
         <p className="m-0">
           Setting to
           <code>application/vnd.github.v3+json</code> is recommended.
-          {hasPreviews && (
+          {numPreviews > 0 && (
             <a href={`#${slug}-preview-notices`} className="d-inline">
-              {xGitHub.previews.length > 1
+              {numPreviews > 1
                 ? ` ${t('rest.reference.see_preview_notices')}`
                 : ` ${t('rest.reference.see_preview_notice')}`}
             </a>

components/rest/RestCodeSamples.tsx

@@ -1,35 +1,92 @@
-import type { xCodeSample } from './types'
+import type { Operation } from './types'
 import { useTranslation } from 'components/hooks/useTranslation'
 import { CodeBlock } from './CodeBlock'
-import { Fragment } from 'react'
+import { getShellExample, getGHExample, getJSExample } from '../lib/get-rest-code-samples'
 
 type Props = {
   slug: string
-  xCodeSamples: Array<xCodeSample>
+  operation: Operation
 }
 
-export function RestCodeSamples({ slug, xCodeSamples }: Props) {
+export function RestCodeSamples({ operation, slug }: Props) {
   const { t } = useTranslation('products')
 
+  const JAVASCRIPT_HEADING = (
+    <span>
+      JavaScript{' '}
+      <a className="text-underline" href="https://github.com/octokit/core.js#readme">
+        @octokit/core.js
+      </a>
+    </span>
+  )
+
+  const GH_CLI_HEADING = (
+    <span>
+      GitHub CLI{' '}
+      <a className="text-underline" href="https://cli.github.com/manual/gh_api">
+        gh api
+      </a>
+    </span>
+  )
+
+  // Format the example properties into different language examples
+  const languageExamples = operation.codeExamples.map((sample) => {
+    const languageExamples = {
+      curl: getShellExample(operation, sample),
+      javascript: getJSExample(operation, sample),
+      ghcli: getGHExample(operation, sample),
+    }
+    return Object.assign({}, sample, languageExamples)
+  })
+
   return (
-    <Fragment key={xCodeSamples + slug}>
+    <>
       <h4 id={`${slug}--code-samples`}>
         <a href={`#${slug}--code-samples`}>{`${t('rest.reference.code_samples')}`}</a>
       </h4>
-      {xCodeSamples.map((sample, index) => {
-        const sampleElements: JSX.Element[] = []
-        if (sample.lang !== 'Ruby') {
-          sampleElements.push(
-            <CodeBlock
-              key={sample.lang + index}
-              headingLang={sample.lang}
-              codeBlock={sample.source}
-              highlight={sample.lang === 'JavaScript' ? 'javascript' : 'curl'}
-            ></CodeBlock>
-          )
-        }
-        return sampleElements
-      })}
-    </Fragment>
+      {languageExamples.map((sample, index) => (
+        <div key={`${JSON.stringify(sample)}-${index}`}>
+          {/* Example requests */}
+          {sample.request && (
+            <>
+              {/* Title of the code sample block */}
+              <h5 dangerouslySetInnerHTML={{ __html: sample.request.description }} />
+              {sample.curl && (
+                <CodeBlock headingLang="Shell" codeBlock={sample.curl} highlight="curl" />
+              )}
+              {sample.javascript && (
+                <CodeBlock
+                  headingLang={JAVASCRIPT_HEADING}
+                  codeBlock={sample.javascript}
+                  highlight="javascript"
+                />
+              )}
+              {sample.ghcli && (
+                <CodeBlock headingLang={GH_CLI_HEADING} codeBlock={sample.ghcli} highlight="curl" />
+              )}
+            </>
+          )}
+
+          {/* Title of the response */}
+          {sample.response && (
+            <>
+              <h5 dangerouslySetInnerHTML={{ __html: sample.response.description }} />
+              {/* Status code */}
+              {sample.response.statusCode && (
+                <CodeBlock codeBlock={`Status: ${sample.response.statusCode}`} />
+              )}
+
+              {/* Example response */}
+              {sample.response.example && (
+                <CodeBlock
+                  codeBlock={JSON.stringify(sample.response.example, null, 2)}
+                  highlight="json"
+                />
+              )}
+            </>
+          )}
+        </div>
+      ))}
+    </>
   )
 }

components/rest/RestHTTPMethod.tsx

@@ -1,10 +0,0 @@
-import { CodeBlock } from './CodeBlock'
-
-type Props = {
-  verb: string
-  requestPath: string
-}
-
-export function RestHTTPMethod({ verb, requestPath }: Props) {
-  return <CodeBlock verb={verb} codeBlock={requestPath}></CodeBlock>
-}

components/rest/RestNotes.tsx

@@ -1,25 +1,21 @@
+import { useRouter } from 'next/router'
+
 import { useTranslation } from 'components/hooks/useTranslation'
+import { Link } from 'components/Link'
 
-type Props = {
-  notes: Array<string>
-  enabledForGitHubApps: boolean
-}
-
-export function RestNotes({ notes, enabledForGitHubApps }: Props) {
+export function RestNotes() {
   const { t } = useTranslation('products')
+  const router = useRouter()
 
   return (
     <>
       <h4 className="pt-4">{t('rest.reference.notes')}</h4>
       <ul className="mt-2 pl-3 pb-2">
-        {enabledForGitHubApps && (
-          <li>
-            <a href="/developers/apps">Works with GitHub Apps</a>
-          </li>
-        )}
-        {notes.map((note: string) => {
-          return <li>{note}</li>
-        })}
+        <li>
+          <Link href={`/${router.locale}/developers/apps`}>
+            {t('rest.reference.works_with_github_apps')}
+          </Link>
+        </li>
       </ul>
     </>
   )

components/rest/RestOperation.tsx

@@ -1,56 +1,62 @@
+import slugger from 'github-slugger'
+
 import { RestOperationHeading } from './RestOperationHeading'
-import { RestHTTPMethod } from './RestHTTPMethod'
+import { CodeBlock } from './CodeBlock'
 import { RestParameterTable } from './RestParameterTable'
 import { RestCodeSamples } from './RestCodeSamples'
-import { RestResponse } from './RestResponse'
+import { RestStatusCodes } from './RestStatusCodes'
 import { Operation } from './types'
 import { RestNotes } from './RestNotes'
 import { RestPreviewNotice } from './RestPreviewNotice'
 import { useTranslation } from 'components/hooks/useTranslation'
-import { RestStatusCodes } from './RestStatusCodes'
 
 type Props = {
   operation: Operation
-  index: number
 }
 
 export function RestOperation({ operation }: Props) {
   const { t } = useTranslation('products')
-  const previews = operation['x-github'].previews
-  const nonErrorResponses = operation.responses.filter(
-    (response) => parseInt(response.httpStatusCode) < 400
-  )
+
+  const slug = slugger.slug(operation.title)
+
+  const numPreviews = operation.previews.length
+  const hasStatusCodes = operation.statusCodes.length > 0
+  const hasCodeSamples = operation.codeExamples.length > 0
+  const hasParameters = operation.parameters.length > 0 || operation.bodyParameters.length > 0
 
   return (
     <div>
       <RestOperationHeading
-        slug={operation.slug}
-        summary={operation.summary}
+        slug={slug}
+        title={operation.title}
         descriptionHTML={operation.descriptionHTML}
       />
-      <RestHTTPMethod verb={operation.verb} requestPath={operation.requestPath} />
-      {operation.parameters && (
+
+      {operation.requestPath && (
+        <CodeBlock verb={operation.verb} codeBlock={operation.requestPath}></CodeBlock>
+      )}
+
+      {hasParameters && (
         <RestParameterTable
-          slug={operation.slug}
-          xGitHub={operation['x-github']}
+          slug={slug}
+          numPreviews={numPreviews}
           parameters={operation.parameters}
           bodyParameters={operation.bodyParameters}
         />
       )}
-      {operation['x-codeSamples'] && operation['x-codeSamples'].length > 0 && (
-        <RestCodeSamples slug={operation.slug} xCodeSamples={operation['x-codeSamples']} />
-      )}
-      <RestResponse responses={nonErrorResponses} />
-      {(operation.notes.length > 0 || operation['x-github'].enabledForGitHubApps) && (
-        <RestNotes
-          notes={operation.notes}
-          enabledForGitHubApps={operation['x-github'].enabledForGitHubApps}
+
+      {hasCodeSamples && <RestCodeSamples operation={operation} slug={slug} />}
+
+      {hasStatusCodes && (
+        <RestStatusCodes
+          heading={t('rest.reference.status_codes')}
+          statusCodes={operation.statusCodes}
         />
       )}
-      {previews && (
-        <RestPreviewNotice slug={operation.slug} previews={operation['x-github'].previews} />
-      )}
-      <RestStatusCodes heading={t('rest.reference.status_codes')} responses={operation.responses} />
+
+      {operation.enabledForGitHubApps && <RestNotes />}
+
+      {numPreviews > 0 && <RestPreviewNotice slug={slug} previews={operation.previews} />}
     </div>
   )
 }

components/rest/RestOperationHeading.tsx

@@ -2,18 +2,18 @@ import { LinkIcon } from '@primer/octicons-react'
 
 type Props = {
   slug: string
-  summary: string
+  title: string
   descriptionHTML: string
 }
 
-export function RestOperationHeading({ slug, summary, descriptionHTML }: Props) {
+export function RestOperationHeading({ slug, title, descriptionHTML }: Props) {
   return (
     <>
       <h3 id={slug}>
         <a href={`#${slug}`}>
           <LinkIcon size={16} className="m-1" />
         </a>
-        {summary}
+        {title}
       </h3>
       <div dangerouslySetInnerHTML={{ __html: descriptionHTML }} />
     </>