Support MDJS in Pages

[bennypowers]

Hello!

open-wc publishes a package called mdjs which allows for executing JS in plain markdown. It includes support for storybook component-story-format stories as well:

```js script
import { LitElement, html } from 'https://unpkg.com/lit-element?module';

class MyEl extends LitElement {
  render() {
    this.innerHTML = '<p style="color: red">I am alive</p>';
  }
}

customElements.define('my-el', MyEl);

This is my-el

This would be quite nice to have in typedoc pages, letting users turn their pages into fully interactive demos.

What do you think of the idea?

[mipatterson]

Currently, this plugin uses the Marked plugin that TypeDoc uses internally in order to parse Markdown and convert it to HTML.

I don't know much about open-wc, but from a quick look, it appears that it fulfills a similar role as Marked- parsing Markdown and producing HTML.

I think support for something like this would be possible, but not trivial to implement. TypeDoc has an internal plugin that exposes a Handlebars helper to allow theme templates to render Markdown: https://github.com/TypeStrong/typedoc/blob/dc965b9be0bf17bbfe1a581b0e88eafd16ebd919/src/lib/output/plugins/MarkedPlugin.ts

This plugin uses that in markdown-page.hbs: https://github.com/mipatterson/typedoc-plugin-pages/blob/develop/theme/v2/templates/markdown-page.hbs

It seems like the best way to approach this would be to first update markdown-page.hbs to use a custom Handlebars helper exposed by this plugin. Then that helper could be updated to conditionally use a different Markdown-to-HTML engine (open-wc in this case) to render the page contents.

This is complicated by the fact that, currently, custom themes need to implement their own version of this Handlebars template and they would need to make the same updates to switch from the current TypeDoc-driven Handlebars helper to a new plugin-provided helper. That would be a breaking change.

All of the above certainly seems doable, but it needs to be planned out well and released carefully. It feels like it might be best to hold on this feature until HTML-page support and custom theme documentation is finished.

[bennypowers]

I wonder if progress to 0.20 at https://github.com/TypeStrong/typedoc/issues/1364 will affect things

[mipatterson]

@bennypowers I haven't been keeping a super close eye on this work, but I'll take a look when I get a chance. Is there something in that release in particular that you think will be relevant?

[bennypowers]

There's some changes to the default theme, for one. I'm not familiar enough with the APIs to say if or how big of a breaking change there is