Windowscommunitytoolkit: New control to display MD (Markdown) files

[deltakosh]

[xied75]

Would this be based on a RichText control?

[deltakosh]

I think so

[ryzngard]

Possibly a RichText renderer for sundown? That way we avoid having to maintain a markdown parser

[deltakosh]

Do you know if there is a nugget package for sundown

[ryzngard]

Hmm, doesn't appear to be. Nor are any of the .NET wrappers. We'd have to fork (they're MIT license), make a packaging ourselves, or find another solution. Markdown exists, and is also MIT license but doesn't support a custom renderer. Depending on need, I don't think it would be terribly hard to fork Markdown and add the ability for custom rendering, just casually looking at the code. Could also see if we could do a PR to add it as a full feature of Markdown.

[ibebbs]

How seeing if @QuinnDamerell would be prepared to contribute UniversalMarkdown to the toolkit? Yes it's a custom parser but it looks extremely well written and comes with a custom user control for rendering the markdown as basic XAML elements. It's also a proven parser/render as it's used in the extremely popular Baconit app.

[ryzngard]

Good call. I shot him an e-mail last night. You're right, the parser code is really cleanly done, and there's already one XAML view for it. I think it would be a nice addition and easy to add

[QuinnDamerell]

I would love to. @paulbartrum has really been the champ of Universal Markdown recently, he's the one who made it amazing. I have been meaning to make a nuget package for it, but haven't had the time. I think this is a great idea, I have had many people ping me outside and internally to MS who would like to use it.

I don't know how we would add it, would we want to move the code and shutdown the other repo? Submodule it? Or just add some information in the docs that there is the Universal Markdown repo available?

[deltakosh]

It depends on you :) we would be honored to host you but we can also think about a simple control with a dependency on a nuget you can publish

I'm obviously more for solution 1

[QuinnDamerell]

Well I would need to see what @paulbartrum thinks, but I think the best bet would be to include it directly into the project and shutdown my repo. I think it would be a lot easier for developers to use if it is already in the toolkit; and I think a lot of people will find it more useful than they might originally think. It works really well for any formatted text you want to show to users, especially for things like update notes, credits, etc.

[deltakosh]

Can't agree more :D

[QuinnDamerell]

If we do so, how would we go about it? Where do you think it should live in the folder structure?

[deltakosh]

I suggest creating a MarkdownTextBlock folder in the controls project

[paulbartrum]

• Currently the public API surface is rather large. This is great for clients that want to dig into the individual nodes within the parsed document, but not so great for our ability to make non-breaking changes. Do we need to lock down the surface area?
• There are a few features which cannot currently be rendered in full fidelity, due to missing functionality in UWP's support for documents & inlines. Specifically lack of superscript support (really, control over text baselines), lack of formatting ability within hyperlinks and lack of strike-through support. Nothing we can do about that here but maybe some Microsofties are reading :-)
• UniversalMarkdown specifically targets Reddit's flavor of markdown. There's been some talk about letting people choose what flavour they want to use (CommonMark, etc) but this would obviously be a large amount of work. This only really matters for users who have an existing corpus of markdown texts.
• There are some known bugs. Reference-style links are especially problematic because they require the document to be parsed twice. There's currently a (single-pass) hack in place to support this type of link but it doesn't work in all cases.

Thoughts?

[deltakosh]

1. I'm clearly for a simple API at the beginning. Easy to maintain. Easy to evolve
2. I will make sure that they read it :) In the meantime I prefer starting with some constraints be sure to provide what 90% of the users want.
3. Is it comparable to github's flavor?
4. No problem. Let's create issues to track what need to be fixed

[xied75]

Second for GitHub flavor.

[QuinnDamerell]

My thoughts

1. I agree, I would suggest we strip down the API to be nothing more than maybe the text for the markdown and some of the formatting options. If people express interest in getting deeper later someone can write some code to expose it down the line.
2. My hope would be if enough people start using this control and demand the missing functionally maybe some of the XAML people will take notice. :)
3. I think this flavor is fine for now, I would guess maybe 90% of it is common, does that seem about right? Again, like you said, if enough people give feedback maybe we can look into adding some flavor flags and changing the behavior of the parse.
4. OPEN ALL THE ISSUES.

[deltakosh]

GOOOOOOO!!!! :)

[xied75]

Cross referencing GuanZhou's work here, he has already released the app in store:
https://www.microsoft.com/store/apps/9nblggh4q9rs

He used another way which is to render MarkDown into HTML, which would demand a use of WebView, this is the reason in the beginning of this thread I asked are we using RichText control.

I myself is working on an app that will need to display all major programming languages with syntax highlighting etc. There is a work done long time ago https://github.com/icsharpcode/AvalonEdit, which is not MVVM. But apparently MarkDown is ALSO a language albeit simpler, if we have a special control to display MarkDown, what about something similar? Are we going to create another control or ignore the demand? Can we somehow make a rather solid foundation or generic solution? (Is the RichText already the foundation? Or something one step above it?) Thoughts?

[deltakosh]

I'm not a big fan of using the webview if we can avoid it as it forces the app to load Edge engine (and then the memory footprint is increased).

I think there is a demand for displaying MD inside the app (I will be one of the first adopter tbh). For other languages it is up to the community. If there is an ask we can think about providing more languages support.

Regarding using RichText I leave this to @QuinnDamerell and @paulbartrum (btw guys, do you think you could integrate your control in the toolkit for 1.2?)

