From e5ac3df3ab9e4b451f804f935a2cc2d44f093765 Mon Sep 17 00:00:00 2001
From: JD De Dios Ojeda <89946133+ojedaJD@users.noreply.github.com>
Date: Fri, 28 Aug 2026 14:33:52 -0400
Subject: [PATCH 1/3] docs: improve local development instructions

Signed-off-by: JD De Dios Ojeda <89946133+ojedaJD@users.noreply.github.com>
---
 CONTRIBUTING.md | 13 ++++++++++++-
 README.md       |  9 ++++++++-
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dd5acd1..cc5413a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -43,12 +43,23 @@ for prior user-research context on content organisation.
 
 ## Building locally
 
+This repository requires Node.js 24. Install the dependencies and generate the
+static site:
+
 ```bash
 npm install
 npm run build
-# Output is written to out/
 ```
 
+The output is written to `out/`. Start a local server from a separate terminal:
+
+```bash
+npx serve out
+```
+
+Open <http://localhost:3000/learn> to preview the site. Run `npm run build`
+again after making changes to update the generated output.
+
 ## Code of Conduct
 
 This project follows the
diff --git a/README.md b/README.md
index ec19120..707185f 100644
--- a/README.md
+++ b/README.md
@@ -32,11 +32,18 @@ conducted at the 2025 Cambridge Node.js Collaborators' Summit.
 
 ## Development
 
+Use Node.js 24, install the dependencies, and build the static site:
+
 ```bash
 npm install
-npm run build   # generates static site + Orama search DB in out/
+npm run build
+npx serve out
 ```
 
+The build generates the static site and Orama search database in `out/`.
+After starting the server, open <http://localhost:3000/learn>. Rebuild the site
+after making changes to preview the updated content.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).

From c3eb4e822f34b1cd75918e03e580803e413f9258 Mon Sep 17 00:00:00 2001
From: JD De Dios Ojeda <89946133+ojedaJD@users.noreply.github.com>
Date: Fri, 28 Aug 2026 16:06:01 -0400
Subject: [PATCH 2/3] fix: support localhost development origin

Signed-off-by: JD De Dios Ojeda <89946133+ojedaJD@users.noreply.github.com>
---
 doc-kit.config.mjs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc-kit.config.mjs b/doc-kit.config.mjs
index 676adc5..06fd267 100644
--- a/doc-kit.config.mjs
+++ b/doc-kit.config.mjs
@@ -2,14 +2,18 @@ import web from '@node-core/doc-kit/src/generators/web/index.mjs';
 import { join } from 'node:path';
 
 const origin =
-  process.env.VERCEL_ENV === 'preview' ? process.env.VERCEL_URL : 'nodejs.org';
+  process.env.VERCEL_ENV === 'preview'
+    ? `https://${process.env.VERCEL_URL}`
+    : process.env.VERCEL_ENV === 'production'
+      ? 'https://nodejs.org'
+      : 'http://localhost:3000';
 
 /** @type {import('@node-core/doc-kit/src/utils/configuration/types.d.ts').Configuration} */
 export default {
   global: {
     output: 'out/learn',
     input: ['pages/**/*.md'],
-    baseURL: `https://${origin}/learn`,
+    baseURL: `${origin}/learn`,
   },
   'jsx-ast': {
     generateIndexPage: false,

From b0e26102d2d3ad3c597e1f84fbdbf1bf062ce752 Mon Sep 17 00:00:00 2001
From: JD Ojeda <jddedios.ojeda@gmail.com>
Date: Mon, 31 Aug 2026 13:32:36 -0400
Subject: [PATCH 3/3] docs: address development guide feedback

Signed-off-by: JD Ojeda <jddedios.ojeda@gmail.com>
---
 CONTRIBUTING.md |  4 ++--
 README.md       | 14 --------------
 2 files changed, 2 insertions(+), 16 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cc5413a..bf3e5b5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -43,8 +43,8 @@ for prior user-research context on content organisation.
 
 ## Building locally
 
-This repository requires Node.js 24. Install the dependencies and generate the
-static site:
+This repository requires the Node.js version specified in the
+[`.nvmrc` file](.nvmrc). Install the dependencies and generate the static site:
 
 ```bash
 npm install
diff --git a/README.md b/README.md
index 707185f..e1792f6 100644
--- a/README.md
+++ b/README.md
@@ -30,20 +30,6 @@ The structure is based on
 [Card Sort research](https://github.com/nodejs/nodejs.org/issues/8234)
 conducted at the 2025 Cambridge Node.js Collaborators' Summit.
 
-## Development
-
-Use Node.js 24, install the dependencies, and build the static site:
-
-```bash
-npm install
-npm run build
-npx serve out
-```
-
-The build generates the static site and Orama search database in `out/`.
-After starting the server, open <http://localhost:3000/learn>. Rebuild the site
-after making changes to preview the updated content.
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).