From a0d62a8cc830a1a8987366ae846b29a4d350f05a Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Wed, 11 Mar 2026 20:40:23 +0100
Subject: [PATCH 01/21] docs: add MD file templates to workshops, labs,
 quizzes, and reviews guides

---
 src/content/docs/how-to-work-on-labs.mdx      | 54 ++++++++++++++++
 src/content/docs/how-to-work-on-quizzes.mdx   | 51 +++++++++++++++
 src/content/docs/how-to-work-on-reviews.mdx   | 62 +++++++++++++++++++
 src/content/docs/how-to-work-on-workshops.mdx | 54 ++++++++++++++++
 4 files changed, 221 insertions(+)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index 07147ca3..49b64470 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -39,3 +39,57 @@ For the labs that do not have a demo project, the solution can be the minimum ne
 The labs that have a demo project have a `demoType` property in the frontmatter with a value of `onClick`, the labs that do not have a demo project do not have a `demoType` project.
 
 The metadata for labs require a `blockLabel` property with a value of `lab`, and a `blockLayout` with a value of `link`.
+
+## Lab File Template
+
+Each lab is a single Markdown file. The `challengeType` and seed language depend on the type of lab:
+
+| `challengeType` | Lab type          | Seed language(s)                          | Solution language(s) |
+| --------------- | ----------------- | ----------------------------------------- | -------------------- |
+| `25`            | HTML/CSS(/JS/JSX) | `html` + `css`, or + `js`, or + `jsx`     | same combination     |
+| `26`            | JavaScript        | `js`                                      | `js`                 |
+| `27`            | Python            | `py`                                      | `py`                 |
+| `13`            | Bash/SQL/etc.     | no seed — runs via a CodeRoad `url` field | none                 |
+
+`saveSubmissionToDB: true` is only present in cert-project labs.
+
+Here is the template for a JavaScript lab:
+
+````md
+---
+id: <ObjectId>
+title: Build / Implement / Design / Debug [Name]
+challengeType: 26
+dashedName: lab-name
+---
+
+# --description--
+
+**Objective:** Fulfill the user stories below and get all the tests to pass to complete the lab.
+
+**User Stories:**
+
+1. ...
+
+# --hints--
+
+Description of what the test checks.
+
+```js
+// test code
+```
+
+# --seed--
+
+## --seed-contents--
+
+```js
+
+```
+
+# --solutions--
+
+```js
+// solution code
+```
+````
diff --git a/src/content/docs/how-to-work-on-quizzes.mdx b/src/content/docs/how-to-work-on-quizzes.mdx
index c19456f4..116f88f0 100644
--- a/src/content/docs/how-to-work-on-quizzes.mdx
+++ b/src/content/docs/how-to-work-on-quizzes.mdx
@@ -150,6 +150,57 @@ developer[2];
 ```
 ````
 
+## Quiz File Template
+
+Each quiz is a single Markdown file. The `### --question--` block is repeated once per question — 10 or 20 times per `## --quiz--` set. A quiz file can contain multiple sets of questions, each introduced by a new `## --quiz--` header within the same `# --quizzes--` section.
+
+```md
+---
+id: <ObjectId>
+title: [Topic] Quiz
+challengeType: 8
+dashedName: quiz-topic-name
+---
+
+# --description--
+
+To pass the quiz, you must correctly answer at least 18 of the 20 questions below.
+
+# --quizzes--
+
+## --quiz--
+
+### --question-- (repeated 10 or 20 times)
+
+#### --text--
+
+Question text
+
+#### --distractors--
+
+Wrong answer 1
+
+---
+
+Wrong answer 2
+
+---
+
+Wrong answer 3
+
+#### --answer--
+
+Correct answer
+
+## --quiz--
+
+### --question-- (another full set of 10 or 20 questions, same structure as above)
+
+#### --text--
+
+...
+```
+
 ## Acceptable Resources to Use for Creating Questions
 
 If you need help creating questions, then you can look through a few of the existing quizzes in the certification.
diff --git a/src/content/docs/how-to-work-on-reviews.mdx b/src/content/docs/how-to-work-on-reviews.mdx
index 3d01b059..5aa75d5d 100644
--- a/src/content/docs/how-to-work-on-reviews.mdx
+++ b/src/content/docs/how-to-work-on-reviews.mdx
@@ -35,3 +35,65 @@ The metadata for reviews require a `blockLabel` property with a value of `review
 Reviews use a `challengeType` of 31.
 
 Reviews have a dashedName with `review-topic`, and titles of the reviews are like `Topic Review`.
+
+## Review File Template
+
+Each review is a single Markdown file. The content section uses either `# --interactive--` or `# --description--` depending on whether the review includes interactive code editors.
+
+Use `# --interactive--` when the review includes `:::interactive_editor` blocks that campers can run directly:
+
+````md
+---
+id: <ObjectId>
+title: [Topic] Review
+challengeType: 31
+dashedName: review-topic-name
+---
+
+# --interactive--
+
+## Section Heading
+
+- **concept**: explanation
+
+```js
+// optional static code example
+```
+
+:::interactive_editor
+
+```js
+// interactive code example campers can run
+```
+
+:::
+
+# --assignment--
+
+Review the [topic] topics and concepts.
+````
+
+Use `# --description--` when the review only contains static markdown content:
+
+````md
+---
+id: <ObjectId>
+title: [Topic] Review
+challengeType: 31
+dashedName: review-topic-name
+---
+
+# --description--
+
+## Section Heading
+
+- **concept**: explanation
+
+```bash
+# optional code example
+```
+
+# --assignment--
+
+Review the [topic] topics and concepts.
+````
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index bfa31da5..6cf478ad 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -213,6 +213,60 @@ The script is to be used if the step-based project has files that have challenge
 pnpm run rename-challenges
 ```
 
+## Step File Template
+
+Each step in a workshop is a Markdown file named after its challenge `id`. The `challengeType` and seed language depend on the type of workshop:
+
+| `challengeType` | Workshop type | Seed language(s)                                               |
+| --------------- | ------------- | -------------------------------------------------------------- |
+| `0`             | HTML/CSS      | `html` only, or `html` + `css`, or `html` + `css` + `js`/`jsx` |
+| `1`             | JavaScript    | `js`                                                           |
+| `20`            | Python        | `py`                                                           |
+| `12`            | Bash/SQL/etc. | no seed — the workshop runs via a CodeRoad `url` field         |
+
+All step files use `--fcc-editable-region--` markers in the seed to highlight where campers should make changes. Only the last step requires a `# --solutions--` section.
+
+Here is the template for a JavaScript workshop step:
+
+<!-- prettier-ignore -->
+````md
+---
+id: <ObjectId>
+title: Step N
+challengeType: 1
+dashedName: step-n
+---
+
+# --description--
+
+Step description in markdown.
+
+# --hints--
+
+Description of what the test checks.
+
+```js
+// test code
+```
+
+# --seed--
+
+## --seed-contents--
+
+```js
+// seed code
+--fcc-editable-region--
+
+--fcc-editable-region--
+```
+
+# --solutions--
+
+```js
+// solution code (only required for the last step)
+```
+````
+
 ## Proposing a Pull Request (PR)
 
 After you've committed your changes, check here for [how to open a Pull Request](/how-to-open-a-pull-request/).

