Renders Storyblok rich text content to Astro elements.
If you are in a hurry, check out live demo:
Official Storyblok + Astro integration (@storyblok/astro
) provides the most basic possibility to render rich-text in Astro. The integration package re-exports the generic rich text utility from @storyblok/js
package, which is framework-agnostic and universal.
This renderer utility outputs HTML markup, which can be used in Astro via the set:html directive:
---
import { renderRichText } from '@storyblok/astro';
const { blok } = Astro.props
const renderedRichText = renderRichText(blok.text)
---
<div set:html={renderedRichText}></div>
Nevertheless, it is possible to customise renderRichText
to some extent by passing the options as the second parameter:
import { RichTextSchema, renderRichText } from "@storyblok/astro";
import cloneDeep from "clone-deep";
const mySchema = cloneDeep(RichTextSchema);
const { blok } = Astro.props;
const renderedRichText = renderRichText(blok.text, {
schema: mySchema,
resolver: (component, blok) => {
switch (component) {
case "my-custom-component":
return `<div class="my-component-class">${blok.text}</div>`;
break;
default:
return `Component ${component} not found`;
}
},
});
Although this works fine and may cover the most basic needs, it may quickly turn out to be limiting and problematic because of the following reasons:
-
renderRichText
utility cannot map rich text elements to actual Astro components, to be able to render embedded Storyblok components inside the rich text field in CMS. - Links that you might want to pass through your app's router, are not possible to be reused as they require the actual function to be mapped with data.
- It is hard to maintain the string values, especially when complex needs appear, f.e. setting classes and other HTML properties dynamically. It may be possible to minimize the complexity by using some HTML parsers, like ultrahtml, but it does not eliminate the problem entirely.
Instead of dealing with HTML markup, storyblok-rich-text-astro-renderer
outputs RichTextRenderer.astro
helper
component (and resolveRichTextToNodes
resolver utility for the needy ones), which provides options to map any Storyblok rich text
element to any custom component, f.e. Astro, SolidJS, Svelte, Vue, etc.
The package converts Storyblok CMS rich text data structure into the nested Astro component nodes structure, with the shape of:
export type ComponentNode = {
component?: unknown; // <-- component function - Astro, SolidJS, Svelte, Vue etc
props?: Record<string, unknown>; // <-- properties object
content?: string | ComponentNode[]; // <-- content, which can either be string or other component node
};
npm install storyblok-rich-text-astro-renderer
To get the most basic functionality, add RichText.astro
Storyblok component to the project:
---
import RichTextRenderer from "storyblok-rich-text-astro-renderer/RichTextRenderer.astro";
import type { RichTextType } from "storyblok-rich-text-astro-renderer"
import { storyblokEditable } from "@storyblok/astro";
export interface Props {
blok: {
text: RichTextType;
};
}
const { blok } = Astro.props;
const { text } = blok;
---
<RichTextRenderer content={text} {...storyblokEditable(blok)} />
Sensible default resolvers for marks and nodes are provided out-of-the-box. You only have to provide custom ones if you want to override the default behavior.
Use resolver
to enable and control the rendering of embedded components, and schema
to control how you want the nodes and marks be rendered:
<RichTextRenderer
content={text}
schema={{
nodes: {
heading: ({ attrs: { level } }) => ({
component: Text,
props: { variant: `h${level}` },
}),
paragraph: () => ({
component: Text,
props: {
class: "this-is-paragraph",
},
}),
},
marks: {
link: ({ attrs }) => {
const { custom, ...restAttrs } = attrs;
return {
component: Link,
props: {
link: { ...custom, ...restAttrs },
class: "i-am-link",
},
};
},
}
}}
resolver={(blok) => {
return {
component: StoryblokComponent,
props: { blok },
};
}}
{...storyblokEditable(blok)}
/>
By default, content in nodes
is handled automatically and passed via slots keeping configuration as follows:
heading: ({ attrs: { level } }) => ({
component: Text,
props: { variant: `h${level}` },
}),
This implies that implementation of Text
is as simple as:
---
const { variant } = Astro.props;
const Component = variant || "p";
---
<Component>
<slot />
</Component>
However in some cases, the users do implementation via props only, thus without slots:
---
const { variant, text } = Astro.props;
const Component = variant || "p";
---
<Component>
{text}
</Component>
This way the content must be handled explictly in the resolver function and passed via prop:
heading: ({ attrs: { level }, content }) => ({
component: Text,
props: {
variant: `h${level}`,
text: content?.[0].text,
},
}),
The schema has nodes
and marks
to be configurable:
schema={{
nodes: {
heading: (node) => ({ ... }),
paragraph: () => ({ ... }),
text: () => ({ ... }),
hard_break: () => ({ ... }),
bullet_list: () => ({ ... }),
ordered_list: (node) => ({ ... }),
list_item: () => ({ ... }),
horizontal_rule: () => ({ ... }),
blockquote: () => ({ ... }),
image: (node) => ({ ... }),
code_block: (node) => ({ ... }),
emoji: (node) => ({ ... }),
},
marks: {
link: (mark) => { ... },
bold: () => ({ ... }),
underline: () => ({ ... }),
italic: () => ({ ... }),
styled: (mark) => { ... },
strike: () => ({ ... }),
superscript: () => ({ ... }),
subscript: () => ({ ... }),
code: () => ({ ... }),
anchor: (mark) => ({ ... }),
textStyle: (mark) => ({ ... }),
highlight: (mark) => ({ ... }),
};
}}
NOTE: if any of the latest Storyblok CMS nodes and marks are not supported, please raise an issue or contribute.
Please see our contributing guidelines and our code of conduct.