Skip to content
portabletextPublic

About

Convert Portable Text to and from Markdown

Resources

Code of conduct

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

155 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@portabletext/markdown

Convert Portable Text to Markdown and back again

Installation

npm install @portabletext/markdown

Quick start

Markdown → Portable Text

import {markdownToPortableText} from '@portabletext/markdown'

const blocks = markdownToPortableText('# Hello **world**')
[
  {
    "_type": "block",
    "_key": "f4s8k2",
    "style": "h1",
    "children": [
      {"_type": "span", "_key": "a9c3x1", "text": "Hello ", "marks": []},
      {"_type": "span", "_key": "b7d2m5", "text": "world", "marks": ["strong"]}
    ],
    "markDefs": []
  }
]

Portable Text → Markdown

import {portableTextToMarkdown} from '@portabletext/markdown'

const markdown = portableTextToMarkdown([
  {
    _type: 'block',
    _key: 'f4s8k2',
    style: 'h1',
    children: [
      {_type: 'span', _key: 'a9c3x1', text: 'Hello ', marks: []},
      {_type: 'span', _key: 'b7d2m5', text: 'world', marks: ['strong']},
    ],
    markDefs: [],
  },
])
# Hello **world**

Edit through Markdown without losing keys

import {applyMarkdownEdit, portableTextToMarkdown} from '@portabletext/markdown'

const markdown = portableTextToMarkdown(stored)
const editedMarkdown = markdown.replace('tomorow', 'tomorrow')
const edited = applyMarkdownEdit(stored, editedMarkdown)
// same content as parsing editedMarkdown, with the stored `_key`s
// kept the way the same edit in an editor would have kept them

Supported features

Feature Markdown → Portable Text Portable Text → Markdown
Headings (h1–h6) ✅ ✅
Paragraphs ✅ ✅
Bold ✅ ✅
Italic ✅ ✅
Inline code ✅ ✅
Strikethrough ✅ ✅
Links ✅ ✅
Blockquotes ✅ ✅
Ordered lists ✅ ✅
Unordered lists ✅ ✅
Task lists ✅ ✅
Nested lists ✅ ✅
Code blocks ✅ ✅
Horizontal rules ✅ ✅
Images ✅ ✅
Tables ✅ ✅
HTML blocks ✅ ✅
Callouts ✅ ✅

Round-trip behavior

Converting Markdown to Portable Text and back isn't a lossless mirror:

  1. Translation preserves semantics, not source spelling: the first MD→PT→MD pass normalizes Markdown to one canonical spelling (autolinks become inline links, indented code becomes fenced code, soft-wrapped lines join into one, and so on).
  2. The normalized Markdown is a fixpoint for plain text and the Supported features table: parsing it and serializing again reproduces it byte-for-byte.
  3. MD→PT survival is schema-driven: a construct whose type the schema doesn't declare keeps its content and drops the structure that named it.
  4. PT structures with no Markdown form degrade predictably on PT→MD (extra table header rows flatten into the body, deep or level-skipping lists collapse to relative nesting, unknown marks pass their text through unformatted). Unknown object types round-trip instead: block-level as a ```json:object fence, inline as a json:object-tagged code span, both carrying the value as JSON. A fence or span whose body isn't a JSON object with a _type is ordinary code.
  5. Identity does not round-trip for text blocks: keys are regenerated on every parse, and adjacent spans with identical marks merge into one. Unknown objects keep their _key when it is a non-empty string, and a payload without one, or with an empty or non-string _key, gets a generated key. applyMarkdownEdit restores stored keys after an edit.
  6. A hard break and a \n in a span's text are exclusive counterparts in both directions: a \n always renders as hard-break syntax on the way out, and hard-break syntax always becomes \n on the way in, never the space a soft wrap joins with.

The named exceptions to the fixpoint claim: an explicit-scheme URL or email keeps its text but gains a link mark on reparse, and a fuzzy www. form does too unless it carries markdown-significant punctuation; a hard break inside an h3 to h6 heading splits into a second block on reparse, since an ATX heading is single-line (an h1 or h2 with a hard break is written as a setext heading, underlined with === or ---, wherever that parses back as the same heading); leading or trailing whitespace that CommonMark's own block parsing trims isn't part of the fixpoint; a code object with the reserved language json:object loses that language on serialization; and span text ending in json:object directly before a code-marked span holding a typed JSON object binds into an inline object on reparse.

See Markdown round-tripping on the docs site for the full contract and worked examples.

Usage

markdownToPortableText

import {markdownToPortableText} from '@portabletext/markdown'

const blocks = markdownToPortableText(`
# Hello World