From 6ccb4dfd948262a6992cbfe7fcef15b75b461139 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Wed, 11 Mar 2026 21:14:38 +0100
Subject: [PATCH 02/21] docs: add demoType to workshop step template

---
 src/content/docs/how-to-work-on-workshops.mdx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 6cf478ad..d9875b21 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -226,6 +226,8 @@ Each step in a workshop is a Markdown file named after its challenge `id`. The `
 
 All step files use `--fcc-editable-region--` markers in the seed to highlight where campers should make changes. Only the last step requires a `# --solutions--` section.
 
+The `demoType: onLoad` field is only present in the first step of workshops that have a demo project.
+
 Here is the template for a JavaScript workshop step:
 
 <!-- prettier-ignore -->
@@ -235,6 +237,7 @@ id: <ObjectId>
 title: Step N
 challengeType: 1
 dashedName: step-n
+demoType: onLoad
 ---
 
 # --description--

From 33fc755e3681407e95a7000fb7e196363d966b02 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Wed, 11 Mar 2026 21:16:08 +0100
Subject: [PATCH 03/21] docs: clarify demoType is only for HTML-based
 challenges with demo

---
 src/content/docs/how-to-work-on-labs.mdx      | 3 ++-
 src/content/docs/how-to-work-on-workshops.mdx | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index 49b64470..e5389d5a 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -36,7 +36,7 @@ All labs have a solution, but not all labs have a demo project.
 For the labs that do not have a demo project, the solution can be the minimum necessary to make sure the tests are working correctly.
 :::
 
-The labs that have a demo project have a `demoType` property in the frontmatter with a value of `onClick`, the labs that do not have a demo project do not have a `demoType` project.
+Labs that have a visual output (i.e. HTML-based) can have a demo project, in which case the frontmatter includes `demoType: onClick`. It is not mandatory even for HTML labs.
 
 The metadata for labs require a `blockLabel` property with a value of `lab`, and a `blockLayout` with a value of `link`.
 
@@ -61,6 +61,7 @@ id: <ObjectId>
 title: Build / Implement / Design / Debug [Name]
 challengeType: 26
 dashedName: lab-name
+demoType: onClick
 ---
 
 # --description--
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index d9875b21..4140c3e1 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -226,7 +226,7 @@ Each step in a workshop is a Markdown file named after its challenge `id`. The `
 
 All step files use `--fcc-editable-region--` markers in the seed to highlight where campers should make changes. Only the last step requires a `# --solutions--` section.
 
-The `demoType: onLoad` field is only present in the first step of workshops that have a demo project.
+The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory even for those.
 
 Here is the template for a JavaScript workshop step:
 

From c8562eaa0ff422fbec1e68786ac276abb2597da1 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Thu, 12 Mar 2026 10:21:32 +0100
Subject: [PATCH 04/21] docs: add hooks section to labs and workshops guides

Documents --before-all--, --before-each--, --after-each--, and --after-all--
hooks: which challengeTypes support them, execution order, and how DOM
challenges (iframe) differ from non-DOM challenges (Web Worker).
---
 src/content/docs/how-to-work-on-labs.mdx      | 73 +++++++++++++++++++
 src/content/docs/how-to-work-on-workshops.mdx | 73 +++++++++++++++++++
 2 files changed, 146 insertions(+)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index e5389d5a..6c915ddf 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -94,3 +94,76 @@ Description of what the test checks.
 // solution code
 ```
 ````
+
+## Hooks
+
+Hooks are optional code blocks that run at specific points during test execution. They can be used to set up shared state, install fake timers, or clean up after tests.
+
+Hooks are supported for lab types `25`, `26`, and `27`.
+
+Four hooks are available:
+
+| Hook              | When it runs                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| `--before-all--`  | Once, before any test runs                                                                  |
+| `--before-each--` | Before each individual test                                                                 |
+| `--after-each--`  | After each individual test (in a `finally` block, so it always runs even if the test fails) |
+| `--after-all--`   | Once, after all tests have finished                                                         |
+
+**Execution order:**
+
+```
+--before-all-- (once)
+  ↓
+  For each test:
+    --before-each-- → test → --after-each--
+  ↓
+--after-all-- (once)
+```
+
+**DOM vs non-DOM labs:**
+
+For HTML/CSS labs (`challengeType: 25`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe when the page loads. It runs with full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery).
+
+For JavaScript and Python labs (`challengeType: 26` and `27`), all hooks run in a Web Worker context. There is no DOM access.
+
+**Syntax:**
+
+Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
+
+<!-- prettier-ignore -->
+````md
+# --description--
+
+...
+
+# --before-all--
+
+```js
+// Runs once before any test. Set up shared state here.
+let clock = __FakeTimers.install();
+```
+
+# --before-each--
+
+```js
+// Runs before each test.
+```
+
+# --after-each--
+
+```js
+// Runs after each test, even if it fails.
+```
+
+# --after-all--
+
+```js
+// Runs once after all tests. Clean up here.
+clock.uninstall();
+```
+
+# --hints--
+
+...
+````
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 4140c3e1..fb723176 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -270,6 +270,79 @@ Description of what the test checks.
 ```
 ````
 
