Ntast
Notion Abstract Syntax Tree specification.
Install / Use
/learn @phuctm97/NtastREADME
![ntast][banner]
Notion Abstract Syntax Tree.
by [Notion Tweet].
ntast is a specification for representing [Notion contents][notion] as [abstract syntax trees][syntax-tree]. It implements the [unist][unist] specification. It can represent different types of pages in Notion: [Page][notion-page], [Table][notion-table], [Board][notion-board], [List][notion-list], [Calendar][notion-calendar], [Gallery][notion-gallery], and [Timeline][notion-timeline].
Contents
Introduction
This document defines a format, written in [TypeScript], for representing [Notion contents][notion] as [abstract syntax trees][syntax-tree].
Where this specification fits
ntast extends [unist], a format for syntax trees, to benefit from [its ecosystem of utilities][unist-utils], [unified], and [unified ecosystem].
ntast relates to [Notion] in that it enables reading from, applying transformations, and writing to Notion. It has a set of utilities to transform between ntast syntax trees and Notion API schemas.
ntast relates to [JavaScript] in that it has an ecosystem of utilities for working with compliant syntax trees in JavaScript. However, ntast is not limited to JavaScript and can be used in other programming languages.
What this specification isn't about
ntast focuses on only content and doesn't work with Notion-application data, such as Workspaces, Accounts, Members, Permissions, and similar settings. Ecosystem plugins may extend functionalities for these data using Notion API.
Nodes
Block
interface Block extends UnistNode {
id: string;
}
Block ([UnistNode][unist-node]) represents a node in ntast and [a content block in Notion][notion-block].
Each block has a unique id.
Example:
{
id: "b3e6e681-2eaa-4f1a-89c4-dde7f7f7a167",
type: "text",
};
Parent
interface Parent extends UnistParent {
children: Block[];
}
Parent ([UnistParent][unist-parent]) represents a node in ntast containing other nodes (said to be [children][unist-child]).
Its children are limited to only Block(s).
Literal
interface Literal extends UnistLiteral {
value: Value[];
}
Literal ([UnistLiteral][unist-literal]) represents a node in ntast containing a value.
Its value is an ordered list of Value object(s).
Page
interface Page extends Block, Parent, Literal {
type: "page";
icon?: string;
cover?: string;
}
Page represents [a Page in Notion][notion-page].
A page can be the [root][unist-root] of a [tree][unist-tree] or a [child][unist-child] of another page (known as a sub-page in Notion).
<p align="left"><img height="128" src="images/subpage-0.png"></p>Example:
<p align="left"><img height="32" src="images/subpage-1.png"></p>Yields:
{
id: "b3e6e681-2eaa-4f1a-89c4-dde7f7f7a167",
type: "page",
value: [["This is a subpage"]],
icon: "☺️",
children: [],
};
Text
interface Text extends Block, Literal {
type: "text";
}
Text represents [a Text block in Notion][notion-basic-blocks].
Example:
<p align="left"><img height="32" src="images/text-1.png"></p>Yields:
{
id: "333f9503-77f2-45b3-92df-89e2094fb354",
type: "text",
value: [
["Tools you're familiar with will just work: "],
["bold", [["b"]]],
[", "],
["italic", [["i"], ["b"]]],
[", "],
["strikethrough", [["s"]]],
[", "],
["code", [["c"]]],
[", and more."],
],
};
ToDo
interface ToDo extends Block, Literal {
type: "to_do";
checked: boolean;
}
ToDo represents [a To-do list block in Notion][notion-basic-blocks].
Example:
<p align="left"><img height="32" src="images/todo-1.png"></p> <p align="left"><img height="32" src="images/todo-2.png"></p>Yields:
[
{
id: "8b3cfeed-c0da-451e-8f18-f7086c321979",
type: "to_do",
value: [["This is a "], ["todo", [["b"]]], [" item."]],
},
{
id: "8b3cfeed-c0da-451e-8f18-f7086c321979",
type: "to_do",
value: [["This is a "], ["todo", [["b"]]], [" item."]],
checked: true,
},
];
Heading1
interface Heading1 extends Block, Literal {
type: "header";
}
Heading1 represents [a Heading 1 block in Notion][notion-basic-blocks].
Example:
<p align="left"><img height="48" src="images/h1-1.png"></p>Yields:
{
id: "f694bbd6-8fa4-44d4-b02c-ad05128fb277",
type: "header",
value: [["This is heading 1"]],
};
Heading2
interface Heading2 extends Block, Literal {
type: "sub_header";
}
Heading2 represents [a Heading 2 block in Notion][notion-basic-blocks].
Example:
<p align="left"><img height="38" src="images/h2-1.png"></p>Yields:
{
id: "f694bbd6-8fa4-44d4-b02c-ad05128fb277",
type: "sub_header",
value: [["This is heading 2"]],
};
Heading3
interface Heading3 extends Block, Literal {
type: "sub_sub_header";
}
Heading3 represents [a Heading 3 block in Notion][notion-basic-blocks].
Example:
<p align="left"><img height="28" src="images/h3-1.png"></p>Yields:
{
id: "f694bbd6-8fa4-44d4-b02c-ad05128fb277",
type: "sub_sub_header",
value: [["This is heading 3"]],
};
BulletedList
interface BulletedList extends Block, Literal, Parent {
type: "bulleted_list";
}
BulletedList represents [a Bulleted list block in
Notion][notion-basic-blocks]. It can have children.
Example:
<p align="left"><img height="110" src="images/ul-1.png"></p>Yields:
[
{
id: "dd130b72-3d53-42ea-bf3b-45e95c8e8c2d",
type: "bulleted_list",
value: [
["Heading 1", [["c"]]],
[": The largest heading, can be easily added with shortcut "],
["/h1", [["c"]]],
["."],
],
children: [],
},
{
id: "093db819-617f-47b0-b776-48abf0ff2792",
type: "bulleted_list",
value: [
["Heading 2", [["c"]]],
[": The medium-sized heading, can be easily added with shortcut "],
["/h2", [["c"]]],
["."],
],
children: [],
},
{
id: "b7d35804-e262-4d99-b039-8372470262f6",
type: "bulleted_list",
value: [
["Heading 3", [["c"]]],
[": The smallest heading, can be easily added with shortcut "],
["/h3", [["c"]]],
["."],
],
children: [],
},
];
NumberedList
interface NumberedList extends Block, Literal, Parent {
type: "numbered_list";
}
NumberedList represents [a Numbered list block in
Notion][notion-basic-blocks]. It can have children.
Example:
<p align="left"><img height="110" src="images/ol-1.png"></p>Yields:
[
{
id: "a405f18e-978e-4c80-9055-1def35f84b47",
type: "numbered_list",
value: [["This is an item"]],
children: [],
},
{
id: "385a10b8-f1fa-49b0-a704-02a109c92953",
type: "numbered_list",
value: [["This is the second item"]],
children: [],
},
{
id: "8c6225e1-78b1-4e8d-b658-adc6e2b045ea",
type: "numbered_list",
value: [["This is the third item"]],
children: [],
},
];
ToggleList
interface ToggleList extends Block, Literal, Parent {
type: "toggle";
}
ToggleList represents [a Toggle list block in
Notion][notion-basic-blocks]. It can have children.
Example:
<p align="left"><img height="64" src="images/toggle-1.png"></p>Yields:
{
id: "edf810ae-1684-491d-a6c1-673ad2d3fc57",
type: "toggle",
value: [["This is a "], ["toggle", [["b"]]], [" "], ["list", [["i"]]]],
children: [
{
id: "689aa04d-d448-48b2-93fa-edbcc93c34d8",
type: "text",
value: [["This is a child block."]],
},
],
};
Quote
interface Quote extends Block, Literal {
type: "quote";
}
Quote represents [a Quote block in Notion][notion-basic-blocks].
Example:
<p align="left"><img height="32" src="images/quote-1.png"></p>Yields:
{
id: "d3a9da64-26e3-44b3-a22a-99a6b02880d3",
type: "quote",
value: [
[
'"The way to get started is to quit talking and begin doing." - Walt Disney',
],
],
};
Divider
interface Divider extends Block {
type: "divider";
}
Divider represents [a Divider block in Notion][notion-basic-blocks]. It
has no content.
Yields:
{
id: "95ee567a-527f-4020-aa6a-e4c170de031c",
Security Score
Audited on Nov 22, 2025