Improve the astro:content <Content /> render props API

[noghartt]

Body

Summary

A better usage and handling of components and other instances around the <Content /> component, allowing to override generated HTML from a markdown text.

Background & Motivation

The principle around this RFC is to give a better DX around parsed markdown in Astro content. Allowing developers to reuse their external components inside rendered HTML from markdown file. Instead of doing it around remark and rehype plugins and handling AST nodes directly, would be cool to have it being handled in the Content instance.

It would allow developers to reuse any component from Astro or any other framework allowed by Astro, like React, Vue, Svelte, etc. And by instance, so we would let to componentize the <Content /> too.

Goals

• Improve astro:content Content component DX (Developer Experience);
• Let users to reuse their components around markdown rendered HTML;
• Let users to reuse their <Content /> component around their codebase;

Example

---
import { getCollection } from 'astro:content';

import { Heading, Link } from '@/components';

export async function getStaticPaths() {
  const posts = await getCollection('blog');

  return posts.map(post => ({
    props: {
      post,
    }
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<Content
  components={{
    h1: Heading,
    a: Link,
  }}
/>

[florian-lefebvre]

I don't understand, isn't it possible already with mdx or markdoc? Or are you talking specifically about .md files?

[noghartt]

Yes, it's possible with MDX or Markdoc. But my point was related to .md files (I think that wasn't to explicit in the RFC, sorry).

IMO, having this kind of structure in a plain-text file allows to share it around an entire gamma of applications is a good, powerful thing.

[Frondor]

I'll upvote this! It shouldn't be necessary to install mdx in order to achieve such simple mappings a for common html tags to astro components.
I'd also suggest that this should be possible to configure globally in astro.config file, under “markdown” prop

[noghartt]

IMO, I don't know if exposing it on astro.config.* file would be good, but it can works.

In case, my idea of exposing it over the Content, to have the option of importing things from other framework integrations, like React, Svelte, etc.

[stereobooster]

This reminds me Hugo render hooks

[stereobooster]

related #423

[stereobooster]

I tested how overrides work in MDX. Some of components work as expected, like image, link, header. But code is kind of "broken". See https://github.com/stereobooster/astro-customize-markdown

[noghartt]

Thinking on the right API for that scenario, I think that should be something like what remark-react does. See here.

In case, the Content, in some way, should iterate over the markdown AST and replace it accordingly to which has been expected by the inserted API.

[stereobooster]

should iterate over the markdown AST

Isn't remark-react iterates over rehype AST (hast), and not remark AST (mdast)? Which would bring us to the same API as Astro-MDX has now.

                                                             react-remark
+---------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                                                                                             |
|            +----------+        +----------------+        +---------------+       +----------------+       +--------------+                  |
|            |          |        |                |        |               |       |                |       |              |                  |
| -markdown->+  remark  +-mdast->+ remark plugins +-mdast->+ remark-rehype +-hast->+ rehype plugins +-hast->+ rehype-react +-react elements-> |
|            |          |        |                |        |               |       |                |       |              |                  |
|            +----------+        +----------------+        +---------------+       +----------------+       +--------------+                  |
|                                                                                                                                             |
+---------------------------------------------------------------------------------------------------------------------------------------------+

[stereobooster]

Extended proposal and some thoughts about API design

Introduction

Idea is very similar to Hugo render hooks. Add ability to custmoize how markdown is rendered with Astro components:

---
// ...
const { Content } = await post.render();
---

<Content
  components={{
    h1: Heading1,
    a: Link,
  }}
/>

Motivating examples

Reuse components

If one already has Astro component it would be trivial to reuse it in markdown. For example, Starlight provides <Aside /> component. There would be no need to reimplement the same component as remark/rehype plugin.

Instead one could do:

// ContainerDirective.astro
---
import Aside from "./Aside.astro";
---
<Aside type={Astro.props.directive}>
  <slot />
</Aside>

and then

<Content
  components={{
    containerdirective: ContainerDirective,
  }}
/>

Astro components are easier to deal with than remark/rehype plugins

Remark and rehype provide low level API, which is nice if you develop plugins, but for the end-users this causes a lot of confusion.

Situation is very similar to Vite API. It is overkill for Astro integration layer. That is why there is Astro Integration Kit, which creates additional layer tailored speciafically for Astro use case.

Take a look how much struggle it is to integrate Mermaid in Astro/Starlight.

On the other hand with proposed API it would be a trivial task:

// CodeOverride.astro
---
import { Code } from "astro:components";
import Mermaid from "./Mermaid.astro";
const { content, lang, inline } = Astro.props;
---
{
  lang === "mermaid" ? (
    <Mermaid diagram={content} />
  ) : (
    <Code code={content} lang={lang} inline={inline} />
  )
}

and then

<Content
  components={{
    code: CodeOverride,
  }}
/>

Astro components can be client-side components

This API opens up door to for using client-side components for Markdown, which would be hard to do with remark/rehype plugins.

For example, one can override code-fences to render Google Maps in place.

```map
38.7223° N, 9.1393° W
```

With something like this:

// CodeOverride.astro
---
import { Code } from "astro:components";
import GoogleMaps from "./GoogleMaps.astro";
const { content, lang, inline } = Astro.props;
---
{
  lang === "map" ? (
    <GoogleMaps center={content} />
  ) : (
    <Code code={content} lang={lang} inline={inline} />
  )
}

Or if you have remark-directive, you can use special directive for this, for example:

::map[38.7223° N, 9.1393° W]

The devil is in the details

While all of this sounds nice, it may be not very clear how to design API.

At which level shall it operate - mdast or hast?

Let's imagine ideal interface for Code Astro component:

---
type Props = {
  content: string;
  inline: boolean;
  lang?: string;
  metastring?: string;
};
---

Which in case of given example:

```ts {1}
const x = 1;
```

would be passed as:

{
  "content": "const x = 1;",
  "inline": false,
  "lang": "ts",
  "metastring": "{1}"
}

This is pretty easy at mdast level. But at hast level we don't have concept of code-fence, instead there is <pre><code class="languages-ts">const x = 1;</code></pre>.

Which means that in order for Astro to support "ideal" interface it would either need to:

• use mdast
  • problem: some plugins work at hast level, for example rehype-slug, which adds ids to headings
• or write custom handlers for each case for hast

Problem with <slot />

Let's take the same Code component example from above.

More traditional way to get content would be: const content = await Astro.slots.render("default");. Instead of passing it as prop.

But the problem here is that content gets processed (html entities escaped, markdown gets processed). So for:

```html
<h1>hi</h1>
```

await Astro.slots.render("default"); would produce <h1>hi</h1>.

Problem with nested markdown

Let's say we want to override Blockquote in order to implement callouts similar to Github:

> [!NOTE]
> something

And Blockquote component is something like this:

---
import Aside from "./Aside.astro";

type Props = {
  content: string;
};

let content = Astro.props.content;
const matches = content.trim().match(/^[!([^\]]*)\]/);
const aside = Boolean(matches);
let type = "note" as any;
if (matches) {
  type = matches[1].toLowerCase();
  content = content.replace(matches[0], "");
}
---

{
  aside ? (
    <Aside type={type}>
      <Markdown content={content}>
    </Aside>
  ) : (
    <blockquote>
      <Markdown content={content}>
    </blockquote>
  )
}

If we pass "raw" string to content we would also need some kind of <Markdown /> component. There is deprecated (AFAIK) componet for this.

What is allowed in Astro components?

Astro component in the context of this proposal can imply different expectations (requirements).

Simplest case: it renders self-contained HTML string. For example, SVG (from Mermaid), syntax-highlighting (like current Shiki plugin), etc.

Harder case: it also has JavaScript and Style blocks. In this case they need to be deduplicated - e.g. even if component rendered multiple times JavaScript and Style should be outputed only ones.

Simplest case probably can be implemented in the "user-space" with something, like await astro.renderToString(Component, { props, slots, request, params }).

MDX compatibility

Is it expected that overrides for Markdown would also work for MDX? Is MDX overrides would stay the same or would they change?

On one side, if we can mix markdown and MDX in Content Collections - it is expected that they would work the same.

On the other side if one already uses MDX they can use it for all files. And treatment of MD and MDX files can be different. For example:

<Content
  components={{}}
  componentsMDX={{}}
/>

If components for MD would work the same way as MDX, they would inherit the same problems as described in astro-customize-markdown.

If current MDX overrides are good enough for your use case, you can rename all files from .md to .mdx.

PS

The main questions are:

• If current overrides for MDX are good enough for your use cases, what prevents you to rename all files from .md to .mdx?
• If there is an intention to implement different API how would it look like? Will new API be compatible with MDX?

[stereobooster]

Here is an alternative thought. The main need here is to be able to "hook" into rendering process. And remark/rehype allows to do that, but it is tedious to write remark plugins. What if we provide easier way to write plugins it would solve the problem. To experiment with the idea I created:

• rehype-code-hook
• remark-code-hook

It is quite convenient. It allows to reuse code at least partially:

rehype plugin:

import { rehypeCodeHook } from "@beoe/rehype-code-hook";
import { generateSvg } from "./generateSvg.js";

export const rehypeExampleDiagram = (options = {}) => {
  return rehypeCodeHook({
    ...options,
    code: ({ code }) => generateSvg(code),
  });
};

Astro component:

---
import { generateSvg } from "./generateSvg.js";
interface Props {
  code: string;
}

const svg = generateSvg(code);
---

<Fragment set:html={svg} />

[bluwy]

If you need to pass components to the markdown, then MDX is the perfect solution for this. If we want to support passing components markdown without MDX, we have to rewrite the markdown rendering to render the HTML tag by tag, so that we know when to render a specific tag with a specific component. And if we did so, we're basically replicating what MDX does under the hood.

So with that, it's better to use MDX as it's the right tool for the job. I don't think it makes sense to extend markdown rendering any further since it'll impact existing users who only need HTML and they'd have to pay the cost of the performance overhead of this feature.

[stereobooster]

And if we did so, we're basically replicating what MDX does under the hood.

MDX does a bit more than that. Proposal here is rather implement something similar to Hugo render hooks, I think

[bluwy]

For sure, but is there a point to implement something new where MDX can already to the job? You also don't have to use all the features of MDX.

[stereobooster]

Fair point. It would be nice to have "render hooks". But I also see how this is a less priority if there is already a workaround and team can spend this time doing something else more useful

[louiss0]

I like this idea