+## Hooks
+
+Hooks are optional code blocks that run at specific points during test execution. They can be used to set up shared state, install fake timers, or clean up after tests.
+
+Hooks are supported for workshop types `0`, `1`, and `20`.
+
+Four hooks are available:
+
+| Hook              | When it runs                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| `--before-all--`  | Once, before any test runs                                                                  |
+| `--before-each--` | Before each individual test                                                                 |
+| `--after-each--`  | After each individual test (in a `finally` block, so it always runs even if the test fails) |
+| `--after-all--`   | Once, after all tests have finished                                                         |
+
+**Execution order:**
+
+```
+--before-all-- (once)
+  ↓
+  For each test:
+    --before-each-- → test → --after-each--
+  ↓
+--after-all-- (once)
+```
+
+**DOM vs non-DOM steps:**
+
+For HTML/CSS workshops (`challengeType: 0`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe when the page loads. It runs with full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery).
+
+For JavaScript and Python workshops (`challengeType: 1` and `20`), all hooks run in a Web Worker context. There is no DOM access.
+
+**Syntax:**
+
+Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
+
+<!-- prettier-ignore -->
+````md
+# --description--
+
+...
+
+# --before-all--
+
+```js
+// Runs once before any test. Set up shared state here.
+let clock = __FakeTimers.install();
+```
+
+# --before-each--
+
+```js
+// Runs before each test.
+```
+
+# --after-each--
+
+```js
+// Runs after each test, even if it fails.
+```
+
+# --after-all--
+
+```js
+// Runs once after all tests. Clean up here.
+clock.uninstall();
+```
+
+# --hints--
+
+...
+````
+
 ## Proposing a Pull Request (PR)
 
 After you've committed your changes, check here for [how to open a Pull Request](/how-to-open-a-pull-request/).

From 2ebea489a60ee419e426bba858f25c2bb978436c Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Thu, 12 Mar 2026 10:29:07 +0100
Subject: [PATCH 05/21] docs: clarify hook execution order and DOM vs non-DOM
 differences

---
 src/content/docs/how-to-work-on-labs.mdx      | 25 +++++++++++++------
 src/content/docs/how-to-work-on-workshops.mdx | 25 +++++++++++++------
 2 files changed, 36 insertions(+), 14 deletions(-)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index 6c915ddf..d191c339 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -112,20 +112,31 @@ Four hooks are available:
 
 **Execution order:**
 