This is **bold** and *italic* text with a [link](https://example.com).

- First item
- Second item
`)
[
  {
    "_type": "block",
    "_key": "k9f2x1",
    "style": "h1",
    "children": [
      {"_type": "span", "_key": "s1a2b3", "text": "Hello World", "marks": []}
    ],
    "markDefs": []
  },
  {
    "_type": "block",
    "_key": "m3n4p5",
    "style": "normal",
    "children": [
      {"_type": "span", "_key": "s2c3d4", "text": "This is ", "marks": []},
      {"_type": "span", "_key": "s3e4f5", "text": "bold", "marks": ["strong"]},
      {"_type": "span", "_key": "s4g5h6", "text": " and ", "marks": []},
      {"_type": "span", "_key": "s5i6j7", "text": "italic", "marks": ["em"]},
      {"_type": "span", "_key": "s6k7l8", "text": " text with a ", "marks": []},
      {"_type": "span", "_key": "s7m8n9", "text": "link", "marks": ["a1b2c3"]},
      {"_type": "span", "_key": "s8o9p0", "text": ".", "marks": []}
    ],
    "markDefs": [
      {"_type": "link", "_key": "a1b2c3", "href": "https://example.com"}
    ]
  },
  {
    "_type": "block",
    "_key": "q1r2s3",
    "style": "normal",
    "listItem": "bullet",
    "level": 1,
    "children": [
      {"_type": "span", "_key": "s9q0r1", "text": "First item", "marks": []}
    ],
    "markDefs": []
  },
  {
    "_type": "block",
    "_key": "t4u5v6",
    "style": "normal",
    "listItem": "bullet",
    "level": 1,
    "children": [
      {"_type": "span", "_key": "s0s1t2", "text": "Second item", "marks": []}
    ],
    "markDefs": []
  }
]

The conversion is driven by two concepts:

  • Schema: Defines what Portable Text types are available (styles, lists, decorators, annotations, block objects). The library only outputs types that exist in the schema.
  • Matchers: Control how Markdown elements map to schema types. For example, the h1 matcher maps # Heading to the 'h1' style.

Out of the box, the library includes sensible defaults for both. Customize them to match your content model.

Schema configuration

The default schema includes the following definitions:

Type Values
styles 'normal', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote'
lists 'number', 'bullet', 'task'
decorators 'strong', 'em', 'code', 'strike-through', 'underline'
annotations 'link' (fields: 'href', 'title')
blockObjects 'code' (fields: 'language', 'code'), 'image' (fields: 'src', 'alt', 'title'), 'horizontal-rule', 'html' (fields: 'html'), 'table' (the canonical nested shape, see Default behavior), 'callout' (fields: 'tone', 'content')
inlineObjects 'image' (fields: 'src', 'alt', 'title')

To use a custom Schema, import compileSchema and defineSchema from @portabletext/schema:

import {markdownToPortableText} from '@portabletext/markdown'
import {compileSchema, defineSchema} from '@portabletext/schema'

markdownToPortableText(markdown, {
  schema: compileSchema(
    defineSchema({
      styles: [{name: 'normal'}, {name: 'heading 1'}],
    }),
  ),
})

To use a Sanity schema, use @portabletext/sanity-bridge to convert it to a Portable Text Schema first:

import {markdownToPortableText} from '@portabletext/markdown'
import {sanitySchemaToPortableTextSchema} from '@portabletext/sanity-bridge'
import {Schema as SanitySchema} from '@sanity/schema'

// Compile the Sanity types, then convert the block array type
const sanitySchema = SanitySchema.compile({name: 'default', types: [richText]})
const schema = sanitySchemaToPortableTextSchema(sanitySchema.get('richText'))

markdownToPortableText(markdown, {schema})

Matchers

Matchers map Markdown concepts to Portable Text types defined in the Schema. Each default matcher checks if a type exists in the schema and returns the appropriate value.

Group Matcher Markdown Maps to schema type
block normal Paragraphs 'normal'
h1–h6 # – ###### headings 'h1'–'h6'
blockquote > blockquotes 'blockquote'
listItem bullet - or * lists 'bullet'
number 1. ordered lists 'number'
task - [ ] / - [x] items 'task'
marks strong **bold** 'strong'
em *italic* 'em'
code `inline code` 'code'
strikeThrough ~~strikethrough~~ 'strike-through'
underline <u>underline</u> 'underline'
link [text](url "title") 'link'
types code Fenced code blocks 'code'
horizontalRule --- 'horizontal-rule'
image ![alt](src) 'image'
html HTML blocks 'html'
callout > [!NOTE], etc. 'callout'
table GFM pipe tables 'table'
blockquote* > blockquotes 'blockquote'
list* - or 1. lists 'list'

* Opt-in, not registered by default: blockquote and list map onto structural container shapes, and the parser only produces those shapes when you register the matcher (see Configuring matchers). Without them, blockquotes and lists parse to flat text blocks, which is the standard Portable Text shape for both, not a degraded fallback.

Default behavior

Tables (GFM pipe tables) convert by default, in the canonical shape @portabletext/plugin-table expects: a table block object (headerRows, rows), each row a row object (cells), each cell a cell object (value, an array of Portable Text blocks). Each part of a cell that holds only an image becomes a block-level image object. alignment is a @portabletext/markdown extension field; @portabletext/plugin-table ignores it. This needs no configuration when the schema declares a table block object with a rows field (see blockObjects above). A schema whose table doesn't declare rows, or that doesn't declare table at all, produces no table object at all: the table's cell content flattens into top-level blocks, in reading order, and the table structure is discarded.

Images are handled based on context:

  • Standalone images (a paragraph containing only an image) become block-level 'image' objects
  • Images mixed with text become inline 'image' objects (if the schema includes 'image' in inlineObjects)
  • If neither is supported, falls back to plain text: ![alt](src)

The default image matcher requires the schema type to have a 'src' field. If your 'image' type doesn't include this field, the matcher returns undefined.

Code is handled based on the Markdown syntax:

  • Fenced code blocks (```) become 'code' block objects with language and code fields
  • Inline code (`) applies the 'code' decorator to a span

The default code block matcher requires the schema type to have a 'code' field. If your 'code' type doesn't include this field, the matcher returns undefined.

Links support optional titles using [text](url "title") syntax. The title is captured in the 'title' field of the 'link' annotation.

Line breaks: soft-wrapped lines within a paragraph join with a single space; a hard break (two or more trailing spaces, or a backslash, before the newline) becomes a line break within the block.

Nested lists are handled automatically. Each list item block includes a level property indicating its nesting depth (1 for top-level, 2 for nested, etc.).

HTML blocks (like <div>...</div>) become 'html' block objects with the raw HTML in the 'html' field. Inline HTML is controlled by the html.inline option.

Callouts use the > [!TYPE] syntax (GFM alerts) where TYPE is one of NOTE, TIP, WARNING, CAUTION, or IMPORTANT. They become 'callout' block objects with a 'tone' field (the lowercased type name) and a 'content' field (an array of Portable Text blocks). When the schema doesn't include a 'callout' block object, the content falls back to blockquote-styled blocks.

Configuring matchers

You can provide custom matchers to change how Markdown maps to your schema.

Custom heading style: If your schema uses 'heading 1' instead of 'h1':

import {markdownToPortableText} from '@portabletext/markdown'
import {compileSchema, defineSchema} from '@portabletext/schema'

markdownToPortableText(markdown, {
  schema: compileSchema(
    defineSchema({
      // Your schema including a 'heading 1' style
    }),
  ),
  block: {
    h1: ({context}) => {
      // Check if 'heading 1' exists in the schema
      const style = context.schema.styles.find((s) => s.name === 'heading 1')
      return style?.name
    },
  },
})

Note: Checking if the type exists in the schema isn't required, but it's good practice. Returning undefined skips unsupported types.

Table matcher: GFM pipe tables convert by default (see Default behavior). Provide your own matcher to map onto a differently-shaped table type:

import {markdownToPortableText} from '@portabletext/markdown'

markdownToPortableText(markdown, {
  types: {
    table: ({context, value}) => {
      const tableType = context.schema.blockObjects.find(
        (obj) => obj.name === 'table',
      )
      if (!tableType) return undefined

      return {
        _type: 'table',
        _key: context.keyGenerator(),
        rows: value.rows,
        headerRows: value.headerRows,
      }
    },
  },
})

List matcher: By default, lists are emitted as flat text blocks with listItem and level fields, and adjacent blocks form a list at render time. If your schema models lists as a structural block-object instead (a list type with an items array holding list-item objects, each with a content array), provide a types.list matcher to opt into that shape:

import {markdownToPortableText} from '@portabletext/markdown'

markdownToPortableText(markdown, {
  schema: schemaWithList,
  types: {
    list: ({context, value}) => ({
      _type: 'list',
      _key: context.keyGenerator(),
      kind: value.kind, // 'bullet' | 'number' | 'task'
      items: value.items, // each item: {_type, _key, checked?, content: [...]}
    }),
  },
})

The matcher receives value.items already assembled. Each item's content array holds whatever blocks the markdown produced inside the item: text blocks, code blocks, callouts, images, even nested lists. kind is promoted to 'task' automatically when any item carries a GFM checkbox (- [ ] / - [x]); items only carry a checked field when the markdown actually has one. If the matcher returns undefined, the parser falls back to flat-list parsing for that list.

Without types.list, the existing flat-block path runs unchanged.

GFM task lists (- [ ] / - [x]): Task lists are recognized when the schema declares a task list item; the default schema does, so task lists parse zero-config. Without a task definition (a custom schema that omits it), the checkbox markers are stripped from the text and the items render as their surrounding list type (bullet or number). With a task definition, items carrying a checkbox become text blocks with listItem: 'task' and a checked: boolean field; items without a checkbox keep their surrounding list type.

import {markdownToPortableText} from '@portabletext/markdown'
import {compileSchema, defineSchema} from '@portabletext/schema'

markdownToPortableText('- [x] done\n- [ ] todo', {
  schema: compileSchema(
    defineSchema({
      lists: [{name: 'bullet'}, {name: 'task'}],
    }),
  ),
})
// → [
//   {_type: 'block', listItem: 'task', level: 1, checked: true,  children: [{text: 'done', ...}], ...},
//   {_type: 'block', listItem: 'task', level: 1, checked: false, children: [{text: 'todo', ...}], ...},
// ]

If your schema uses a different name for the task list type (e.g. 'todo'), provide a custom listItem.task matcher:

import {markdownToPortableText} from '@portabletext/markdown'
import {compileSchema, defineSchema} from '@portabletext/schema'

markdownToPortableText(markdown, {
  schema: compileSchema(defineSchema({lists: [{name: 'todo'}]})),
  listItem: {
    task: ({context}) =>
      context.schema.lists.find((list) => list.name === 'todo')?.name,
  },
})

When emitting Portable Text back to Markdown, blocks with listItem: 'task' render as - [x] or - [ ] based on the checked field.

Blockquote matcher: By default, blockquotes are emitted as flat text blocks with style: 'blockquote', and adjacent blocks form a visual blockquote at render time. If your schema models a blockquote as a structural block-object instead (a blockquote type with a content array), provide a types.blockquote matcher to opt into that shape:

import {markdownToPortableText} from '@portabletext/markdown'

markdownToPortableText(markdown, {
  schema: schemaWithBlockquote,
  types: {
    blockquote: ({context, value}) => ({
      _type: 'blockquote',
      _key: context.keyGenerator(),
      content: value.content, // array of blocks the markdown produced inside the blockquote
    }),
  },
})

The matcher receives value.content already assembled. The array holds whatever blocks the markdown produced inside the blockquote: text blocks, code blocks, images, even nested blockquotes. GFM alerts (> [!NOTE], > [!TIP], etc.) use a different token stream and produce callouts instead, so types.blockquote and types.callout can be registered side-by-side without conflict.

If the matcher returns undefined, the parser falls back to flat-style by re-emitting the content blocks with style: 'blockquote'.

Without types.blockquote, the existing flat-block path runs unchanged.

Matchers receive:

  • context.schema – the compiled schema to validate against
  • context.keyGenerator – function to generate unique keys
  • value – the parsed Markdown data (structure depends on the matcher type)
  • isInline – whether the element appears inline (for ObjectMatcher only)

Return undefined to skip the element (e.g., if the type isn't in the schema).

Other options

import {markdownToPortableText} from '@portabletext/markdown'

markdownToPortableText(markdown, {
  // Custom key generator for blocks and spans
  keyGenerator: () => nanoid(),

  // Configure how inline HTML is handled (default: 'skip')
  html: {
    inline: 'skip' | 'text', // 'skip' ignores inline HTML, 'text' converts it to plain text
  },
})

Reporting degradation

Every construct the schema can't represent (a decorator not in the schema, a table with no table block object, a task checkbox with no task list, and so on) degrades to a lossier shape rather than throwing. A ```json:object fence or tagged code span that fails to reconstruct (invalid JSON, or no string _type) reports too, as object-carrier-invalid, even on a schema that would otherwise accept everything: it's the payload that's unusable, not the schema. A fence or tagged code span that does reconstruct keeps its payload's fields as written (only a missing or unusable _key is filled in), even when the schema doesn't declare its _type at that position (blockObjects for a fence, inlineObjects for a code span, and for an object a table cell lifts to block position, blockObjects). Such an object reports as object-type-undeclared, so the caller learns that the result holds a type its schema doesn't expect. Without a schema the check runs against the default schema, like every other construct. onDegradation observes all of these, one callback covering all uses. Left unset, the conversion stays silent and returns the lossiest representation it can build, since a library shouldn't log on its own initiative. Passed a function, observe the losses: it's called once, after the whole document has been walked, only when at least one construct degraded, with a report object holding every Degradation in encounter order and a canonical grouped message. Enforce against lossy output by throwing your own error from inside that callback; the throw propagates out of markdownToPortableText.

import {markdownToPortableText} from '@portabletext/markdown'

markdownToPortableText(markdown, {
  onDegradation: ({degradations, message}) => {
    // degradations: every Degradation, in encounter order
    // message: the same degradations grouped, snippeted, and sorted by line
    logger.warn(message)
  },
})

Each Degradation carries type, a human-readable message, line when a source line is available, and snippet (the offending construct's text, truncated to 40 characters) when there's a specific piece of source text to quote. Match on type, not message: the type is the stable contract, the message can change between releases.

Enforcing means throwing your own error from inside the callback:

import {markdownToPortableText} from '@portabletext/markdown'
import {compileSchema, defineSchema} from '@portabletext/schema'

markdownToPortableText('# heading\n\n**bold**', {
  schema: compileSchema(defineSchema({})),
  onDegradation: ({message}) => {
    throw new Error(message)
  },
})
// throws Error:
// Markdown could not be converted without loss:
// - line 1: `#` heading became a normal paragraph: the schema has no `h1` style ("heading")
// - line 3: Removed bold formatting, kept the text: the schema has no `strong` decorator ("bold")

Repeated declines of the same kind (the same missing decorator on three spans, say) collapse into one line of message instead of repeating the sentence: - Removed bold formatting, kept the text: the schema has no \strong` decorator (3×: "a", "b", "c"). degradations` stays ungrouped, one entry per occurrence.

portableTextToMarkdown

import {portableTextToMarkdown} from '@portabletext/markdown'

const markdown = portableTextToMarkdown([
  {
    _type: 'block',
    _key: 'k9f2x1',
    style: 'h1',
    children: [{_type: 'span', _key: 's1a2b3', text: 'Hello World', marks: []}],
    markDefs: [],
  },
  {
    _type: 'block',
    _key: 'm3n4p5',
    style: 'normal',
    children: [
      {_type: 'span', _key: 's2c3d4', text: 'This is ', marks: []},
      {_type: 'span', _key: 's3e4f5', text: 'bold', marks: ['strong']},
      {_type: 'span', _key: 's4g5h6', text: ' and ', marks: []},
      {_type: 'span', _key: 's5i6j7', text: 'italic', marks: ['em']},
      {_type: 'span', _key: 's6k7l8', text: ' text with a ', marks: []},
      {_type: 'span', _key: 's7m8n9', text: 'link', marks: ['a1b2c3']},
      {_type: 'span', _key: 's8o9p0', text: '.', marks: []},
    ],
    markDefs: [{_type: 'link', _key: 'a1b2c3', href: 'https://example.com'}],
  },
  {
    _type: 'block',
    _key: 'q1r2s3',
    style: 'normal',
    listItem: 'bullet',
    level: 1,
    children: [{_type: 'span', _key: 's9q0r1', text: 'First item', marks: []}],
    markDefs: [],
  },
  {
    _type: 'block',
    _key: 't4u5v6',
    style: 'normal',
    listItem: 'bullet',
    level: 1,
    children: [{_type: 'span', _key: 's0s1t2', text: 'Second item', marks: []}],
    markDefs: [],
  },
])
# Hello World

This is **bold** and _italic_ text with a [link](https://example.com).

- First item
- Second item

The conversion is driven by Renderers: functions that render Portable Text elements to Markdown strings. The library includes default renderers for common types; provide your own for custom block types.

Default renderers

Group Renderer Renders Output
types callout callout block objects > [!TYPE]\n> content
code code block objects Fenced code block
horizontal-rule horizontal-rule block objects ---
html html block objects Raw HTML
image image block/inline objects ![alt](src "title")
table table block objects Markdown table
block normal Paragraphs {children}
h1–h6 Headings # –######
blockquote Blockquotes > {children}
marks strong Bold text **{children}**
em Italic text _{children}_
code Inline code `{children}`
underline Underlined text <u>{children}</u>
strike-through Strikethrough ~~{children}~~
link Links [{children}](url)
listItem List items (bullet, number, task) - , 1. , or - [x]
hardBreak Line breaks within blocks \n (two spaces)
blockSpacing Spacing between blocks \n\n, \n, \n>\n
unknownType Unknown block types JSON code block
unknownBlockStyle Unknown block styles {children}
unknownListItem Unknown list item types - {children}
unknownMark Unknown marks {children}

Unknown types render as JSON code blocks by default; unknown styles, list items, and marks pass through their children.

The default type renderers are collision-safe: because the serializer dispatches on the _type name alone, code, html, image, callout, and table fall back to the unknownType renderer (a JSON code block) when a value doesn't match the shape their renderer expects (say, your own differently-shaped code type); horizontal-rule has no shape to check and always renders ---. image also falls back when src is a string a Markdown parser would refuse (a javascript:/vbscript:/file: URI, or a data: URI outside png/gif/jpeg/webp), so the value survives as a json:object fence instead of reparsing as literal text. Register your own types.<name> renderer to override how any of them serialize, or to handle a same-named type of a different shape.

Note: There's no standard Markdown syntax for underline, so the underline renderer writes HTML <u> tags. markdownToPortableText reads a bare <u>/</u> pair back as the underline decorator, so underline round-trips.

Configuring renderers

Provide custom renderers to control how Portable Text renders to Markdown.

Custom type renderers: Render custom block types (objects in the blocks array). A custom renderer under a default's name (see Default renderers) replaces that default:

import {portableTextToMarkdown} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  types: {
    // Render a custom "chart" block object
    chart: ({value}) => `![${value.title}](${value.imageUrl})`,
  },
})

Custom block styles: Override how block styles render:

import {portableTextToMarkdown} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  block: {
    // Use ATX-style heading with closing hashes
    h1: ({children}) => `# ${children} #`,
    // Use HTML for blockquotes
    blockquote: ({children}) => `<blockquote>${children}</blockquote>`,
  },
})

