Render post summary to HTML

[cemerick]

I'm trying to get better descriptions into my RSS feed (ideally the entire post summary, not just the first sentence). I have the MDX source in hand, but unfortunately, I'm having a hard time getting some reasonable mdx-to-html action going:

• All of docusaurus' MDX loader stuff emits JSX AFAICT, so that's not super helpful.
• For this corner of things, I'm not particularly picky about all of the bells and whistles that docusaurus packages up for mdx handling (remark plugins, etc), so I thought I'd just use mdx-js directly. Unfortunately, attempting to use it (import { compileSync } from "@mdx-js/mdx";) throws a gnarly and odd error: [cause]: Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in /home/chas/dev/site/node_modules/estree-walker/package.json. (Perhaps this is a jiti problem? Use shiki for code highlight #9122 (comment) is the only thing I've found that appears similar.)

Any thoughts on how to go about this?

[slorber]

I'm trying to get better descriptions into my RSS feed (ideally the entire post summary, not just the first sentence).

Afaik the RSS item description is based on the blogPost.metadata.description field, which itself is created based on blogPost.frontMatter.description or uses a fallback excerpt that we try to extract from the MDX content. This is also what is used for SEO meta description tags.

My recommendation: do not rely on a best-effort excerpt generation fallback or try to improve it. Instead, always provide an explicit frontMatter.description that will be used for both SEO and RSS feeds.

---

Keep in mind that what you try to do (MDX to HTML) might be costly. Our excerpt generation is much simpler on purpose for that reason. Also if you use markdown tables, interactive React components, tabs, and other fancy things at the beginning of a post, it's unlikely any system will be able to infer a proper description that would be better than an explicitly defined one.

However, if you don't like our default excerpt generation, you have multiple hooks to customize it:

• Globally with parseFrontMatter(): https://docusaurus.io/blog/releases/3.1#parsefrontmatter-hook
• RSS-only with createFeedItems(): https://docusaurus.io/blog/releases/2.3#blog-createfeeditems

The error you get is likely because MDX is using ESM. You likely need to use dynamic imports like we do:

async function mdxToHtml(mdxString: string) {
  const {compileSync} = await import('@mdx-js/mdx')
  // ...
}

[cemerick]

Also if you use markdown tables, interactive React components, tabs, and other fancy things at the beginning of a post, it's unlikely any system will be able to infer a proper description that would be better than an explicitly defined one.

I'm confused by this. Isn't the truncation marker there exactly so one can control this sort of thing? I think maybe we're working with different semantics of "description" here? Related:

My recommendation: do not rely on a best-effort excerpt generation fallback or try to improve it. Instead, always provide an explicit frontMatter.description that will be used for both SEO and RSS feeds.

In this case, I'm using docusaurus (with some patches here and there) to host a podcast feed + blog. Putting the description in the frontmatter isn't great, as podcast descriptions can contain basic HTML (according to apple; you'll have to search for "description", couldn't find a suitable anchor), and so I was hoping to simply drop each post's "summary" (everything up to the truncation marker) in. I am currently using the createFeedItems hook to do this in the most basic way (just splitting markdown paragraphs into <p>s; inline styling in the summaries are currently just being sent as raw markdown for now).

You likely need to use dynamic imports like we do:

Yeah, I tried doing the import within the body of a function as well. The error remains ~the same:

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in /home/chas/dev/site/node_modules/estree-walker/package.json

Why it's mentioning estree-walker here, I've no idea 😕. I can start a node REPL within my site's project and happily import and use mdx-js just fine, so it seems there's some docusaurus magic that's happening/going wrong.

[slorber]

I'm confused by this. Isn't the truncation marker there exactly so one can control this sort of thing?

The truncate marker is here to define what appears in "blog list views" such as paginated blog pages, tags pages and authors pages:

• https://docusaurus.io/blog
• https://docusaurus.io/blog/tags/release
• https://docusaurus.io/blog/authors/slorber

It's not related to the SEO description or RSS feed description.

Consider the following:

---
description: "SEO and RSS item description"
--- 

<FancyBlogPostIntro/>

{/* truncate */}

... rest of the blog post

If you don't provide an explicit frontMatter.description, then your SEO / RSS item description would be the <FancyBlogPostIntro/> string, and not what actually gets rendered. That's why you should rather always provide an explicit description.

The code we use to infer the markdown excerpt is a best effort based on quite hacky regexps. We do not "evaluate" the MDX, we simply process a string and try to create a decent description from it.

In this case, I'm using docusaurus (with some patches here and there) to host a podcast feed + blog. Putting the description in the frontmatter isn't great, as podcast descriptions can contain basic HTML (according to apple; you'll have to search for "description", couldn't find a suitable anchor), and so I was hoping to simply drop each post's "summary" (everything up to the truncation marker) in. I am currently using the createFeedItems hook to do this in the most basic way (just splitting markdown paragraphs into <p>s; inline styling in the summaries are currently just being sent as raw markdown for now).

We have lifecycles that could eventually permit you to create your own custom frontMatter.description_for_rss_feed.

A pseudo-code example to help you understand the idea:

async function createFeedItems(params) {
  const feedItems = params.defaultCreateFeedItems(params);
  feedItems.forEach((feedItem,index) => {
    const blogPost = params.blogPosts[index];
    feedItem.description = blogPost.frontMatter.description_for_rss_feed ?? feedItem.description;
  })
})

Now you can pass both the SEO description and the RSS feed item description independently:

---
description: "SEO description"
description_for_rss_feed: "RSS feed <b>description</b> containing HTML"
--- 

<FancyBlogPostIntro/>

{/* truncate */}

... rest of the blog post

Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in /home/chas/dev/site/node_modules/estree-walker/package.json

🤷‍♂️ no idea