@notionhq/custom-blocks 0.0.68 → 0.0.70
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/dist/version.js +1 -1
- package/docs/pages.md +15 -5
- package/package.json +1 -1
package/dist/version.js
CHANGED
package/docs/pages.md
CHANGED
|
@@ -10,7 +10,7 @@ Every helper follows the SDK's [error-handling contract](./errors.md). Check `re
|
|
|
10
10
|
|
|
11
11
|
## Creating pages
|
|
12
12
|
|
|
13
|
-
`pages.create` mirrors Notion's [`POST /v1/pages`](https://developers.notion.com/reference/post-page). Pass a parent, a property map, and
|
|
13
|
+
`pages.create` mirrors Notion's [`POST /v1/pages`](https://developers.notion.com/reference/post-page). Pass a parent, a property map, and optionally an `icon` or `cover`:
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
16
|
const result = await pages.create({
|
|
@@ -23,7 +23,6 @@ const result = await pages.create({
|
|
|
23
23
|
dueDate: { type: "date", date: { start: "2026-06-01" } },
|
|
24
24
|
},
|
|
25
25
|
icon: { type: "emoji", emoji: "📝" },
|
|
26
|
-
position: { type: "end" },
|
|
27
26
|
});
|
|
28
27
|
|
|
29
28
|
if (result.status === "success") {
|
|
@@ -33,7 +32,12 @@ if (result.status === "success") {
|
|
|
33
32
|
|
|
34
33
|
### Choosing a parent
|
|
35
34
|
|
|
36
|
-
`parent` is
|
|
35
|
+
`parent` is the **destination for the new page**. It does not describe the custom block's own location.
|
|
36
|
+
|
|
37
|
+
- A data-source parent creates a new row in that data source.
|
|
38
|
+
- A page parent creates a child page (subpage) inside that page.
|
|
39
|
+
|
|
40
|
+
The accepted shape is `CreatePageParent`:
|
|
37
41
|
|
|
38
42
|
```ts
|
|
39
43
|
type CreatePageParent =
|
|
@@ -42,7 +46,11 @@ type CreatePageParent =
|
|
|
42
46
|
| { type: "data_source_key"; key: string };
|
|
43
47
|
```
|
|
44
48
|
|
|
45
|
-
`
|
|
49
|
+
Use `data_source_key` for a data source key declared in the custom block's manifest. When the block is configured, that slot is bound to an actual Notion data source. The SDK resolves the binding and creates a row there.
|
|
50
|
+
|
|
51
|
+
Use `page_id` when you want a subpage under a specific page. For example, `parent: { type: "page_id", page_id: page.id }` creates a child of the page returned by `usePage()`. Only page parents support `position`.
|
|
52
|
+
|
|
53
|
+
Use `data_source_id` when you already have a raw Notion data-source ID. In normal custom-block code, prefer `data_source_key` so the block uses its configured binding rather than a deployment-specific ID.
|
|
46
54
|
|
|
47
55
|
### Property keys
|
|
48
56
|
|
|
@@ -55,11 +63,13 @@ So if your manifest declares `title` and `dueDate`, you can write them by name (
|
|
|
55
63
|
|
|
56
64
|
### Where the new page lands
|
|
57
65
|
|
|
58
|
-
`position` is a `NotionCreatePagePosition` and controls placement inside the parent:
|
|
66
|
+
For a `page_id` parent, `position` is a `NotionCreatePagePosition` and controls placement inside the parent:
|
|
59
67
|
|
|
60
68
|
- `{ type: "start" }` / `{ type: "end" }` — prepend or append (default).
|
|
61
69
|
- `{ type: "before", blockId }` / `{ type: "after", blockId }` — insert as a sibling of the given block (which can be nested anywhere under the parent).
|
|
62
70
|
|
|
71
|
+
Do not pass `position` with a `data_source_id` or `data_source_key` parent. Data source rows are ordered by the view rather than by sibling anchors.
|
|
72
|
+
|
|
63
73
|
## Reading pages
|
|
64
74
|
|
|
65
75
|
`pages.get(pageId)` fetches a single page by ID:
|