Built-in type renderers: the library exports every built-in type renderer, in case you want to compose one into a different renderer or reuse it under a different type name. Two of them are exported but not registered by default: DefaultBlockquoteObjectRenderer and DefaultListRenderer render the structural container shapes (types.blockquote/types.list on the parser side) and stay opt-in, since the parser only produces those shapes when a matcher is registered for them:

import {
  DefaultBlockquoteObjectRenderer,
  DefaultListRenderer,
  portableTextToMarkdown,
} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  types: {
    blockquote: DefaultBlockquoteObjectRenderer,
    list: DefaultListRenderer,
  },
})
Renderer Expected value Output
DefaultBlockquoteObjectRenderer {content: PortableTextBlock[]} > content
DefaultCalloutRenderer {tone: string, content: PortableTextBlock[]} > [!TYPE]\n> content
DefaultCodeBlockRenderer {code: string, language?: string} ```lang\ncode\n```
DefaultHorizontalRuleRenderer (no fields required) ---
DefaultHtmlRenderer {html: string} Raw HTML
DefaultImageRenderer {src: string, alt?: string, title?: string} ![alt](src "title")
DefaultListRenderer {kind: 'bullet' | 'number' | 'task', items: [...]} Markdown list
DefaultTableRenderer {rows: [...], headerRows?: number} Markdown table

