@portabletext/markdown 1.0.0

package/src/from-portable-text/build-list-index-map.ts

@@ -0,0 +1,133 @@
+import {
+  compileSchema,
+  defineSchema,
+  isTextBlock,
+  type PortableTextBlock,
+} from '@portabletext/schema'
+import type {ArbitraryTypedObject, TypedObject} from '@portabletext/types'
+import {defaultKeyGenerator} from '../key-generator'
+
+const schema = compileSchema(defineSchema({}))
+
+/**
+ * Builds a map of list item `_key`s to their index.
+ *
+ * Mutates the blocks in place by adding a `_key` if necessary.
+ */
+export function buildListIndexMap<
+  Block extends TypedObject = PortableTextBlock | ArbitraryTypedObject,
+>(blocks: Array<Block>): Map<string, number> {
+  const levelIndexMaps = new Map<string, Map<number, number>>()
+  const listIndexMap = new Map<string, number>()
+
+  let previousListItem:
+    | {
+        listItem: string
+        level: number
+      }
+    | undefined
+
+  for (let blockIndex = 0; blockIndex < blocks.length; blockIndex++) {
+    const block = blocks.at(blockIndex)
+
+    if (block === undefined) {
+      continue
+    }
+
+    if (!block._key) {
+      block._key = defaultKeyGenerator()
+    }
+
+    // Clear the state if we encounter a non-text block
+    if (!isTextBlock({schema}, block)) {
+      levelIndexMaps.clear()
+      previousListItem = undefined
+
+      continue
+    }
+
+    // Clear the state if we encounter a non-list text block
+    if (block.listItem === undefined || block.level === undefined) {
+      levelIndexMaps.clear()
+      previousListItem = undefined
+
+      continue
+    }
+
+    // If we encounter a new list item, we set the initial index to 1 for the
+    // list type on that level.
+    if (!previousListItem) {
+      const listIndex = 1
+      const levelIndexMap =
+        levelIndexMaps.get(block.listItem) ?? new Map<number, number>()
+      levelIndexMap.set(block.level, listIndex)
+      levelIndexMaps.set(block.listItem, levelIndexMap)
+
+      listIndexMap.set(block._key, listIndex)
+
+      previousListItem = {
+        listItem: block.listItem,
+        level: block.level,
+      }
+
+      continue
+    }
+
+    // If the previous list item is of the same type but on a lower level, we
+    // need to reset the level index map for that type.
+    if (
+      previousListItem.listItem === block.listItem &&
+      previousListItem.level < block.level
+    ) {
+      const listIndex = 1
+      const levelIndexMap =
+        levelIndexMaps.get(block.listItem) ?? new Map<number, number>()
+      levelIndexMap.set(block.level, listIndex)
+      levelIndexMaps.set(block.listItem, levelIndexMap)
+
+      listIndexMap.set(block._key, listIndex)
+
+      previousListItem = {
+        listItem: block.listItem,
+        level: block.level,
+      }
+
+      continue
+    }
+
+    // Reset other list types at current level and deeper
+    levelIndexMaps.forEach((levelIndexMap, listItem) => {
+      if (listItem === block.listItem) {
+        return
+      }
+
+      // Reset all levels that are >= current level
+      const levelsToDelete: number[] = []
+
+      levelIndexMap.forEach((_, level) => {
+        if (level >= block.level!) {
+          levelsToDelete.push(level)
+        }
+      })
+
+      levelsToDelete.forEach((level) => {
+        levelIndexMap.delete(level)
+      })
+    })
+
+    const levelIndexMap =
+      levelIndexMaps.get(block.listItem) ?? new Map<number, number>()
+    const levelCounter = levelIndexMap.get(block.level) ?? 0
+    levelIndexMap.set(block.level, levelCounter + 1)
+    levelIndexMaps.set(block.listItem, levelIndexMap)
+
+    listIndexMap.set(block._key, levelCounter + 1)
+
+    previousListItem = {
+      listItem: block.listItem,
+      level: block.level,
+    }
+  }
+
+  return listIndexMap
+}

package/src/from-portable-text/portable-text-to-markdown.ts

