Documentation advises against using remark/rehype, but markdown example includes such plugins

[Because789]

📚 Subject area/topic

Modifying Frontmatter with Remark

📋 Page(s) affected (or suggested, for new content)

https://docs.astro.build/en/guides/content-collections/#modifying-frontmatter-with-remark https://github.com/withastro/astro/blob/main/examples/with-markdown-plugins/package.json

📋 Description of content that is out-of-date or incorrect

Not sure if here is the right place for this, but I think it's not a good idea to advises against using remark/rehype in the documentation, but include remark/rehype plugins in the markdown example. It seems to me that the examples should reflect best practice. So I guess it's more a problem of the example, but what do I know, maybe it's the documentation which is outdated...

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[delucis]

Hi @Because789!

The two things here are actually distinct, but maybe we don’t make that clear enough:

• The with-markdown-plugins example shows using remark/rehype to transform your Markdown content with several plugins

• The caution in the docs you linked to is related specifically to using remark/rehype to transform your Markdown frontmatter

While we don’t recommend modifying frontmatter like this, modifying content is safe and something many Astro sites do, including the Astro docs.

[Because789]

Hey @delucis, thanks for your answer, now I understand. Obviously, I didn't check how the plugins in with-markdown-plugins are actually used. I just saw rehype-slug and thought, that it probably does something with the frontmatter slug.

I think what tripped me off was, that the caution box sounds like ALL the remark and rehype plugins are dangerous: "Remark and rehype plugins access the raw Markdown or MDX document frontmatter." That sounds pretty absolute, I feel like this could be improved. No idea how though, I'm simply not familiar enough with these plugins.

[sarah11918]

Thanks for this comment! I will be revising our content pages (markdown, MDX, Markdoc and Content Collections) in the next little while and will take this under advisement to make sure we are clear in our recommendations.