What renderers receive

One question decides which text field a renderer reads: are you wrapping markdown, or emitting something else? children is markdown: nested marks are rendered and literal punctuation is backslash-escaped, so it embeds in markdown output as-is (`**${children}**`). text is source: the raw span text exactly as stored, for renderers that emit their own delimiters or non-markdown output (code fences, HTML tags), where escapes would appear literally. The built-in code decorator renderer reads text; every other built-in reads children.

Block renderers (block.*):

  • value – the block object
  • children – rendered content of the block, as markdown (escaped)
  • index – position in the blocks array

Mark renderers (marks.*):

  • value – the mark definition (for annotations like links)
  • children – the rendered marked content, as markdown (escaped)
  • text – the raw text content (unescaped, no nested mark rendering)
  • markType – the mark type name
  • markKey – the mark's key (for annotations)

Type renderers (types.*):

  • value – the typed object
  • index – position in the blocks array
  • isInline – whether it appears inline or as a block

Use isInline to handle block vs inline objects differently:

import {portableTextToMarkdown} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  types: {
    image: ({value, isInline}) => {
      if (isInline) {
        // Skip inline images entirely by returning empty string
        return ''
      }
      // Render block images as full Markdown
      return `![${value.alt || ''}](${value.src})`
    },
  },
})