@@ -0,0 +1,135 @@
+import type {
+  ArbitraryTypedObject,
+  PortableTextBlock,
+  TypedObject,
+} from '@portabletext/types'
+import {buildListIndexMap} from './build-list-index-map'
+import {createRenderNode} from './render-node'
+import {
+  DefaultBlockSpacingRenderer,
+  type BlockSpacingRenderer,
+} from './renderers/block-spacing'
+import {DefaultHardBreakRenderer} from './renderers/hard-break'
+import {
+  DefaultListItemRenderer,
+  DefaultUnknownListItemRenderer,
+} from './renderers/list-item'
+import {
+  DefaultCodeRenderer,
+  DefaultEmRenderer,
+  DefaultLinkRenderer,
+  DefaultStrikeThroughRenderer,
+  DefaultStrongRenderer,
+  DefaultUnderlineRenderer,
+  DefaultUnknownMarkRenderer,
+} from './renderers/marks'
+import {
+  DefaultBlockquoteRenderer,
+  DefaultH1Renderer,
+  DefaultH2Renderer,
+  DefaultH3Renderer,
+  DefaultH4Renderer,
+  DefaultH5Renderer,
+  DefaultH6Renderer,
+  DefaultNormalRenderer,
+  DefaultUnknownStyleRenderer,
+} from './renderers/style'
+import {DefaultUnknownTypeRenderer} from './renderers/type'
+import type {PortableTextRenderers} from './types'
+
+const defaultRenderers: PortableTextRenderers = {
+  types: {},
+
+  block: {
+    normal: DefaultNormalRenderer,
+    blockquote: DefaultBlockquoteRenderer,
+    h1: DefaultH1Renderer,
+    h2: DefaultH2Renderer,
+    h3: DefaultH3Renderer,
+    h4: DefaultH4Renderer,
+    h5: DefaultH5Renderer,
+    h6: DefaultH6Renderer,
+  },
+  marks: {
+    'em': DefaultEmRenderer,
+    'strong': DefaultStrongRenderer,
+    'code': DefaultCodeRenderer,
+    'underline': DefaultUnderlineRenderer,
+    'strike-through': DefaultStrikeThroughRenderer,
+    'link': DefaultLinkRenderer,
+  },
+  listItem: DefaultListItemRenderer,
+  hardBreak: DefaultHardBreakRenderer,
+
+  unknownType: DefaultUnknownTypeRenderer,
+  unknownMark: DefaultUnknownMarkRenderer,
+  unknownListItem: DefaultUnknownListItemRenderer,
+  unknownBlockStyle: DefaultUnknownStyleRenderer,
+}
+
+type Options = Partial<PortableTextRenderers> & {
+  blockSpacing?: BlockSpacingRenderer
+}
+
+/**
+ * @public
+ */
+export function portableTextToMarkdown<
+  Block extends TypedObject = PortableTextBlock | ArbitraryTypedObject,
+>(blocks: Array<Block>, options: Options = {}): string {
+  const renderers = {
+    block: {
+      ...defaultRenderers.block,
+      ...options.block,
+    },
+    listItem: options.listItem ?? defaultRenderers.listItem,
+    marks: {
+      ...defaultRenderers.marks,
+      ...options.marks,
+    },
+    types: {
+      ...defaultRenderers.types,
+      ...options.types,
+    },
+    hardBreak: options.hardBreak ?? defaultRenderers.hardBreak,
+    unknownType: options.unknownType ?? defaultRenderers.unknownType,
+    unknownBlockStyle:
+      options.unknownBlockStyle ?? defaultRenderers.unknownBlockStyle,
+    unknownListItem:
+      options.unknownListItem ?? defaultRenderers.unknownListItem,
+    unknownMark: options.unknownMark ?? defaultRenderers.unknownMark,
+  }
+  const renderBlockSpacing = options.blockSpacing ?? DefaultBlockSpacingRenderer
+
+  const listIndexMap = buildListIndexMap(blocks)
+  const renderNode = createRenderNode(renderers, listIndexMap)
+
+  return blocks
+    .map((node, index) => {
+      const renderedNode = renderNode({
+        node,
+        index,
+        isInline: false,
+        renderNode,
+      })
+
+      if (index === blocks.length - 1) {
+        return renderedNode
+      }
+
+      const nextNode = blocks.at(index + 1)
+
+      if (!nextNode) {
+        return renderedNode
+      }
+
+      const blockSpacing =
+        renderBlockSpacing({
+          current: node,
+          next: nextNode,
+        }) ?? '\n\n'
+
+      return `${renderedNode}${blockSpacing}`
+    })
+    .join('')
+}

