Bug: blog RSS feed generation failures with MDX posts

[slorber]

🐛 Bug Report

With #4330, we now render the full blog posts in the RSS feed, as HTML.

The way we currently do it is "good enough" but has several limitations:

MDX components replaced by divs

Using this MDX:

# title

import SomeCompent from "@site/src/someComponent"

<SomeCompent>Hello</SomeCompent>

Will render as:

<h1>title</h1>

<div>Hello</div>

The logic of <SomeComponent> is never evaluated.

For layout/wrapper components, it's not a big deal as the content remains in the RSS feed, but in some cases, it can be worst.

Not having a global MDX config and giving themes the ability to "register" some MDX comps and scope can help solve this problem. Related to #4625

No ```mdx-code-block support

```mdx-code-block is an escape hatch we added so that external tools (like Crowdin) do not mess-up with unsupported MDX markup.

The MDX content in these code blocks must be evaluated, as if it was not a code block

No relative image path support

MD referencing co-located assets such as:

![Docusaurus beta party](./img/image_cropped.png)

will be transformed as

<img src="./img/image_cropped.png" alt="Docusaurus beta party"/>

Unfortunately, the image is not hosted at ./img/image_cropped.png in the production site due to using Webpack's file-loader.

The real image URL in prod is /assets/images/image_cropped-2744c01b1fc0b451dbdb65a1d568fbff.png

We need a way to ensure such MD image declarations work in the RSS feed properly (ideally without changing the existing image asset URL or duplicating the asset in final site build)

[Josh-Cena]

Regressions that make sites fail to build at all:

• styles is not defined when import styles from './styles.module.css';
• require is not defined when require('./assets/img.png').default.

The missing Webpack infra is more severe than missing MDX features

[slorber]

In case of MDX to HTML conversion failures, generally due to require() calls, I added a quickfix to temporarily swallow errors here: #5753

• For Error reported by "useBaseUrl" during construction #5736
• For Site fails to build production site with blog post that uses require after upgrading to beta 7 #5718

This is not a big deal because posts without HTML content are still useful in the RSS feed (behavior we had before). I'm not sure how this problem must be solved so I didn't want to introduce a new temporary API for this.

---

@wooorm any insight to share on how to render an MDX file (including JSX tags/imports/exports + require("./img.png") to a RSS feed HTML string?

We have something like that currently but it's obviously not ideal:

import React from 'react';
import ReactDOMServer from 'react-dom/server';
import MDX from '@mdx-js/runtime';
import removeImports from 'remark-mdx-remove-imports';
import removeExports from 'remark-mdx-remove-exports';

export function mdxToHtml(
  mdxStr: string,
): string {
  return ReactDOMServer.renderToString(
    React.createElement(MDX, {remarkPlugins: [removeImports, removeExports]}, [
      mdxStr,
    ]),
  );
}

Of all the popular MDX-based blogs, I couldn't find one where the RSS feed renders full HTML content.

[wooorm]

I’m doing this as a post step on the generated HTML. As in, I first generate the site. Then I take the generated HTML of recent blog posts. And turn those into a feed:

https://github.com/mdx-js/mdx/blob/7d09ef8266ffffb089d583363e16db76e841bec1/website/post.js#L48-L110

Assuming there’s some static generation, then at some point, you already have a component for the MDX page?

[slorber]

Thanks @wooorm, that was also one idea I had, and yes when we generate the blog feed the HTML files are already generated so we can definitively read them here.

I found this idea a bit hacky (likely to break due to generated filenames or HTML structure), but it can probably be good enough for now until we find better 🤪

[wooorm]

You do need to have the metadata about blog posts again, and where they were rendered. And a class or ID on the body of the text. But I don't really find it hack if it's then very close to what instapaper or safari reader or so do, too.
Alnternatively: do it when you render the content into the body. Perhaps render it twice, once with a "this is for the static website" and once with "this is for the static feed", so components can switch and return different markup for each "media query"?