Return an empty string to skip rendering an element entirely.

List item renderer (listItem):

  • value – the list item block
  • children – rendered content
  • listIndex – position in the list (for numbered lists)

Handling unknown types

The library provides fallback renderers for unknown content:

import {portableTextToMarkdown} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  // Called for block types not in `types`
  unknownType: ({value}) => `<!-- Unknown type: ${value._type} -->`,

  // Called for block styles not in `block`
  unknownBlockStyle: ({value, children}) => children ?? '',

  // Called for list item types not in `listItem`
  unknownListItem: ({children}) => `- ${children}`,

  // Called for marks not in `marks`
  unknownMark: ({children}) => children,
})

By default, unknown types render as json:object fences or tagged code spans that round-trip (see Round-trip behavior), and unknown marks/styles pass through their children unchanged.

Gating default renderers on a schema

Going to convert the markdown back with markdownToPortableText? Pass the same schema to both, and nothing the schema can't rebuild becomes markdown that gets destroyed on the way back: undeclared types travel as json:object fences that reparse to the same value.

import {portableTextToMarkdown} from '@portabletext/markdown'
import {compileSchema, defineSchema} from '@portabletext/schema'

const schema = compileSchema(
  defineSchema({
    blockObjects: [
      {
        name: 'code',
        fields: [
          {name: 'code', type: 'string'},
          {name: 'language', type: 'string'},
        ],
      },
    ],
  }),
)

