Add dev container configuration (#434)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

4 files changed, 50 insertions, 3 deletions

diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
new file mode 100644
index 00000000..f3d56a54
--- /dev/null
+++ b/.devcontainer/Dockerfile
@@ -0,0 +1,7 @@
+# Based on https://github.com/withastro/astro/blob/main/.devcontainer/Dockerfile
+FROM mcr.microsoft.com/devcontainers/javascript-node:0-18
+
+# Install latest pnpm
+RUN npm install -g pnpm
+
+COPY welcome-message.txt /usr/local/etc/vscode-dev-containers/first-run-notice.txt
\ No newline at end of file
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 00000000..2b192ec9
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,16 @@
+{
+  "name": "Contribute to Starlight",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "postCreateCommand": "pnpm install",
+  "waitFor": "postCreateCommand",
+  "customizations": {
+    "codespaces": {
+      "openFiles": ["CONTRIBUTING.md"]
+    },
+    "vscode": {
+      "extensions": ["astro-build.astro-vscode", "esbenp.prettier-vscode"]
+    }
+  }
+}
diff --git a/.devcontainer/welcome-message.txt b/.devcontainer/welcome-message.txt
new file mode 100644
index 00000000..439f7ea9
--- /dev/null
+++ b/.devcontainer/welcome-message.txt
@@ -0,0 +1,11 @@
+🌟 Welcome to Starlight!
+
+🛠️  Your environment is fully setup with all required software installed.
+
+Next steps:
+
+  - Preview the docs site:
+    cd docs && pnpm dev --host
+
+  - Run tests:
+    cd packages/starlight && pnpm test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0cc41f03..851ca5dc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -38,9 +38,11 @@ This repo is a “monorepo,” meaning it contains several projects in one. It c
 
 ### Setting up a development environment
 
+You can [develop locally](#developing-locally) or use an online coding development environment like [GitHub Codespaces](#developing-using-github-codespaces) or [Gitpod](#developing-using-gitpod) to get started quickly.
+
 #### Developing locally
 
-**Prerequisites:** Developing Starlight requires [Node.js](https://nodejs.org/en) and [pnpm](https://pnpm.io/). Make sure you have these installed before following these steps.
+**Prerequisites:** Developing Starlight requires [Node.js](https://nodejs.org/en) (v16 or higher) and [pnpm](https://pnpm.io/) (v8.2 or higher). Make sure you have these installed before following these steps.
 
 1. **Fork Starlight** to your personal GitHub account by clicking <kbd>Fork</kbd> on the [main Starlight repo page][sl].
 
@@ -64,8 +66,6 @@ This repo is a “monorepo,” meaning it contains several projects in one. It c
 
 #### Developing using Gitpod
 
-Instead of working locally on your machine, you can also contribute using an online coding development environment like Gitpod.
-
 **Prerequisites:** Developing Starlight using Gitpod requires a free [Gitpod account](https://gitpod.io).
 
 1. **Open the Gitpod URL** [https://gitpod.io/#https://github.com/withastro/starlight](https://gitpod.io/#https://github.com/withastro/starlight). You can alternatively install a [Gitpod browser extension](https://www.gitpod.io/docs/configure/user-settings/browser-extension) which will add a "Gitpod" button when viewing [Starlight's repo on GitHub](https://github.com/withastro/starlight).
@@ -76,6 +76,19 @@ Instead of working locally on your machine, you can also contribute using an onl
    pnpm i
    ```
 
+#### Developing using GitHub Codespaces
+
+1. **Create a new codespace** via https://codespaces.new/withastro/starlight
+
+2. If running the docs site, pass the `--host` flag to avoid “502 Bad Gateway” errors:
+
+   ```sh
+   cd docs
+   pnpm dev --host
+   ```
+
+The dev container used for GitHub Codespaces can also be used with [other supporting tools](https://containers.dev/supporting), including VS Code.
+
 ## Testing
 
 ### Testing visual changes while you work