[Experiment] MarkdownTextBlock

[nerocui]

MarkdownTextBlock

Problem Statement

The existing MarkdownTextBlock in the toolkit is old and out of maintenance. It's based on custom parser code and the users have been requesting more features and bug fixes.

Proposed Solution

Since in .NET ecosystem, there's already an existing state of the art markdown library, Markdig, it'd be in our best interest to integrate that into a new MarkdownTextBlock and explore the various possibilities it brings.

Open Questions

• How do we bring the same level of extensibility of the Markdig library to the new MarkdownTextBlock?
• There are some limitations from using RichTextBlock as the rendering target. What's the best way to mitigate them?
• How will this run in Uno Platform if it depends on RichTextBlock?
• What kind of performance metrics are necessary? How do we measure and achieve them?
• What's the accessibility requirement?

Code: https://github.com/CommunityToolkit/Labs-Windows/tree/main/components/MarkdownTextBlock
Initial PR: #480
Tracking Issue: #606

[JoeTomkinson]

@nerocui can you give us a bit of an update as we're 3 months on from your initial post above, as to what you think the current state of the MarkdownTextBlock is?

I've installed the pre-release '0.1.240517-build.1678' version to take a look at it, can already see some interesting issues with rendering code blocks and when the MarkdownTextBlock is inside of data templates, although still testing as to whether that's an issue specific to being inside of a data template or something related to binding.

[nerocui]

Thanks for your interest in the control. There are some dependency that needs to be fixed first before the code block can function properly. Currently we have the syntax highlighting turned off because of that.

I'm interested in what kind of issue you are seeing when rendering in templates. Could you post them here? I want to collect feedback and improve this control as it's still in an "experiment" phase.

[JoeTomkinson]

I raised an issue initially outlining the main issue that is present in the pre-release NuGet version of the Markdown control. I've included a comment in there as well that outlines a handful of other issues I've noticed so far.

I am going to try and get an environment set-up to start creating PRs against the Labs so I can help out a bit.

[JoeTomkinson]

The issue with rendering inside of the data template was a bit of a red--herring, there's an exception when ApplyText recieves a null string for any reason and that causes it to just stop rendering the rest of the markdown, so just needed a check and return rather than an exception throw.

[euju-ms]

I'm seeing an AOT compatibility issue with MarkdownTextBlock that roots from HtmlAgilityPack. Specifically, HtmlAgilityPack's HtmlNode.GetAttributeValue calls into an AOT incompatible code and MarkdownTextBlock uses it (e.g. Link).

I know the root problem lies with HtmlAgilityPack, but I was wondering if we can add a workaround here as well that avoids calling into GetAttributeValue. In fact, MarkdownTextBlock's code always gets the string attribute value and does its own parsing of the attribute value, so I think we should be able to just work with HtmlNode.Attributes directly and avoid the code path that is incompatible with AOT.

If you guys are ok with it, I can create a PR for this too. Thoughts?

[michael-hawker]

Sounds like a good solution @euju-ms, thanks for identifying it. Looking forward to your PR. 🦙❤️ FYI @Arlodotexe.

[euju-ms]

Here's my PR: #587

Thank you!

[jcoc611-microsoft]

Proposal: Extensions

The underlying parser Markdig supports extensions. Some of these come bundled with that package, such as Pipe Tables and Diagrams. Others can be added with extra code.

Simple properties for built-in extensions

<md:MarkdownTextBlock UseEmphasisExtras="True" UseAutoLinks="True" Text="..." />

We can ship with a few UseFoo properties that allow to configure the built-in extensions that end up both in the MarkdownPipeline and the Renderer. This makes it super easy to control which Markdown extensions get enabled without having to mess around with a MarkdownPipeline or any C# code.

Custom extensions

Declaration in XAML:

<md:MarkdownTextBlock Text="...">
  <md:MarkdownTextBlock.CustomElements>
    <foo:CustomElement />
  </md:MarkdownTextBlock.CustomElements>
</md:MarkdownTextBlock>

And C#, implementing a new interface we ship IElement:

class CustomElement : IElement<CustomObject>
{
  // Parsing
  public void AddToPipeline(MarkdownPipelineBuilder pipelineBuilder)
  {
    pipelineBuilder.Extensions.Add(...);
  }

  // Rendering
  public UWPObjectRenderer<CustomObject> GetObjectRenderer() => new CustomRenderer();
}

With this approach, we can allow users to add arbitrary extensions on top of the control in a very simple and declarative manner. A quick glance at the XAML tells you all the built-in and custom extensions currently being used.

[nerocui]

This method works. The bar is pretty high for custom elements tho. One would need to 1) understand how to write a parser and 2) under the rendering logic of MarkdownTextBlock. The rendering process is very much imperative. One wrong move the rendering of the following elements will all be wrong.

[michael-hawker]

We had custom support in the old control, so it's something we need to consider, here is our old doc on the prior control: https://learn.microsoft.com/windows/communitytoolkit/controls/markdowntextblock

And that system lived here: https://github.com/CommunityToolkit/WindowsCommunityToolkit/tree/rel/7.1.0/Microsoft.Toolkit.Uwp.UI.Controls.Markdown/Render

This was how we added custom DocFX support for within blocks:
https://github.com/CommunityToolkit/WindowsCommunityToolkit/blob/rel/7.1.0/Microsoft.Toolkit.Uwp.SampleApp/Controls/SampleAppMarkdownRenderer.cs

So, my understanding was that you could hook in at any part and look for your markers and override the default construction of the control.

Mind you this was built years ago, so maybe there's a better approach now, especially if we can hook-in leverage custom extensions to MarkDig to do the parsing bit and just get called at that specific moment as needed for the rendering side? (There are already parsing extensions for MarkDig that exist, so being able to call one of those and just write a renderer would be an interesting scenario as it means two different groups of developers may solve different aspects of these scenarios.)

[jcoc611-microsoft]

Yes exactly! The idea is to leverage the Markdig extension functionality:

1. Markdig extensions modify existing Markdown Blocks or output new custom Blocks
2. MarkdownTextBlock renderer maps Block subclasses into UWPObjectRenderer implementations

So if you use a Markdig extension that outputs a custom block type, all you have to implement is the corresponding UWPObjectRenderer and MarkdownTextBlock will do the mapping for you automatically.

[michael-hawker]

I'd suggest we use MarkdownObjectRenderer and IMarkdownElement for type names if we go with this sort of approach. We'd want to avoid using 'UWP' in a type name as this works for more than just UWP technology, and IElement is a bit too general. Though that could depend on if they're in the general CT.WinUI.Controls namespace or a sub-namespace

[nerocui]

Moved this discussion to a sub-issue #609 of #606

[michael-hawker]

We've opened a tracking issue we're going to start populating with the known issues and open work for the control here: #606 - It'll be the first use of the new sub-issue feature for us too. Looks promising for us to split out individual issues for components but have them tied to our central tracking issue. 🎉