AiMarkdownView

Bit.BlazorUI.AI

BitAiMarkdownView renders a parsed Markdown document: the prose of an assistant message, with its code blocks, tables, task lists, footnotes, mathematics and inline citation markers. It takes an already-parsed document rather than a string, so the caller decides how parsing happens - BitAiStreamingMarkdown reuses an incremental parser across deltas, a static caller parses once with BitAiMarkdownParser. Model output is untrusted, so raw HTML is escaped unless it is opted into, link and image URLs of a scheme that can run script are neutralised, and images follow the image policy of the options. Fenced code in a language the app registered (a chart, a diagram) and mathematics defer to renderers of the app's own.

ForceAnimation (whole page)

Notes

To use this component, you need to install the Bit.BlazorUI.AI(opens in a new tab) nuget package, as described in the Optional steps of the Getting started page.

It needs no chat session: parse the Markdown with BitAiMarkdownParser.Parse and hand it the document - a public tree of BitAiMarkdownBlock and BitAiMarkdownInline nodes (see the tables below) an app can read as well. For text that is still arriving, use BitAiStreamingMarkdown, which parses incrementally and renders through this view. Fenced code is drawn by a BitAiCodeBlockView, whose page lists the highlighted languages and how to add one, and resolved citation markers by a BitAiCitationMarker. The registered renderers (BitAiRendererRegistry) are a singleton: register them once, at startup, with ConfigureRenderers of AddBitBlazorUIAIServices.

