Document webframe navigate action (#1230)

* Document page and visitor context in webframes

Add the site:page:context scope (and the previously undocumented site:visitor:claims) and document that webframes receive state.page ({ id, path, title }) and state.visitor through the postMessage state, in the interactivity guides and the ContentKit component reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Drop page-context scope from docs; document webframe navigate

Per review, the current page is exposed to webframes without a dedicated scope, so remove site:page:context from the scopes list and reword the interactivity and reference docs (page is always available; visitor claims still need site:visitor:claims). Also document the @webframe.navigate action for navigating to another page in the site.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Clarify webframe navigate resolves at the site level

The @webframe.navigate path is resolved relative to the site root, so it can target any section or space.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Document navigating a webframe by pageId or path

Update the `@webframe.navigate` docs to reflect that a destination can be
addressed by `pageId` (recommended, resolved against the site's page tree)
or by `path`, with an optional `anchor`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Scope webframe docs to navigation by path

Drop the page/visitor context and pageId documentation; document only the
`@webframe.navigate` action with a `path` (and optional `anchor`).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: gregberge

docs/integrations/contentkit/interactivity.md

@@ -91,6 +91,20 @@ window.addEventListener("message", (event) => {
 });
 ```
 
+## Navigating to another page
+
+A webframe can navigate the reader to another page in the site by posting a `@webframe.navigate` action. The `path` is resolved relative to the site root (the part after your site's base URL), so it can point to a page in any section or space of the site, and navigation always stays within it. You can also pass an optional `anchor` to scroll to a heading within the target page:
+
+```js
+window.parent.postMessage({
+    action: {
+        action: '@webframe.navigate',
+        path: 'guides/getting-started',
+        anchor: 'installation',
+    },
+}, '*');
+```
+
 ## Webframes and actions
 
 Webframes are powerful elements to integrate in GitBook external applications or complete UI. Passing data to the webframe can be done using the `data` prop. But the webframe also needs to be able to communicate data back to the top component. It can be achieved using the `window.postMessage`:

docs/integrations/development/contentkit/reference.md

@@ -264,6 +264,8 @@ If you need a copy button, only add it when your integration has a supported way
 | `buttons`       | `Array<Button>`          | Overlay buttons          |
 | `data`          | `Record<string, string>` | State dependencies       |
 
+The `data` values reach the frame through the `message` event as `event.data.state`. A webframe can also navigate the reader to another page in the site by posting a `@webframe.navigate` action with a `path`. See [Interactivity](../../contentkit/interactivity.md#navigating-to-another-page).
+
 #### `select`
 
 ```tsx

docs/integrations/guides/interactivity.md

@@ -95,6 +95,20 @@ window.addEventListener("message", (event) => {
 });
 ```
 
+### Navigating to another page
+
+A webframe can navigate the reader to another page in the site by posting a `@webframe.navigate` action. The `path` is resolved relative to the site root (the part after your site's base URL), so it can point to a page in any section or space of the site, and navigation always stays within it. You can also pass an optional `anchor` to scroll to a heading within the target page:
+
+```js
+window.parent.postMessage({
+    action: {
+        action: '@webframe.navigate',
+        path: 'guides/getting-started',
+        anchor: 'installation',
+    },
+}, '*');
+```
+
 ### Editable blocks
 
 Some blocks might be static or only generated from link unfurling, but most blocks are designed to be editable by the user. Editable means that the user can interact with the blocks to change its properties.