Docusaurus: V2: Non truncated blog article in feeds

[MatanBobi]

🚀 Feature

When working with the blog feed, in testing-library's, we would like a way to contain the full article and not just a truncated version of it within the feed since we don't really care about retention or something like that.

Motivation

Following this PR in testing-library, we think that having a way to send a non truncated version of an article can be helpful for people that just want to spread the word and don't care about traffic to their site rather than just spread updates.

Pitch

I believe we can add this by adding another config to the blog feed options, I'd be glad to help and create a PR for this one if you find it suitable.

Thanks for your hard work and help!

[nickmccurdy]

Adding to the rationale here, I would expect most Docusaurus sites to be for community projects that don't need users to visit blog posts for monetization via advertisements or conversions. I think leaving blog posts non-truncated by default and adding an option for the old behavior (if encouraging site traffic or reducing feed size is necessary) would be even better.

[nickmccurdy]

Also, this should be relevant to both V1 and V2. If approved, perhaps it should be backported from 2 to 1 or merged into 2 after 1.

[slorber]

Ok for an option to have non-truncated feeds.

I don't know much about RSS feeds and best practices regarding monetization/conversions, but if you can back up your claims by some authority link that explains why it's better to have non-truncated articles in feeds, we can make this the default.

[slorber]

Also, this should be relevant to both V1 and V2. If approved, perhaps it should be backported from 2 to 1 or merged into 2 after 1.

v1 is in low maintenance mode, it's not very important to backport this feature now, we'll encourage people to adopt v2 instead.

[MatanBobi]

I can take this one if it's ok :)

[MatanBobi]

Ok for an option to have non-truncated feeds.

I don't know much about RSS feeds and best practices regarding monetization/conversions, but if you can back up your claims by some authority link that explains why it's better to have non-truncated articles in feeds, we can make this the default.

Taken from the RSS 2.0 Spec:

A channel may contain any number of <item>s. An item may represent a "story" -- much like a story in a newspaper or magazine; if so its description is a synopsis of the story, and the link points to the full story. An item may also be complete in itself, if so, the description contains the text (entity-encoded HTML is allowed), and the link and title may be omitted. All elements of an item are optional, however at least one of title or description must be present.

I think we should keep the title and URL even if the description contains the whole item.
Any thoughts? I've already started working on this btw.

[nickmccurdy]

If I remember correctly the generated description didn't seem to include the title and URL

[MatanBobi]

@slorber I've implemented this and I did get the full post in the description but it was plain markdown and nothing rendered it.. I saw that in the classic-theme you use MDXProvider to render the MDX.. Any ideas what we can do here for the feeds?
Thanks!

[slorber]

I see

The thing is, a user might be able to add mdx interactive components in the blog post. In such case, what should be the behavior of such feed? The feed reader won't be able to render the React component, but we can still render such component and get it as a static HTML string (it's just it won't be interactive anymore).

You should likely call ReactDOM.renderToString to generate the feed as HTML

MDXProvider only permits to replace default HTML elements with custom implementations, that does not seem 100% mandatory, but may be helpful to improve the default renderToString if not good enough. Unfortunately due to the modular architecture, the blog plugin does not know anything about the classic theme, and can't reuse this MDX provider. Maybe we need it for proper code block highlighting?

The question is: how do we transform markdown to a JSX tree on the server, so that we can feed renderToString with it?

The MDX apis I know compile markdown to React component source code, not a JSX directly.
We generally write this source code to disk, and require it like regular source code. Wonder if we can avoid this step that seems a bit useless in such case.

[slorber]

Looks like mdx/runtime is what we are looking for: https://mdxjs.com/advanced/runtime

Something like this may work

import React from "react";
import ReactDOMServer from 'react-dom/server';
import MDX from "@mdx-js/runtime";

async function mdxToHtml(sourceFilePath) {
  const mdxString = await fs.readFile(sourceFilePath);
  return ReactDOMServer.renderToString(<MDX>{mdxString}</MDX>);
}