@portabletext/markdown 1.0.3 → 1.0.5

package/src/example-document.terse-pt.json

@@ -1,124 +0,0 @@
-[
-  "h1:Markdown to Portable Text: A Complete Guide",
-  "Converting markdown to Portable Text is a ,powerful, way to bridge the gap between ,simple text formatting, and ,structured content,.",
-  "h2:Why Portable Text?",
-  "Portable Text is a ,specification, for ,rich text, that is:",
-  ">-:Platform ,agnostic",
-  ">-:Structured, and ,queryable",
-  ">-:Designed for ,modern content workflows",
-  "Visit ,https://portabletext.org, for more information, or check out the ,official documentation,.",
-  "{horizontal-rule}",
-  "h2:Supported Features",
-  "h3:Text Formatting",
-  "You can use ,bold text,, ,italic text,, ,inline code,, and even ,strikethrough, text. The parser handles ,nested formatting, gracefully, including ,bold and italic, combined.",
-  "Here's some ,code with **bold inside**, and ,text with ,code inside, to test edge cases.",
-  "h3:Links and Images",
-  "Reference-style links work too! Check out this ,example link, that uses references defined elsewhere.",
-  "{image}",
-  "Here's an inline image in text: ,{image}, followed by more text.",
-  "h3:Code Blocks",
-  "Fenced code blocks with syntax highlighting:",
-  "{code}",
-  "Indented code blocks also work:",
-  "{code}",
-  "h3:Blockquotes",
-  "q:Markdown is a lightweight markup language for creating formatted text.",
-  "q:It was created by John Gruber in 2004.",
-  "Nested blockquotes are supported:",
-  "q:This is the outer quote",
-  "q:And this is nested deeper",
-  "q:With multiple paragraphs",
-  "h3:Lists",
-  "h4:Unordered Lists",
-  ">-:Bold item, in a list",
-  ">-:Italic item, with ,a link",
-  ">-:Item with ,inline code",
-  ">>-:Nested item one",
-  ">>-:Nested item two",
-  ">>>-:Even deeper nesting",
-  ">-:Back to top level",
-  "h4:Ordered Lists",
-  ">#:First step: Parse the markdown",
-  ">#:Second step: Generate tokens",
-  ">#:Third step: Transform to Portable Text",
-  ">>#:Map block types",
-  ">>#:Handle inline formatting",
-  ">>#:Preserve structure",
-  "h4:Mixed Lists",
-  ">#:Ordered parent",
-  ">>-:Unordered child",
-  ">>-:Another unordered",
-  ">>>#:Back to ordered",
-  ">>>#:Still ordered",
-  ">#:Continue ordered parent",
-  "h3:Tables",
-  "Here's a comparison of different content formats:",
-  "{table}",
-  "Feature support matrix:",
-  "{table}",
-  "h3:Horizontal Rules",
-  "You can separate sections with horizontal rules:",
-  "{horizontal-rule}",
-  "They create visual breaks in the content.",
-  "{horizontal-rule}",
-  "h3:All Heading Levels",
-  "h1:Heading 1",
-  "h2:Heading 2",
-  "h3:Heading 3",
-  "h4:Heading 4",
-  "h5:Heading 5",
-  "h6:Heading 6",
-  "h2:Advanced Examples",
-  "h3:Overlapping Formatting",
-  "This paragraph contains ,bold with ,italic inside, and ,italic with ,bold inside, to test proper nesting.",
-  "You can also have ,bold with ,code, and ,italic with ,code, and even ,code with **bold** and _italic_, (though the formatting inside code should be preserved as-is).",
-  "h3:Links with Formatting",
-  "Here's a ,bold link, and an ,italic link, and even a ,code link,.",
-  "h3:Complex List Items",
-  ">-:Item with ,bold,, ,italic,, and ,code",
-  ">-:Item with a ,link to ,bold, content",
-  ">-:Item with an inline image ,{image}, in the middle",
-  ">>-:Nested ,bold item, with ,italic, and ,code",
-  ">>-:Another nested item",
-  "h3:Line Breaks",
-  "This is a line with a hard break\nthat continues on the next line but stays in the same paragraph.",
-  "Another paragraph with a break\nand more content.",
-  "h3:Autolinks",
-  "Check out these autolinks: ,https://example.com, and ,mailto:hello@example.com, for quick linking.",
-  "h3:HTML Passthrough",
-  "{html}",
-  "Inline HTML like highlighted text can be handled too.",
-  "h3:Reference Links",
-  "This is ,reference link one, and this is ,reference link two,.",
-  "You can also use ,implicit references, by just using the text as the reference.",
-  "h2:Implementation Notes",
-  "The transformation process involves several key steps:",
-  ">#:Lexical Analysis,: Parse markdown into tokens",
-  ">#:Syntax Tree Building,: Construct an AST from tokens",
-  ">#:Transformation,: Map markdown AST to Portable Text structure",
-  ">#:Validation,: Ensure output conforms to schema",
-  "h3:Edge Cases",
-  "h4:Empty Blocks",
-  "Sometimes you have empty paragraphs:",
-  "Or consecutive horizontal rules:",
-  "{horizontal-rule}",
-  "{horizontal-rule}",
-  "h4:Special Characters",
-  "Text with special characters like ,&,, ,<,, and ,>, should be handled correctly.",
-  "h4:URLs in Text",
-  "Raw URLs like ,https://example.com, (without angle brackets) may or may not become links depending on the parser configuration.",
-  "h2:Conclusion",
-  "This document demonstrates the ,comprehensive, support for ,markdown features, in the ,markdown-to-portable-text, converter. With proper handling of:",
-  ">-:All basic formatting",
-  ">-:Complex nesting",
-  ">-:Various link types",
-  ">-:Images (block and inline)",
-  ">-:Code blocks",
-  ">-:Lists of all types",
-  ">-:Tables",
-  ">-:And much more!",
-  "The result is ,robust, reliable, content transformation that preserves both structure and semantics.",
-  "{horizontal-rule}",
-  "Happy converting!, 🎉",
-  "Last updated: 2025"
-]

