jupyterlab_markdown_syntax_rendering_fix 0.6.9

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Stellars Henson
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,47 @@
+# jupyterlab_markdown_syntax_rendering_fix
+
+[![GitHub Actions](https://github.com/stellarshenson/jupyterlab_markdown_syntax_rendering_fix/actions/workflows/build.yml/badge.svg)](https://github.com/stellarshenson/jupyterlab_markdown_syntax_rendering_fix/actions/workflows/build.yml)
+[![npm version](https://img.shields.io/npm/v/jupyterlab_markdown_syntax_rendering_fix.svg)](https://www.npmjs.com/package/jupyterlab_markdown_syntax_rendering_fix)
+[![PyPI version](https://img.shields.io/pypi/v/jupyterlab-markdown-syntax-rendering-fix.svg)](https://pypi.org/project/jupyterlab-markdown-syntax-rendering-fix/)
+[![Total PyPI downloads](https://static.pepy.tech/badge/jupyterlab-markdown-syntax-rendering-fix)](https://pepy.tech/project/jupyterlab-markdown-syntax-rendering-fix)
+[![JupyterLab 4](https://img.shields.io/badge/JupyterLab-4-orange.svg)](https://jupyterlab.readthedocs.io/en/stable/)
+[![Brought To You By KOLOMOLO](https://img.shields.io/badge/Brought%20To%20You%20By-KOLOMOLO-00ffff?style=flat)](https://kolomolo.com)
+[![Donate PayPal](https://img.shields.io/badge/Donate-PayPal-blue?style=flat)](https://www.paypal.com/donate/?hosted_button_id=B4KPBJDLLXTSA)
+
+Fenced code blocks in rendered Markdown sometimes appear plain and uncoloured - the highlighting silently fails when a CodeMirror language chunk loads late or the language registry is not yet ready, and JupyterLab falls back to plain text. This extension restores the highlighting that was lost to that race.
+
+## Features
+
+- **Recovers lost highlighting** - re-applies syntax highlighting to fenced code blocks that rendered plain because the async highlighter missed the cache
+- **Language agnostic** - works for any fenced language (bash, python, json, ...), independent of mermaid
+- **Targets the cold-load race** - handles the case where a language chunk imports late or the registry is wired after an early render
+- **Frontend only** - pure TypeScript labextension, no server component
+
+## How it works
+
+JupyterLab highlights fenced code in rendered Markdown with an async pass that fills a cache and a synchronous renderer that reads it. When the async highlight throws - a CodeMirror language-chunk import that rejects, or a registry that is not yet wired when an early render fires - the cache misses and the renderer emits a plain `<pre><code>`. This extension watches the application shell for those plain blocks and re-runs the highlight once the language is available.
+
+- **Detect** - a `MutationObserver` flags any rendered `pre > code` that has a `language-*` class and text but no token `<span>` children
+- **Recover** - re-runs the highlight through `IEditorLanguageRegistry` and swaps in the token spans, only when the highlighted text matches the source exactly so it never truncates content
+- **Resilient** - retries a thrown highlight a few times with backoff while the language chunk finishes loading, then gives up cleanly and leaves the original plain text untouched
+- **Unobtrusive** - each block is handled at most once, and editor and overlay churn is skipped to keep the observer cheap
+
+## Requirements
+
+- JupyterLab >= 4.0.0
+
+## Install
+
+To install the extension, execute:
+
+```bash
+pip install jupyterlab_markdown_syntax_rendering_fix
+```
+
+## Uninstall
+
+To remove the extension, execute:
+
+```bash
+pip uninstall jupyterlab_markdown_syntax_rendering_fix
+```

package/lib/highlight.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure DOM helpers for detecting fenced code blocks that rendered without
+ * syntax highlighting. Kept free of JupyterLab imports so they can be unit
+ * tested directly.
+ */
+/**
+ * Attribute marking a code block this extension has already handled, so the
+ * MutationObserver never re-processes the same block.
+ */
+export declare const PROCESSED_ATTR = "data-msrf";
+/**
+ * Fenced languages rendered by their own renderer (e.g. mermaid -> SVG). They
+ * are never plain `pre > code` highlight candidates, so leave them untouched.
+ */
+export declare const SKIP_LANGUAGES: Set<string>;
+/**
+ * Extract the CodeMirror language name from a `language-<name>` class token.
+ * Returns null when no such class is present.
+ */
+export declare function languageFromClass(className: string): string | null;
+/**
+ * A rendered fenced code block has lost its syntax highlighting when it carries
+ * a `language-*` class and non-empty text, yet has no child elements - the
+ * async highlighter threw and the markdown renderer fell back to a plain
+ * `<pre><code>` (cache miss). A correctly highlighted block holds token
+ * `<span>` children, so `childElementCount > 0`.
+ */
+export declare function needsHighlight(code: HTMLElement): boolean;
+/**
+ * Collect the plain `pre > code.language-*` blocks at or under `root` that need
+ * their highlighting recovered. `root` itself is considered, since
+ * `querySelectorAll` only matches descendants and an observer may hand us the
+ * `<code>` element directly.
+ */
+export declare function collectPlainBlocks(root: ParentNode): HTMLElement[];

package/lib/highlight.js

@@ -0,0 +1,62 @@
+/**
+ * Pure DOM helpers for detecting fenced code blocks that rendered without
+ * syntax highlighting. Kept free of JupyterLab imports so they can be unit
+ * tested directly.
+ */
+/**
+ * Attribute marking a code block this extension has already handled, so the
+ * MutationObserver never re-processes the same block.
+ */
+export const PROCESSED_ATTR = 'data-msrf';
+/**
+ * Fenced languages rendered by their own renderer (e.g. mermaid -> SVG). They
+ * are never plain `pre > code` highlight candidates, so leave them untouched.
+ */
+export const SKIP_LANGUAGES = new Set(['mermaid']);
+/**
+ * Extract the CodeMirror language name from a `language-<name>` class token.
+ * Returns null when no such class is present.
+ */
+export function languageFromClass(className) {
+    const match = /(?:^|\s)language-([\w+#-]+)/.exec(className);
+    return match ? match[1] : null;
+}
+/**
+ * A rendered fenced code block has lost its syntax highlighting when it carries
+ * a `language-*` class and non-empty text, yet has no child elements - the
+ * async highlighter threw and the markdown renderer fell back to a plain
+ * `<pre><code>` (cache miss). A correctly highlighted block holds token
+ * `<span>` children, so `childElementCount > 0`.
+ */
+export function needsHighlight(code) {
+    var _a;
+    if (code.hasAttribute(PROCESSED_ATTR) || code.childElementCount > 0) {
+        return false;
+    }
+    const language = languageFromClass(code.className);
+    if (!language || SKIP_LANGUAGES.has(language)) {
+        return false;
+    }
+    return ((_a = code.textContent) !== null && _a !== void 0 ? _a : '').trim().length > 0;
+}
+/** CSS selector for a fenced code block carrying a language hint. */
+const CODE_SELECTOR = 'pre > code[class*="language-"]';
+/**
+ * Collect the plain `pre > code.language-*` blocks at or under `root` that need
+ * their highlighting recovered. `root` itself is considered, since
+ * `querySelectorAll` only matches descendants and an observer may hand us the
+ * `<code>` element directly.
+ */
+export function collectPlainBlocks(root) {
+    const blocks = [];
+    const consider = (code) => {
+        if (needsHighlight(code)) {
+            blocks.push(code);
+        }
+    };
+    if (root instanceof HTMLElement && root.matches(CODE_SELECTOR)) {
+        consider(root);
+    }
+    root.querySelectorAll(CODE_SELECTOR).forEach(consider);
+    return blocks;
+}

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+/**
+ * Initialization data for the jupyterlab_markdown_syntax_rendering_fix extension.
+ */
+declare const plugin: JupyterFrontEndPlugin<void>;
+export default plugin;

package/lib/index.js

@@ -0,0 +1,146 @@
+import { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
+import { PROCESSED_ATTR, collectPlainBlocks, languageFromClass } from './highlight';
+/** How many times to attempt recovery (only a thrown highlight is retried). */
+const MAX_ATTEMPTS = 4;
+/** Base retry delay; backs off 750/1500/3000ms (~5s total) so a slow chunk import can settle. */
+const BASE_RETRY_DELAY_MS = 750;
+/** Blocks currently being recovered, to dedupe concurrent observer callbacks. */
+const inFlight = new WeakSet();
+const delay = (ms) => new Promise(resolve => {
+    window.setTimeout(resolve, ms);
+});
+/**
+ * Recover highlighting on a single plain block, and mark it with a terminal
+ * `data-msrf` state so it is processed at most once:
+ *
+ * - `1`       success - token spans written
+ * - `plain`   highlight ran cleanly but produced no tokens (span-less content) -
+ *             not a failure, the original plain text is left untouched
+ * - `skipped` the language is unsupported (`findBest` miss) - deterministic, so
+ *             no retry and no warning
+ * - `failed`  the highlight threw on every attempt - left as plain text, no
+ *             regression vs without this extension
+ *
+ * Only a thrown highlight is retried, since that is the one transient case (a
+ * cold/flaky CodeMirror language-chunk import). Retrying is effective, not
+ * theatre: `highlight()` awaits `getLanguage()` internally, which caches the
+ * loaded support on the spec only on success (`spec.support = await spec.load()`)
+ * - a rejected load throws and leaves `spec.support` unset, and webpack resets a
+ * failed chunk load, so each attempt genuinely re-runs the dynamic import.
+ * Retries back off over ~5s; a chunk that never loads within that window stays
+ * plain until the block is re-rendered (reload / reopen). Concurrent callbacks
+ * are deduped via `inFlight`.
+ */
+async function rehighlight(code, languages) {
+    var _a;
+    const language = languageFromClass(code.className);
+    if (!language || inFlight.has(code) || code.hasAttribute(PROCESSED_ATTR)) {
+        return;
+    }
+    const text = (_a = code.textContent) !== null && _a !== void 0 ? _a : '';
+    inFlight.add(code);
+    try {
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+            const spec = languages.findBest(language);
+            if (!spec) {
+                // Unsupported language - a synchronous registry miss is deterministic,
+                // so retrying cannot help. Leave it plain, no warning.
+                code.setAttribute(PROCESSED_ATTR, 'skipped');
+                return;
+            }
+            const host = document.createElement('div');
+            try {
+                await languages.highlight(text, spec, host);
+            }
+            catch (_b) {
+                // The one retryable case: a transient chunk-load flake.
+                if (attempt < MAX_ATTEMPTS) {
+                    await delay(BASE_RETRY_DELAY_MS * 2 ** (attempt - 1));
+                    // The host may have been re-rendered during the back-off; a fresh node
+                    // is handled independently, so stop working this detached one.
+                    if (!code.isConnected) {
+                        return;
+                    }
+                    continue;
+                }
+                code.setAttribute(PROCESSED_ATTR, 'failed');
+                console.warn(`[jupyterlab_markdown_syntax_rendering_fix] gave up re-highlighting ${language} after ${MAX_ATTEMPTS} attempts`);
+                return;
+            }
+            // The node may have been re-rendered during the await; a fresh node is
+            // handled independently, so don't write to a detached one.
+            if (!code.isConnected) {
+                return;
+            }
+            // Highlight ran without throwing. Commit the swap only when the rendered
+            // text round-trips exactly - never replace the block with a truncated or
+            // divergent fragment (worse than leaving it plain). An empty result is
+            // deterministic for the content (a parser that failed to load throws
+            // rather than resolving empty), so it is terminal, not retried.
+            if (host.childElementCount > 0 && host.textContent === text) {
+                // Set the marker in the same synchronous frame as the write so the
+                // observer's async callback sees data-msrf and skips the spans we add.
+                code.setAttribute(PROCESSED_ATTR, '1');
+                code.replaceChildren(...Array.from(host.childNodes));
+            }
+            else {
+                if (host.childElementCount > 0) {
+                    // Spans were produced but the text did not round-trip - surface this
+                    // rare case rather than silently suppressing a possibly-correct render.
+                    console.warn(`[jupyterlab_markdown_syntax_rendering_fix] skipped re-highlight of ${language}: highlighted text did not match source`);
+                }
+                code.setAttribute(PROCESSED_ATTR, 'plain');
+            }
+            return;
+        }
+    }
+    finally {
+        inFlight.delete(code);
+    }
+}
+/**
+ * Initialization data for the jupyterlab_markdown_syntax_rendering_fix extension.
+ */
+const plugin = {
+    id: 'jupyterlab_markdown_syntax_rendering_fix:plugin',
+    description: 'Jupyterlab extension to fix a common issue with Markdown renderer where some race condition causes for the fenced code block to not have proper syntax highlighting',
+    autoStart: true,
+    requires: [IEditorLanguageRegistry],
+    activate: (app, languages) => {
+        console.log('JupyterLab extension jupyterlab_markdown_syntax_rendering_fix is activated!');
+        const scan = (root) => {
+            for (const code of collectPlainBlocks(root)) {
+                rehighlight(code, languages).catch(error => {
+                    console.warn('[jupyterlab_markdown_syntax_rendering_fix] unexpected error while re-highlighting', error);
+                });
+            }
+        };
+        const observer = new MutationObserver(mutations => {
+            for (const mutation of mutations) {
+                mutation.addedNodes.forEach(node => {
+                    if (node.nodeType !== Node.ELEMENT_NODE) {
+                        return;
+                    }
+                    const element = node;
+                    // Skip pure observer churn: CodeMirror editors mutate on every
+                    // keystroke and never hold rendered markdown, and the token spans this
+                    // extension itself writes land under an already-processed code block.
+                    if (element.closest('.cm-editor, code[data-msrf]')) {
+                        return;
+                    }
+                    scan(element);
+                });
+            }
+        });
+        // Observe the application shell rather than document.body: rendered markdown
+        // lives in the shell (notebook cells, markdown preview). Markdown rendered in
+        // body-level overlays (completer / hover docstrings) is intentionally not
+        // covered - a deliberate tradeoff to avoid observing the high-churn overlay
+        // layer; such code blocks recover on the next in-shell render or a reload.
+        const root = app.shell.node;
+        observer.observe(root, { childList: true, subtree: true });
+        // Recover any markdown already rendered before this extension activated.
+        scan(root);
+    }
+};
+export default plugin;

package/package.json

@@ -0,0 +1,140 @@
+{
+    "name": "jupyterlab_markdown_syntax_rendering_fix",
+    "version": "0.6.9",
+    "description": "Jupyterlab extension to fix a common issue with Markdown renderer where some race condition causes for the fenced code block to not have proper syntax highlighting",
+    "keywords": [
+        "jupyter",
+        "jupyterlab",
+        "jupyterlab-extension"
+    ],
+    "homepage": "https://github.com/stellarshenson/jupyterlab_markdown_syntax_rendering_fix",
+    "bugs": {
+        "url": "https://github.com/stellarshenson/jupyterlab_markdown_syntax_rendering_fix/issues"
+    },
+    "license": "BSD-3-Clause",
+    "author": {
+        "name": "Stellars Henson",
+        "email": "konrad.jelen+github@gmail.com"
+    },
+    "files": [
+        "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
+        "style/**/*.{css,js,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
+        "src/**/*.{ts,tsx}"
+    ],
+    "main": "lib/index.js",
+    "types": "lib/index.d.ts",
+    "style": "style/index.css",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/stellarshenson/jupyterlab_markdown_syntax_rendering_fix.git"
+    },
+    "scripts": {
+        "build": "jlpm build:lib && jlpm build:labextension:dev",
+        "build:prod": "jlpm clean && jlpm build:lib:prod && jlpm build:labextension",
+        "build:labextension": "jupyter-builder build .",
+        "build:labextension:dev": "jupyter-builder build --development True .",
+        "build:lib": "tsc --sourceMap",
+        "build:lib:prod": "tsc",
+        "clean": "jlpm clean:lib",
+        "clean:lib": "rimraf lib tsconfig.tsbuildinfo",
+        "clean:lintcache": "rimraf .eslintcache .stylelintcache",
+        "clean:labextension": "rimraf jupyterlab_markdown_syntax_rendering_fix/labextension jupyterlab_markdown_syntax_rendering_fix/_version.py",
+        "clean:all": "jlpm clean:lib && jlpm clean:labextension && jlpm clean:lintcache",
+        "eslint": "jlpm eslint:check --fix",
+        "eslint:check": "eslint . --cache",
+        "install:extension": "jlpm build",
+        "lint": "jlpm stylelint && jlpm prettier && jlpm eslint",
+        "lint:check": "jlpm stylelint:check && jlpm prettier:check && jlpm eslint:check",
+        "prettier": "jlpm prettier:base --write --list-different",
+        "prettier:base": "prettier \"**/*{.ts,.tsx,.js,.jsx,.css,.json,.md}\"",
+        "prettier:check": "jlpm prettier:base --check",
+        "stylelint": "jlpm stylelint:check --fix",
+        "stylelint:check": "stylelint --cache \"style/**/*.css\"",
+        "test": "jest --coverage",
+        "watch": "run-p watch:src watch:labextension",
+        "watch:src": "tsc -w --sourceMap",
+        "watch:labextension": "jupyter-builder watch ."
+    },
+    "dependencies": {
+        "@jupyterlab/application": "^4.0.0",
+        "@jupyterlab/codemirror": "^4.0.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.0.0",
+        "@jupyter/builder": "^1.0.0",
+        "@jupyter/eslint-plugin": "^0.0.5",
+        "@jupyterlab/testutils": "^4.0.0",
+        "@types/jest": "^29.2.0",
+        "@types/json-schema": "^7.0.11",
+        "@types/react": "^18.0.26",
+        "@types/react-addons-linked-state-mixin": "^0.14.22",
+        "eslint": "^9.0.0",
+        "eslint-config-prettier": "^9.0.0",
+        "eslint-plugin-prettier": "^5.0.0",
+        "globals": "^15.0.0",
+        "jest": "^29.2.0",
+        "npm-run-all2": "^7.0.1",
+        "prettier": "^3.0.0",
+        "rimraf": "^5.0.1",
+        "stylelint": "^15.10.1",
+        "stylelint-config-recommended": "^13.0.0",
+        "stylelint-config-standard": "^34.0.0",
+        "stylelint-csstree-validator": "^3.0.0",
+        "stylelint-prettier": "^4.0.0",
+        "typescript": "~5.8.0",
+        "typescript-eslint": "^8.0.0",
+        "yjs": "^13.5.0"
+    },
+    "resolutions": {
+        "lib0": "0.2.111",
+        "webpack": "5.106.0",
+        "chalk": "4.1.2"
+    },
+    "overrides": {
+        "webpack": "5.106.0",
+        "chalk": "4.1.2"
+    },
+    "sideEffects": [
+        "style/*.css",
+        "style/index.js"
+    ],
+    "styleModule": "style/index.js",
+    "publishConfig": {
+        "access": "public"
+    },
+    "jupyterlab": {
+        "extension": true,
+        "outputDir": "jupyterlab_markdown_syntax_rendering_fix/labextension"
+    },
+    "prettier": {
+        "singleQuote": true,
+        "trailingComma": "none",
+        "arrowParens": "avoid",
+        "endOfLine": "auto",
+        "overrides": [
+            {
+                "files": "package.json",
+                "options": {
+                    "tabWidth": 4
+                }
+            }
+        ]
+    },
+    "stylelint": {
+        "extends": [
+            "stylelint-config-recommended",
+            "stylelint-config-standard",
+            "stylelint-prettier/recommended"
+        ],
+        "plugins": [
+            "stylelint-csstree-validator"
+        ],
+        "rules": {
+            "csstree/validator": true,
+            "property-no-vendor-prefix": null,
+            "selector-class-pattern": "^([a-z][A-z\\d]*)(-[A-z\\d]+)*$",
+            "selector-no-vendor-prefix": null,
+            "value-no-vendor-prefix": null
+        }
+    }
+}

package/src/__tests__/jupyterlab_markdown_syntax_rendering_fix.spec.ts

@@ -0,0 +1,100 @@
+import {
+  PROCESSED_ATTR,
+  collectPlainBlocks,
+  languageFromClass,
+  needsHighlight
+} from '../highlight';
+
+/** Build a `pre > code` block with the given class and inner HTML. */
+function block(className: string, inner: string): HTMLElement {
+  const pre = document.createElement('pre');
+  const code = document.createElement('code');
+  code.className = className;
+  code.innerHTML = inner;
+  pre.appendChild(code);
+  return code;
+}
+
+describe('languageFromClass', () => {
+  it('extracts the language from a language-* class', () => {
+    expect(languageFromClass('language-bash')).toBe('bash');
+  });
+
+  it('finds the token among other classes', () => {
+    expect(languageFromClass('hljs language-python foo')).toBe('python');
+  });
+
+  it('keeps symbol-bearing language names', () => {
+    expect(languageFromClass('language-c++')).toBe('c++');
+    expect(languageFromClass('language-c#')).toBe('c#');
+  });
+
+  it('returns null without a language class', () => {
+    expect(languageFromClass('hljs')).toBeNull();
+    expect(languageFromClass('')).toBeNull();
+  });
+});
+
+describe('needsHighlight', () => {
+  it('flags a plain block with a language and text', () => {
+    expect(needsHighlight(block('language-bash', 'pip install x'))).toBe(true);
+  });
+
+  it('ignores a block that already has token spans', () => {
+    expect(
+      needsHighlight(block('language-bash', '<span class="tok">pip</span>'))
+    ).toBe(false);
+  });
+
+  it('ignores an already-processed block', () => {
+    const code = block('language-bash', 'pip install x');
+    code.setAttribute(PROCESSED_ATTR, '1');
+    expect(needsHighlight(code)).toBe(false);
+  });
+
+  it('ignores blocks without a language class', () => {
+    expect(needsHighlight(block('', 'plain text'))).toBe(false);
+  });
+
+  it('ignores empty or whitespace-only blocks', () => {
+    expect(needsHighlight(block('language-bash', '   '))).toBe(false);
+  });
+
+  it('skips languages owned by other renderers (mermaid)', () => {
+    expect(needsHighlight(block('language-mermaid', 'graph TD; A-->B'))).toBe(
+      false
+    );
+  });
+});
+
+describe('collectPlainBlocks', () => {
+  it('returns only the plain language blocks under a root', () => {
+    const root = document.createElement('div');
+    root.appendChild(block('language-bash', 'echo hi').parentElement!);
+    root.appendChild(
+      block('language-python', '<span class="tok">import os</span>')
+        .parentElement!
+    );
+    root.appendChild(block('language-json', '{"a": 1}').parentElement!);
+    root.appendChild(
+      block('language-mermaid', 'graph TD; A-->B').parentElement!
+    );
+
+    const found = collectPlainBlocks(root);
+    const langs = found.map(c => languageFromClass(c.className));
+    expect(langs).toEqual(['bash', 'json']);
+  });
+
+  it('matches a bare code element passed as the root', () => {
+    const code = block('language-bash', 'echo hi');
+    expect(collectPlainBlocks(code)).toEqual([code]);
+  });
+
+  it('returns an empty list when everything is already highlighted', () => {
+    const root = document.createElement('div');
+    root.appendChild(
+      block('language-bash', '<span class="tok">echo</span>').parentElement!
+    );
+    expect(collectPlainBlocks(root)).toHaveLength(0);
+  });
+});

package/src/highlight.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure DOM helpers for detecting fenced code blocks that rendered without
+ * syntax highlighting. Kept free of JupyterLab imports so they can be unit
+ * tested directly.
+ */
+
+/**
+ * Attribute marking a code block this extension has already handled, so the
+ * MutationObserver never re-processes the same block.
+ */
+export const PROCESSED_ATTR = 'data-msrf';
+
+/**
+ * Fenced languages rendered by their own renderer (e.g. mermaid -> SVG). They
+ * are never plain `pre > code` highlight candidates, so leave them untouched.
+ */
+export const SKIP_LANGUAGES = new Set(['mermaid']);
+
+/**
+ * Extract the CodeMirror language name from a `language-<name>` class token.
+ * Returns null when no such class is present.
+ */
+export function languageFromClass(className: string): string | null {
+  const match = /(?:^|\s)language-([\w+#-]+)/.exec(className);
+  return match ? match[1] : null;
+}
+
+/**
+ * A rendered fenced code block has lost its syntax highlighting when it carries
+ * a `language-*` class and non-empty text, yet has no child elements - the
+ * async highlighter threw and the markdown renderer fell back to a plain
+ * `<pre><code>` (cache miss). A correctly highlighted block holds token
+ * `<span>` children, so `childElementCount > 0`.
+ */
+export function needsHighlight(code: HTMLElement): boolean {
+  if (code.hasAttribute(PROCESSED_ATTR) || code.childElementCount > 0) {
+    return false;
+  }
+  const language = languageFromClass(code.className);
+  if (!language || SKIP_LANGUAGES.has(language)) {
+    return false;
+  }
+  return (code.textContent ?? '').trim().length > 0;
+}
+
+/** CSS selector for a fenced code block carrying a language hint. */
+const CODE_SELECTOR = 'pre > code[class*="language-"]';
+
+/**
+ * Collect the plain `pre > code.language-*` blocks at or under `root` that need
+ * their highlighting recovered. `root` itself is considered, since
+ * `querySelectorAll` only matches descendants and an observer may hand us the
+ * `<code>` element directly.
+ */
+export function collectPlainBlocks(root: ParentNode): HTMLElement[] {
+  const blocks: HTMLElement[] = [];
+  const consider = (code: HTMLElement): void => {
+    if (needsHighlight(code)) {
+      blocks.push(code);
+    }
+  };
+  if (root instanceof HTMLElement && root.matches(CODE_SELECTOR)) {
+    consider(root);
+  }
+  root.querySelectorAll<HTMLElement>(CODE_SELECTOR).forEach(consider);
+  return blocks;
+}

package/src/index.ts

@@ -0,0 +1,175 @@
+import {
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
+import {
+  PROCESSED_ATTR,
+  collectPlainBlocks,
+  languageFromClass
+} from './highlight';
+
+/** How many times to attempt recovery (only a thrown highlight is retried). */
+const MAX_ATTEMPTS = 4;
+
+/** Base retry delay; backs off 750/1500/3000ms (~5s total) so a slow chunk import can settle. */
+const BASE_RETRY_DELAY_MS = 750;
+
+/** Blocks currently being recovered, to dedupe concurrent observer callbacks. */
+const inFlight = new WeakSet<HTMLElement>();
+
+const delay = (ms: number): Promise<void> =>
+  new Promise(resolve => {
+    window.setTimeout(resolve, ms);
+  });
+
+/**
+ * Recover highlighting on a single plain block, and mark it with a terminal
+ * `data-msrf` state so it is processed at most once:
+ *
+ * - `1`       success - token spans written
+ * - `plain`   highlight ran cleanly but produced no tokens (span-less content) -
+ *             not a failure, the original plain text is left untouched
+ * - `skipped` the language is unsupported (`findBest` miss) - deterministic, so
+ *             no retry and no warning
+ * - `failed`  the highlight threw on every attempt - left as plain text, no
+ *             regression vs without this extension
+ *
+ * Only a thrown highlight is retried, since that is the one transient case (a
+ * cold/flaky CodeMirror language-chunk import). Retrying is effective, not
+ * theatre: `highlight()` awaits `getLanguage()` internally, which caches the
+ * loaded support on the spec only on success (`spec.support = await spec.load()`)
+ * - a rejected load throws and leaves `spec.support` unset, and webpack resets a
+ * failed chunk load, so each attempt genuinely re-runs the dynamic import.
+ * Retries back off over ~5s; a chunk that never loads within that window stays
+ * plain until the block is re-rendered (reload / reopen). Concurrent callbacks
+ * are deduped via `inFlight`.
+ */
+async function rehighlight(
+  code: HTMLElement,
+  languages: IEditorLanguageRegistry
+): Promise<void> {
+  const language = languageFromClass(code.className);
+  if (!language || inFlight.has(code) || code.hasAttribute(PROCESSED_ATTR)) {
+    return;
+  }
+  const text = code.textContent ?? '';
+  inFlight.add(code);
+  try {
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      const spec = languages.findBest(language);
+      if (!spec) {
+        // Unsupported language - a synchronous registry miss is deterministic,
+        // so retrying cannot help. Leave it plain, no warning.
+        code.setAttribute(PROCESSED_ATTR, 'skipped');
+        return;
+      }
+      const host = document.createElement('div');
+      try {
+        await languages.highlight(text, spec, host);
+      } catch {
+        // The one retryable case: a transient chunk-load flake.
+        if (attempt < MAX_ATTEMPTS) {
+          await delay(BASE_RETRY_DELAY_MS * 2 ** (attempt - 1));
+          // The host may have been re-rendered during the back-off; a fresh node
+          // is handled independently, so stop working this detached one.
+          if (!code.isConnected) {
+            return;
+          }
+          continue;
+        }
+        code.setAttribute(PROCESSED_ATTR, 'failed');
+        console.warn(
+          `[jupyterlab_markdown_syntax_rendering_fix] gave up re-highlighting ${language} after ${MAX_ATTEMPTS} attempts`
+        );
+        return;
+      }
+      // The node may have been re-rendered during the await; a fresh node is
+      // handled independently, so don't write to a detached one.
+      if (!code.isConnected) {
+        return;
+      }
+      // Highlight ran without throwing. Commit the swap only when the rendered
+      // text round-trips exactly - never replace the block with a truncated or
+      // divergent fragment (worse than leaving it plain). An empty result is
+      // deterministic for the content (a parser that failed to load throws
+      // rather than resolving empty), so it is terminal, not retried.
+      if (host.childElementCount > 0 && host.textContent === text) {
+        // Set the marker in the same synchronous frame as the write so the
+        // observer's async callback sees data-msrf and skips the spans we add.
+        code.setAttribute(PROCESSED_ATTR, '1');
+        code.replaceChildren(...Array.from(host.childNodes));
+      } else {
+        if (host.childElementCount > 0) {
+          // Spans were produced but the text did not round-trip - surface this
+          // rare case rather than silently suppressing a possibly-correct render.
+          console.warn(
+            `[jupyterlab_markdown_syntax_rendering_fix] skipped re-highlight of ${language}: highlighted text did not match source`
+          );
+        }
+        code.setAttribute(PROCESSED_ATTR, 'plain');
+      }
+      return;
+    }
+  } finally {
+    inFlight.delete(code);
+  }
+}
+
+/**
+ * Initialization data for the jupyterlab_markdown_syntax_rendering_fix extension.
+ */
+const plugin: JupyterFrontEndPlugin<void> = {
+  id: 'jupyterlab_markdown_syntax_rendering_fix:plugin',
+  description:
+    'Jupyterlab extension to fix a common issue with Markdown renderer where some race condition causes for the fenced code block to not have proper syntax highlighting',
+  autoStart: true,
+  requires: [IEditorLanguageRegistry],
+  activate: (app: JupyterFrontEnd, languages: IEditorLanguageRegistry) => {
+    console.log(
+      'JupyterLab extension jupyterlab_markdown_syntax_rendering_fix is activated!'
+    );
+
+    const scan = (root: ParentNode): void => {
+      for (const code of collectPlainBlocks(root)) {
+        rehighlight(code, languages).catch(error => {
+          console.warn(
+            '[jupyterlab_markdown_syntax_rendering_fix] unexpected error while re-highlighting',
+            error
+          );
+        });
+      }
+    };
+
+    const observer = new MutationObserver(mutations => {
+      for (const mutation of mutations) {
+        mutation.addedNodes.forEach(node => {
+          if (node.nodeType !== Node.ELEMENT_NODE) {
+            return;
+          }
+          const element = node as HTMLElement;
+          // Skip pure observer churn: CodeMirror editors mutate on every
+          // keystroke and never hold rendered markdown, and the token spans this
+          // extension itself writes land under an already-processed code block.
+          if (element.closest('.cm-editor, code[data-msrf]')) {
+            return;
+          }
+          scan(element);
+        });
+      }
+    });
+
+    // Observe the application shell rather than document.body: rendered markdown
+    // lives in the shell (notebook cells, markdown preview). Markdown rendered in
+    // body-level overlays (completer / hover docstrings) is intentionally not
+    // covered - a deliberate tradeoff to avoid observing the high-churn overlay
+    // layer; such code blocks recover on the next in-shell render or a reload.
+    const root = app.shell.node;
+    observer.observe(root, { childList: true, subtree: true });
+
+    // Recover any markdown already rendered before this extension activated.
+    scan(root);
+  }
+};
+
+export default plugin;

package/style/base.css

@@ -0,0 +1,5 @@
+/*
+    See the JupyterLab Developer Guide for useful CSS Patterns:
+
+    https://jupyterlab.readthedocs.io/en/stable/developer/css.html
+*/

package/style/index.css

@@ -0,0 +1 @@
+@import url('base.css');

package/style/index.js

@@ -0,0 +1 @@
+import './base.css';