Add mdx-react generator

[ovflowd]

Following up the extraction of the MDX parser into a dedicated generator that converts the plain Markdown into an MDX template, we should compile it into React.

This effectively introduces the react and mdx dependencies into the project. Proper ESLint and Prettier configuration for React and JSX should be added. This can be done by importing compatible rules from the Node.js Website repository.

This generator should pretty much receive the content transformed into an MDX template from the mdx generator; the MDX generator returns a VFile, with the caveat that the main content is now replaced with the MDX template, but both the metadata and file metadata remain in the VFile.

Then the mdx-react receives that VFile and pretty much compiles the MDX and evaluates it into JSX by running it with MDX https://mdxjs.com/packages/mdx/#evaluatefile-options

Hence, this generator's output is again a VFile containing the source content and the generated JSX function within the data attribute.

Note that the generated React is simply the content of the page, not the whole page (navigation, header, etc.). Think of this as the inner content of a blog post.

[avivkeller]

This generator should pretty much receive the content transformed into an MDX template from the mdx generator; the MDX generator returns a VFile, with the caveat that the main content is now replaced with the MDX template, but both the metadata and file metadata remain in the VFile.

Then the mdx-react receives that VFile and pretty much compiles the MDX and evaluates it into JSX by running it with MDX mdxjs.com/packages/mdx#evaluatefile-options

Could you share a bit more about how you see the mdx generator working? I’m trying to wrap my head around the step between Markdown and the final compiled JSX. Why does the content need to be turned "into an MDX template" first? Wouldn't that just be part of converting it to JSX in the mdx-react generator?

Specifically, when you say " the main content is now replaced with the MDX template", the main content is markdown, which is already basically mdx?

[ovflowd]

Could you share a bit more about how you see the mdx generator working? I’m trying to wrap my head around the step between Markdown and the final compiled JSX. Why does the content need to be turned "into an MDX template" first? Wouldn't that just be part of converting it to JSX in the mdx-react generator?

So, pretty much the base generator transforms the raw Markdown content into Nodes, these Nodes also have the raw content (Markdown there), then we have the legacy-html generator for example, that transforms into HTML pages.

The mdx generator in question is just a "jsx" generator, or "md-jsx" or "mdx-jsx" (we don't really need any MDX parser at the moment, because unified already parsed it). But the point is that it is grabbing the source "mdx/md" into -> "jsx" which is pretty much "grabbing the md content (and metadata) and filling it inside JSX layouts.

This parser will contains also all the JSX-specific components.

• package.json - add @node-core/ui-components
• generators/md-jsx (or mdx-jsx or just jsx)
  • components/ (components specific to API docs)
  • layouts/ (layouts specific to API docs)

Then we have the "react-web" generator or "jsx-html" (whatever we name it) (probably replacing #7) (idk?)

When I wrote those generator ideas... it was a long time ago 😅

But the final generator, would have HTML templates and have the bundles being bundled into it (either inline or what not) -- or whatever we decide to use to build the final app. It could be Vite, or what not :)

[avivkeller]

Got it! Thanks for elaborating. I think I got confused between mdx, mdx-react, and react-web, thanks for clarifying!