package/src/example-document.test.ts

@@ -1,87 +0,0 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import type {BlockObjectDefinition} from '@portabletext/schema'
-import {createTestKeyGenerator, getTersePt} from '@portabletext/test'
-import {describe, expect, test} from 'vitest'
-import {defaultSchema} from './default-schema'
-import {portableTextToMarkdown} from './from-portable-text/portable-text-to-markdown'
-import {
-  DefaultCodeBlockRenderer,
-  DefaultTableRenderer,
-} from './from-portable-text/renderers/type'
-import {markdownToPortableText} from './to-portable-text/markdown-to-portable-text'
-import {buildObjectMatcher} from './to-portable-text/matchers'
-
-const exampleDocumentMarkdown = fs.readFileSync(
-  path.resolve(__dirname, 'example-document.md'),
-  'utf-8',
-)
-const exampleDocumentMarkdownOut = fs
-  .readFileSync(path.resolve(__dirname, 'example-document.out.md'), 'utf-8')
-  // Account for hard break spaces that may be stripped by editors/tools
-  .replace('hard break\nthat continues', 'hard break  \nthat continues')
-  .replace('with a break\nand more', 'with a break  \nand more')
-const exampleDocumentTersePt = JSON.parse(
-  fs.readFileSync(
-    path.resolve(__dirname, 'example-document.terse-pt.json'),
-    'utf-8',
-  ),
-)
-
-const tableObjectDefinition = {
-  name: 'table',
-  fields: [
-    {name: 'headerRows', type: 'number'},
-    {name: 'rows', type: 'array'},
-  ],
-} as const satisfies BlockObjectDefinition
-
-const tableObjectMatcher = buildObjectMatcher(tableObjectDefinition)
-
-describe('example document', () => {
-  test('markdown to portable text', () => {
-    const keyGenerator = createTestKeyGenerator()
-    const blocks = markdownToPortableText(exampleDocumentMarkdown, {
-      keyGenerator,
-      schema: {
-        ...defaultSchema,
-        blockObjects: [...defaultSchema.blockObjects, tableObjectDefinition],
-      },
-      types: {
-        table: tableObjectMatcher,
-      },
-    })
-    const tersePt = getTersePt({schema: defaultSchema, value: blocks})
-
-    expect(tersePt).toEqual(exampleDocumentTersePt)
-  })
-
-  test('portable text to markdown', () => {
-    const keyGenerator = createTestKeyGenerator()
-    const blocks = markdownToPortableText(exampleDocumentMarkdown, {
-      keyGenerator,
-      schema: {
-        ...defaultSchema,
-        blockObjects: [...defaultSchema.blockObjects, tableObjectDefinition],
-      },
-      types: {
-        table: tableObjectMatcher,
-      },
-      html: {
-        inline: 'text',
-      },
-    })
-    const markdown = portableTextToMarkdown(blocks, {
-      types: {
-        'horizontal-rule': () => '---',
-        'table': DefaultTableRenderer,
-        'code': DefaultCodeBlockRenderer,
-        'html': ({value}) => value.html || '',
-        'image': ({value}) =>
-          `![${value.alt}](${value.src}${value.title ? ` "${value.title}"` : ''})`,
-      },
-    })
-
-    expect(`${markdown}\n`).toBe(exampleDocumentMarkdownOut)
-  })
-})

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

@@ -1,133 +0,0 @@
-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

@@ -1,135 +0,0 @@
-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

@@ -1,176 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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

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