[Sample App] Markdown Renderer Polyfill

[michael-hawker]

Split out from CommunityToolkit/Tooling-Windows-Submodule#72, Follow-on from PR #85

Problem Statement

Our current documentation is shown in raw Markdown instead of nice documentation.

We can use the Toolkit's MarkdownTextblock to resolve this, except on WASM. So we need a wrapper to make this work everywhere (in the sample app, not something we want to ship as a control).

Technical Background

In #85, I wrote code to split out the markdown snippets and inject the displayed samples in the ToolkitDocumentationRenderer:

Labs-Windows/common/CommunityToolkit.Labs.Shared/Renderers/ToolkitDocumentationRenderer.xaml.cs

Lines 121 to 141 in 8f23803

	var doctext = await GetDocumentationFileContents(Metadata);
	var matches = MarkdownRegexSampleTag.Matches(doctext);
	DocsAndSamples.Clear();
	if (matches.Count == 0)
	{
	DocsAndSamples.Add(doctext);
	}
	else
	{
	int index = 0;
	foreach (Match match in matches)
	{
	DocsAndSamples.Add(doctext.Substring(index, match.Index - index - 1));
	DocsAndSamples.Add(ToolkitSampleRegistry.Listing[match.Groups["sampleid"].Value]);
	index = match.Index + match.Length;
	}
	// Put rest of text at end
	DocsAndSamples.Add(doctext.Substring(index));

As well as a Template Selector to pick the right template to use:

Labs-Windows/common/CommunityToolkit.Labs.Shared/Renderers/ToolkitDocumentationRenderer.xaml

Lines 13 to 29 in 8f23803

	<Page.Resources>
	<DataTemplate x:Key="DocumentTemplate"
	x:DataType="x:String">
	<TextBlock win:IsTextSelectionEnabled="True"
	Text="{Binding}" />
	</DataTemplate>
	<DataTemplate x:Key="SampleTemplate"
	x:DataType="metadata:ToolkitSampleMetadata">
	<!-- TODO: Display Header for name of sample? -->
	<renderer:ToolkitSampleRenderer Metadata="{Binding}" />
	</DataTemplate>
	<local:DocOrSampleTemplateSelector x:Key="DocOrSampleTemplateSelector"
	Document="{StaticResource DocumentTemplate}"
	Sample="{StaticResource SampleTemplate}" />
	</Page.Resources>

So, all we should have to do is update the DocumentTemplate to leverage this new control that understands how to display the Markdown snippet.

Solution

Fortunately, @nickrandolph started a markdown based solution using marked.js for WASM that we can use for the individual blurbs from the MVVM Toolkit Sample App, see here: CommunityToolkit/MVVM-Samples@911b355~

And he's given us permission to leverage that code from that PR which didn't get merged:

I'm not sure if his version used WebView/marked even on native platform, so that may be a difference, but the general approach and code here should be handy to reference.

We'll probably want to update the Marked version referenced from the original PR there (and not sure if they included minified version).

We'll also need to a Third Party Notice file like we have in the toolkit since we'll be including the source directly as it's JavaScript.

Open Questions

• Do we worry about supporting DocFX or the new GitHub flavored Note/Warning sections at the moment? We should eventually, but we did this with a specific custom renderer in the toolkit and not sure of marked.js support (though they also have custom rendering).
  • Was thinking would be useful for 'preview/experimental' banner at top of experiments, but maybe we inject that on top of everything manually or in the side-bar of the app? @niels9001 thoughts?

[niels9001]

• Was thinking would be useful for 'preview/experimental' banner at top of experiments, but maybe we inject that on top of everything manually or in the side-bar of the app? @niels9001 thoughts?

Yeah, I guess we could use a InfoBar for this that shows that its an experimental control with maybe a link to some readme that explains what that means? I'll take it along in the mock-up!

[michael-hawker]

Hmm... I'm having trouble even just trying to add a split reference to Microsoft.Toolkit.Uwp/CommunityToolkit.WinUI.UI.Controls.Markdown package in Labs.Heads.props, figured I could pull in the Labs.Uno.props file helpers as well and do something like:

  <!-- Project Head/Sample App dependencies -->
  <ItemGroup Condition="'$(IsUwp)' == 'True' AND '$(IsUno)' == 'False'">
    <PackageReference Include="Microsoft.Toolkit.Uwp.UI.Controls.Markdown" Version="7.1.2"/>
  </ItemGroup>
  <ItemGroup Condition="'$(IsWinAppSdk)' == 'True' AND '$(IsUno)' == 'False'">
    <PackageReference Include="CommunityToolkit.WinUI.UI.Controls.Markdown" Version="7.1.2"/>
  </ItemGroup>

(See branch llama/markdown)

But it's not restoring properly... hmm. May need some help here @Arlodotexe. In the meantime, I'm going to try and clean-up the MSB4011 warnings with an idea I had for #99

[michael-hawker]

Filed #182 to resolve underlying dependency issue needed to proceed here.

[michael-hawker]

I have the initial work by @nickrandolph ported over, tried to update Marked.js while I was at it (and added a third-party notice). However, couldn't get it to work on web assembly. It appears like it's loading the marked library, but then can't find it when it goes to execute parsing of the markdown blurb.

This work is in the llama/markdown-wasm branch if anyone wants to investigate this more. I was having a hard time debugging this under the browser.

[michael-hawker]

Was thinking the other day, we could just try using Markdig directly as a .NET dependency side. Means we wouldn't have to include js source in the repo and try injecting that into web page contents. Would just be able to grab Markdown and grab HTML output from Markdig, then either write to WASM page content or inject in WebView on other non-windows platforms. 🤔

This would also mean that if we ever get to re-writing the MarkdownTextblock to use Markdig, we could leverage this as a stop-gap for Uno platforms until they have RichTextBlock support. (unless we also change our rendering approach).

(This would also give us the opportunity to evaluate how we plug-in to Markdig and rendering for custom Markdown things and display that before we rework the Toolkit control... I think, maybe?)

[michael-hawker]

Could maybe do a similar approach with code preview to use ColorCode in order to spit out HTML to inject in the page for the code samples.

[michael-hawker]

Good news is that Markdig is working in WASM. Uno JS interop makes it pretty easy. Though need to match fonts. Also, issues with layout... so needs some more work. Probably has to do with height of control changing after initial layout pass?

[michael-hawker]

Have an initial version which works decently, though not sure how to properly color the links parsed by MarkDig, assume there's a CSS style we'd have to apply or something? I'm not sure how these things interact with Uno and how the WinUI styles work there... @Arlodotexe any thoughts?

Though, if this is a good enough approach, should be simple enough to have another RichTextBlock wrapper for ColorCode which uses that on Windows and Html on WASM for the C#/XAML examples. Don't have time to do that now though.