From 2239bf11ae0ced40fecae645ae0a1645554c97b4 Mon Sep 17 00:00:00 2001
From: Peter Murphy <26548438+pete-murphy@users.noreply.github.com>
Date: Wed, 21 Oct 2026 21:19:07 -0400
Subject: [PATCH 1/2] Fix args to halogen:dev script

Fixes 1427.

Explanation of changes:

- `--outfile` path is relative to the package directory
  (`docs-search/client-halogen`) and so `./../../generated-docs`
  resolves to `./generated-docs` (where `spago docs` outputs to). So
  this is assuming that the `halogen:dev` is intended to be used with
  generated docs for `spago` itself (and its dependencies).
- `esbuild`'s serve mode (`--servedir`) does not read from stdin, which
  is where `spago --bundle` writes to, and serve mode doesn't seem to be
  necessary anyways because the HTML can be opened over `file://`
  protocol.
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index e2916bcce..6d0b903c2 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,7 @@
     "format:check": "purs-tidy check core src bin docs-search test",
     "bundle": "spago bundle -p spago-bin",
     "prepublishOnly": "spago build && ./bin/index.dev.js bundle -p spago-bin && ./bin/index.dev.js bundle -p docs-search-client-halogen",
-    "halogen:dev": "./bin/index.dev.js bundle -p docs-search-client-halogen --outfile=./generated-docs/html/docs-search-app.js --bundler-args '--watch=forever' --bundler-args '--servedir=./generated-docs/html'"
+    "halogen:dev": "./bin/index.dev.js bundle -p docs-search-client-halogen --outfile=../../generated-docs/html/docs-search-app.js --bundler-args '--watch=forever'"
   },
   "dependencies": {
     "@nodelib/fs.walk": "^3.0.1",

From 499e9ff8863e38d33e6ba4e40968d2ff62049e64 Mon Sep 17 00:00:00 2001
From: Peter Murphy <26548438+pete-murphy@users.noreply.github.com>
Date: Wed, 21 Oct 2026 23:48:37 -0400
Subject: [PATCH 2/2] Add to CONTRIBUTING and CHANGELOG

---
 CHANGELOG.md    |  3 +++
 CONTRIBUTING.md | 20 ++++++++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index cf0184ae6..a3601c286 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+Bugfixes:
+* Fix `halogen:dev` script (#1427)
+
 ## [1.0.5] - 2026-10-13
 
 Bugfixes:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0584f59bd..3190e8d4b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -69,6 +69,26 @@ SPAGO_TEST_DEBUG=1 spago
 SPAGO_TEST_ACCEPT=1 spago
 ```
 
+## Developing the `spago docs` Halogen app
+
+The `spago docs` command generates a "project-local Pursuit"--package docs as HTML files. The docs HTML also includes a `docs-search-app.js` for search functionality, and that is a compiled Halogen app. The source for the app is in `docs-search/client-halogen`. To develop that locally, run the same install and bootstrap scripts as above
+
+```shell
+npm ci
+spago bundle -p spago-bin
+```
+
+then generate the initial app bundle and Spago's own docs
+
+```bash
+./bin/index.dev.js bundle -p docs-search-client-halogen
+./bin/index.dev.js docs
+```
+
+That will output a link like `file://path/to/spago/generated-docs/html/index.html` where you can view the generated docs. Then run `npm run halogen:dev`, make edits to `docs-search/client-halogen`, and reload the browser to see changes.
+
+The script bundles the Halogen app in watch mode, so it updates whenever `output/` changes (which happens on edit, if your editor has the language server installed).
+
 ## Developing docs
 
 If you edit any title in the readme, run `doctoc` to update the Table of Contents: