Add block text highlighting in instruction panel (#1584)

Closes
RaspberryPiFoundation/digital-editor-issues#1690

## Block-type text highlighting
- Used
[rpf-markdown-core](https://github.com/RaspberryPiFoundation/rpf-markdown-core)
(built by the Code Club team) for rendering instructions, chosen for its
inline Kramdown class support.
- Refactored the css file so that they apply to both light and dark mode
without breaking others.

| Before   | After |
| -------- | ------- |
| <img width="392" height="349" alt="Screenshot 2026-08-10 at 17 02 22"
src="https://github.com/user-attachments/assets/907a3a46-c871-4128-8f2d-081a9293edcf"
/> | <img width="395" height="364" alt="Screenshot 2026-08-10 at 17 04
13"
src="https://github.com/user-attachments/assets/8ac0b8f3-9a34-45ae-b134-334f8a98454a"
/> |

## Prism and other fixes
- While doing this work, I found Prism had stopped working possibly due
to the partial Vite migration. Prism provides syntax highlighting, line
numbering and line highlighting in code blocks of instructions.
Classroom and ExpCS instructions don't use these currently, but CCP
instructions do (and CCP team also noticed this when running projects
site locally along with latest editor-ui).
<img width="360" alt="Screenshot 2026-08-10 at 17 02 57"
src="https://github.com/user-attachments/assets/6d134da6-0bb3-476f-8c80-08a3cacb9456"
/>

- The existing `vite.lib.js` configured `babel-plugin-prismjs` via
@vitejs/plugin-react's babel option. But the plugin-react v6 no longer
has, so the config was ignored. Replaced with explicit imports in
src/utils/prism.js.
- In dev environment, `vite-plugin-node-polyfills` prepends a shim
banner to every pre-bundled dependency without terminating the last
statement. Prism's plugin files start with (function(){…})(), so it was
parsed as an argument to the shim and then short-circuited away,
resulting in line-numbers and line-highlight not registered. Worked
around with optimizeDeps.exclude in vite.config.js.
- Jest couldn't load any test importing rpf-markdown-core. Its CJS build
requires marked and scratchblocks, both ESM-only with no CommonJS entry.
Updated transformIgnorePatterns to exempt both, matched against the full
path so the nested rpf-markdown-core/node_modules/scratchblocks copy is
also covered.

## Can our users use any other features that the rpf-markdown-core
provides?
- Not yet. There are some styling issues with others which we need to
address first.
- CCP team is also open to collaboration if we require certain set of
functionalities from or improvements to the library.

| Spacing issues   | issues with dark mode |
| -------- | ------- |
| <img width="400" height="580" alt="Screenshot 2026-08-10 at 17 04 34"
src="https://github.com/user-attachments/assets/8b5e80ff-5f78-4857-9adc-21d5ee06387c"
/> | <img width="400" alt="Screenshot 2026-08-10 at 17 19 52"
src="https://github.com/user-attachments/assets/044320f4-70ee-4017-8b4f-4b5c95753e14"
/> |

Author: cocomarine

.babelrc

@@ -1,19 +1,3 @@
 {
-  "presets": ["react-app"],
-  "plugins": [
-    [
-      "prismjs",
-      {
-        "languages": ["javascript", "css", "python", "html"],
-        "plugins": [
-          "line-numbers",
-          "line-highlight",
-          "highlight-keywords",
-          "normalize-whitespace"
-        ],
-        "theme": "twilight",
-        "css": true
-      }
-    ]
-  ]
+  "presets": ["react-app"]
 }

jest.config.js

@@ -20,7 +20,13 @@ module.exports = {
       "<rootDir>/node_modules/jest-transform-stub",
   },
   transformIgnorePatterns: [
-    "[/\\\\]node_modules[/\\\\](?!three).+\\.(js|jsx|mjs|cjs|ts|tsx)$",
+    // Ignore everything under node_modules except the packages listed below,
+    // which Jest has to transform because they are "type": "module" with no
+    // CommonJS entry point: rpf-markdown-core's CJS build requires marked and
+    // scratchblocks/index.js, so their raw `export` syntax would otherwise
+    // reach the CJS loader. A nested copy (rpf-markdown-core/node_modules/
+    // scratchblocks) is also exempted.
+    "^(?!.*[/\\\\]node_modules[/\\\\](?:three|marked|scratchblocks)[/\\\\]).*[/\\\\]node_modules[/\\\\].+\\.(js|jsx|mjs|cjs|ts|tsx)$",
     "^.+\\.module\\.(css|sass|scss)$",
   ],
   modulePaths: [],

package.json

@@ -15,6 +15,7 @@
     "@juggle/resize-observer": "^3.3.1",
     "@raspberrypifoundation/design-system-react": "^2.9.2",
     "@raspberrypifoundation/python-friendly-error-messages": "0.8.0",
+    "@raspberrypifoundation/rpf-markdown-core": "^0.1.2",
     "@react-three/drei": "^10.0.0",
     "@react-three/fiber": "^9.6.1",
     "@reduxjs/toolkit": "^1.6.2",
@@ -38,7 +39,6 @@
     "js-convert-case": "^4.2.0",
     "jszip": "^3.10.1",
     "jszip-utils": "^0.1.0",
-    "marked": "^15.0.6",
     "mime-types": "^2.1.35",
     "node-html-parser": "^6.1.5",
     "oidc-client": "^1.11.5",
@@ -110,7 +110,6 @@
     "@vitejs/plugin-react": "^6",
     "babel-eslint": "^10.1.0",
     "babel-jest": "^29.1.2",
-    "babel-plugin-prismjs": "^2.1.0",
     "babel-preset-react-app": "^10.0.1",
     "browserslist": "^4.28.6",
     "browserslist-to-esbuild": "^2.1.1",

src/assets/stylesheets/Instructions.scss

@@ -8,48 +8,14 @@
 .project-instructions {
   block-size: 100%;
 
-  code.block3control {
-    background-color: var(--scratch-control-primary);
-  }
-  code.block3events {
-    background-color: var(--scratch-events-primary);
-  }
-  code.block3extensions {
-    background-color: var(--scratch-pen-primary);
-  }
-  code.block3looks {
-    background-color: var(--scratch-looks-primary);
-  }
-  code.block3motion {
-    background-color: var(--scratch-motion-primary);
-  }
-  code.block3myblocks {
-    background-color: var(--scratch-more-primary);
-  }
-  code.block3operators {
-    background-color: var(--scratch-operators-primary);
-  }
-  code.block3sensing {
-    background-color: var(--scratch-sensing-primary);
-  }
-  code.block3sound {
-    background-color: var(--scratch-sounds-primary);
-  }
-  code.block3variables {
-    background-color: var(--scratch-data-primary);
+  @each $block, $category in $scratch-block-categories {
+    code.block3#{$block} {
+      background-color: var(--scratch-#{$category}-primary);
+    }
   }
 
   @media (prefers-contrast: more) {
-    code.block3control,
-    code.block3events,
-    code.block3extensions,
-    code.block3looks,
-    code.block3motion,
-    code.block3myblocks,
-    code.block3operators,
-    code.block3sensing,
-    code.block3sound,
-    code.block3variables {
+    code[class*="block3"] {
       color: var(--rpf-black);
     }
   }
@@ -416,10 +382,10 @@
 }
 
 .--dark .project-instructions {
-  pre {
-    background-color: $rpf-grey-850;
-  }
-  code {
+  // Exclude scratchblocks references, otherwise this would tie on specificity
+  // with their category colours above and win by coming later in the file.
+  pre,
+  code:not([class*="block3"]) {
     background-color: $rpf-grey-850;
   }
 }

src/assets/stylesheets/_scratch_colours.scss

@@ -1,5 +1,21 @@
 // Scratch block category colours, sourced from
 // @RaspberryPiFoundation/scratch-gui's src/lib/settings/color-mode/*/index.js
+
+// scratchblocks names its categories differently to scratch-gui, so map the
+// `code.block3<key>` class it emits onto the `--scratch-<value>-primary` var.
+$scratch-block-categories: (
+  "control": "control",
+  "events": "events",
+  "extensions": "pen",
+  "looks": "looks",
+  "motion": "motion",
+  "myblocks": "more",
+  "operators": "operators",
+  "sensing": "sensing",
+  "sound": "sounds",
+  "variables": "data",
+);
+
 .project-instructions {
   --scratch-motion-primary: #4c97ff;
   --scratch-looks-primary: #9966ff;

src/components/Menus/Sidebar/InstructionsPanel/InstructionsPanel.test.jsx

@@ -4,15 +4,11 @@ import { setInstructionsEditable } from "../../../../redux/EditorSlice";
 import { setCurrentStepPosition } from "../../../../redux/InstructionsSlice";
 import { act } from "react";
 import Modal from "react-modal";
-import Prism from "prismjs";
 import { scratchblocksInit } from "../../../../utils/scratchblocks";
 import { renderWithProviders } from "../../../../utils/renderWithProviders";
 
 window.HTMLElement.prototype.scrollTo = jest.fn();
-jest.mock("prismjs", () => ({
-  ...jest.requireActual("prismjs"),
-  highlightElement: jest.fn(),
-}));
+
 jest.mock("../../../../utils/scratchblocks", () => ({
   scratchblocksInit: jest.fn(),
 }));
@@ -279,11 +275,6 @@ describe("When instructions are not editable", () => {
     test("Renders the progress bar", () => {
       expect(screen.queryByRole("progressbar")).toBeInTheDocument();
     });
-
-    test("Applies syntax highlighting to step content", () => {
-      const codeElement = document.getElementsByClassName("language-python")[0];
-      expect(Prism.highlightElement).toHaveBeenCalledWith(codeElement);
-    });
   });
 
   describe("When there is only one step", () => {

src/components/Menus/Sidebar/InstructionsPanel/InstructionsStep/InstructionsStep.jsx

@@ -1,20 +1,13 @@
 import React, { useEffect, useRef } from "react";
-import { marked } from "marked";
-import Prism from "prismjs";
+import { processEditorProject } from "@raspberrypifoundation/rpf-markdown-core";
+import Prism from "../../../../../utils/prism";
 import { scratchblocksInit } from "../../../../../utils/scratchblocks";
 
-const markdownRenderer = new marked.Renderer();
-markdownRenderer.link = function (data) {
-  return `<a href="${data.href}" target="_blank" rel="noreferrer"
-    }">${data.text}</a>`;
-};
-marked.setOptions({ renderer: markdownRenderer });
-
 const getStepHtml = (step) => {
   if (step.content !== undefined) {
     return step.content;
   }
-  return marked.parse(step.markdown_content ?? "");
+  return processEditorProject(step.markdown_content ?? "");
 };
 
 const applySyntaxHighlighting = (container) => {
@@ -23,11 +16,15 @@ const applySyntaxHighlighting = (container) => {
   );
 
   codeElements.forEach((element) => {
-    if (window.syntaxHighlight) {
-      window.syntaxHighlight.highlightElement(element);
-    } else {
-      Prism.highlightElement(element);
-    }
+    Prism.highlightElement(element);
+  });
+};
+
+const applyExternalLinkAttributes = (container) => {
+  container.querySelectorAll("a[href]").forEach((link) => {
+    if (link.getAttribute("href").startsWith("#")) return;
+    link.setAttribute("target", "_blank");
+    link.setAttribute("rel", "noreferrer");
   });
 };
 
@@ -39,29 +36,13 @@ const InstructionsStep = ({
 }) => {
   const stepContent = useRef();
 
-  useEffect(() => {
-    Prism.manual = true;
-    if (Prism.plugins.NormalizeWhitespace) {
-      Prism.plugins.NormalizeWhitespace.setDefaults({
-        "remove-indent": false,
-        "remove-initial-line-feed": true,
-        "left-trim": false,
-      });
-      Prism.hooks.add("before-sanity-check", function (env) {
-        if (!env.code) return;
-
-        // Remove multiple leading blank lines (empty or whitespace-only)
-        env.code = env.code.replace(/^(?:\s*\n)+/, "");
-      });
-    }
-  }, []);
-
   useEffect(() => {
     if (!stepContent.current || !step) return;
 
     stepContent.current.parentElement?.scrollTo({ top: 0 });
     stepContent.current.innerHTML = getStepHtml(step);
     applySyntaxHighlighting(stepContent.current);
+    applyExternalLinkAttributes(stepContent.current);
 
     if (isScratchProject) {
       scratchblocksInit(language, stepContent.current);

src/components/Menus/Sidebar/InstructionsPanel/InstructionsStep/InstructionsStep.test.jsx

@@ -1,5 +1,5 @@
 import { render, screen } from "@testing-library/react";
-import Prism from "prismjs";
+import Prism from "../../../../../utils/prism";
 import InstructionsStep from "./InstructionsStep";
 import { scratchblocksInit } from "../../../../../utils/scratchblocks";
 
@@ -47,6 +47,39 @@ describe("When the step has markdown_content", () => {
   });
 });
 
+describe("When markdown attaches a class to inline code", () => {
+  const renderMarkdown = (markdown_content) =>
+    render(<InstructionsStep step={{ markdown_content }} />).container;
+
+  const scratchBlockClasses = [
+    "block3control",
+    "block3events",
+    "block3extensions",
+    "block3looks",
+    "block3motion",
+    "block3myblocks",
+    "block3operators",
+    "block3sensing",
+    "block3sound",
+    "block3variables",
+  ];
+
+  test.each(scratchBlockClasses)("Applies %s to the code element", (name) => {
+    const container = renderMarkdown(`\`Move\`{:class="${name}"}`);
+
+    const code = container.querySelector("code");
+    expect(code).toHaveClass(name);
+    expect(code).toHaveTextContent("Move");
+  });
+
+  test("Consumes the attribute syntax instead of rendering it", () => {
+    const container = renderMarkdown('`Motion`{:class="block3motion"}');
+
+    expect(container.textContent).toContain("Motion");
+    expect(container.textContent).not.toContain("{:class");
+  });
+});
+
 describe("When there is no step", () => {
   test("Renders without crashing", () => {
     const { container } = render(<InstructionsStep step={undefined} />);
@@ -66,23 +99,6 @@ describe("Syntax highlighting", () => {
     const codeElement = document.getElementsByClassName("language-python")[0];
     expect(Prism.highlightElement).toHaveBeenCalledWith(codeElement);
   });
-
-  test("Uses window.syntaxHighlight when defined", () => {
-    window.syntaxHighlight = { highlightElement: vi.fn() };
-
-    render(
-      <InstructionsStep
-        step={{ content: "<code class='language-python'>print(1)</code>" }}
-      />,
-    );
-
-    const codeElement = document.getElementsByClassName("language-python")[0];
-    expect(window.syntaxHighlight.highlightElement).toHaveBeenCalledWith(
-      codeElement,
-    );
-
-    delete window.syntaxHighlight;
-  });
 });
 
 describe("When isScratchProject is true", () => {

src/containers/WebComponentLoader.jsx

@@ -204,24 +204,6 @@ const WebComponentLoader = (props) => {
     dispatch(setOfflineEnabled(offlineEnabled));
   }, [offlineEnabled, dispatch]);
 
-  useEffect(() => {
-    // Create a script element to save the existing Prism object if there is one
-    const script = document.createElement("script");
-    script.textContent = `
-      if (window.Prism) {
-        window.syntaxHighlight = window.Prism;
-      }
-    `;
-
-    // Append the script to the document body
-    document.body.appendChild(script);
-
-    // Clean up the script when the component unmounts
-    return () => {
-      document.body.removeChild(script);
-    };
-  }, []);
-
   const renderSuccessState = () => (
     <>
       <SettingsContext.Provider

src/containers/WebComponentLoader.test.jsx

@@ -57,7 +57,6 @@ const user = { access_token: "my_token" };
 describe("When initially rendered", () => {
   beforeEach(() => {
     document.dispatchEvent = jest.fn();
-    window.Prism = jest.fn();
     const mockStore = configureStore([]);
     const initialState = {
       editor: {
@@ -103,10 +102,6 @@ describe("When initially rendered", () => {
     );
   });
 
-  test("It saves window.Prism to window.syntaxHighlight", () => {
-    expect(window.syntaxHighlight).toEqual(window.Prism);
-  });
-
   test("it sets the language in i18n", () => {
     expect(mockedChangeLanguage).toHaveBeenCalledWith("es-LA");
   });