@datocms/astro 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -38
- package/package.json +5 -2
- package/src/Image/README.md +124 -0
- package/src/Image/index.ts +2 -0
- package/src/QueryListener/README.md +67 -0
- package/src/QueryListener/index.ts +1 -0
- package/src/Seo/README.md +57 -0
- package/src/StructuredText/README.md +41 -95
- package/src/index.ts +4 -0
package/README.md
CHANGED
|
@@ -1,54 +1,66 @@
|
|
|
1
|
-
|
|
1
|
+
<!--datocms-autoinclude-header start-->
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
<a href="https://www.datocms.com/"><img src="https://www.datocms.com/images/full_logo.svg" height="60"></a>
|
|
4
|
+
|
|
5
|
+
👉 [Visit the DatoCMS homepage](https://www.datocms.com) or see [What is DatoCMS?](#what-is-datocms)
|
|
6
|
+
|
|
7
|
+
<!--datocms-autoinclude-header end-->
|
|
8
|
+
|
|
9
|
+
# @datocms/astro
|
|
10
|
+
|
|
11
|
+
[](https://github.com/datocms/astro-datocms/blob/master/LICENSE) [](https://www.npmjs.com/package/@datocms/astro)
|
|
12
|
+
|
|
13
|
+
A set of TypeScript-ready components and utilities to work faster with [DatoCMS](https://www.datocms.com/) in Astro project. Integrates seamlessly with [DatoCMS's GraphQL Content Delivery API](https://www.datocms.com/docs/content-delivery-api).
|
|
6
14
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
[](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/basics/devcontainer.json)
|
|
15
|
+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
16
|
+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
10
17
|
|
|
11
|
-
|
|
18
|
+
- [Features](#features)
|
|
19
|
+
- [Installation](#installation)
|
|
20
|
+
- [What is DatoCMS?](#what-is-datocms)
|
|
12
21
|
|
|
13
|
-
|
|
22
|
+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
14
23
|
|
|
15
|
-
##
|
|
24
|
+
## Features
|
|
16
25
|
|
|
17
|
-
|
|
26
|
+
`@datocms/astro` contains ready-to-use Astro components and helpers:
|
|
18
27
|
|
|
19
|
-
|
|
20
|
-
/
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
│ └── pages/
|
|
29
|
-
│ └── index.astro
|
|
30
|
-
└── package.json
|
|
28
|
+
- [`<Image />`](src/Image)
|
|
29
|
+
- [`<Seo />`](src/Seo)
|
|
30
|
+
- [`<StructuredText />`](src/StructuredText)
|
|
31
|
+
- [`<QueryListener />`](src/QueryListener)
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
npm install @datocms/astro
|
|
31
37
|
```
|
|
32
38
|
|
|
33
|
-
|
|
39
|
+
<!--datocms-autoinclude-footer start-->
|
|
40
|
+
|
|
41
|
+
# What is DatoCMS?
|
|
42
|
+
|
|
43
|
+
<a href="https://www.datocms.com/"><img src="https://www.datocms.com/images/full_logo.svg" height="60"></a>
|
|
44
|
+
|
|
45
|
+
[DatoCMS](https://www.datocms.com/) is the REST & GraphQL Headless CMS for the modern web.
|
|
34
46
|
|
|
35
|
-
|
|
47
|
+
Trusted by over 25,000 enterprise businesses, agency partners, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our [developers](https://www.datocms.com/team/best-cms-for-developers), [content editors](https://www.datocms.com/team/content-creators) and [marketers](https://www.datocms.com/team/cms-digital-marketing)!
|
|
36
48
|
|
|
37
|
-
|
|
49
|
+
**Quick links:**
|
|
38
50
|
|
|
39
|
-
|
|
51
|
+
- ⚡️ Get started with a [free DatoCMS account](https://dashboard.datocms.com/signup)
|
|
52
|
+
- 🔖 Go through the [docs](https://www.datocms.com/docs)
|
|
53
|
+
- ⚙️ Get [support from us and the community](https://community.datocms.com/)
|
|
54
|
+
- 🆕 Stay up to date on new features and fixes on the [changelog](https://www.datocms.com/product-updates)
|
|
40
55
|
|
|
41
|
-
|
|
56
|
+
**Our featured repos:**
|
|
42
57
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
| `npm run preview` | Preview your build locally, before deploying |
|
|
49
|
-
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
|
|
50
|
-
| `npm run astro -- --help` | Get help using the Astro CLI |
|
|
58
|
+
- [datocms/react-datocms](https://github.com/datocms/react-datocms): React helper components for images, Structured Text rendering, and more
|
|
59
|
+
- [datocms/js-rest-api-clients](https://github.com/datocms/js-rest-api-clients): Node and browser JavaScript clients for updating and administering your content. For frontend fetches, we recommend using our [GraphQL Content Delivery API](https://www.datocms.com/docs/content-delivery-api) instead.
|
|
60
|
+
- [datocms/cli](https://github.com/datocms/cli): Command-line interface that includes our [Contentful importer](https://github.com/datocms/cli/tree/main/packages/cli-plugin-contentful) and [Wordpress importer](https://github.com/datocms/cli/tree/main/packages/cli-plugin-wordpress)
|
|
61
|
+
- [datocms/plugins](https://github.com/datocms/plugins): Example plugins we've made that extend the editor/admin dashboard
|
|
62
|
+
- [DatoCMS Starters](https://www.datocms.com/marketplace/starters) has examples for various Javascript frontend frameworks
|
|
51
63
|
|
|
52
|
-
|
|
64
|
+
Or see [all our public repos](https://github.com/orgs/datocms/repositories?q=&type=public&language=&sort=stargazers)
|
|
53
65
|
|
|
54
|
-
|
|
66
|
+
<!--datocms-autoinclude-footer end-->
|
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "@datocms/astro",
|
|
3
3
|
"description": "A set of components and utilities to work faster with DatoCMS in Astro projects.",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"version": "0.2.
|
|
5
|
+
"version": "0.2.1",
|
|
6
6
|
"sideEffects": false,
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|
|
@@ -25,10 +25,12 @@
|
|
|
25
25
|
"scripts": {
|
|
26
26
|
"prepare": "npx simple-git-hooks",
|
|
27
27
|
"lint": "prettier --check .",
|
|
28
|
-
"format": "npx prettier . --write",
|
|
28
|
+
"format": "npm run toc && npx prettier . --write",
|
|
29
|
+
"toc": "doctoc --github README.md src",
|
|
29
30
|
"test": "echo 1"
|
|
30
31
|
},
|
|
31
32
|
"exports": {
|
|
33
|
+
".": "./src/index.ts",
|
|
32
34
|
"./Image": "./src/Image/index.ts",
|
|
33
35
|
"./StructuredText": "./src/StructuredText/index.ts",
|
|
34
36
|
"./Seo": "./src/Seo/index.ts",
|
|
@@ -50,6 +52,7 @@
|
|
|
50
52
|
},
|
|
51
53
|
"devDependencies": {
|
|
52
54
|
"astro": "^4.13.1",
|
|
55
|
+
"doctoc": "^2.2.1",
|
|
53
56
|
"np": "^10.0.7",
|
|
54
57
|
"prettier": "^3.3.3",
|
|
55
58
|
"prettier-plugin-astro": "^0.14.1",
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# Progressive responsive image
|
|
2
|
+
|
|
3
|
+
`<Image>` is a TypeScript-ready Astro component specially designed to work seamlessly with DatoCMS’s [`responsiveImage` GraphQL query](https://www.datocms.com/docs/content-delivery-api/uploads#responsive-images) which optimizes image loading for your websites.
|
|
4
|
+
|
|
5
|
+
### Out-of-the-box features
|
|
6
|
+
|
|
7
|
+
- Completely native, with no JavaScript footprint
|
|
8
|
+
- Offers optimized version of images for browsers that support WebP/AVIF format
|
|
9
|
+
- Generates multiple smaller images so smartphones and tablets don’t download desktop-sized images
|
|
10
|
+
- Efficiently lazy loads images to speed initial page load and save bandwidth
|
|
11
|
+
- Holds the image position so your page doesn’t jump while images load
|
|
12
|
+
- Uses either blur-up or background color techniques to show a preview of the image while it loads
|
|
13
|
+
|
|
14
|
+
### Table of contents
|
|
15
|
+
|
|
16
|
+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
17
|
+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
18
|
+
|
|
19
|
+
- [Setup](#setup)
|
|
20
|
+
- [Usage](#usage)
|
|
21
|
+
- [Example](#example)
|
|
22
|
+
- [The `ResponsiveImage` object](#the-responsiveimage-object)
|
|
23
|
+
- [`<Image />`](#image-)
|
|
24
|
+
- [Props](#props)
|
|
25
|
+
|
|
26
|
+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
27
|
+
|
|
28
|
+
### Setup
|
|
29
|
+
|
|
30
|
+
You can import the component like this:
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
import { Image } from '@datocms/astro/Image';
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Usage
|
|
37
|
+
|
|
38
|
+
1. Use `<Image>` in place of the regular `<img />` tag
|
|
39
|
+
2. Write a GraphQL query to your DatoCMS project using the [`responsiveImage` query](https://www.datocms.com/docs/content-delivery-api/images-and-videos#responsive-images)
|
|
40
|
+
|
|
41
|
+
The GraphQL query returns multiple thumbnails with optimized compression. The components automatically set up the "blur-up" effect as well as lazy loading of images further down the screen.
|
|
42
|
+
|
|
43
|
+
## Example
|
|
44
|
+
|
|
45
|
+
Here is a minimal starting point:
|
|
46
|
+
|
|
47
|
+
```astro
|
|
48
|
+
---
|
|
49
|
+
import { Image } from '@datocms/astro/Image';
|
|
50
|
+
import { executeQuery } from '@datocms/cda-client';
|
|
51
|
+
|
|
52
|
+
const query = gql`
|
|
53
|
+
query {
|
|
54
|
+
blogPost {
|
|
55
|
+
title
|
|
56
|
+
cover {
|
|
57
|
+
responsiveImage(imgixParams: { fit: crop, w: 300, h: 300, auto: format }) {
|
|
58
|
+
# always required
|
|
59
|
+
src
|
|
60
|
+
width
|
|
61
|
+
height
|
|
62
|
+
# not required, but strongly suggested!
|
|
63
|
+
alt
|
|
64
|
+
title
|
|
65
|
+
# blur-up placeholder, JPEG format, base64-encoded, or...
|
|
66
|
+
base64
|
|
67
|
+
# background color placeholder
|
|
68
|
+
bgColor
|
|
69
|
+
# you can omit sizes if you explicitly pass the sizes prop to the image component
|
|
70
|
+
sizes
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
`;
|
|
76
|
+
|
|
77
|
+
const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
<Image data={blogPost.cover.responsiveImage} />
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## The `ResponsiveImage` object
|
|
84
|
+
|
|
85
|
+
The `data` prop of both components expects an object with the same shape as the one returned by `responsiveImage` GraphQL call. It's up to you to make a GraphQL query that will return the properties you need for a specific use of the `<Image>` component.
|
|
86
|
+
|
|
87
|
+
- The minimum required properties for `data` are: `src`, `width` and `height`;
|
|
88
|
+
- `alt` and `title`, while not mandatory, are all highly suggested, so remember to use them!
|
|
89
|
+
- If you don't request `srcSet`, the component will auto-generate an `srcset` based on `src` + the `srcSetCandidates` prop (it can help reducing the GraphQL response size drammatically when many images are returned);
|
|
90
|
+
- We strongly to suggest to always specify [`{ auto: format }`](https://docs.imgix.com/apis/rendering/auto/auto#format) in your `imgixParams`, instead of requesting `webpSrcSet`, so that you can also take advantage of more performant optimizations (AVIF), without increasing GraphQL response size;
|
|
91
|
+
- If you request both the `bgColor` and `base64` property, the latter will take precedence, so just avoid querying both fields at the same time, as it will only make the GraphQL response bigger :wink:;
|
|
92
|
+
- You can avoid requesting `sizes` and directly pass a `sizes` prop to the component to reduce the GraphQL response size;
|
|
93
|
+
|
|
94
|
+
Here's a complete recap of what `responsiveImage` offers:
|
|
95
|
+
|
|
96
|
+
| property | type | required | description |
|
|
97
|
+
| ----------- | ------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
98
|
+
| src | string | :white_check_mark: | The `src` attribute for the image |
|
|
99
|
+
| width | integer | :white_check_mark: | The width of the image |
|
|
100
|
+
| height | integer | :white_check_mark: | The height of the image |
|
|
101
|
+
| alt | string | :x: | Alternate text (`alt`) for the image (not required, but strongly suggested!) |
|
|
102
|
+
| title | string | :x: | Title attribute (`title`) for the image (not required, but strongly suggested!) |
|
|
103
|
+
| sizes | string | :x: | The HTML5 `sizes` attribute for the image (omit it if you're already passing a `sizes` prop to the Image component) |
|
|
104
|
+
| base64 | string | :x: | A base64-encoded thumbnail to offer during image loading |
|
|
105
|
+
| bgColor | string | :x: | The background color for the image placeholder (omit it if you're already requesting `base64`) |
|
|
106
|
+
| srcSet | string | :x: | The HTML5 `srcSet` attribute for the image (can be omitted, the Image component knows how to build it based on `src`) |
|
|
107
|
+
| webpSrcSet | string | :x: | The HTML5 `srcSet` attribute for the image in WebP format (deprecated, it's better to use the [`auto=format`](https://docs.imgix.com/apis/rendering/auto/auto#format) Imgix transform instead) |
|
|
108
|
+
| aspectRatio | float | :x: | The aspect ratio (width/height) of the image |
|
|
109
|
+
|
|
110
|
+
## `<Image />`
|
|
111
|
+
|
|
112
|
+
### Props
|
|
113
|
+
|
|
114
|
+
| prop | type | default | required | description |
|
|
115
|
+
| ---------------- | ------------------------ | ---------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
116
|
+
| data | `ResponsiveImage` object | | :white_check_mark: | The actual response you get from a DatoCMS `responsiveImage` GraphQL query \*\*\*\* |
|
|
117
|
+
| pictureClass | string | null | :x: | Additional CSS class for the root `<picture>` tag |
|
|
118
|
+
| pictureStyle | CSS properties | null | :x: | Additional CSS rules to add to the root `<picture>` tag |
|
|
119
|
+
| imgClass | string | null | :x: | Additional CSS class for the `<img>` tag |
|
|
120
|
+
| imgStyle | CSS properties | null | :x: | Additional CSS rules to add to the `<img>` tag |
|
|
121
|
+
| priority | Boolean | false | :x: | Disables lazy loading, and sets the image [fetchPriority](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority) to "high" |
|
|
122
|
+
| sizes | string | undefined | :x: | The HTML5 [`sizes`](https://web.dev/learn/design/responsive-images/#sizes) attribute for the image (will be used `data.sizes` as a fallback) |
|
|
123
|
+
| usePlaceholder | Boolean | true | :x: | Whether the image should use a blurred image placeholder |
|
|
124
|
+
| srcSetCandidates | Array<number> | [0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4] | :x: | If `data` does not contain `srcSet`, the candidates for the `srcset` attribute of the image will be auto-generated based on these width multipliers |
|
package/src/Image/index.ts
CHANGED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Live real-time updates
|
|
2
|
+
|
|
3
|
+
`<QueryListener />` is an Astro component that you can use to implement client-side reload of the page as soon as the content of a query changes. It uses DatoCMS's [Real-time Updates API](https://www.datocms.com/docs/real-time-updates-api/api-reference) to receive the updated query results in real-time, and is able to reconnect in case of network failures.
|
|
4
|
+
|
|
5
|
+
Live reloads are great to get instant previews of your content while editing it inside DatoCMS.
|
|
6
|
+
|
|
7
|
+
`<QueryListener />` is based on the `subscribeToQuery` helper provided by the [datocms-listen](https://www.npmjs.com/package/datocms-listen) package.
|
|
8
|
+
|
|
9
|
+
## Table of Contents
|
|
10
|
+
|
|
11
|
+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
12
|
+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
13
|
+
|
|
14
|
+
- [Installation](#installation)
|
|
15
|
+
- [Reference](#reference)
|
|
16
|
+
- [Initialization options](#initialization-options)
|
|
17
|
+
|
|
18
|
+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
npm install --save @datocms/astro
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Reference
|
|
27
|
+
|
|
28
|
+
Import `<QueryListener>` from `@datocms/astro` and use it inside your components setup function like this:
|
|
29
|
+
|
|
30
|
+
```astro
|
|
31
|
+
---
|
|
32
|
+
import { QueryListener } from '@datocms/astro/QueryListener';
|
|
33
|
+
import { executeQuery } from '@datocms/cda-client';
|
|
34
|
+
|
|
35
|
+
const query = gql`
|
|
36
|
+
query {
|
|
37
|
+
homepage {
|
|
38
|
+
title
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
`;
|
|
42
|
+
|
|
43
|
+
const data = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
<h1>{data.homepage.title}</h1>
|
|
47
|
+
|
|
48
|
+
<QueryListener query={query} token="<YOUR-API-TOKEN>" />
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Initialization options
|
|
52
|
+
|
|
53
|
+
| prop | type | required | description | default |
|
|
54
|
+
| ------------------ | ------------------------------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------ |
|
|
55
|
+
| enabled | boolean | :x: | Whether the subscription has to be performed or not | true |
|
|
56
|
+
| query | string \| [`TypedDocumentNode`](https://github.com/dotansimha/graphql-typed-document-node) | :white_check_mark: | The GraphQL query to subscribe | |
|
|
57
|
+
| token | string | :white_check_mark: | DatoCMS API token to use | |
|
|
58
|
+
| variables | Object | :x: | GraphQL variables for the query | |
|
|
59
|
+
| includeDrafts | boolean | :x: | If true, draft records will be returned | |
|
|
60
|
+
| excludeInvalid | boolean | :x: | If true, invalid records will be filtered out | |
|
|
61
|
+
| environment | string | :x: | The name of the DatoCMS environment where to perform the query (defaults to primary environment) | |
|
|
62
|
+
| contentLink | `'vercel-1'` or `undefined` | :x: | If true, embed metadata that enable Content Link | |
|
|
63
|
+
| baseEditingUrl | string | :x: | The base URL of the DatoCMS project | |
|
|
64
|
+
| cacheTags | boolean | :x: | If true, receive the Cache Tags associated with the query | |
|
|
65
|
+
| initialData | Object | :x: | The initial data to use on the first render | |
|
|
66
|
+
| reconnectionPeriod | number | :x: | In case of network errors, the period (in ms) to wait to reconnect | 1000 |
|
|
67
|
+
| baseUrl | string | :x: | The base URL to use to perform the query | `https://graphql-listen.datocms.com` |
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# Social share, SEO and Favicon meta tags
|
|
2
|
+
|
|
3
|
+
Just like the image component, `<Seo />` is a component specially designed to work seamlessly with DatoCMS’s [`_seoMetaTags` and `faviconMetaTags` GraphQL queries](https://www.datocms.com/docs/content-delivery-api/seo) so that you can handle proper SEO in your pages.
|
|
4
|
+
|
|
5
|
+
You can use `<Seo />` in your pages, and it will inject title, meta and link tags in the document's `<head>` tag.
|
|
6
|
+
|
|
7
|
+
### Table of contents
|
|
8
|
+
|
|
9
|
+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
|
10
|
+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
11
|
+
|
|
12
|
+
- [Usage](#usage)
|
|
13
|
+
- [Example](#example)
|
|
14
|
+
|
|
15
|
+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
`<Seo />`'s `data` prop takes an array of `Tag`s in the exact form they're returned by the following [DatoCMS GraphQL API](https://www.datocms.com/docs/content-delivery-api/seo) queries:
|
|
20
|
+
|
|
21
|
+
- `_seoMetaTags` query on any record, or
|
|
22
|
+
- `faviconMetaTags` on the global `_site` object.
|
|
23
|
+
|
|
24
|
+
## Example
|
|
25
|
+
|
|
26
|
+
Here is an example:
|
|
27
|
+
|
|
28
|
+
```astro
|
|
29
|
+
---
|
|
30
|
+
import { Seo } from '@datocms/astro/Seo';
|
|
31
|
+
import { executeQuery } from '@datocms/cda-client';
|
|
32
|
+
|
|
33
|
+
const query = gql`
|
|
34
|
+
query {
|
|
35
|
+
page: homepage {
|
|
36
|
+
title
|
|
37
|
+
seo: _seoMetaTags {
|
|
38
|
+
attributes
|
|
39
|
+
content
|
|
40
|
+
tag
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
site: _site {
|
|
44
|
+
favicon: faviconMetaTags {
|
|
45
|
+
attributes
|
|
46
|
+
content
|
|
47
|
+
tag
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
`;
|
|
52
|
+
|
|
53
|
+
const result = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
<Seo data={[...result.page.seo, ...result.site.favicon]} />
|
|
57
|
+
```
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Structured text
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`<StructuredText />` is an Astro component that you can use to render the value contained inside a DatoCMS [Structured Text field type](https://www.datocms.com/docs/structured-text/dast).
|
|
4
4
|
|
|
5
5
|
### Table of contents
|
|
6
6
|
|
|
@@ -21,19 +21,17 @@
|
|
|
21
21
|
Import the component like this:
|
|
22
22
|
|
|
23
23
|
```js
|
|
24
|
-
import { StructuredText } from '@datocms/
|
|
24
|
+
import { StructuredText } from '@datocms/astro/StructuredText';
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
## Basic usage
|
|
28
28
|
|
|
29
|
-
```
|
|
30
|
-
|
|
29
|
+
```astro
|
|
30
|
+
---
|
|
31
|
+
import { StructuredText } from '@datocms/astro/StructuredText';
|
|
32
|
+
import { executeQuery } from '@datocms/cda-client';
|
|
31
33
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
import { StructuredText } from '@datocms/svelte';
|
|
35
|
-
|
|
36
|
-
const query = `
|
|
34
|
+
const query = gql`
|
|
37
35
|
query {
|
|
38
36
|
blogPost {
|
|
39
37
|
title
|
|
@@ -44,30 +42,12 @@ const query = `
|
|
|
44
42
|
}
|
|
45
43
|
`;
|
|
46
44
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
onMount(async () => {
|
|
50
|
-
const response = await fetch('https://graphql.datocms.com/', {
|
|
51
|
-
method: 'POST',
|
|
52
|
-
headers: {
|
|
53
|
-
'Content-Type': 'application/json',
|
|
54
|
-
Authorization: "Bearer AN_API_TOKEN",
|
|
55
|
-
},
|
|
56
|
-
body: JSON.stringify({ query })
|
|
57
|
-
})
|
|
58
|
-
|
|
59
|
-
const json = await response.json()
|
|
60
|
-
|
|
61
|
-
data = json.data;
|
|
62
|
-
});
|
|
63
|
-
|
|
64
|
-
</script>
|
|
45
|
+
const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
|
|
46
|
+
---
|
|
65
47
|
|
|
66
48
|
<article>
|
|
67
|
-
{
|
|
68
|
-
|
|
69
|
-
<StructuredText data={data.blogPost.content} />
|
|
70
|
-
{/if}
|
|
49
|
+
<h1>{data.blogPost.title}</h1>
|
|
50
|
+
<StructuredText data={data.blogPost.content} />
|
|
71
51
|
</article>
|
|
72
52
|
```
|
|
73
53
|
|
|
@@ -84,20 +64,16 @@ You need to use custom components in the following cases:
|
|
|
84
64
|
|
|
85
65
|
Here is an example using custom components for blocks, inline and item links. Take a look at the [test fixtures](https://github.com/datocms/datocms-svelte/tree/main/src/lib/components/StructuredText/__tests__/__fixtures__) to see examples on how to implement these components.
|
|
86
66
|
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
import { onMount } from 'svelte';
|
|
91
|
-
|
|
67
|
+
```astro
|
|
68
|
+
---
|
|
92
69
|
import { isBlock, isInlineItem, isItemLink } from 'datocms-structured-text-utils';
|
|
70
|
+
import { StructuredText } from '@datocms/astro/StructuredText';
|
|
93
71
|
|
|
94
|
-
import
|
|
72
|
+
import Block from '~/components/Block/index.astro';
|
|
73
|
+
import InlineItem from '~/components/InlineItem/index.astro';
|
|
74
|
+
import ItemLink from '~/components/ItemLink/index.astro';
|
|
95
75
|
|
|
96
|
-
|
|
97
|
-
import InlineItem from './InlineItem.svelte';
|
|
98
|
-
import ItemLink from './ItemLink.svelte';
|
|
99
|
-
|
|
100
|
-
const query = `
|
|
76
|
+
const query = gql`
|
|
101
77
|
query {
|
|
102
78
|
blogPost {
|
|
103
79
|
title
|
|
@@ -116,9 +92,7 @@ const query = `
|
|
|
116
92
|
... on ImageRecord {
|
|
117
93
|
id
|
|
118
94
|
image {
|
|
119
|
-
responsiveImage(
|
|
120
|
-
imgixParams: { fit: crop, w: 300, h: 300, auto: format }
|
|
121
|
-
) {
|
|
95
|
+
responsiveImage(imgixParams: { fit: crop, w: 300, h: 300, auto: format }) {
|
|
122
96
|
srcSet
|
|
123
97
|
webpSrcSet
|
|
124
98
|
sizes
|
|
@@ -138,37 +112,19 @@ const query = `
|
|
|
138
112
|
}
|
|
139
113
|
`;
|
|
140
114
|
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
onMount(async () => {
|
|
144
|
-
const response = await fetch('https://graphql.datocms.com/', {
|
|
145
|
-
method: 'POST',
|
|
146
|
-
headers: {
|
|
147
|
-
'Content-Type': 'application/json',
|
|
148
|
-
Authorization: "Bearer AN_API_TOKEN",
|
|
149
|
-
},
|
|
150
|
-
body: JSON.stringify({ query })
|
|
151
|
-
})
|
|
152
|
-
|
|
153
|
-
const json = await response.json()
|
|
154
|
-
|
|
155
|
-
data = json.data;
|
|
156
|
-
});
|
|
157
|
-
|
|
158
|
-
</script>
|
|
115
|
+
const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
|
|
116
|
+
---
|
|
159
117
|
|
|
160
118
|
<article>
|
|
161
|
-
{
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
/>
|
|
171
|
-
{/if}
|
|
119
|
+
<h1>{blogPost.title}</h1>
|
|
120
|
+
<StructuredText
|
|
121
|
+
data={blogPost.content}
|
|
122
|
+
components={[
|
|
123
|
+
[isInlineItem, InlineItem],
|
|
124
|
+
[isItemLink, ItemLink],
|
|
125
|
+
[isBlock, Block],
|
|
126
|
+
]}
|
|
127
|
+
/>
|
|
172
128
|
</article>
|
|
173
129
|
```
|
|
174
130
|
|
|
@@ -179,30 +135,20 @@ onMount(async () => {
|
|
|
179
135
|
- For `heading` nodes, you might want to add an anchor;
|
|
180
136
|
- For `code` nodes, you might want to use a custom syntax highlighting component;
|
|
181
137
|
|
|
182
|
-
In this case, you can easily override default rendering rules with the `components` props.
|
|
183
|
-
|
|
184
|
-
```svelte
|
|
185
|
-
<script>
|
|
186
|
-
import { isHeading, isCode } from 'datocms-structured-text-utils';
|
|
187
|
-
|
|
188
|
-
import Heading from './Heading.svelte';
|
|
189
|
-
import Code from './Code.svelte';
|
|
138
|
+
In this case, you can easily override default rendering rules with the `components` props.
|
|
190
139
|
|
|
191
|
-
|
|
192
|
-
|
|
140
|
+
```astro
|
|
141
|
+
---
|
|
142
|
+
import { isHeading } from 'datocms-structured-text-utils';
|
|
143
|
+
import HeadingWithAnchorLink from '~/components/HeadingWithAnchorLink/index.astro';
|
|
144
|
+
---
|
|
193
145
|
|
|
194
|
-
<StructuredText
|
|
195
|
-
data={data.blogPost.content}
|
|
196
|
-
components={[
|
|
197
|
-
[isHeading, Heading],
|
|
198
|
-
[isCode, Code]
|
|
199
|
-
]}
|
|
200
|
-
/>
|
|
146
|
+
<StructuredText data={blogPost.content} components={[[isHeading, HeadingWithAnchorLink]]} />
|
|
201
147
|
```
|
|
202
148
|
|
|
203
149
|
## Props
|
|
204
150
|
|
|
205
|
-
| prop | type
|
|
206
|
-
| ---------- |
|
|
207
|
-
| data | `StructuredText \| DastNode`
|
|
208
|
-
| components | [`PredicateComponentTuple[] \| null`](https://github.com/datocms/datocms
|
|
151
|
+
| prop | type | required | description | default |
|
|
152
|
+
| ---------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------- |
|
|
153
|
+
| data | `StructuredText \| DastNode` | :white_check_mark: | The actual [field value](https://www.datocms.com/docs/structured-text/dast) you get from DatoCMS | |
|
|
154
|
+
| components | [`PredicateComponentTuple[] \| null`](https://github.com/datocms/astro-datocms/blob/main/src/StructuredText/types.ts#L6) | Only required if data contain `block`, `inline_item` or `item_link` nodes | Array of tuples formed by a predicate function and custom component | `[]` |
|
package/src/index.ts
ADDED