package/src/from-portable-text/render-node.ts

@@ -0,0 +1,176 @@
+import {
+  buildMarksTree,
+  isPortableTextBlock,
+  isPortableTextListItemBlock,
+  isPortableTextToolkitSpan,
+  isPortableTextToolkitTextNode,
+  spanToPlainText,
+  type ToolkitNestedPortableTextSpan,
+  type ToolkitTextNode,
+} from '@portabletext/toolkit'
+import type {
+  PortableTextBlock,
+  PortableTextListItemBlock,
+  PortableTextMarkDefinition,
+  PortableTextSpan,
+  TypedObject,
+} from '@portabletext/types'
+import {defaultKeyGenerator} from '../key-generator'
+import type {PortableTextRenderers, RenderNode, Serializable} from './types'
+
+interface SerializedBlock {
+  _key: string
+  children: string
+  index: number
+  isInline: boolean
+  node: PortableTextBlock | PortableTextListItemBlock
+}
+
+export const createRenderNode = (
+  renderers: PortableTextRenderers,
+  listIndexMap: Map<string, number>,
+): RenderNode => {
+  function renderNode<N extends TypedObject>(options: Serializable<N>): string {
+    const {node, index, isInline} = options
+
+    if (isPortableTextListItemBlock(node)) {
+      return renderListItem(node, index)
+    }
+
+    if (isPortableTextToolkitSpan(node)) {
+      return renderSpan(node)
+    }
+
+    if (isPortableTextBlock(node)) {
+      return renderBlock(node, index, isInline)
+    }
+
+    if (isPortableTextToolkitTextNode(node)) {
+      return renderText(node)
+    }
+
+    return renderCustomBlock(node, index, isInline)
+  }
+
+  function renderListItem(
+    node: PortableTextListItemBlock<
+      PortableTextMarkDefinition,
+      PortableTextSpan
+    >,
+    index: number,
+  ): string {
+    const renderer = renderers.listItem
+    const handler =
+      typeof renderer === 'function' ? renderer : renderer[node.listItem]
+    const itemHandler = handler || renderers.unknownListItem
+
+    // Build the text content from the block
+    const tree = buildMarksTree(node)
+    const textContent = tree
+      .map((child, i) => {
+        return renderNode({node: child, isInline: true, index: i, renderNode})
+      })
+      .join('')
+
+    let children = textContent
+
+    if (node.style && node.style !== 'normal') {
+      // Wrap any other style in whatever the block component says to use
+      const {listItem: _listItem, ...blockNode} = node
+      children = renderNode({
+        node: blockNode,
+        index,
+        isInline: false,
+        renderNode,
+      })
+      // Strip trailing newlines from block styles - list item component handles spacing
+      children = children.replace(/\n+$/, '')
+    }
+
+    return itemHandler({
+      value: node,
+      index,
+      listIndex: node._key ? listIndexMap.get(node._key) : undefined,
+      isInline: false,
+      renderNode,
+      children,
+    })
+  }
+
+  function renderSpan(node: ToolkitNestedPortableTextSpan): string {
+    const {markDef, markType, markKey} = node
+    const span = renderers.marks[markType] || renderers.unknownMark
+    const children = node.children.map((child, childIndex) =>
+      renderNode({node: child, index: childIndex, isInline: true, renderNode}),
+    )
+
+    return span({
+      text: spanToPlainText(node),
+      value: markDef,
+      markType,
+      markKey,
+      renderNode,
+      children: children.join(''),
+    })
+  }
+
+  function renderBlock(
+    node: PortableTextBlock,
+    index: number,
+    isInline: boolean,
+  ): string {
+    const {_key, ...props} = serializeBlock({node, index, isInline, renderNode})
+    const style = props.node.style || 'normal'
+    const handler =
+      typeof renderers.block === 'function'
+        ? renderers.block
+        : renderers.block[style]
+    const block = handler || renderers.unknownBlockStyle
+
+    return block({...props, value: props.node, renderNode})
+  }
+
+  function renderText(node: ToolkitTextNode): string {
+    if (node.text === '\n') {
+      return renderers.hardBreak()
+    }
+
+    return node.text
+  }
+
+  function renderCustomBlock(
+    value: TypedObject,
+    index: number,
+    isInline: boolean,
+  ): string {
+    const component = renderers.types[value._type] ?? renderers.unknownType
+
+    return component({
+      value,
+      isInline,
+      index,
+      renderNode,
+    })
+  }
+
+  return renderNode
+}
+
+function serializeBlock(
+  options: Serializable<PortableTextBlock>,
+): SerializedBlock {
+  const {node, index, isInline, renderNode} = options
+  const tree = buildMarksTree(node)
+
+  const renderedChildren = tree.map((child, i) =>
+    renderNode({node: child, isInline: true, index: i, renderNode}),
+  )
+
+  return {
+    _key: node._key || defaultKeyGenerator(),
+    children: renderedChildren.join(''),
+    index,
+    isInline,
+    node,
+  }
+}