portableTextToMarkdown(blocks, {schema})

A default renderer (callout, code, horizontal-rule, html, image, table) runs only when the schema declares that type at the position the node appears in: blockObjects for a block, inlineObjects for an inline object. An image declared in only one of the two still falls back to unknownType at the other position.

The gate reads type names, never field values: declaring a type doesn't validate anything, and a value's fields play no part in which renderer runs. Fields matter on the parse side instead: markdownToPortableText filters a construct down to its declared fields, so declare each type with the fields its values carry, or the markdown forms this gate lets through come back rebuilt without them.

An undeclared type falls back to unknownType, whose default output is the same json:object fence or tagged code span described above, so it round-trips at block and inline positions. Renderers you register in types bypass the gate entirely, whether or not the schema declares them.

In a table cell, a plain paragraph and an image are written as Markdown. A plain paragraph has the normal style and is not a list item. Other blocks in a cell are written as the one-line json:object tagged code span holding the whole block, including nested content and keys. Blocks in a cell are separated by <br><br>. A cell with one plain paragraph, only an image or only an unknown object is written exactly as before. Any other block in a cell is written as JSON, and custom renderers in types, block, listItem and unknownType are not called for it. An image in a cell still uses types.image.

Without a schema, every default renderer stays active.

Hard breaks

Customize how a hard break (a \n inside a span's text) renders:

import {portableTextToMarkdown} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  // Render as HTML break instead of Markdown hard break
  hardBreak: () => '<br />\n',

  // Or render as plain newline (no trailing spaces)
  hardBreak: () => '\n',
})

Block spacing

By default, blocks are separated by double newlines (\n\n), with special handling for list items (single newline) and consecutive blockquotes. Customize with blockSpacing. It replaces the default renderer, and returning undefined separates the two blocks with \n\n, not with the default spacing. To keep the default spacing for the cases you don't handle, delegate to DefaultBlockSpacingRenderer:

import {
  DefaultBlockSpacingRenderer,
  portableTextToMarkdown,
} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  blockSpacing: ({current, next}) => {
    // Double newline between list items instead of single
    if (isListItem(current) && isListItem(next)) {
      return '\n\n'
    }
    return DefaultBlockSpacingRenderer({current, next})
  },
})

function isListItem(node: object) {
  return 'listItem' in node && typeof node.listItem === 'string'
}

Reporting degradation

An annotation or decorator with no mark renderer drops to plain text, a block style with no renderer falls back to a normal paragraph, and a list-item kind with no renderer falls back to a plain bullet item: each degrades rather than throwing. onDegradation observes those losses, called once, after the whole document has been walked, only when at least one construct degraded, with a report object holding every SerializeDegradation in encounter order and a canonical grouped message. Left unset, the conversion stays silent and returns the lossiest representation it can build. Enforce against lossy output by throwing your own error from inside that callback. The throw propagates out of portableTextToMarkdown.

import {portableTextToMarkdown} from '@portabletext/markdown'

portableTextToMarkdown(blocks, {
  onDegradation: ({degradations, message}) => {
    // degradations: every SerializeDegradation, in encounter order
    // message: the same degradations grouped, snippeted, and sorted by block
    logger.warn(message)
  },
})

Each SerializeDegradation carries type (annotation-dropped, decorator-dropped, style-fallback, or list-item-fallback), a human-readable message, path, and snippet (the offending text, truncated to 40 characters) when there's a specific piece of text to quote. path addresses the node the loss occurred on, from the top-level blocks array down: an array position is {_key: node._key} when the node has a _key, the numeric index otherwise, and an object property is its field name. A degradation inside a table cell carries the full path down to the offending node, not just the table's own position. path is best-effort: it names the deepest node the conversion can re-find, falling back to just the top-level segment when it can't (a custom renderer cloning a node before rendering it, or a keyless nested span with nothing left to search by). Match on type, not message: the type is the stable contract, the message can change between releases, and the set of type values itself grows in minor releases, so compare against the values you handle rather than switching exhaustively.

Providing your own renderer for the affected construct (a custom unknownMark, unknownBlockStyle, or unknownListItem, or a listItem map covering every kind the document uses) suppresses the report for that construct: onDegradation only fires for fallbacks the library's own default renderers produced. list-item-fallback never fires under the default configuration, since the default listItem renderer already covers every kind. It only fires behind a consumer-supplied partial listItem map.

applyMarkdownEdit's serialize option doesn't accept onDegradation: it serializes storedPortableText only for internal alignment, never editedMarkdown itself, so there's nothing there for a caller to observe losses in.

applyMarkdownEdit

Parsing markdown mints fresh _keys for text blocks (see Round-trip behavior), so converting a document to markdown, editing one word, and converting back returns what looks like a full rewrite: comment anchors detach, history churns, and granular patching is impossible. applyMarkdownEdit converts edited markdown back to Portable Text and restores stored _keys the way the same edit in an editor would have kept them:

