Update to marked 7.0.2, add mermaidjs 10.3.1

galata/test/jupyterlab/notebook-markdown.test.ts

@@ -75,4 +75,18 @@ test.describe('Notebook Markdown', () => {
       imageName
     );
   });
+
+  test('Render a MermaidJS flowchart', async ({ page, tmpPath }) => {
+    await page.notebook.openByPath(`${tmpPath}/${fileName}`);
+    const imageName = 'render-mermaid-flowchart.png';
+    const cell = await page.notebook.getCell(3);
+    expect(await cell.screenshot()).toMatchSnapshot(imageName);
+  });
+
+  test('Render a MermaidJS error', async ({ page, tmpPath }) => {
+    await page.notebook.openByPath(`${tmpPath}/${fileName}`);
+    const imageName = 'render-mermaid-error.png';
+    const cell = await page.notebook.getCell(4);
+    expect(await cell.screenshot()).toMatchSnapshot(imageName);
+  });
 });

galata/test/jupyterlab/notebooks/markdown_notebook.ipynb

@@ -77,6 +77,34 @@
     "$ ls\n",
     "```"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Demonstration of MermaidJS\n",
+    "\n",
+    "Below is a diagram of a chicken and an egg.\n",
+    "\n",
+    "```mermaid\n",
+    "flowchart LR\n",
+    "  chicken --> egg --> chicken\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Broken MermaidJS\n",
+    "\n",
+    "Below is a broken diagram.\n",
+    "\n",
+    "```mermaid\n",
+    "flowchart LR\n",
+    "  chicken --> egg --> \n",
+    "```"
+   ]
   }
  ],
  "metadata": {
@@ -95,7 +123,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.3"
+   "version": "3.11.0"
   }
  },
  "nbformat": 4,

packages/markedparser-extension/package.json

@@ -24,6 +24,7 @@
   },
   "files": [
     "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
+    "style/base.css",
     "style/index.css",
     "style/index.js",
     "src/**/*.{ts,tsx}"
@@ -36,12 +37,17 @@
   },
   "dependencies": {
     "@jupyterlab/application": "^4.0.0-alpha.19",
+    "@jupyterlab/apputils": "^4.0.0-alpha.19",
     "@jupyterlab/codemirror": "^4.0.0-alpha.19",
     "@jupyterlab/rendermime": "^4.0.0-alpha.19",
-    "marked": "^4.0.17"
+    "@lumino/coreutils": "^2.0.0-rc.0",
+    "marked": "^4.2.12",
+    "mermaid": "^10.0.0"
   },
   "devDependencies": {
-    "@types/marked": "^4.0.3",
+    "@types/d3": "^7.4.0",
+    "@types/dompurify": "^2.4.0",
+    "@types/marked": "^4.0.8",
     "rimraf": "~3.0.0",
     "typescript": "~5.0.0-beta"
   },

packages/markedparser-extension/src/index.ts

@@ -7,13 +7,23 @@
  * @module markedparser-extension
  */
 
+import { PromiseDelegate } from '@lumino/coreutils';
+
 import {
   JupyterFrontEnd,
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
+import { IThemeManager } from '@jupyterlab/apputils';
 import { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
 import { IMarkdownParser } from '@jupyterlab/rendermime';
-import { marked } from 'marked';
+
+import type { marked, Renderer } from 'marked';
+import type mermaid from 'mermaid';
+
+const FENCE = '```~~~';
+const MAX_CACHE = 256;
+const MERMAID_CLASS = 'jp-RenderedMermaid';
+const ERROR_CLASS = 'jp-mod-error';
 
 /**
  * The markdown parser plugin.
@@ -22,20 +32,16 @@ const plugin: JupyterFrontEndPlugin<IMarkdownParser> = {
   id: '@jupyterlab/markedparser-extension:plugin',
   autoStart: true,
   provides: IMarkdownParser,
-  requires: [IEditorLanguageRegistry],
-  activate: (app: JupyterFrontEnd, languages: IEditorLanguageRegistry) => {
-    Private.initializeMarked(languages);
+  requires: [IEditorLanguageRegistry, IThemeManager],
+  activate: (
+    app: JupyterFrontEnd,
+    languages: IEditorLanguageRegistry,
+    themes: IThemeManager
+  ) => {
     return {
-      render: (content: string): Promise<string> =>
-        new Promise<string>((resolve, reject) => {
-          marked(content, (err: any, content: string) => {
-            if (err) {
-              reject(err);
-            } else {
-              resolve(content);
-            }
-          });
-        })
+      render: async (content: string): Promise<string> => {
+        return await Private.render(content, languages, themes);
+      }
     };
   }
 };
@@ -46,45 +52,207 @@ const plugin: JupyterFrontEndPlugin<IMarkdownParser> = {
 export default plugin;
 
 namespace Private {
-  let markedInitialized = false;
-  export function initializeMarked(languages: IEditorLanguageRegistry): void {
-    if (markedInitialized) {
-      return;
-    } else {
-      markedInitialized = true;
+  let _initializing: PromiseDelegate<typeof marked> | null = null;
+  let _marked: typeof marked | null = null;
+  let _mermaid: typeof mermaid | null = null;
+  let _themes: IThemeManager | null = null;
+  let _languages: IEditorLanguageRegistry | null = null;
+  let _markedOptions: marked.MarkedOptions = {};
+  let _highlights = new Map<string, string>();
+  let _diagrams = new Map<string, string>();
+  let _nextMermaidId = 0;
+
+  export async function render(
+    content: string,
+    languages: IEditorLanguageRegistry,
+    themes: IThemeManager
+  ): Promise<string> {
+    if (!_marked) {
+      _marked = await initializeMarked(languages, themes);
+    }
+    return _marked(content, _markedOptions);
+  }
+
+  /**
+   * Load marked lazily and exactly once.
+   */
+  export async function initializeMarked(
+    languages: IEditorLanguageRegistry,
+    themes: IThemeManager
+  ): Promise<typeof marked> {
+    if (_marked) {
+      return _marked;
+    }
+
+    if (_initializing) {
+      return await _initializing.promise;
     }
 
-    marked.setOptions({
+    _initializing = new PromiseDelegate();
+    _themes = themes;
+    _languages = languages;
+
+    // load marked lazily, and exactly once
+    const { marked, Renderer } = await import('marked');
+
+    // finish marked configuration
+    _markedOptions = {
+      // use the explicit async paradigm for `walkTokens`
+      async: true,
+      // enable all built-in GitHub-flavored Markdown opinions
       gfm: true,
+      // santizing is applied by the sanitizer
       sanitize: false,
-      // breaks: true; We can't use GFM breaks as it causes problems with tables
-      langPrefix: `language-`,
-      highlight: (code, lang, callback) => {
-        const cb = (err: Error | null, code: string) => {
-          if (callback) {
-            callback(err, code);
-          }
-          return code;
-        };
-        if (!lang) {
-          // no language, no highlight
-          return cb(null, code);
-        }
-        const el = document.createElement('div');
-        try {
-          languages
-            .highlight(code, languages.findBest(lang), el)
-            .then(() => {
-              return cb(null, el.innerHTML);
-            })
-            .catch(reason => {
-              return cb(reason, code);
-            });
-        } catch (err) {
-          console.error(`Failed to highlight ${lang} code`, err);
-          return cb(err, code);
-        }
+      // asynchronously prepare for any special tokens, like mermaid and highlighting
+      walkTokens,
+      // use custom renderer
+      renderer: makeRenderer(Renderer)
+    };
+
+    // handle changes to theme (e.g. for mermaid theme)
+    themes.themeChanged.connect(initTheme);
+
+    // complete initialization
+    _marked = marked;
+    _initializing.resolve(_marked);
+    return _marked;
+  }
+
+  /**
+   * Build a custom marked renderer.
+   */
+  function makeRenderer(Renderer_: typeof Renderer): Renderer {
+    const renderer = new Renderer_();
+    const originalCode = renderer.code;
+
+    renderer.code = (code: string, language: string) => {
+      if (language === 'mermaid' && _mermaid) {
+        return cacheGet(_diagrams, code);
       }
-    });
+      const key = `${language}${FENCE}${code}${FENCE}`;
+      const highlight = cacheGet(_highlights, key);
+      if (highlight != null) {
+        return highlight;
+      }
+      // call with the renderer as `this`
+      return originalCode.call(renderer, code, language);
+    };
+
+    return renderer;
+  }
+
+  /**
+   * Apply and cache syntax highlighting for code blocks.
+   */
+  async function highlight(token: marked.Tokens.Code): Promise<void> {
+    const languages = _languages as IEditorLanguageRegistry;
+    const { lang, text } = token;
+    if (!lang) {
+      // no language, no highlight
+      return;
+    }
+    const key = `${lang}${FENCE}${text}${FENCE}`;
+    if (cacheGet(_highlights, key)) {
+      // already cached, don't make another DOM element
+      return;
+    }
+    const el = document.createElement('div');
+    try {
+      await languages.highlight(text, languages.findBest(lang), el);
+      const html = `<pre><code class="language-${lang}">${el.innerHTML}</code></pre>`;
+      cacheSet(_highlights, key, html);
+    } catch (err) {
+      console.error(`Failed to highlight ${lang} code`, err);
+    } finally {
+      el.remove();
+    }
+  }
+
+  /**
+   * After parsing, lazily load and highlight/render code blocks into the cache.
+   */
+  async function walkTokens(token: marked.Token): Promise<void> {
+    switch (token.type) {
+      case 'code':
+        if (token.lang === 'mermaid') {
+          return await handleMermaid(token);
+        }
+        await highlight(token);
+    }
+  }
+
+  /**
+   * Load mermaid, and then update the diagram cache.
+   */
+  async function handleMermaid(token: marked.Tokens.Code): Promise<void> {
+    if (!_mermaid) {
+      _mermaid = (await import('mermaid')).default;
+      initTheme();
+    }
+
+    // bail if already cached
+    if (cacheGet(_diagrams, token.text)) {
+      return;
+    }
+
+    let html: string;
+    let className = MERMAID_CLASS;
+    const id = `jp-mermaid-${_nextMermaidId++}`;
+
+    // create temporary element into which to render
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+
+    try {
+      const { svg } = await _mermaid.render(id, token.text, el);
+      html = `<img src="data:image/svg+xml,${encodeURIComponent(svg)}" />`;
+    } catch (err) {
+      className = `${className} ${ERROR_CLASS}`;
+      html = `<code>${err.message}</code>`;
+    } finally {
+      // always remove the element
+      el.remove();
+    }
+
+    // update the cache for use when rendering
+    cacheSet(_diagrams, token.text, `<div class="${className}">${html}</div>`);
+  }
+
+  /**
+   * Clear the diagram cache and reconfigure mermaid if loaded.
+   */
+  function initTheme() {
+    if (_mermaid && _themes && _themes.theme) {
+      _diagrams.clear();
+      _mermaid.mermaidAPI.initialize({
+        theme: _themes.isLight(_themes.theme) ? 'default' : 'dark',
+        startOnLoad: false,
+        fontFamily: window
+          .getComputedStyle(document.body)
+          .getPropertyValue('--jp-ui-font-family')
+      });
+    }
+  }
+
+  /**
+   * Restore from cache, and move to the front of the queue.
+   */
+  function cacheGet<K, V>(cache: Map<K, V>, key: K): V | undefined {
+    const item = cache.get(key);
+    if (item != null) {
+      cache.delete(key);
+      cache.set(key, item);
+    }
+    return item;
+  }
+
+  /**
+   * Set to the front of the cache queue, potentially evicting the oldest key.
+   */
+  function cacheSet<K, V>(cache: Map<K, V>, key: K, item: V): void {
+    if (cache.size >= MAX_CACHE) {
+      cache.delete(cache.keys().next().value);
+    }
+    cache.set(key, item);
   }
 }