+For HTML/CSS labs (`challengeType: 25`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe _before_ the user's HTML is parsed, so it runs before user code. It has full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery). The user's code then renders into the page, and each test runs against the live DOM:
+
 ```
---before-all-- (once)
+--before-all--
+  ↓
+user code (renders once)
   ↓
-  For each test:
-    --before-each-- → test → --after-each--
+for each test:
+  --before-each-- + test → --after-each--
   ↓
---after-all-- (once)
+--after-all--
 ```
 
-**DOM vs non-DOM labs:**
+For JavaScript and Python labs (`challengeType: 26` and `27`), `--before-all--` runs once when the Worker initialises, before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
 
-For HTML/CSS labs (`challengeType: 25`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe when the page loads. It runs with full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery).
+```
+--before-all-- (Worker init)
+  ↓
+for each test:
+  --before-each-- + user code + test → --after-each--
+  ↓
+--after-all--
+```
 
-For JavaScript and Python labs (`challengeType: 26` and `27`), all hooks run in a Web Worker context. There is no DOM access.
+There is no DOM access in Worker-based labs.
 
 **Syntax:**
 
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index fb723176..5c2019a7 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -287,20 +287,31 @@ Four hooks are available:
 
 **Execution order:**
 
+For HTML/CSS workshops (`challengeType: 0`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe _before_ the user's HTML is parsed, so it runs before user code. It has full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery). The user's code then renders into the page, and each test runs against the live DOM:
+
 ```
---before-all-- (once)
+--before-all--
+  ↓
+user code (renders once)
   ↓
-  For each test:
-    --before-each-- → test → --after-each--
+for each test:
+  --before-each-- + test → --after-each--
   ↓
---after-all-- (once)
+--after-all--
 ```
 
-**DOM vs non-DOM steps:**
+For JavaScript and Python workshops (`challengeType: 1` and `20`), `--before-all--` runs once when the Worker initialises, before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
 
-For HTML/CSS workshops (`challengeType: 0`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe when the page loads. It runs with full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery).
+```
+--before-all-- (Worker init)
+  ↓
+for each test:
+  --before-each-- + user code + test → --after-each--
+  ↓
+--after-all--
+```
 
-For JavaScript and Python workshops (`challengeType: 1` and `20`), all hooks run in a Web Worker context. There is no DOM access.
+There is no DOM access in Worker-based workshops.
 
 **Syntax:**
 

From 07db53dd913b418ec6bb44d68043f3e43bc20965 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Thu, 12 Mar 2026 10:38:44 +0100
Subject: [PATCH 06/21] docs: clean up hooks execution order section

---
 src/content/docs/how-to-work-on-labs.mdx      |  9 +++------
 src/content/docs/how-to-work-on-workshops.mdx | 14 +++++---------
 2 files changed, 8 insertions(+), 15 deletions(-)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index d191c339..f89982c9 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -36,7 +36,7 @@ All labs have a solution, but not all labs have a demo project.
 For the labs that do not have a demo project, the solution can be the minimum necessary to make sure the tests are working correctly.
 :::
 
-Labs that have a visual output (i.e. HTML-based) can have a demo project, in which case the frontmatter includes `demoType: onClick`. It is not mandatory even for HTML labs.
+Labs that have a visual output (i.e. HTML-based) can have a demo project, in which case the frontmatter includes `demoType: onClick`. It is not mandatory, if the project design calls for it it can be omitted.
 
 The metadata for labs require a `blockLabel` property with a value of `lab`, and a `blockLayout` with a value of `link`.
 
@@ -125,10 +125,10 @@ for each test:
 --after-all--
 ```
 
-For JavaScript and Python labs (`challengeType: 26` and `27`), `--before-all--` runs once when the Worker initialises, before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
+For JavaScript and Python labs (`challengeType: 26` and `27`), `--before-all--` runs once before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
 
 ```
---before-all-- (Worker init)
+--before-all-- (once)
   ↓
 for each test:
   --before-each-- + user code + test → --after-each--
@@ -136,13 +136,10 @@ for each test:
 --after-all--
 ```
 
-There is no DOM access in Worker-based labs.
-
 **Syntax:**
 
 Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
 
-<!-- prettier-ignore -->
 ````md
 # --description--
 
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 5c2019a7..418b415e 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -226,11 +226,10 @@ Each step in a workshop is a Markdown file named after its challenge `id`. The `
 
 All step files use `--fcc-editable-region--` markers in the seed to highlight where campers should make changes. Only the last step requires a `# --solutions--` section.
 
-The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory even for those.
+The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory, if the project design calls for it it can be omitted.
 
 Here is the template for a JavaScript workshop step:
 
-<!-- prettier-ignore -->
 ````md
 ---
 id: <ObjectId>
@@ -258,9 +257,9 @@ Description of what the test checks.
 
 ```js
 // seed code
---fcc-editable-region--
+--fcc - editable - region--;
 
---fcc-editable-region--
+--fcc - editable - region--;
 ```
 
 # --solutions--
@@ -300,10 +299,10 @@ for each test:
 --after-all--
 ```
 
-For JavaScript and Python workshops (`challengeType: 1` and `20`), `--before-all--` runs once when the Worker initialises, before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
+For JavaScript and Python workshops (`challengeType: 1` and `20`), `--before-all--` runs once before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
 
 ```
---before-all-- (Worker init)
+--before-all-- (once)
   ↓
 for each test:
   --before-each-- + user code + test → --after-each--
@@ -311,13 +310,10 @@ for each test:
 --after-all--
 ```
 
-There is no DOM access in Worker-based workshops.
-
 **Syntax:**
 
 Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
 
-<!-- prettier-ignore -->
 ````md
 # --description--
 

From 5d52088aa39a9d80fd8f974bfbfb0a2ea2d42c92 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Thu, 12 Mar 2026 10:40:53 +0100
Subject: [PATCH 07/21] docs: fix fcc-editable-region markers mangled by
 prettier

---
 src/content/docs/how-to-work-on-workshops.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 418b415e..15d369af 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -255,11 +255,11 @@ Description of what the test checks.
 
 ## --seed-contents--
 
-```js
+```text
 // seed code
---fcc - editable - region--;
+--fcc-editable-region--
 
---fcc - editable - region--;
+--fcc-editable-region--
 ```
 
 # --solutions--

From 764b382fef03c7c1232d98833e50bf075e15e6e3 Mon Sep 17 00:00:00 2001
From: majestic-owl448 <26656284+majestic-owl448@users.noreply.github.com>
Date: Thu, 12 Mar 2026 16:27:01 +0100
Subject: [PATCH 08/21] Apply suggestions from code review

Co-authored-by: Jeevankumar S <jeevenkumar2003@gmail.com>
---
 src/content/docs/how-to-work-on-workshops.mdx | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 15d369af..99305739 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -224,7 +224,8 @@ Each step in a workshop is a Markdown file named after its challenge `id`. The `
 | `20`            | Python        | `py`                                                           |
 | `12`            | Bash/SQL/etc. | no seed — the workshop runs via a CodeRoad `url` field         |
 
-All step files use `--fcc-editable-region--` markers in the seed to highlight where campers should make changes. Only the last step requires a `# --solutions--` section.
+All step files use exactly two `--fcc-editable-region--` markers in the seed to highlight 
+where campers should make changes. Only the last step requires a `# --solutions--` section.
 
 The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory, if the project design calls for it it can be omitted.
 
@@ -255,7 +256,7 @@ Description of what the test checks.
 
 ## --seed-contents--
 
-```text
+```lang
 // seed code
 --fcc-editable-region--
 
@@ -264,7 +265,7 @@ Description of what the test checks.
 
 # --solutions--
 
-```js
+```lang
 // solution code (only required for the last step)
 ```
 ````

From d6165114a53b3238e508759c0387ad79640a239e Mon Sep 17 00:00:00 2001
From: majestic-owl448 <26656284+majestic-owl448@users.noreply.github.com>
Date: Thu, 12 Mar 2026 16:27:40 +0100
Subject: [PATCH 09/21] Apply suggestions from code review

---
 src/content/docs/how-to-work-on-labs.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index f89982c9..9f4a924a 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -84,13 +84,13 @@ Description of what the test checks.
 
 ## --seed-contents--
 
-```js
+```lang
 
 ```
 
 # --solutions--
 
-```js
+```lang
 // solution code
 ```
 ````

From fb7995f5b4606520b77dedb16951782cceccdf55 Mon Sep 17 00:00:00 2001
From: majestic-owl448 <26656284+majestic-owl448@users.noreply.github.com>
Date: Thu, 12 Mar 2026 16:28:50 +0100
Subject: [PATCH 10/21] Apply suggestions from code review

---
 src/content/docs/how-to-work-on-labs.mdx      | 2 +-
 src/content/docs/how-to-work-on-workshops.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index 9f4a924a..56e07d48 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -59,7 +59,7 @@ Here is the template for a JavaScript lab:
 ---
 id: <ObjectId>
 title: Build / Implement / Design / Debug [Name]
-challengeType: 26
+challengeType: X
 dashedName: lab-name
 demoType: onClick
 ---
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 99305739..7e14796f 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -235,7 +235,7 @@ Here is the template for a JavaScript workshop step:
 ---
 id: <ObjectId>
 title: Step N
-challengeType: 1
+challengeType: X
 dashedName: step-n
 demoType: onLoad
 ---

From 0e08006b52973d53c67ea868327bacd2bac4571a Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Thu, 12 Mar 2026 21:40:12 +0100
Subject: [PATCH 11/21] style: fix trailing whitespace flagged by prettier

---
 src/content/docs/how-to-work-on-workshops.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 7e14796f..1668b3b3 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -224,7 +224,7 @@ Each step in a workshop is a Markdown file named after its challenge `id`. The `
 | `20`            | Python        | `py`                                                           |
 | `12`            | Bash/SQL/etc. | no seed — the workshop runs via a CodeRoad `url` field         |
 
-All step files use exactly two `--fcc-editable-region--` markers in the seed to highlight 
+All step files use exactly two `--fcc-editable-region--` markers in the seed to highlight
 where campers should make changes. Only the last step requires a `# --solutions--` section.
 
 The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory, if the project design calls for it it can be omitted.

From 862c7fba193c2f267f789e57f39a201643f36d55 Mon Sep 17 00:00:00 2001
From: majestic-owl448 <26656284+majestic-owl448@users.noreply.github.com>
Date: Thu, 12 Mar 2026 21:47:46 +0100
Subject: [PATCH 12/21] Apply suggestions from code review

---
 src/content/docs/how-to-work-on-workshops.mdx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 1668b3b3..58a85de2 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -224,8 +224,7 @@ Each step in a workshop is a Markdown file named after its challenge `id`. The `
 | `20`            | Python        | `py`                                                           |
 | `12`            | Bash/SQL/etc. | no seed — the workshop runs via a CodeRoad `url` field         |
 
-All step files use exactly two `--fcc-editable-region--` markers in the seed to highlight
-where campers should make changes. Only the last step requires a `# --solutions--` section.
+All step files use exactly two `--fcc-editable-region--` markers in the seed to highlight where campers should make changes. Only the last step requires a `# --solutions--` section.
 
 The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory, if the project design calls for it it can be omitted.
 

From 5ce4b9d6edee8a21959fd18dadcff3dd3dbab502 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Fri, 13 Mar 2026 09:51:07 +0100
Subject: [PATCH 13/21] address review comments

---
 src/content/docs/_hooks-shared.mdx            | 48 +++++++++++++++++
 src/content/docs/how-to-work-on-labs.mdx      | 53 ++-----------------
 src/content/docs/how-to-work-on-workshops.mdx | 53 ++-----------------
 3 files changed, 56 insertions(+), 98 deletions(-)
 create mode 100644 src/content/docs/_hooks-shared.mdx

diff --git a/src/content/docs/_hooks-shared.mdx b/src/content/docs/_hooks-shared.mdx
new file mode 100644
index 00000000..39799baf
--- /dev/null
+++ b/src/content/docs/_hooks-shared.mdx
@@ -0,0 +1,48 @@
+Four hooks are available:
+
+| Hook              | When it runs                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------------- |
+| `--before-all--`  | Once, before any test runs                                                                  |
+| `--before-each--` | Before each individual test                                                                 |
+| `--after-each--`  | After each individual test (in a `finally` block, so it always runs even if the test fails) |
+| `--after-all--`   | Once, after all tests have finished                                                         |
+
+**Syntax:**
+
+Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
+
+````md
+# --description--
+
+...
+
+# --before-all--
+
+```js
+// Runs once before any test. Set up shared state here.
+let clock = __FakeTimers.install();
+```
+
+# --before-each--
+
+```js
+// Runs before each test.
+```
+
+# --after-each--
+
+```js
+// Runs after each test, even if it fails.
+```
+
+# --after-all--
+
+```js
+// Runs once after all tests. Clean up here.
+clock.uninstall();
+```
+
+# --hints--
+
+...
+````
diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index 56e07d48..fcd1917a 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -4,6 +4,8 @@ sidebar:
   label: Work on Lab Challenges
 ---
 
+import HooksShared from './_hooks-shared.mdx';
+
 :::tip
 You'll need this guide if you're creating or modifying lab challenges (project-based learning with user stories). If you're working on other types of challenges like workshops, coding projects, or quizzes, check their respective guides.
 :::
@@ -36,7 +38,7 @@ All labs have a solution, but not all labs have a demo project.
 For the labs that do not have a demo project, the solution can be the minimum necessary to make sure the tests are working correctly.
 :::
 
-Labs that have a visual output (i.e. HTML-based) can have a demo project, in which case the frontmatter includes `demoType: onClick`. It is not mandatory, if the project design calls for it it can be omitted.
+Labs that have a visual output (i.e. HTML-based) can have a demo project, in which case the frontmatter includes `demoType: onClick`. It is not mandatory, if the project design does not require it it can be omitted.
 
 The metadata for labs require a `blockLabel` property with a value of `lab`, and a `blockLayout` with a value of `link`.
 
@@ -101,14 +103,7 @@ Hooks are optional code blocks that run at specific points during test execution
 
 Hooks are supported for lab types `25`, `26`, and `27`.
 
-Four hooks are available:
-
-| Hook              | When it runs                                                                                |
-| ----------------- | ------------------------------------------------------------------------------------------- |
-| `--before-all--`  | Once, before any test runs                                                                  |
-| `--before-each--` | Before each individual test                                                                 |
-| `--after-each--`  | After each individual test (in a `finally` block, so it always runs even if the test fails) |
-| `--after-all--`   | Once, after all tests have finished                                                         |
+<HooksShared />
 
 **Execution order:**
 
@@ -135,43 +130,3 @@ for each test:
   ↓
 --after-all--
 ```
-
-**Syntax:**
-
-Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
-
-````md
-# --description--
-
-...
-
-# --before-all--
-
-```js
-// Runs once before any test. Set up shared state here.
-let clock = __FakeTimers.install();
-```
-
-# --before-each--
-
-```js
-// Runs before each test.
-```
-
-# --after-each--
-
-```js
-// Runs after each test, even if it fails.
-```
-
-# --after-all--
-
-```js
-// Runs once after all tests. Clean up here.
-clock.uninstall();
-```
-
-# --hints--
-
-...
-````
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 58a85de2..1e21366d 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -4,6 +4,8 @@ sidebar:
   label: Work on Workshops
 ---
 
+import HooksShared from './_hooks-shared.mdx';
+
 :::tip
 You'll need this guide if you're creating or modifying workshop-style curriculum (step-based learning). If you're working on other types of challenges like coding projects, labs, or quizzes, check their respective guides.
 :::
@@ -226,7 +228,7 @@ Each step in a workshop is a Markdown file named after its challenge `id`. The `
 
 All step files use exactly two `--fcc-editable-region--` markers in the seed to highlight where campers should make changes. Only the last step requires a `# --solutions--` section.
 
-The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory, if the project design calls for it it can be omitted.
+The `demoType: onLoad` field is only present in the first step, and only for workshops that have a visual output (i.e. HTML-based). It is not mandatory, if the project design does not require it it can be omitted.
 
 Here is the template for a JavaScript workshop step:
 
@@ -275,14 +277,7 @@ Hooks are optional code blocks that run at specific points during test execution
 
 Hooks are supported for workshop types `0`, `1`, and `20`.
 
-Four hooks are available:
-
-| Hook              | When it runs                                                                                |
-| ----------------- | ------------------------------------------------------------------------------------------- |
-| `--before-all--`  | Once, before any test runs                                                                  |
-| `--before-each--` | Before each individual test                                                                 |
-| `--after-each--`  | After each individual test (in a `finally` block, so it always runs even if the test fails) |
-| `--after-all--`   | Once, after all tests have finished                                                         |
+<HooksShared />
 
 **Execution order:**
 
@@ -310,46 +305,6 @@ for each test:
 --after-all--
 ```
 
-**Syntax:**
-
-Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
-
-````md
-# --description--
-
-...
-
-# --before-all--
-
-```js
-// Runs once before any test. Set up shared state here.
-let clock = __FakeTimers.install();
-```
-
-# --before-each--
-
-```js
-// Runs before each test.
-```
-
-# --after-each--
-
-```js
-// Runs after each test, even if it fails.
-```
-
-# --after-all--
-
-```js
-// Runs once after all tests. Clean up here.
-clock.uninstall();
-```
-
-# --hints--
-
-...
-````
-
 ## Proposing a Pull Request (PR)
 
 After you've committed your changes, check here for [how to open a Pull Request](/how-to-open-a-pull-request/).

From dad1a8b08f38f4081178d8ad5a2bb6416215be28 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Fri, 13 Mar 2026 10:08:44 +0100
Subject: [PATCH 14/21] move execution order to shared partial and genericize
 language

---
 src/content/docs/_hooks-shared.mdx            | 26 +++++++++++++++++++
 src/content/docs/how-to-work-on-labs.mdx      | 26 -------------------
 src/content/docs/how-to-work-on-workshops.mdx | 26 -------------------
 3 files changed, 26 insertions(+), 52 deletions(-)

diff --git a/src/content/docs/_hooks-shared.mdx b/src/content/docs/_hooks-shared.mdx
index 39799baf..3ce7fadc 100644
--- a/src/content/docs/_hooks-shared.mdx
+++ b/src/content/docs/_hooks-shared.mdx
@@ -7,6 +7,32 @@ Four hooks are available:
 | `--after-each--`  | After each individual test (in a `finally` block, so it always runs even if the test fails) |
 | `--after-all--`   | Once, after all tests have finished                                                         |
 
+**Execution order:**
+
+For challenges that have an HTML file, `--before-all--` is injected as a `<script>` tag into the sandboxed iframe _before_ the user's HTML is parsed, so it runs before user code. It has full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery). The user's code then renders into the page, and each test runs against the live DOM:
+
+```
+--before-all--
+  ↓
+user code (renders once)
+  ↓
+for each test:
+  --before-each-- + test → --after-each--
+  ↓
+--after-all--
+```
+
+For challenges that do not have an HTML file, `--before-all--` runs once before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
+
+```
+--before-all-- (once)
+  ↓
+for each test:
+  --before-each-- + user code + test → --after-each--
+  ↓
+--after-all--
+```
+
 **Syntax:**
 
 Hooks use the same `# --hook-name--` heading syntax as other sections. Each hook must contain exactly one code block. Hooks are placed after `--description--` and before `--hints--`:
diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index fcd1917a..d923abb9 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -104,29 +104,3 @@ Hooks are optional code blocks that run at specific points during test execution
 Hooks are supported for lab types `25`, `26`, and `27`.
 
 <HooksShared />
-
-**Execution order:**
-
-For HTML/CSS labs (`challengeType: 25`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe _before_ the user's HTML is parsed, so it runs before user code. It has full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery). The user's code then renders into the page, and each test runs against the live DOM:
-
-```
---before-all--
-  ↓
-user code (renders once)
-  ↓
-for each test:
-  --before-each-- + test → --after-each--
-  ↓
---after-all--
-```
-
-For JavaScript and Python labs (`challengeType: 26` and `27`), `--before-all--` runs once before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
-
-```
---before-all-- (once)
-  ↓
-for each test:
-  --before-each-- + user code + test → --after-each--
-  ↓
---after-all--
-```
diff --git a/src/content/docs/how-to-work-on-workshops.mdx b/src/content/docs/how-to-work-on-workshops.mdx
index 1e21366d..b4108ceb 100644
--- a/src/content/docs/how-to-work-on-workshops.mdx
+++ b/src/content/docs/how-to-work-on-workshops.mdx
@@ -279,32 +279,6 @@ Hooks are supported for workshop types `0`, `1`, and `20`.
 
 <HooksShared />
 
-**Execution order:**
-
-For HTML/CSS workshops (`challengeType: 0`), `--before-all--` is injected as a `<script>` tag into the sandboxed iframe _before_ the user's HTML is parsed, so it runs before user code. It has full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery). The user's code then renders into the page, and each test runs against the live DOM:
-
-```
---before-all--
-  ↓
-user code (renders once)
-  ↓
-for each test:
-  --before-each-- + test → --after-each--
-  ↓
---after-all--
-```
-
-For JavaScript and Python workshops (`challengeType: 1` and `20`), `--before-all--` runs once before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
-
-```
---before-all-- (once)
-  ↓
-for each test:
-  --before-each-- + user code + test → --after-each--
-  ↓
---after-all--
-```
-
 ## Proposing a Pull Request (PR)
 
 After you've committed your changes, check here for [how to open a Pull Request](/how-to-open-a-pull-request/).

From 2f8cac8a22198b24e864ad481b850c691f2f45f8 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Fri, 13 Mar 2026 10:17:56 +0100
Subject: [PATCH 15/21] docs: add Proposing a Pull Request section to labs
 guide

---
 src/content/docs/how-to-work-on-labs.mdx | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/content/docs/how-to-work-on-labs.mdx b/src/content/docs/how-to-work-on-labs.mdx
index d923abb9..ab6d77d2 100644
--- a/src/content/docs/how-to-work-on-labs.mdx
+++ b/src/content/docs/how-to-work-on-labs.mdx
@@ -104,3 +104,7 @@ Hooks are optional code blocks that run at specific points during test execution
 Hooks are supported for lab types `25`, `26`, and `27`.
 
 <HooksShared />
+
+## Proposing a Pull Request (PR)
+
+After you've committed your changes, check here for [how to open a Pull Request](/how-to-open-a-pull-request/).

From e60fc4ea705c28633e5d940e3b53ccaa094be60c Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Fri, 13 Mar 2026 10:50:05 +0100
Subject: [PATCH 16/21] docs: add HTML/CSS/JS multi-file interactive editor
 example to reviews guide

---
 src/content/docs/how-to-work-on-reviews.mdx | 26 ++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/how-to-work-on-reviews.mdx b/src/content/docs/how-to-work-on-reviews.mdx
index 5aa75d5d..bf9b10f1 100644
--- a/src/content/docs/how-to-work-on-reviews.mdx
+++ b/src/content/docs/how-to-work-on-reviews.mdx
@@ -40,7 +40,9 @@ Reviews have a dashedName with `review-topic`, and titles of the reviews are lik
 
 Each review is a single Markdown file. The content section uses either `# --interactive--` or `# --description--` depending on whether the review includes interactive code editors.
 
-Use `# --interactive--` when the review includes `:::interactive_editor` blocks that campers can run directly:
+Use `# --interactive--` when the review includes `:::interactive_editor` blocks that campers can run directly.
+
+For JavaScript-only examples:
 
 ````md
 ---
@@ -73,6 +75,28 @@ dashedName: review-topic-name
 Review the [topic] topics and concepts.
 ````
 
+For HTML/CSS/JS examples, include all three file types inside the same `:::interactive_editor` block. The HTML file must explicitly link to the CSS and JS files — they are not linked automatically:
+
+````md
+:::interactive_editor
+
+```html
+<link rel="stylesheet" href="styles.css" />
+<!-- HTML content -->
+<script src="index.js"></script>
+```
+
+```css
+/* CSS styles */
+```
+
+```js
+// JavaScript code
+```
+
+:::
+````
+
 Use `# --description--` when the review only contains static markdown content:
 
 ````md

From 66bbe4eed266ecf0d6bf901aa4bce984d754179b Mon Sep 17 00:00:00 2001
From: majestic-owl448 <26656284+majestic-owl448@users.noreply.github.com>
Date: Fri, 13 Mar 2026 10:51:37 +0100
Subject: [PATCH 17/21] Apply suggestions from code review

---
 src/content/docs/how-to-work-on-reviews.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/how-to-work-on-reviews.mdx b/src/content/docs/how-to-work-on-reviews.mdx
index bf9b10f1..e2a61b04 100644
--- a/src/content/docs/how-to-work-on-reviews.mdx
+++ b/src/content/docs/how-to-work-on-reviews.mdx
@@ -75,7 +75,7 @@ dashedName: review-topic-name
 Review the [topic] topics and concepts.
 ````
 
-For HTML/CSS/JS examples, include all three file types inside the same `:::interactive_editor` block. The HTML file must explicitly link to the CSS and JS files — they are not linked automatically:
+For CSS and JS examples, include the HTML file inside the same `:::interactive_editor` block. The HTML file must explicitly link to the CSS and/or the JS files — they are not linked automatically:
 
 ````md
 :::interactive_editor

From 40e4bab1d7ece00a676d0534ce9106d82550f8d3 Mon Sep 17 00:00:00 2001
From: majestic-owl448 <26656284+majestic-owl448@users.noreply.github.com>
Date: Fri, 13 Mar 2026 10:52:46 +0100
Subject: [PATCH 18/21] Apply suggestions from code review

---
 src/content/docs/how-to-work-on-reviews.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/how-to-work-on-reviews.mdx b/src/content/docs/how-to-work-on-reviews.mdx
index e2a61b04..4b25ea27 100644
--- a/src/content/docs/how-to-work-on-reviews.mdx
+++ b/src/content/docs/how-to-work-on-reviews.mdx
@@ -75,7 +75,7 @@ dashedName: review-topic-name
 Review the [topic] topics and concepts.
 ````
 
-For CSS and JS examples, include the HTML file inside the same `:::interactive_editor` block. The HTML file must explicitly link to the CSS and/or the JS files — they are not linked automatically:
+For CSS and JS examples, include the HTML file inside the same `:::interactive_editor` block. The HTML file must explicitly link to the CSS and/or the JS files, they are not linked automatically:
 
 ````md
 :::interactive_editor

From 5e980d346df0d43c0aef87e8e6016280f6c085ad Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Fri, 13 Mar 2026 16:45:30 +0100
Subject: [PATCH 19/21] docs: clarify before-all scoping in non-DOM challenges

Variables declared in --before-all-- are not in scope during isolated
tests. State must be assigned to globalThis to persist across tests.
---
 src/content/docs/_hooks-shared.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/_hooks-shared.mdx b/src/content/docs/_hooks-shared.mdx
index 3ce7fadc..7a12cb4a 100644
--- a/src/content/docs/_hooks-shared.mdx
+++ b/src/content/docs/_hooks-shared.mdx
@@ -22,7 +22,7 @@ for each test:
 --after-all--
 ```
 
-For challenges that do not have an HTML file, `--before-all--` runs once before any test. User code is then re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`):
+For challenges that do not have an HTML file, `--before-all--` runs once before any test. However, because user code is re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`), variables declared in `--before-all--` will not be in scope during tests. To share state across tests, assign to the global object directly (e.g. `globalThis.x = 1` instead of `let x = 1`):
 
 ```
 --before-all-- (once)

From 529d7906b902c6c75c61a93d8d60bc793c6cf421 Mon Sep 17 00:00:00 2001
From: majestic-owl448 <26656284+majestic-owl448@users.noreply.github.com>
Date: Fri, 13 Mar 2026 17:25:23 +0100
Subject: [PATCH 20/21] Apply suggestions from code review

Co-authored-by: Oliver Eyton-Williams <ojeytonwilliams@gmail.com>
---
 src/content/docs/_hooks-shared.mdx | 26 ++++++++++++--------------
 1 file changed, 12 insertions(+), 14 deletions(-)

diff --git a/src/content/docs/_hooks-shared.mdx b/src/content/docs/_hooks-shared.mdx
index 7a12cb4a..9517401f 100644
--- a/src/content/docs/_hooks-shared.mdx
+++ b/src/content/docs/_hooks-shared.mdx
@@ -12,25 +12,23 @@ Four hooks are available:
 For challenges that have an HTML file, `--before-all--` is injected as a `<script>` tag into the sandboxed iframe _before_ the user's HTML is parsed, so it runs before user code. It has full access to DOM APIs and global test helpers like `__FakeTimers` and `$` (jQuery). The user's code then renders into the page, and each test runs against the live DOM:
 
 ```
---before-all--
-  ↓
-user code (renders once)
-  ↓
-for each test:
-  --before-each-- + test → --after-each--
-  ↓
---after-all--
+1. --before-all--
+
+2. user code (evaluated once)
+
+3. (for each test): --before-each-- → test → --after-each--
+
+4.--after-all--
 ```
 
 For challenges that do not have an HTML file, `--before-all--` runs once before any test. However, because user code is re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`), variables declared in `--before-all--` will not be in scope during tests. To share state across tests, assign to the global object directly (e.g. `globalThis.x = 1` instead of `let x = 1`):
 
 ```
---before-all-- (once)
-  ↓
-for each test:
-  --before-each-- + user code + test → --after-each--
-  ↓
---after-all--
+1. --before-all-- 
+
+2. (for each test): --before-each-- → user code → test → --after-each--
+
+3. --after-all--
 ```
 
 **Syntax:**

From 82f51df4f93de9506e7df30380c1882880a69d87 Mon Sep 17 00:00:00 2001
From: Ilenia M <nethleen@gmail.com>
Date: Fri, 13 Mar 2026 17:30:06 +0100
Subject: [PATCH 21/21] fix: remove trailing whitespace in hooks-shared

---
 src/content/docs/_hooks-shared.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/content/docs/_hooks-shared.mdx b/src/content/docs/_hooks-shared.mdx
index 9517401f..26178cd1 100644
--- a/src/content/docs/_hooks-shared.mdx
+++ b/src/content/docs/_hooks-shared.mdx
@@ -24,7 +24,7 @@ For challenges that have an HTML file, `--before-all--` is injected as a `<scrip
 For challenges that do not have an HTML file, `--before-all--` runs once before any test. However, because user code is re-evaluated as part of each individual test (concatenated with `--before-each--` and the test in a single `eval`), variables declared in `--before-all--` will not be in scope during tests. To share state across tests, assign to the global object directly (e.g. `globalThis.x = 1` instead of `let x = 1`):
 
 ```
-1. --before-all-- 
+1. --before-all--
 
 2. (for each test): --before-each-- → user code → test → --after-each--