[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.