[RFC] Split markdown rendering to a separate package. #595

ditman · 2026-02-04T03:43:52Z

Description

This PR separates the markdown-it dependency from the lit renderer, by allowing users to @provide a markdown renderer of their own.

BREAKING CHANGE: By default, now incoming markdown is rendered as a pre element, and users must inject a markdown renderer of their choosing for markdown to be rendered (see below).

In order to keep the "batteries" somewhat included in the sdk, a couple of new packages are introduced:

@a2ui/markdown-it-shared: the pre-configured markdown-it instance for all web renderers. This allows us to have a single configured markdown renderer with markdown-it and dompurify (TBD) that can be reused across all packages. This is pretty much a markdown string -> html string converter, but if we want to add plugins to markdown-it later, all packages get the new output at once.
@a2ui/markdown-it-lit: the bridge package between the lit renderer and markdown-it-shared. This is what people will use when using the lit renderer to @provide the markdown renderer. They can also use this package as a jumping off point to create their own markdown renderer, if they prefer anything else other than markdown-it.

The lit samples are updated to inject the new markdown renderer.

The idea for this PR is to create an @a2ui/markdown-it-angular package to bridge the gap in the angular renderer. I haven't checked how to inject the renderer in angular, but I expect angular to have some DI mechanism that we're already leveraging.

Fixes

Fixes Figure out how to resolve Markdown dependency in OSS and google repository #475

Tests

The new packages need some tests, that may already exist (and break) in the current lit renderer package. I just didn't have time to set those up yet, but will do before landing this, if we like this approach.

Pre-launch Checklist

I signed the CLA.
I read the Contributors Guide.
I read the Style Guide.
I have added updates to the CHANGELOG.
I updated/added relevant documentation.
My code changes (if any) have tests.

If you need help, consider asking for advice on the discussion board.

ditman

I posted some comments to guide through the PR, and maybe start some discussions. PTAL!

ditman · 2026-02-04T03:45:19Z

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

+ */
+class NoopMarkdownRendererDirective extends Directive {
+  render(markdown: string, _tagClassMap?: Record<string, string[]>) : TemplateResult {
+    return html`<pre>${markdown}</pre>`;


This should probably console.warn once to let users know that they need to use @a2ui/markdown-it-lit, and maybe link to some documentation site.

ditman · 2026-02-04T03:46:10Z

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


-import { googleAI } from "@genkit-ai/google-genai";
-import { configure } from "genkit";
+import {markdownContext} from "./markdown.js";


Suggested change

import {markdownContext} from "./markdown.js";

import { markdownContext } from "./markdown.js";

? I need to setup some form of "format on save" or something I guess?

ditman · 2026-02-04T03:46:41Z

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

This file is now probably redundant.

ditman · 2026-02-04T03:47:50Z

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

  accessor usageHint: Types.ResolvedText["usageHint"] | null = null;

+  @consume({context: Context.markdown})
+  accessor markdownRenderer = noopMarkdown;


Not to toot my own horn, but this ended up looking quite nice. I like Lit!

ditman · 2026-02-04T03:49:06Z

renderers/lit/package-lock.json

Can we stop comitting the lockfiles to the repo? They add a lot of noise and can cause unnecessary merge trouble! Any advantage of checking this in??

ditman · 2026-02-04T03:59:12Z

renderers/web_core/src/v0_8/schemas/a2ui_client_capabilities_schema.json

I don't understand why am I getting these .JSON updates, is my branch too old? Is this being updated off of master, instead of the contents of my branch?

Updating off of master sounds dangerous.

ditman · 2026-02-04T04:00:21Z

samples/client/lit/contact/theme/theme.ts

Changes to this file are 100% cosmetic, just because I thought I had broken the contact example with my markdown changes (turns out I hadn't, but it rubbed me the wrong way)... I can remove this from this PR since it's not too related!

ditman · 2026-02-04T04:01:19Z

samples/client/lit/contact/contact.ts

This is the gist of the "integration" for Lit users, I think it turned out fairly simple, but still it's a breaking change with the previous version of the package, unfortunately.

ditman · 2026-02-04T04:02:49Z

samples/client/lit/shell/app.ts

 export class A2UILayoutEditor extends SignalWatcher(LitElement) {
-  @provide({ context: UI.Context.themeContext })
-  accessor theme: v0_8.Types.Theme = uiTheme;
+  @provide({ context: UI.Context.theme })


Renaming UI.Context.themeContext to UI.Context.theme is also a breaking change, but IMO it improves legibility a little bit (especially now that there's more than one inhabitant in the UI.Context namespace.

samples/client/lit/package.json

ditman · 2026-02-04T18:47:05Z

(Rebasing to resolve merge conflicts)

…o the noop version.

…enderer dependencies.

ditman · 2026-02-04T23:59:27Z

I had to tweak the build script task a little bit to ensure the new packages I added as path dependencies for the lit renderer are being built.

ditman commented Feb 4, 2026

View reviewed changes

ditman added 13 commits February 4, 2026 10:55

Make the default markdown renderer noop

30b8e7a

Introduce lit-markdown-it package

36f4176

Add shared markdown renderer for all JS web renderers.

1307029

Add the markdown-lit facade package

9427692

Import markdownit from module name, instead of index.js

9de5c17

Move the markdown context to the UI library, next to the theme.

be3d984

Inject the Context.markdown Directive into the text widget. Default t…

92f4dbc

…o the noop version.

Inject the markdown-it-lit renderer on shell app

269094a

Update miscellaneous lockfiles

f1d6737

Fix typo in shell a2ui-surface closing tag

b46e5f6

Wire the markdown renderer to the contact app.

89de7ed

Miscellaneous package-lock.json update

8a8e527

Tweak the contact theme to align the h5 a little bit better

ecf80b1

ditman force-pushed the inject-markdown-rendering branch from 6ac6fd5 to ecf80b1 Compare February 4, 2026 19:01

ditman mentioned this pull request Feb 4, 2026

Add React renderer #542

Open

ditman added 2 commits February 4, 2026 15:38

Refactor build:renderer as a bash for loop so it builds all the lit r…

731bd50

…enderer dependencies.

Update lit_samples_build.yml to use the existing build:renderer script.

63cdbaa

github-project-automation bot added this to A2UI Feb 5, 2026

github-project-automation bot moved this to Todo in A2UI Feb 5, 2026

	import {markdownContext} from "./markdown.js";
	import { markdownContext } from "./markdown.js";

[RFC] Split markdown rendering to a separate package. #595

Are you sure you want to change the base?

[RFC] Split markdown rendering to a separate package. #595

Uh oh!

Conversation

ditman commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Fixes

Tests

Pre-launch Checklist

Uh oh!

ditman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ditman commented Feb 4, 2026

Uh oh!

ditman commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ditman commented Feb 4, 2026 •

edited

Loading