Markdown to Portable Text

Convert Markdown strings into Portable Text blocks. Use this for importing content from Markdown-based systems (static site generators, GitHub READMEs, AI-generated content), processing user input, or migrating from Markdown-first CMSes.

Looking to render Portable Text as Markdown? See the Markdown rendering guide.

Install

npm i @portabletext/markdown

pnpm add @portabletext/markdown

yarn add @portabletext/markdown

Basic usage

markdownToPortableText takes a Markdown string and returns an array of Portable Text blocks.

import {markdownToPortableText} from '@portabletext/markdown'

const blocks = markdownToPortableText('# Hello **world**')

Standard Markdown elements (headings, paragraphs, bold, italic, links, lists, blockquotes, inline code) are handled automatically using the default schema.

Schema configuration

The conversion is schema-driven. The library only outputs types that exist in the schema, so the output always matches your content model.

The default schema includes:

| Type | Values | | --------------- | -------------------------------------------------------------- | | styles | normal, h1-h6, blockquote | | lists | bullet, number | | decorators | strong, em, code, strike-through | | annotations | link (fields: href, title) | | blockObjects | code, image, horizontal-rule, html, table, callout | | inlineObjects | image |

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

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

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

If you are using a Sanity schema, use @portabletext/sanity-bridge to convert it first:

import {sanitySchemaToPortableTextSchema} from '@portabletext/sanity-bridge'

const schema = sanitySchemaToPortableTextSchema(sanityBlockArraySchema)
markdownToPortableText(markdown, {schema})

Matchers

Matchers control how Markdown elements map to schema types. The library includes defaults for all standard elements. You can override individual matchers when your schema uses different type names.

| Group | Matcher | Markdown | Maps to | | ---------- | ---------------- | --------------------- | ------------------- | | block | normal | Paragraphs | 'normal' | | | h1-h6 | #-###### headings | 'h1'-'h6' | | | blockquote | > blockquotes | 'blockquote' | | listItem | bullet | - or * lists | 'bullet' | | | number | 1. ordered lists | 'number' | | marks | strong | **bold** | 'strong' | | | em | *italic* | 'em' | | | code | `inline code` | 'code' | | | strikeThrough | ~~strikethrough~~ | 'strike-through' | | | 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' |

Override a matcher when your schema uses a different name for a type. For example, if your schema uses 'heading 1' instead of 'h1':

markdownToPortableText(markdown, {
  schema: compileSchema(
    defineSchema({
      /* your schema */
    }),
  ),
  block: {
    h1: ({context}) => {
      const style = context.schema.styles.find((s) => s.name === 'heading 1')
      return style?.name
    },
  },
})

Returning undefined from a matcher skips the element gracefully. This is useful when a type may or may not exist in the schema depending on the content model.

Supported features

| Feature | Markdown to PT | | ---------------- | :------------: | | Headings (h1-h6) | ✅ | | Paragraphs | ✅ | | Bold | ✅ | | Italic | ✅ | | Inline code | ✅ | | Strikethrough | ✅ | | Links | ✅ | | Blockquotes | ✅ | | Ordered lists | ✅ | | Unordered lists | ✅ | | Nested lists | ✅ | | Code blocks | ✅ | | Horizontal rules | ✅ | | Images | ✅ | | Tables | ✅* | | HTML blocks | ✅ | | Callouts | ✅* |

* Requires custom schema configuration (see above).

Other conversion paths

| Source format | Tool | | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | | HTML → PT | @portabletext/html | | Gutenberg → PT | @emdash-cms/gutenberg-to-portable-text (30+ block types) | | Contentful → PT | @portabletext/contentful-rich-text-to-portable-text |