Astro > Structured Text fields

Rich text in DatoCMS is stored in Structured Text fields, which lets us use it in many different contexts, from HTML in the browser to speech fulfillments in voice interfaces, if that's what you want.

There's a lot to be said about Structured Text and the extensibility of it, but for now let's just say that it returns content in a particular JSON format called dast which will resemble this example:

1
{
2
  "schema": "dast",
3
  "document": {
4
    "type": "root",
5
    "children": [
6
      {
7
        "type": "heading",
8
        "level": 1,
9
        "children": [
10
          {
11
            "type": "span",
12
            "marks": [],
13
            "value": "Hello world!"
14
          }
15
        ]
16
      }
17
    ]
18
  }
19
}

To make it easy to convert this format in HTML inside your Astro projects, we released a package called @datocms/astro that exposes a <StructuredText /> component that does all the tedious work for you.

To take advantage of it, install the @datocms/astro package if you haven't already:

yarn add @datocms/astro

Now let's make a GraphQL query to fetch a Structured Text field and feed the result to the data prop of a <StructuredText /> component:

1
---
2
import { StructuredText } from '@datocms/astro';
3

4
const query = `
5
  query HomeQuery {
6
    blogPost {
7
      title
8
      content {
9
        value
10
      }
11
    }
12
  }
13
`;
14
const data = await executeQuery(query);
15
---
16

17
<StructuredText data={data.blogPost.content} />

Rendering special nodes

Other than "regular" formatting nodes (paragraphs, lists, etc.), Structured Text documents can contain three special types of node:

• itemLink nodes are just like regular HTML hyperlinks, but point to other records instead of URLs;

• inlineItem nodes lets you directly embed a reference to a record in-between regular text;

• block nodes lets you embed a DatoCMS block record in-between regular paragraphs;

If a Structured Text document contains one of these nodes, then we need to change the GraphQL query, so that we also fetch all the records and blocks it references. As an example, if the field can link to other Blog posts, and can embed blocks of type "Image block", then the query should change like this:

1
const query = `query HomeQuery {
2
  blogPostfirst {
3
    id
4
    title
5
    content {
6
      value
7
      blocks {
8
        ... on RecordInterface {
9
          id
10
          __typename
11
        }
12
        ... on ImageBlockRecord {
13
          image { url alt }
14
        }
15
      }
16
      links {
17
        ... on RecordInterface {
18
          id
19
          __typename
20
        }
21
        ... on BlogPostRecord {
22
          slug
23
          title
24
        }
25
      }
26
    }
27
  }
28
}`;

You also need to instruct <StructuredText /> on how to display these nodes. This can be done by using the blockComponents, inlineRecordComponents, and linkToRecordComponents props to specify the Astro component to render the node.

1
---
2
import { StructuredText } from '@datocms/svelte';
3

4
import ImageBlock from '~/components/ImageBlock/index.astro';
5
import InlineBlogPost from '~/components/InlineBlogPost/index.astro';
6
import LinkToBlogPost from '~/components/LinkToBlogPost/index.astro';
7
---
8

9
<StructuredText
10
  data={blogPost.content}
11
  blockComponents={{
12
    ImageBlockRecord: ImageBlock,
13
  }}
14
  inlineRecordComponents={{
15
    BlogPostRecord: InlineBlogPost,
16
  }}
17
  linkToRecordComponents={{
18
    BlogPostRecord: LinkToBlogPost,
19
  }}
20
/>

The following rules will apply:

• Astro components passed in blockComponents will be used to render blocks and will receive a block prop containing the actual block data.

• Astro components passed in inlineRecordComponents will be used to render inline records and will receive a record prop containing the actual record.

• Astro components passed in linkToRecordComponents will be used to render links to records and will receive the following props: node (the actual 'inlineItem' node), record (the record linked to the node), and attrs (the custom attributes for the link specified by the node).