import {applyMarkdownEdit, portableTextToMarkdown} from '@portabletext/markdown'

const stored = [
  {
    _type: 'block',
    _key: 'b1',
    style: 'normal',
    children: [{_type: 'span', _key: 's1', text: 'Ships tomorow.', marks: []}],
    markDefs: [],
  },
]

const markdown = portableTextToMarkdown(stored)
// markdown === 'Ships tomorow.'; an agent (or anything else) fixes the typo
const edited = applyMarkdownEdit(stored, 'Ships tomorrow.')

edited:

[
  {
    "_type": "block",
    "_key": "b1",
    "style": "normal",
    "children": [
      {"_type": "span", "_key": "s1", "text": "Ships tomorrow.", "marks": []}
    ],
    "markDefs": []
  }
]

Keys follow the edit the way they would in an editor, and when the evidence is unclear, a block gets a fresh key rather than a wrong one. The result is a value, not patches; output keys are always unique among siblings; the inputs are never mutated.

What keeps its key

  • Unchanged and moved blocks. Repeated content pairs in order.
  • A block rewritten in place, like typing over it. Style changes count as rewrites, and an edited table cell keeps the whole table's keys.
  • A split keeps the key on the first non-empty fragment, like pressing enter; a merge keeps the first block's key, like pressing backspace. A soft-wrap join is a merge.
  • A typo fix lands as a text change on the same span, and editing a link's URL keeps its annotation key. Two identical annotations in one block (the same link twice, say) pair in order, like any repeated content.
  • A json:object payload keeps the _key it carries, unless the payload matches stored content, which keeps the stored key: editing markdown cannot re-key existing content.
  • A json:object payload without a _key, or with an empty or non-string one, gets a generated key, unless it matches stored content, which keeps the stored key.

What gets restored