Security: raw HTML is shown as text unless both the parse options and the options in force allow it, which is only for Markdown you trust as much as your own code; links open in a new tab with rel="noopener noreferrer nofollow" and only the http, https, mailto, tel and ftp schemes; and a browser fetching an image URL a model was talked into leaks the reader's address - restrict images with the BitAiImagePolicy below. Accessibility: the headings are rendered one level below the Markdown's own (a # is an h2), so an answer never competes with the h1 of the page, and a table keeps its row and column semantics while it scrolls. See it at work in the Streaming and Citations scenarios.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Document is the parsed Markdown to render; nothing is rendered while it is null. Parse it once with BitAiMarkdownParser.Parse: headings, emphasis, strikethrough, links, bare URLs, inline code and lists.

Choosing a render mode

Blazor renders on the server, over a circuit, or in the browser, on WebAssembly - and ~~one size fits all~~ each page can pick its own. Start with the docs or https://blazorui.bitplatform.dev, and set it with @rendermode.

Measure the first paint.
Measure the cost of every update:
- on the server, in messages;
- in the browser, in milliseconds.

Blocks

Tables, their columns aligned by the delimiter row (:--- start, :---: centre, ---: end - see BitAiColumnAlignment) and scrolling in their own frame; block quotes; task lists, whose checkboxes show what the model wrote and cannot be changed; thematic breaks; and fenced code - every fenced block is a BitAiCodeBlockView with its header, copy button and highlighting in the language of its fence.

Mode	Runs on	First paint	Offline
Server	The server, over a circuit	Fast	No
WebAssembly	The browser	Slower	Yes

Rendering more often than the eye can follow is not smoother. It is just louder.

Pick a render mode
Measure the first paint

csharp

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

Streaming caret

ShowCaret draws a caret at the end of the text while the document is still being written - one parsed with isComplete false, the sign that more text is on its way. It follows the paragraph or the heading being written (the first view), and after a code block, a table or a blank line it waits where the next block will start (the second). A document with no block yet draws none. BitAiUiOptions.ShowStreamingCaret turns it off for every view at once.

The answer is still being written, so its last paragraph is open

Install the package:

bash

dotnet add package Bit.BlazorUI.AI

Footnotes & headings

Footnotes are listed after the text in the order they are first cited, each with a link back to every place that cites it. The anchors of the footnotes and the ids of the headings are named after the id of the view (answer-bit-ai-h-setup here), so two messages of one transcript never give the page two elements of one id.

Setup

Server rendering keeps the state on the server¹, which is also why a dropped connection loses it¹. WebAssembly downloads the runtime once².

Over a SignalR circuit.
↩↩
And caches it for the next visit.
↩

Mathematics

Dollar-delimited mathematics - $inline$ and $$display$$ - is left as its source, in monospace, with a data-math attribute a script can typeset from. BitAiRendererRegistry.MathRenderer replaces that fallback with a renderer of your own, handed a BitAiMathContext; the one here is a tiny typesetter of superscripts, subscripts and symbols, where an app would use KaTeX or MathJax. The registered registry is app-wide, so an app sets it once at startup; this page cascades a registry of its own to the views of these examples (a CascadingValue of a BitAiRendererRegistry), and the toggle sets the renderer on that one.

Use a math renderer of my own

The energy of a body at rest is E = mc^2, and the area of a circle is \pi r^2.

\sigma = \sqrt{\sum_{i=1}^{n} (x_i - \mu)^2 / n}

Code languages

BitAiRendererRegistry.RegisterCodeLanguage renders the fenced blocks of one language - a chart, a diagram - with a renderer of your own in place of the code view, handed a BitAiCodeBlockContext. A half-written diagram is a syntax error, so a renderer waits for IsStreaming to turn false: the second block below has not been closed yet. This page registers a bars language on the registry it cascades to its views as it initializes.

Where the time of a first visit goes:

Download420 msStart the runtime180 msFirst render60 ms

And of a second visit:

Drawing the chart...

Citations

A bracketed number in the text ([1]) is drawn as a citation chip when Citations holds a citation of that Number; one that matches none stays the text it was. OnCitationClick is raised when the user activates a chip. BitAiUiOptions.InlineCitations turns the chips off for every view at once.

Interactive Server keeps component state on the server and streams UI diffs over a SignalR circuit . If that circuit drops, the state goes with it unless you have persisted it yourself . A number no citation has, such as [3], stays the text it is.

Activated: none yet

Custom citation chip

BitAiRendererRegistry.CitationRenderer draws the chips with a renderer of your own, handed a BitAiCitationContext: the Citation, and OnActivate - the OnCitationClick of the view - which the chip raises through ActivateAsync(), so it acts the way the built-in one does. The one here is a pill naming the site. The registered registry is app-wide, so an app sets it once at startup; this page cascades a registry of its own to the view below, and the toggle sets the renderer on that one - the chips of the example above, which reads the registered registry, stay as they are.

Use a citation chip of my own

Activated: none yet

Images

BitAiUiOptions.Images is the BitAiImagePolicy the images of the Markdown follow. Allow (the default) shows them all; AllowListedHosts shows the images of the listed hosts and a placeholder for the rest; ClickToLoad fetches nothing until the reader asks; Block shows the alternative text instead. A placeholder is a button that loads the image, named after its alternative text. A relative URL is resolved against the base address of the page before the policy is asked, so the host list here names this site's own host too. Inline data: images are fetched from nowhere, so they are shown under every policy but Block - unless AllowDataImages is off. Script-capable URL schemes are neutralised whatever the policy. Decide is what the views ask the policy about each image, and an app can ask it about images of its own: below, what the policy decides about the clock.

Policy

Allow

AllowListedHosts

ClickToLoad

Block

AllowDataImages

From this site: A portrait of a woman

From a listed host: A portrait of a woman, from a CDN

From another host:

Inline: A blue square

Images.Decide(the clock): Show

Untrusted content

Model output is untrusted. A javascript: link keeps its text but loses its address, so there is nothing to follow, and raw HTML - inline or a block - is shown as the text it is. Rendering it takes AllowRawHtml in both the options the document is parsed with and the options in force (BitAiUiOptions.Markdown): turn it on only for Markdown you trust as much as your own code, since a model can be talked into writing a script tag.

AllowRawHtml (trusted Markdown only)

A link a model was talked into: claim your prize.

Press <kbd>Ctrl</kbd> + <kbd>K</kbd> to search.

<details><summary>An HTML block</summary>Rendered as markup only when raw HTML is allowed.</details>

Markdown options

BitAiMarkdownOptions picks the extensions the parser reads: pipe tables, task lists, strikethrough, bare URLs as links, mathematics, footnotes, citation markers and heading ids are on by default, and SoftBreaksAsHardBreaks - for chat models that write one line per sentence and mean the breaks - is off. Hand them to BitAiMarkdownParser.Parse; a BitAiStreamingMarkdown reads them from BitAiUiOptions.Markdown. Turn each off to see what it reads: the text it covers stays as written. The view here is handed the Citations of the Citations example, so [1] is a chip while CitationMarkers is on. HideDanglingDelimiters only matters while text streams (see the Markdown options of AiStreamingMarkdown), and AllowRawHtml is shown under Untrusted content above.

Option	Default
Tables	on

a task that is done
one that is not

~~Struck through~~, a bare URL https://bitplatform.dev and x^2. One line, and the next.

A cited claim and a footnote¹.

Listed under the text.
↩

More of the syntax

The parser reads the rest of the CommonMark a model writes too: a heading underlined with = or -; a link with a title, which is its tooltip; a reference link ([text][label]) whose address a [label]: url line gives anywhere in the text; www. addresses and addresses or e-mails in angle brackets as links (while AutoLinks is on); a backslash - or two spaces - at the end of a line as a line break; backslash escapes and HTML entities; a block indented by four spaces as code; and a numbered list that starts at any number.

A heading underlined

A link with a title: the docs, and a reference link whose address is given further down. https://www.bitplatform.dev, https://github.com/bitfoundation/bitplatform and mailto:[email protected] are links too.

A backslash at the end of a line
breaks it. Escapes keep *stars* and [brackets] as they are, and entities read as their characters: © → €.

text

An indented block is code: dotnet run

A numbered list may start at any number
and counts on from there.

The document tree

The parsed document is a public tree (see BitAiMarkdownBlock and BitAiMarkdownInline below), so an app can read an answer as well as show it - for a table of contents, or to offer the code it holds. Here its headings, with the ids the view gives them (the view's own Id before the heading's Id), and its code blocks, found by walking the blocks down through the quotes and the list items.

Install

Add the package to the project:

bash

dotnet add package Bit.BlazorUI.AI

Register

Register the services once, at startup:
csharp
builder.Services.AddBitBlazorUIAIServices();

Then put a chat on a page:
razor
```
<BitAiChat />
```

Headings:

level 2, "Install", id guide-bit-ai-h-install
level 2, "Register", id guide-bit-ai-h-register

Code blocks:

bash, 1 line(s)
csharp, 1 line(s)
razor, 1 line(s)

Cascading parameters

BitParams with a BitAiMarkdownViewParams sets the defaults of every Markdown view inside it - here the styles of its links and quotes, bold and italic. A parameter of the view itself still wins, and wins whole: the second view sets Styles of its own, which take the place of the cascaded ones, so its link is green but not bold, and its quote is not italic.

A link of a view inside the BitParams, such as this one, is bold - unless its view sets Styles of its own.

Style & Class

Style and Class reach the root, Styles and Classes every element the view renders - each under a class of its own, so the prose styles never reach into what a registered renderer draws. The public --bit-AiMarkdownView-* variables (see the CSS variables table) restyle every view under the element they are set on, the ones a reasoning panel or an artifact renders inside a message included.