package/src/from-portable-text/renderers/block-spacing.ts

@@ -0,0 +1,39 @@
+import {
+  isPortableTextBlock,
+  isPortableTextListItemBlock,
+} from '@portabletext/toolkit'
+import type {TypedObject} from '@portabletext/types'
+
+/**
+ * @public
+ */
+export type BlockSpacingRenderer = (options: {
+  current: TypedObject
+  next: TypedObject
+}) => string | undefined
+
+/**
+ * @public
+ */
+export const DefaultBlockSpacingRenderer: BlockSpacingRenderer = ({
+  current,
+  next,
+}) => {
+  if (
+    isPortableTextListItemBlock(current) &&
+    isPortableTextListItemBlock(next)
+  ) {
+    return '\n'
+  }
+
+  if (
+    isPortableTextBlock(current) &&
+    isPortableTextBlock(next) &&
+    current.style === 'blockquote' &&
+    next.style === 'blockquote'
+  ) {
+    return '\n>\n'
+  }
+
+  return '\n\n'
+}

package/src/from-portable-text/renderers/hard-break.ts

@@ -0,0 +1,4 @@
+/**
+ * @public
+ */
+export const DefaultHardBreakRenderer = (): string => '  \n'

package/src/from-portable-text/renderers/list-item.ts

@@ -0,0 +1,32 @@
+import type {PortableTextListItemRenderer} from '../types'
+
+/**
+ * @public
+ */
+export const DefaultListItemRenderer: PortableTextListItemRenderer = ({
+  children,
+  value,
+  listIndex,
+}) => {
+  const listStyle = value.listItem || 'bullet'
+  const level = value.level || 1
+
+  if (listStyle === 'number') {
+    const indent = '   '.repeat(level - 1)
+
+    return `${indent}${listIndex ?? 1}. ${children}`
+  }
+
+  const indent = '   '.repeat(level - 1)
+
+  return `${indent}- ${children}`
+}
+
+/**
+ * @public
+ */
+export const DefaultUnknownListItemRenderer: PortableTextListItemRenderer = ({
+  children,
+}) => {
+  return `- ${children}\n`
+}

package/src/from-portable-text/renderers/marks.ts