[QuinnDamerell]

Yeah, the current version of Universal Markdown uses a rich edit control so the perf is good. In Baconit I use these elements in a list view for comments that are virtualized in and out, so the perf had to be good, a web view would be way to heavy handed for each comment. In Baconit you can scroll the list just about as fast as you can and the Markdown system keeps up with parsing and rendering with no UI shudders. 😄

When is 1.2 released? I was going to try to work on this over the weekend, idk how far I will get.

[deltakosh]

Mid November so you have time:)

[paulbartrum]

I've started on this. Question: should I replace the Copyright (c) 2016 Quinn Damerell copyright notice with the MS one?

[paulbartrum]

Another problem: I've made all the parsing classes (CodeBlock, etc) internal. Am I okay to add InternalsVisibleTo to the controls assembly, so that I can add my unit tests to the unit test project?

[paulbartrum]

Current progress is here: https://github.com/Microsoft/UWPCommunityToolkit/compare/dev...paulbartrum:integrate-universal-markdown

[deltakosh]

If @QuinnDamerell is ok, yes please!
No problem to mark assembly to be able to test it

[deltakosh]

Hello @QuinnDamerell
Just checking if everything is fine on your side?

[deltakosh]

Hello guys, I would like to flag what we will have in 1.2. Do you think you will make it? (Code freeze on 11/6)

[paulbartrum]

I don't have much time to spend on this, so I would prefer it was targeted at the next release after v1.2, if that's okay. There's still a bunch of decisions to make, like determining how error handling should work and locking down the public API surface.

[deltakosh]

Ok understood..I flag it for 1.3 then

[xied75]

Would be great to see this get done for v1.3 as new year gift. :)

[deltakosh]

can't agree more!

[QuinnDamerell]

I will try to find sometime to pull it in. Sorry that it has taken so long, life and work have been busy!

[deltakosh]

feel free to do a pr and ask for help:) Ivan dedicate some time to it

[xied75]

@QuinnDamerell got a naive slightly off question: what is the pros/cons for rendering parsed MarkDown to XAML than to RichText? What would be the consideration?

[QuinnDamerell]

It is all about flexibility. The rich text APIs don't allow all of the styling necessary to correctly render all of the elements markdown, especially when it comes to items like grids and list. But there's a trade off, I would bet the rich text renders more efficiently than a ton of xaml objects. So if you need full markdown support, you need xaml. But if you just need a simpler subset of markdown, you might be able to get away with rich text.

That said, @paulbartrum did an amazing job with the renderer. All of the comments in baconit are rendered in markdown text boxes. The comments are virtualized in a huge scrolling listview, yet the scroll perf is practically perfect.

[QuinnDamerell]

@deltakosh and @xied75 my biggest concern for integration are the unit tests and sample app. I saw that the universal controls have unit tests, but they are a different kind than the tests in universal markdown. Is it fine to pull the entire markdown project into the folder structure and keep it as-is for now with the different tests? I can integrate the makrdown control into the universal controls sample app as an example implementation, but I don't think I will have time to convert all of the unit tests over to use the same framework.

[deltakosh]

It is COMPLETELY fine. we could even ask for help after the merge to migrate unit tests

[ibebbs]

@QuinnDamerell, I was the one who originally suggested approaching you about pulling Universal Markdown into the toolkit but didn't mean to dump you with loads of extra work to get this done. If it would be helpful, I could put some time aside to be your lackey here and do whatever is needed to get this integrated.

[QuinnDamerell]

@deltakosh @ibebbs ok, so I had some time and got some of it in. I was able to get the control in, hooked up, and in the sample. I have also added the unit tests project to the solution and fixed them up.

Let me know what you think:
https://github.com/QuinnDamerell/UWPCommunityToolkit/tree/markdown

Things I still need to do:

• Get an icon for the MarkdownTextBlock in the sample (can someone make one?)
• Clean up all of the style issues (there are a ton of them, any ideas on how we can work around them)
• Clean up the MarkdownTextBlock interface and make sure the public interface looks good.

[QuinnDamerell]

Ok, I went crazier. I fixed up the public interface and fixed all of the style issues in the main code. So the only thing that remains is getting an image for the sample app and fixing the style issues in the unit tests.

[Odonno]

@QuinnDamerell For the icon, why not using the MarkDown logo ?

[QuinnDamerell]

That is a perfect idea. I took one of the other icons and kind of made it my own. 😁

I started the pull request process here
https://github.com/Microsoft/UWPCommunityToolkit/pull/772

[deltakosh]

Let me know when you think we can start reviewing it :)
I would love to add documentation preview in the sample app using your control

[QuinnDamerell]

@deltakosh I would say it is ready now! I added the control to the sample app, but haven't added any documentation.

The markdown control is really simple. Plop it in, set the Text property, and you get rendered markdown. There are two events; one for when the makrdown is rendered and one for when links are tapped (so the app can handle special links like subreddits). There are also a ton of properties exposed, but they are quite simple. They control all of the different properties of how the markdown is rendered (code block background, header font sizes, list padding, etc)

[deltakosh]

Sounds good. Let's go through a cycle of review. Documentation can be added at the end :)

[QuinnDamerell]

Cool. How does the review process work? Anything I need to do?

[deltakosh]

Nope..We need two people to review it and approve it
I'll be one of them (Will review this afternoon).

Reviewers may comment and this could trigger some updates on your side
Once two reviewers approved your code, you can add doc and we can merge and celebrate :D