[RFC] Built-in Markdown/MDX Support

[Nate Moore]

I've pushed up a WIP Markdown integration under the feat/mdx branch! Give it a spin locally and let me know if you have any feedback.

The package source is under packages/markdown with an example at examples/markdown. It is powered by esbuild via xdm.

You'll notice that it supports both plan .md files as well as .mdx. You may customize the rendering of any element by passing a Preact component for that element's tag name ({ components: { a: (props) => <a {...props} /> } }). Unlike NextJS's built-in markdown support, this integration does not allow Markdown/MDX files to be used as pages/, but I think this is the most flexible choice for the same reasons outlined in next-mdx-remote's README. Unlike next-mdx-remote, hydration is handled entirely by Microsite, so only your components wrapped in withHydrate are rehydrated on the client. I'd be very interested in hearing your thoughts on this integration!

cc @ratorx

[eyelidlessness]

RE: pages, I think a good compromise is to use the getStatic* methods on a template page, to collect pages/paths and pre-render/pass to props. I have a similar setup for a project I’m working on (though I wish I’d known about xdm sooner!) and it’s working out well.

[Reeto Chatterjee]

Thanks for adding markdown support! A few of thoughts:

• I don’t like the inflexibility of always wrapping the Markdown in an article. Is it possible for the default component to return just the rendered markdown, and then let the user decide what to wrap it in? I realise that not wrapping raw HTML is a surprisingly hard problem because of upstream limitations (fragments don’t support dangerouslysetinnerhtml...), so a workaround might be to use something like preact-markup?
• I think adding some Typescript could improve the API a bit. Instead of returning a HTML string, the API could return a special markdown object (which internally could be e.g. a branded string) and then Article (or equivalent could consume the special type rather than just a string? It would be really nice to have a special type for markdown, especially if there are already a lot of string props, and it would get a bit more type safety if Article could only consume markdown rather than any string.
• Is it possible to have both renderToString as well as Markdown import support (not having pages support is fine, but I want to be able to treat MDX like JS) via a Snowpack plugin? Not a big deal, but treating Markdown as a first-class citizen, rather than “hardcode” (to some extent) the import path would be really nice. One minor (actual) usability benefit would be typescript import completions (rather than relying on the editor to have path completions) and aliases.

EDIT: A quick additional note on why 3 would be really nice to have as part of this project. I haven’t managed to get MDX imports working at all for various reasons. The biggest one (when trying xdm) is that snowpack uses CJS config, whilst xdm is ESM. However, this project is ideally placed to import ESM code for use in Snowpack plugins since it interacts directly with the Snowpack API. I don’t think this is a compelling reason, because this is entirely a Snowpack issue (not supporting mjs config), but it would be really nice if Microsite could make MDX just work.