Markdown cannot carry everything a block stores, so an adopted block gets back what the edit could not have touched:

  • A field the dialect cannot express, like a text block's alignment, including a whole custom object-array field the dialect drops. A field markdown does express, like language on a code block, follows the edit.
  • A custom style, list kind, or decorator markdown has no syntax for.
  • An empty or whitespace-only paragraph, which has no markdown form at all (blank lines are the block separator): it is restored next to its surviving neighbor, and deleted along with that neighbor if the neighbor goes. This covers top-level blocks; an empty paragraph nested inside a table cell or callout content is not restored. An empty heading or list item has a visible markdown form (## , - ) and round-trips like any other block.
  • A block the edit did not touch comes back exactly as stored, span structure and unmappable marks included: an adjacent pair of spans that only differ by a decorator markdown has no syntax for keeps its split rather than merging into the one span a plain parse would produce.

When keys reset

  • Ambiguity: when an insertion or deletion makes a match unclear, a block keeps its key only on clear evidence; everything else gets a new key, and short blocks near the change are the usual casualties.
  • Indistinguishable edits: replacing a block with unrelated content in the same position keeps its key (the end state is identical to a rewrite), and a whole-document rewrite that keeps the block count pairs blocks in order. That last one is deliberate: a translation keeps every anchor by position, which is the behavior translate flows need. The cost is that a reorder-plus-edit with balanced counts mispairs the same way, block-level and sibling-level alike.
  • Caps: on very large ambiguous edits, evidence gathering is size- and time-capped and degrades to fresh keys rather than waiting, so near the caps, which keys survive can vary with machine speed.
  • Refusal: a stored value that cannot survive its own serialize→parse round trip resets the whole document to the plain conversion, every key fresh except the ones json:object payloads carry.

Options

The options bag mirrors the two converters, plus a top-level schema: deserialize takes the rest of markdownToPortableText's options and serialize takes the rest of portableTextToMarkdown's. schema is taken once and governs both directions, because restoring keys depends on the two serializations agreeing. Pass the same serialize options that produced the markdown that was edited. The deserialize options apply to the stored value as well as the edited markdown, with two exceptions: new keys come from deserialize.keyGenerator (or the built-in generator), and onDegradation reports only on the edited markdown.

Observing reconciliation

Pass onReconciliation to see what happened to every key. The callback fires exactly once per call, synchronously, right before the function returns:

import {applyMarkdownEdit} from '@portabletext/markdown'

applyMarkdownEdit(stored, editedMarkdown, {
  onReconciliation: (report) => {
    if (report.keyMatching === 'skipped') {
      // report.reason is 'round-trip-mismatch' (the stored value cannot
      // survive its own serialize→parse round trip) or
      // 'document-too-large'. The returned value is the plain
      // conversion, every key fresh except the ones `json:object`
      // payloads carry. A 'round-trip-mismatch' report also carries
      // report.mismatch, naming where and why the round trip failed:
      // a `type`, a `storedPath` into the stored value, a readable
      // `message`, and an optional `snippet` of the text that came
      // back
      return
    }
    report.preservedKeys // stored keys that survived, with a basis, a path, and whether the value changed
    report.keyFallbacks // regions that got fresh keys instead of a guess
    report.renamedKeys // keys rewritten to keep siblings unique
    report.hiddenLosses // stored content the markdown never showed that is missing from the result
    report.markdownLosses // what the edited markdown said that the result does not hold
    report.undeclaredObjects // objects the edit added whose type the schema does not declare
  },
})

Every key and path in the report matches the returned value exactly, except mismatch.storedPath and each hiddenLosses entry's path, which address the stored value passed in. A path segment is a string field name, a number array index, or {_key} for a keyed element, the same convention as editor paths. Which keys survived, the paths, renamedKeys, keyMatching, and mismatch.type are facts of that invocation, safe to branch on. Match on mismatch.type ('type-changed', 'text-changed', or 'block-count-changed'), not mismatch.message: the message can change between releases. A preserved key's basis names the matching method ('content-unchanged', 'content-moved', 'content-split', 'content-merged', 'same-position', 'similar-content') and is advisory: near the evidence caps it can vary with machine speed, so never branch on it. valueChanged, by contrast, is a stable fact of the invocation, safe to branch on: it is true when the node wearing that key differs from its stored counterpart, field order aside but array order significant. Any difference counts, including a descendant key rewritten to keep siblings unique, or a key filled in for a stored node that had none. false guarantees the returned node deep-equals the stored one. A node absent from preservedKeys was not restored from the stored value, whether its key is fresh or carried by a json:object payload, so a caller who needs to know whether one of those changed has to compare it directly. The next section shows how to check json:object payloads that way. The exported ReconciliationReport, ReconciliationKeyPath and UndeclaredObject types are @beta.

Losses the markdown did not show

Content the serialize options have no markdown form for (an annotation or decorator with no mark renderer, a block style or list-item kind with no renderer) never reaches whoever edits the markdown. applyMarkdownEdit restores it where it can. Both report variants carry hiddenLosses: one SerializeDegradation per such loss whose content is missing from the returned value, with path addressing the stored value. A stored block whose _key is missing from the returned value has all of its losses listed, whether the edit deleted it or rewrote it so far that it came back with a fresh key. Whether the removal was intended is yours to decide.

Losses in the edited markdown

The edited markdown can also say things the schema cannot hold. Both report variants carry markdownLosses: the Degradation entries deserialize.onDegradation receives for editedMarkdown, in the same order, except object-type-undeclared. Each one means the result differs from what the markdown said, for example a heading level the schema has no style for, a dropped decorator, a flattened table, or fields dropped from a json:object carrier. Your own deserialize.onDegradation still receives every entry, and a throw from it still propagates.

Objects the schema does not declare

A json:object payload whose type the schema does not declare is kept as written, so nothing is lost, but the result holds content the schema does not allow. Both report variants carry undeclaredObjects: one UndeclaredObject per such object in the returned value that the stored value did not already hold, in document order. Each entry has the object's _type, its _key when it has one, a position of 'block' or 'inline', a path into the returned value, and a message for display, the same text as the object's object-type-undeclared degradation. Only top-level block objects and the inline objects of top-level text blocks are checked. The fields of a declared object, such as a table's cells or a container's own array, are not searched: what a payload holds inside its fields is validated like any other write of that object. An object the stored value already held in the same position, with the same _type and _key, is not listed, and editing the paragraph around an inline object does not list it even when the paragraph gets a fresh key. A stored object with no _key gets a fresh one from the round trip, so it is matched by its _type and content instead. Each stored object matches at most one object in the result, so adding a second object of a stored type lists the new one.

Together the three lists say whether saving the result loses content or adds content the schema does not allow. Refuse or retry when any of them is non-empty:

import {applyMarkdownEdit} from '@portabletext/markdown'

const problems: Array<string> = []
const edited = applyMarkdownEdit(stored, editedMarkdown, {
  onReconciliation: (report) => {
    problems.push(
      ...report.hiddenLosses.map((loss) => loss.message),
      ...report.markdownLosses.map((loss) => loss.message),
      ...report.undeclaredObjects.map((object) => object.message),
    )
  },
})

if (problems.length > 0) {
  throw new Error(`The edit cannot be saved as is: ${problems.join('\n')}`)
}

Guarding json:object payloads

An edit can change json:object payloads like any other content. To keep an agent away from certain objects, check the result before saving it:

import {isDeepStrictEqual} from 'node:util'
import {applyMarkdownEdit} from '@portabletext/markdown'

const edited = applyMarkdownEdit(stored, editedMarkdown)

// The objects the agent must leave alone
const isProtected = (block: {_type: string}) => block._type === 'productTeaser'

const protectedBefore = stored.filter(isProtected)
const keysBefore = new Set(protectedBefore.map((block) => block._key))
const editedByKey = new Map(edited.map((block) => [block._key, block]))

const changedOrDeleted = protectedBefore.filter(
  (block) => !isDeepStrictEqual(block, editedByKey.get(block._key)),
)
const added = edited.filter(
  (block) => isProtected(block) && !keysBefore.has(block._key),
)

if (changedOrDeleted.length > 0 || added.length > 0) {
  // Reject the edit. An agent loop can pass this message back as the retry prompt.
  throw new Error('Leave the product teasers exactly as they are.')
}

The snippet checks top-level blocks. For objects inside a text block's children or a table cell, run the same two checks within each parent, matching parents by _key: objects under a parent whose key did not survive count as deleted, and objects under a new parent count as added.

Concurrent edits

Reconciling an unchanged serialization returns the stored value byte for byte for the content the edit did not touch, keys, span structure, and unmappable marks included; content the edit did touch still comes back canonicalized, with its keys restored where reconciliation can trace them. applyMarkdownEdit does not merge concurrent edits: reconcile against the exact value that produced the markdown, and before writing the result back, check that the stored field still equals that value. If it changed while the markdown was being edited, the edit describes a document that no longer exists, and writing it would silently overwrite the newer changes: serialize the current value and redo the edit instead.

License

MIT © Sanity.io

About

Convert Portable Text to and from Markdown

Resources

Code of conduct

Security policy

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages