[RFC] Split markdown rendering to a separate package.

.github/workflows/lit_samples_build.yml

@@ -35,21 +35,9 @@ jobs:
         with:
           node-version: '20'
 
-      - name: Install web_core deps
-        working-directory: ./renderers/web_core
-        run: npm ci
-
-      - name: Build web_core
-        working-directory: ./renderers/web_core
-        run: npm run build
-
-      - name: Install lib's deps
-        working-directory: ./renderers/lit
-        run: npm i
-
-      - name: Build lib
-        working-directory: ./renderers/lit
-        run: npm run build
+      - name: Build lit renderer and its dependencies
+        working-directory: ./samples/client/lit
+        run: npm run build:renderer
 
       - name: Install all lit samples workspaces' dependencies
         working-directory: ./samples/client/lit

.github/workflows/ng_build_and_test.yml

@@ -51,18 +51,14 @@ jobs:
         working-directory: ./renderers/lit
         run: npm run build
 
-      - name: Install renderer deps
-        working-directory: ./renderers/angular
-        run: npm i
-
-      - name: Build Angular renderer
-        working-directory: ./renderers/angular
-        run: npm run build
-
       - name: Install top-level deps
         working-directory: ./samples/client/angular
         run: npm i
 
+      - name: Build Angular renderer and its dependencies
+        working-directory: ./samples/client/angular
+        run: npm run build:renderer
+
       - name: Build contact sample
         working-directory: ./samples/client/angular
         run: npm run build contact

renderers/angular/package.json

@@ -6,7 +6,6 @@
   },
   "dependencies": {
     "@a2ui/web_core": "file:../web_core",
-    "markdown-it": "^14.1.0",
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
@@ -22,7 +21,6 @@
     "@angular/core": "^21.0.0",
     "@types/express": "^5.0.1",
     "@types/jasmine": "~5.1.0",
-    "@types/markdown-it": "^14.1.2",
     "@types/node": "^20.17.19",
     "@types/uuid": "^10.0.0",
     "@vitest/browser": "^4.0.15",

renderers/angular/src/lib/data/index.ts

@@ -14,5 +14,6 @@
  limitations under the License.
  */
 
+export * from './markdown';
 export * from './processor';
 export * from './types';

renderers/angular/src/lib/data/markdown.ts

@@ -14,101 +14,74 @@
  limitations under the License.
  */
 
-import { inject, Injectable, SecurityContext } from '@angular/core';
-import { DomSanitizer } from '@angular/platform-browser';
-import MarkdownIt from 'markdown-it';
+import { Injectable } from '@angular/core';
+import * as Types from "@a2ui/web_core/types/types";
 
+/**
+ * A minimal Markdown renderer that only supports a few tags.
+ *
+ * Configure @a2ui/markdown-it-angular, or build a custom Markdown renderer
+ * to actually parse and render Markdown in your app.
+ */
 @Injectable({ providedIn: 'root' })
 export class MarkdownRenderer {
-  private originalClassMap = new Map<string, any>();
-  private sanitizer = inject(DomSanitizer);
-
-  private markdownIt = MarkdownIt({
-    highlight: (str, lang) => {
-      if (lang === 'html') {
-        const iframe = document.createElement('iframe');
-        iframe.classList.add('html-view');
-        iframe.srcdoc = str;
-        iframe.sandbox = '';
-        return iframe.innerHTML;
-      }
 
-      return str;
-    },
-  });
+  static _warned = false;
 
-  render(value: string, tagClassMap?: Record<string, string[]>) {
-    if (tagClassMap) {
-      this.applyTagClassMap(tagClassMap);
+  constructor() {
+    /**
+     * Warn the user in case they need actual Markdown rendering.
+     */
+    if (!MarkdownRenderer._warned) {
+      console.warn("[MarkdownRenderer]",
+        "is a placeholder Markdown renderer. Most features are not supported.\n",
+        "Use `@a2ui/markdown-it-angular` for a fully-featured Markdown renderer.");
+      MarkdownRenderer._warned = true;
     }
-    const htmlString = this.markdownIt.render(value);
-    this.unapplyTagClassMap();
-    return this.sanitizer.sanitize(SecurityContext.HTML, htmlString);
-  }
-
-  private applyTagClassMap(tagClassMap: Record<string, string[]>) {
-    Object.entries(tagClassMap).forEach(([tag, classes]) => {
-      let tokenName;
-      switch (tag) {
-        case 'p':
-          tokenName = 'paragraph';
-          break;
-        case 'h1':
-        case 'h2':
-        case 'h3':
-        case 'h4':
-        case 'h5':
-        case 'h6':
-          tokenName = 'heading';
-          break;
-        case 'ul':
-          tokenName = 'bullet_list';
-          break;
-        case 'ol':
-          tokenName = 'ordered_list';
-          break;
-        case 'li':
-          tokenName = 'list_item';
-          break;
-        case 'a':
-          tokenName = 'link';
-          break;
-        case 'strong':
-          tokenName = 'strong';
-          break;
-        case 'em':
-          tokenName = 'em';
-          break;
-      }
-
-      if (!tokenName) {
-        return;
-      }
-
-      const key = `${tokenName}_open`;
-      const original = this.markdownIt.renderer.rules[key];
-      this.originalClassMap.set(key, original);
-
-      this.markdownIt.renderer.rules[key] = (tokens, idx, options, env, self) => {
-        const token = tokens[idx];
-        for (const clazz of classes) {
-          token.attrJoin('class', clazz);
-        }
-
-        if (original) {
-          return original.call(this, tokens, idx, options, env, self);
-        } else {
-          return self.renderToken(tokens, idx, options);
-        }
-      };
-    });
   }
 
-  private unapplyTagClassMap() {
-    for (const [key, original] of this.originalClassMap) {
-      this.markdownIt.renderer.rules[key] = original;
+  /**
+   * Attempts to render some Markdown.
+   *
+   * Resist the urge to "improve" this method. Instead, use a more proper
+   * Markdown renderer. This is just a placeholder.
+   */
+  render(markdown: string, _tagClassMap?: Types.MarkdownRendererTagClassMap) : string {
+    if (markdown.startsWith('# ')) {
+      let classes = this.getClasses("h1", _tagClassMap);
+      return `<h1 class="${classes}">${markdown.substring(2)}</h1>`;
+    }
+    if (markdown.startsWith('## ')) {
+      let classes = this.getClasses("h2", _tagClassMap);
+      return `<h2 class="${classes}">${markdown.substring(3)}</h2>`;
+    }
+    if (markdown.startsWith('### ')) {
+      let classes = this.getClasses("h3", _tagClassMap);
+      return `<h3 class="${classes}">${markdown.substring(4)}</h3>`;
+    }
+    if (markdown.startsWith('#### ')) {
+      let classes = this.getClasses("h4", _tagClassMap);
+      return `<h4 class="${classes}">${markdown.substring(5)}</h4>`;
     }
+    if (markdown.startsWith('##### ')) {
+      let classes = this.getClasses("h5", _tagClassMap);
+      return `<h5 class="${classes}">${markdown.substring(6)}</h5>`;
+    }
+    if (markdown.startsWith('*') && markdown.endsWith('*')) {
+      let classes = this.getClasses("strong", _tagClassMap);
+      return `<strong class="${classes}">${markdown.substring(1, markdown.length - 1)}</strong>`;
+    }
+    let classes = this.getClasses("p", _tagClassMap);
+    return `<p class="${classes}">${markdown}</p>`;
+  }
 
-    this.originalClassMap.clear();
+  /**
+   * Returns a space-separated lists of clases for `tag` from `_tagClassMap`.
+   * @param tag The name of the tag ("h1", "p", etc.)
+   * @param _tagClassMap The class map to use.
+   * @returns A space-separated list of class names.
+   */
+  getClasses(tag: string, _tagClassMap?: Types.MarkdownRendererTagClassMap) {
+    return _tagClassMap?.[tag]?.join(' ') ?? '';
   }
 }

renderers/lit/package.json

@@ -79,7 +79,6 @@
   },
   "homepage": "https://github.com/google/A2UI/tree/main/web#readme",
   "devDependencies": {
-    "@types/markdown-it": "^14.1.2",
     "@types/node": "^24.10.1",
     "google-artifactregistry-auth": "^3.5.0",
     "typescript": "^5.8.3",
@@ -89,7 +88,6 @@
     "@lit-labs/signals": "^0.1.3",
     "@lit/context": "^1.1.4",
     "lit": "^3.3.1",
-    "markdown-it": "^14.1.0",
     "signal-utils": "^0.21.1",
     "@a2ui/web_core": "file:../web_core"
   }

renderers/lit/src/0.8/ui/context/context.ts

@@ -0,0 +1,24 @@
+/*
+ Copyright 2025 Google LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+      https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ */
+
+import {markdownContext} from "./markdown.js";
+import {themeContext} from "./theme.js";
+
+export { 
+  markdownContext as markdown, 
+  themeContext as theme, 
+  themeContext, // Preserved for backwards compatibility. Prefer using `theme`.
+};

renderers/lit/src/0.8/ui/context/markdown.ts

@@ -0,0 +1,26 @@
+/*
+ Copyright 2025 Google LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+      https://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ */
+import {
+  DirectiveResult,
+} from "lit/directive.js";
+import { createContext } from "@lit/context";
+
+/**
+ * A Lit Context to override the default (noop) markdown renderer.
+ */
+export const markdownContext = createContext<DirectiveResult>(
+  Symbol("a2ui-lit-markdown-renderer")
+);

renderers/lit/src/0.8/ui/directives/directives.ts

@@ -14,4 +14,4 @@
  limitations under the License.
  */
 
-export { markdown } from "./markdown.js";
+export { minimalMarkdown } from "./minimal_markdown.js";