Return html when render markdown content

[bluwy]

Changes

When render() a markdown file (not MDX), return the html too.

Implements this feature for better RSS composing experience.

Testing

Added new tests to make sure it renders

Docs

• Changeset
• RSS guide update Add html to RSS guide docs#2545
• API reference update Add content collections render html feature docs#2547

[changeset-bot]

🦋 Changeset detected

Latest commit: 845f308

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

[bholmesdev]

Thanks @bluwy! Yes, apologies for not detailing a use case on the ticket. The primary utility is RSS feeds, where you may want to the html content for each RSS feed item. This also brings content collections in-line with the compiledContent() helper present on Markdown imports today.

As for docs updates, I'd expect to:

1. Update the RSS docs to suggest html over manual Markdown parsing (I'll take this one!)
2. Update render() API reference to include html

I'd leave the Content Collections guide page alone looking at what it includes today. We can always update later if support tickets prove anything is unclear.

[bholmesdev]

Code looks good! Just nits on the changeset and about a potential unit test

[bluwy]

Makes sense! Thanks for the explanation. I'll update the docs later for no2, and set up the unit test.

[delucis]

Is there any concern about introducing this API before we can offer something similar for MDX? Is the intention that we might one day figure this out for MDX too? Render components but exclude scripts & styles?

[github-actions]

This PR is blocked because it contains a minor changeset. A reviewer will merge this at the next release if approved.

[bluwy]

After further discussion with the maintainers, we decided to close this for now until we have a proper way to expose html for MDX files too. This avoids confusion when a user switches .md to .mdx that a property is missing. Closing the docs PR too.

[oliverpool]

I would really like to have this feature for my RSS feed (I don't use mdx at all).

Wouldn't it be reasonable to make html a function (renderResult.html = mod.compiledContent in case of .md) which throws a (nice) error in case of mdx? (maybe pointing to some issue here about proper way to expose html for MDX files).

For now I have to use import.meta.glob on the feed page (which return different objects than getCollection and without proper type)

Edit: having to introduce another dependency for markdown rendering as recommended by the docs feels wrong (since a markdown renderer is already used internally)

[OverflowCat]

So why isn't compiledContent() present in MDX? I have extensively used MDX and components in my blog, but most of the pages are static. Only a few pages contain <script> tags.

[bholmesdev]

@OverflowCat In short, because MDX needs to be "executed" as Astro components, and we need an API to safely render Astro components to strings of HTML. This is being tracked here!