@@ -0,0 +1,113 @@
+import type {TypedObject} from '@portabletext/types'
+import type {PortableTextMarkRenderer} from '../types'
+
+/**
+ * @public
+ */
+export const DefaultEmRenderer: PortableTextMarkRenderer = ({children}) =>
+  `_${children}_`
+
+/**
+ * @public
+ */
+export const DefaultStrongRenderer: PortableTextMarkRenderer = ({children}) =>
+  `**${children}**`
+
+/**
+ * @public
+ */
+export const DefaultCodeRenderer: PortableTextMarkRenderer = ({children}) =>
+  `\`${children}\``
+
+/**
+ * @public
+ */
+export const DefaultUnderlineRenderer: PortableTextMarkRenderer = ({
+  children,
+}) => `<u>${children}</u>`
+
+/**
+ * @public
+ */
+export const DefaultStrikeThroughRenderer: PortableTextMarkRenderer = ({
+  children,
+}) => `~~${children}~~`
+
+interface DefaultLink extends TypedObject {
+  _type: 'link'
+  href: string
+  title: string | undefined
+}
+
+/**
+ * @public
+ */
+export const DefaultLinkRenderer: PortableTextMarkRenderer<DefaultLink> = ({
+  children,
+  value,
+}) => {
+  const href = value?.href || ''
+  const title = value?.title || ''
+  const looksSafe = uriLooksSafe(href)
+
+  if (looksSafe) {
+    // Check if the URL looks like an HTML injection attempt
+    // If it has quotes AND angle brackets, or other suspicious patterns, encode more aggressively
+    const looksLikeInjection = /["'][^"']*[<>]|[<>][^<>]*["']/.test(href)
+
+    if (looksLikeInjection) {
+      // Encode all special characters that could be used for injection
+      const encodedHref = href.replace(/["<>() ]/g, (char) => {
+        return `%${char.charCodeAt(0).toString(16).toUpperCase()}`
+      })
+      return `[${children}](${encodedHref})`
+    }
+
+    // For normal URLs, don't encode parentheses - Markdown handles balanced parens fine
+    return `[${children}](${href}${title ? ` "${title}"` : ''})`
+  }
+
+  // Return children without link when URL is unsafe
+  return children
+}
+
+function uriLooksSafe(uri: string): boolean {
+  const url = (uri || '').trim()
+  const first = url.charAt(0)
+
+  if (first === '#' || first === '/') {
+    return true
+  }
+
+  const colonIndex = url.indexOf(':')
+  if (colonIndex === -1) {
+    return true
+  }
+
+  const allowedProtocols = ['http', 'https', 'mailto', 'tel']
+  const proto = url.slice(0, colonIndex).toLowerCase()
+  if (allowedProtocols.indexOf(proto) !== -1) {
+    return true
+  }
+
+  const queryIndex = url.indexOf('?')
+  if (queryIndex !== -1 && colonIndex > queryIndex) {
+    return true
+  }
+
+  const hashIndex = url.indexOf('#')
+  if (hashIndex !== -1 && colonIndex > hashIndex) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * @public
+ */
+export const DefaultUnknownMarkRenderer: PortableTextMarkRenderer = ({
+  children,
+}) => {
+  return children
+}

package/src/from-portable-text/renderers/style.ts

@@ -0,0 +1,79 @@
+import type {PortableTextBlock} from '@portabletext/types'
+import type {PortableTextRenderer} from '../types'
+
+type PortableTextBlockRenderer = PortableTextRenderer<PortableTextBlock>
+
+/**
+ * @public
+ */
+export const DefaultNormalRenderer: PortableTextBlockRenderer = ({
+  children,
+}) => {
+  // Empty blocks should not add extra spacing
+  if (!children || children.trim() === '') {
+    return ''
+  }
+
+  return children
+}
+
+/**
+ * @public
+ */
+export const DefaultBlockquoteRenderer: PortableTextBlockRenderer = ({
+  children,
+}) => {
+  // Prefix each line with "> " for proper blockquote formatting
+  // This handles multi-line content and preserves empty lines
+  if (!children) return '>'
+
+  return children
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .join('\n')
+}
+
+/**
+ * @public
+ */
+export const DefaultH1Renderer: PortableTextBlockRenderer = ({children}) =>
+  `# ${children}`
+
+/**
+ * @public
+ */
+export const DefaultH2Renderer: PortableTextBlockRenderer = ({children}) =>
+  `## ${children}`
+
+/**
+ * @public
+ */
+export const DefaultH3Renderer: PortableTextBlockRenderer = ({children}) =>
+  `### ${children}`
+
+/**
+ * @public
+ */
+export const DefaultH4Renderer: PortableTextBlockRenderer = ({children}) =>
+  `#### ${children}`
+
+/**
+ * @public
+ */
+export const DefaultH5Renderer: PortableTextBlockRenderer = ({children}) =>
+  `##### ${children}`
+
+/**
+ * @public
+ */
+export const DefaultH6Renderer: PortableTextBlockRenderer = ({children}) =>
+  `###### ${children}`
+
+/**
+ * @public
+ */
+export const DefaultUnknownStyleRenderer: PortableTextBlockRenderer = ({
+  children,
+}) => {
+  return children ?? ''
+}