Sorry, no results found for "".
Structured Text content is stored as a JSON object consisting of two mandatory keys:
document
: the content, expressed as a unist
tree;
schema
: a string that specifies the unist dialect used inside the document
itself.
Generally speaking, you want to set the schema
key to the dast
dialect (which stands for DatoCMS Abstract Syntax Tree), so that:
you can take advantage of the default Structured Text editor that DatoCMS offers;
you can reinforce a number of additional validations to ensure consistency within the document.
If you would like to to use a custom unist format rather than dast
, please let us know!
dast
) specification The dast
specification adheres to the Unified collective, which offers a large ecosystem of utilities to parse, transform, manipulate, convert, and serialize content of any kind.
Unified is implemented and used as foundation by several popular libraries, such as rehype (HTML parser), remark (Markdown parser) and the MDX project. All these different projects are able to integrate with each other due to the fact that, to describe the content they treat, they all use the same common JSON format called unist
.
Just like HTML, a dast
document is composed of nodes within nodes:
Each node has a type attributed called type
The top-level node in the dast
specification must be of type root
Most nodes have a children
attribute to specify the nodes it contains
The leaves of the tree are nodes of type span
, which do not offer a children
attribute but store the final text as a string in their value
attribute
The specs define exactly which attributes and children each node permits.
Let's look at an example:
1{2 "type": "root",3 "children": [4 {5 "type": "heading",6 "level": 1,7 "children": [8 {9 "type": "span",10 "marks": [],11 "value": "This is a title!"12 }13 ]14 },15 {16 "type": "paragraph",17 "children": [18 {19 "type": "span",20 "value": "This is a "21 }22 {23 "type": "span",24 "marks": ["strong"],25 "value": "paragraph!"26 }27 ]28 },29 {30 "type": "list",31 "style": "bulleted",32 "children": [33 {34 "type": "listItem",35 {36 "type": "paragraph",37 "children": [38 {39 "type": "span",40 "value": "And this is a list!"41 }42 ]43 },44 }45 ]46 }47 ]48}
dast
documents You can take advantage of several utilities to work with nodes in a dast
document. For example, you can:
compose and assemble a document with unist-builder
;
select nodes with a CSS-like syntax using unist-util-select
;
have a compact representation of the document via unist-util-inspect
;
1import u from 'unist-builder';2import inspect from 'unist-util-inspect';3
4const document =5 u('root', [6 u('heading', { level: 1}, [7 u('span', 'This is the title!')8 ]),9 u('paragraph', [10 u('span', 'And '),11 u('span', { marks: ['strong'] }, 'this'),12 u('span', ' is a paragraph!')13 ])14 ]);15
16console.log(inspect(document));17
18root[2]19├─0 heading[1]20│ │ level: 121│ └─0 span "This is the title!"22└─1 paragraph[3]23 ├─0 span "And "24 ├─1 span "this"25 │ marks: ["strong"]26 └─2 span " is a paragraph!"
In addition to that, we built a set of specific tools to work with Structured Text and dast
documents:
datocms-html-to-structured-text
to convert HTML/Markdown into Structured Text;
datocms-structured-text-utils
to validate a document for dast
-compliance before submitting to the API, and to have JavaScript nodes definitions and Typescript types and type guards;
datocms-structured-text-to-plain-text
to render Structured Text as plain text;
datocms-structured-text-to-html-string
to render Structured Text as an HTML string;
datocms-structured-text-to-dom-nodes
to transform Structured Text into a list of DOM nodes;
<StructuredText />
component if you need to render Structured Text in React;
<datocms-structured-text />
component if you need to render Structured Text in Vue.
dast
The latest dast
format specification is always available at the following url:
https://site-api.datocms.com/docs/dast-schema.json
root
Every dast
document MUST start with a root
node.
It allows the following children nodes: paragraph
, heading
, list
, code
, blockquote
, block
and thematicBreak
.
1{2 "type": "root",3 "children": [4 {5 "type": "heading",6 "level": 1,7 "children": [8 {9 "type": "span",10 "value": "Title"11 }12 ]13 },14 {15 "type": "paragraph",16 "children": [17 {18 "type": "span",19 "value": "A simple paragraph!"20 }21 ]22 }23 ]24}
paragraph
A paragraph
node represents a unit of textual content.
It allows the following children nodes: span
, link
, itemLink
and inlineItem
.
1{2 "type": "paragraph",3 "children": [4 {5 "type": "span",6 "value": "A simple paragraph!"7 }8 ]9}
span
A span
node represents a text node. It might optionally contain decorators called marks
. It is worth
mentioning that you can use the \n
newline character to express line breaks.
It does not allow children nodes.
1{2 "type": "span",3 "marks": ["highlight", "emphasis"],4 "value": "Some random text here, move on!"5}
link
A link
node represents a normal hyperlink. It might optionally contain a number of additional
custom information under the meta
key. You can also link to DatoCMS records using
the itemLink
node.
It allows the following children nodes: span
.
1{2 "type": "link",3 "url": "https://www.datocms.com/",4 "meta": [5 { "id": "rel", "value": "nofollow" },6 { "id": "target", "value": "_blank" }7 ],8 "children": [9 {10 "type": "span",11 "value": "The best CMS in town"12 }13 ]14}
itemLink
An itemLink
node is similar to a link
node node, but instead of
linking a portion of text to a URL, it links the document to another record
present in the same DatoCMS project.
It might optionally contain a number of additional custom information under
the meta
key.
If you want to link to a DatoCMS record without having to specify some
inner content, then please use the inlineItem
node.
It allows the following children nodes: span
.
1{2 "type": "itemLink",3 "item": "38945648",4 "meta": [5 { "id": "rel", "value": "nofollow" },6 { "id": "target", "value": "_blank" }7 ],8 "children": [9 {10 "type": "span",11 "value": "Matteo Giaccone"12 }13 ]14}
inlineItem
An inlineItem
, similarly to itemLink
, links the document to
another record but does not specify any inner content (children).
It can be used in situations where it is up to the frontend to decide how to present the
record (ie. a widget, or an <a>
tag pointing to the URL of the record with a text that
is the title of the linked record).
It does not allow children nodes.
1{2 "type": "inlineItem",3 "item": "74619345"4}
heading
An heading
node represents a heading of a section. Using the level
attribute you
can control the rank of the heading.
It allows the following children nodes: span
, link
, itemLink
and inlineItem
.
1{2 "type": "heading",3 "level": 2,4 "children": [5 {6 "type": "span",7 "value": "An h2 heading!"8 }9 ]10}
list
A list
node represents a list of items. Unordered lists must have its style
field
set to bulleted
, while ordered lists, instead, have its style
field set to numbered
.
It allows the following children nodes: listItem
.
1{2 "type": "list",3 "style": "bulleted",4 "children": [5 {6 "type": "listItem",7 "children": [8 {9 "type": "paragraph",10 "children": [11 {12 "type": "span",13 "value": "This is a list item!"14 }15 ]16 }17 ]18 }19 ]20}
listItem
A listItem
node represents an item in a list.
It allows the following children nodes: paragraph
and list
.
1{2 "type": "listItem",3 "children": [4 {5 "type": "paragraph",6 "children": [7 {8 "type": "span",9 "value": "This is a list item!"10 }11 ]12 }13 ]14}
code
A code
node represents a block of preformatted text, such as computer code.
It does not allow children nodes.
1{2 "type": "code",3 "language": "javascript",4 "highlight": [1],5 "code": "function greetings() {\n console.log('Hi!');\n}"6}
blockquote
A blockquote
node is a containter that represents text which is an extended quotation.
It allows the following children nodes: paragraph
.
1{2 "type": "blockquote",3 "attribution": "Oscar Wilde",4 "children": [5 {6 "type": "paragraph",7 "children": [8 {9 "type": "span",10 "value": "Be yourself; everyone else is taken."11 }12 ]13 }14 ]15}
block
Similarly to Modular Content fields,
you can also embed block records into Structured Text. A block
node stores a reference to a
DatoCMS block record embedded inside the dast
document.
This type of node can only be put as a direct child of the root
node.
It does not allow children nodes.
1{2 "type": "block",3 "item": "1238455312"4}
thematicBreak
A thematicBreak
node represents a thematic break between paragraph-level elements:
for example, a change of scene in a story, or a shift of topic within a section.
It does not allow children nodes.
1{2 "type": "thematicBreak"3}