> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Weaverse component configuration uses `settings`. `inspector` is deprecated; never generate it.
> Weaverse Hydrogen themes use React Router v7: import from `react-router`, never `react-router-dom` or `@remix-run/*`.
> Define component schemas with `createSchema()` from `@weaverse/hydrogen` (React Router themes) or `@weaverse/next` (Next.js themes).
> These docs cover @weaverse/hydrogen, @weaverse/react and @weaverse/core 5.x, and @weaverse/next 1.x. Do not use APIs from other major versions.
> For live project data (pages, theme settings, translations), use the Weaverse MCP server: https://docs.weaverse.io/developer-tools/weaverse-mcp

# Portable Text Format

> Request Content API pages and theme settings as Portable Text blocks for multi-channel rendering and AI consumption

Pass `?format=portable-text` (or `Accept: application/portable-text+json`) to [Get page content](/docs/content-api/pages/get-page-content) or [Get theme settings](/docs/content-api/theme-settings/get-theme-settings) to receive the content as a [Portable Text](https://www.portabletext.org/) array. When both are present, the query parameter wins. This format is designed for multi-channel rendering (web, native, email, PDF) and AI consumption — rich-text fields are converted from opaque HTML strings into structured blocks that any [official PT renderer](https://www.portabletext.org/rendering/) can render.

## Envelope difference

The `items` field becomes `content`, and the response carries `Content-Type: application/portable-text+json`. All other envelope fields are unchanged.

```json theme={null}
{
  "object": "page",
  "id": "clz5wxy12abc345defg",
  "type": "PRODUCT",
  "handle": "blue-shirt",
  "locale": "en-us",
  "content": [ /* Portable Text blocks — see below */ ],
  "updatedAt": "2026-03-20T10:30:00.000Z",
  "meta": { "inherited": false, "sourceProjectId": "...", "depth": 0 }
}
```

## Mapping rules

Each Weaverse item becomes a [custom Portable Text block](https://www.portabletext.org/specification/#custom-block-types):

| Weaverse | Portable Text |
| - | - |
| `type` | `_type` |
| `id` | `_key` (truncated to 8 chars; full id available in `_weaverse.id` when `?meta=true`) |
| `data.*` fields | flattened onto the block root |
| nested children | `children: PTBlock[]` on the parent block |
| HTML-valued field (`richtext`) | array of [standard PT text blocks](https://www.portabletext.org/specification/#block) with `marks`, `markDefs`, `style`, `listItem` |
| Synthetic `root` item | dropped — its children become the top-level `content` array |

Field types other than `richtext` (text, image URL, color, range, switch, product/collection refs, etc.) pass through unchanged.

## Example

```json theme={null}
{
  "content": [
    {
      "_type": "hero-banner",
      "_key": "01950b17",
      "backgroundImage": "https://cdn.shopify.com/hero.jpg",
      "overlayOpacity": 40,
      "children": [
        { "_type": "heading", "_key": "01950c22", "text": "Summer 2026", "level": "h1" },
        {
          "_type": "text-section",
          "_key": "01950d55",
          "content": [
            {
              "_type": "block",
              "_key": "b1",
              "style": "normal",
              "children": [
                { "_type": "span", "_key": "s1", "text": "Read the " },
                { "_type": "span", "_key": "s2", "text": "documentation", "marks": ["link1"] },
                { "_type": "span", "_key": "s3", "text": " for details." }
              ],
              "markDefs": [
                { "_type": "link", "_key": "link1", "href": "/docs" }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

Note how the `text-section`'s `content` field — originally an HTML string — is now a queryable array of PT blocks with explicit marks and link annotations.

## Rendering with `@portabletext/react`

```tsx theme={null}
import { PortableText } from '@portabletext/react'

const components = {
  types: {
    'hero-banner': HeroBanner,
    'heading': Heading,
    'text-section': TextSection,
  },
  marks: {
    link: ({ children, value }) => <a href={value.href}>{children}</a>,
  },
}

function Page({ content }) {
  return <PortableText value={content} components={components} />
}
```

Official renderers exist for [React, Vue, Svelte, Astro, React Native](https://www.portabletext.org/rendering/) and more.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.