fix(markdown): indent nested list content to the parent marker (#8219)

* fix(markdown): indent nested list content to the parent marker

Nested content under a list item was always indented by the configured
indent size, two spaces by default. CommonMark only treats a block as a
child of a list item when it starts at that item's content column, which
for an ordered list is as wide as the marker: three columns for `1. `,
four for `10. `.

Exports were therefore ambiguous. Reading `1. one\n  1. inner` back with a
strict parser puts the sub-list at the top level, so a Markdown round trip
lost the hierarchy for anything that stores Markdown as its source of truth.

Nested content is now aligned to the marker. Bullet lists are unchanged,
since `- ` is already two columns wide.

Fixes #8182

* fix(markdown): keep configured indentation for bullet lists

Aligning every list item to its prefix meant bullet lists ignored
`Markdown.indentation`, so a custom size or tab indentation came out as two
spaces. Bullets never needed the alignment — `- ` is already two columns.

Alignment is now limited to ordered lists, and it only widens the indent
when the configured one is narrower than the marker.

Also document the new option on the exported helper.

* fix(markdown): measure configured indentation in columns

A tab is one character but runs to the next tab stop, so comparing string
length against the marker width replaced a configured tab with spaces on an
ordered list even though the tab already cleared the marker.

Compare in Markdown columns instead.

* fix(markdown): measure the prefix width in columns too

The configured indent was compared in Markdown columns while the prefix was
still counted in characters. Both sides use columns now, so a prefix
containing a tab is measured the same way as the indent it is compared with.

The list callers only ever build `- ` or `N. `, so nothing reachable today
changes. The helper is exported, so cover it directly.

Author: solomonaustin

.changeset/2026-08-20-ordered-list-markdown-indent.md

@@ -0,0 +1,6 @@
+---
+'@tiptap/core': patch
+'@tiptap/extension-list': patch
+---
+
+Nested lists exported to Markdown now keep their hierarchy when the file is read back by other Markdown tools.

packages/core/__tests__/renderNestedMarkdownContent.spec.ts

@@ -0,0 +1,50 @@
+import { renderNestedMarkdownContent } from '@tiptap/core'
+import { describe, expect, it } from 'vitest'
+
+const node = {
+  type: 'listItem',
+  content: [
+    { type: 'paragraph', content: [{ type: 'text', text: 'parent' }] },
+    { type: 'paragraph', content: [{ type: 'text', text: 'child' }] },
+  ],
+}
+
+/** Stand-in for the renderer helpers, with a configurable indent. */
+const helpers = (indent: string) => ({
+  renderChildren: (nodes: any[]) => nodes[0]?.content?.[0]?.text ?? '',
+  renderChild: (child: any) => child?.content?.[0]?.text ?? '',
+  indent: (text: string) => indent + text,
+})
+
+describe('renderNestedMarkdownContent', () => {
+  it('uses the configured indent when alignment is off', () => {
+    const out = renderNestedMarkdownContent(node, helpers('  '), '10. ')
+
+    expect(out).toBe('10. parent\n\n  child')
+  })
+
+  it('widens a narrow indent to the prefix width', () => {
+    const out = renderNestedMarkdownContent(node, helpers('  '), '10. ', undefined, {
+      alignNestedToPrefix: true,
+    })
+
+    expect(out).toBe('10. parent\n\n    child')
+  })
+
+  it('keeps a tab, which already reaches the prefix width', () => {
+    const out = renderNestedMarkdownContent(node, helpers('\t'), '10. ', undefined, {
+      alignNestedToPrefix: true,
+    })
+
+    expect(out).toBe('10. parent\n\n\tchild')
+  })
+
+  it('measures a tabbed prefix in columns rather than characters', () => {
+    // `\t- ` is one tab plus two characters, so it spans six columns, not three.
+    const out = renderNestedMarkdownContent(node, helpers('  '), '\t- ', undefined, {
+      alignNestedToPrefix: true,
+    })
+
+    expect(out).toBe('\t- parent\n\n      child')
+  })
+})

packages/core/src/utilities/markdown/renderNestedMarkdownContent.ts

@@ -18,6 +18,9 @@ import type { JSONContent } from '@tiptap/core'
  * @param h - The markdown renderer helper
  * @param prefixOrGenerator - Either a string prefix or a function that generates the prefix from context
  * @param ctx - Optional context object (used when prefixOrGenerator is a function)
+ * @param options - Optional rendering options
+ * @param options.alignNestedToPrefix - Indent nested content to the width of the prefix
+ * instead of the configured indent size, when the configured one is narrower
  * @returns The rendered markdown string
  *
  * @example
@@ -29,6 +32,9 @@ import type { JSONContent } from '@tiptap/core'
  * const prefix = `- [${node.attrs?.checked ? 'x' : ' '}] `
  * return renderNestedMarkdownContent(node, h, prefix)
  *
+ * // For an ordered list item, where the nested block has to line up with the marker
+ * return renderNestedMarkdownContent(node, h, '10. ', ctx, { alignNestedToPrefix: true })
+ *
  * // For a blockquote with static prefix
  * return renderNestedMarkdownContent(node, h, '> ')
  *
@@ -53,6 +59,19 @@ import type { JSONContent } from '@tiptap/core'
  * })
  * ```
  */
+const TAB_STOP = 4
+
+/** Width of indentation in Markdown columns, where a tab runs to the next tab stop. */
+function columnWidth(text: string): number {
+  let width = 0
+
+  for (const character of text) {
+    width = character === '\t' ? width + TAB_STOP - (width % TAB_STOP) : width + 1
+  }
+
+  return width
+}
+
 export function renderNestedMarkdownContent(
   node: JSONContent,
   h: {
@@ -62,6 +81,10 @@ export function renderNestedMarkdownContent(
   },
   prefixOrGenerator: string | ((ctx: any) => string),
   ctx?: any,
+  options?: {
+    /** See the `@param` note above. */
+    alignNestedToPrefix?: boolean
+  },
 ): string {
   if (!node || !Array.isArray(node.content)) {
     return ''
@@ -83,9 +106,25 @@ export function renderNestedMarkdownContent(
       const childContent = h.renderChild?.(child, index + 1) ?? h.renderChildren([child])
       if (childContent !== undefined && childContent !== null) {
         // Split the child content by lines and indent each line
+        const indentLine = (line: string) => {
+          if (!options?.alignNestedToPrefix) {
+            return h.indent(line)
+          }
+
+          // Keep the configured indentation when it already reaches the
+          // content column, so `Markdown.indentation` still applies. A tab
+          // runs to the next tab stop, so it is wider than its one character.
+          const configured = h.indent('')
+          const prefixWidth = columnWidth(prefix)
+
+          return (
+            (columnWidth(configured) >= prefixWidth ? configured : ' '.repeat(prefixWidth)) + line
+          )
+        }
+
         const indentedChild = childContent
           .split('\n')
-          .map(line => (line ? h.indent(line) : h.indent('')))
+          .map(line => (line ? indentLine(line) : indentLine('')))
           .join('\n')
 
         output += child.type === 'paragraph' ? `\n\n${indentedChild}` : `\n${indentedChild}`

packages/extension-list/src/item/list-item.ts

@@ -183,6 +183,7 @@ export const ListItem = Node.create<ListItemOptions>({
         return '- '
       },
       ctx,
+      { alignNestedToPrefix: ctx?.parentType === 'orderedList' },
     )
   },
 

packages/markdown/__tests__/conversion-files/index.ts

@@ -10,6 +10,7 @@ export * as mixedListTypes from './mixed-list-types.js'
 export * as nestedNodes from './nested-nodes.js'
 export * as orderedList from './ordered-list.js'
 export * as orderedListSeparatedByBullet from './ordered-list-separated-by-bullet.js'
+export * as orderedListWideMarker from './ordered-list-wide-marker.js'
 export * as orderedListWithBulletList from './ordered-list-with-bullet-list.js'
 export * as softBreakMarks from './soft-break-marks.js'
 export * as taskList from './task-list.js'

packages/markdown/__tests__/conversion-files/ordered-list-wide-marker.ts

@@ -0,0 +1,53 @@
+export const name = 'Ordered List with a Wide Marker'
+
+// `10. ` is four characters, so the nested list has to start at column four to
+// stay a child of it.
+export const expectedInput = `
+10. ten
+    1. inner
+11. eleven
+`.trim()
+
+export const expectedOutput = {
+  type: 'doc',
+  content: [
+    {
+      type: 'orderedList',
+      attrs: { start: 10 },
+      content: [
+        {
+          type: 'listItem',
+          content: [
+            {
+              type: 'paragraph',
+              content: [{ type: 'text', text: 'ten' }],
+            },
+            {
+              type: 'orderedList',
+              content: [
+                {
+                  type: 'listItem',
+                  content: [
+                    {
+                      type: 'paragraph',
+                      content: [{ type: 'text', text: 'inner' }],
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+        {
+          type: 'listItem',
+          content: [
+            {
+              type: 'paragraph',
+              content: [{ type: 'text', text: 'eleven' }],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+}

packages/markdown/__tests__/conversion-files/ordered-list-with-bullet-list.ts

@@ -2,7 +2,7 @@ export const name = 'Ordered List with Nested Bullet List'
 
 export const expectedInput = `
 1. one
-  - inner
+   - inner
 2. two
 `.trim()
 

packages/markdown/__tests__/conversion-files/ordered-list.ts

@@ -3,15 +3,15 @@ export const name = 'Ordered List'
 export const expectedInput = `
 1. Item 1
 2. Item 2
-  1. Subitem 1
-  2. Subitem 2
-    1. Subsubitem 1
-    2. Subsubitem 2
+   1. Subitem 1
+   2. Subitem 2
+      1. Subsubitem 1
+      2. Subsubitem 2
 3. Item 3
-  1. Subitem 1
-  2. Subitem 2
-    1. Subsubitem 1
-    2. Subsubitem 2
+   1. Subitem 1
+   2. Subitem 2
+      1. Subsubitem 1
+      2. Subsubitem 2
 `.trim()
 
 export const expectedOutput = {

packages/markdown/__tests__/list-indentation.spec.ts

@@ -0,0 +1,52 @@
+import { Document } from '@tiptap/extension-document'
+import { BulletList, ListItem, OrderedList } from '@tiptap/extension-list'
+import { Paragraph } from '@tiptap/extension-paragraph'
+import { Text } from '@tiptap/extension-text'
+import { MarkdownManager } from '@tiptap/markdown'
+import { describe, expect, it } from 'vitest'
+
+const manager = (indentation?: { style?: 'space' | 'tab'; size?: number }) =>
+  new MarkdownManager({
+    extensions: [Document, Paragraph, Text, BulletList, OrderedList, ListItem],
+    ...(indentation ? { indentation } : {}),
+  } as any)
+
+const roundTrip = (mm: MarkdownManager, markdown: string) => mm.serialize(mm.parse(markdown) as any)
+
+const ordered = ['1. one', '   1. inner', '2. two'].join('\n')
+const orderedWide = ['10. ten', '    1. inner', '11. eleven'].join('\n')
+const bullet = ['- one', '  - inner', '- two'].join('\n')
+
+describe('list indentation on serialize', () => {
+  it('indents a nested ordered list to the marker width', () => {
+    expect(roundTrip(manager(), ordered)).toBe(ordered)
+  })
+
+  it('widens the indent for a marker wider than the indent size', () => {
+    expect(roundTrip(manager({ style: 'space', size: 2 }), orderedWide)).toBe(orderedWide)
+  })
+
+  it('keeps a configured indent that is already past the marker', () => {
+    expect(roundTrip(manager({ style: 'space', size: 4 }), ordered)).toBe(
+      ['1. one', '    1. inner', '2. two'].join('\n'),
+    )
+  })
+
+  it('keeps tab indentation on an ordered list, since a tab clears the marker', () => {
+    expect(roundTrip(manager({ style: 'tab', size: 1 }), orderedWide)).toBe(
+      ['10. ten', '\t1. inner', '11. eleven'].join('\n'),
+    )
+  })
+
+  it('leaves bullet lists on the configured indent size', () => {
+    expect(roundTrip(manager({ style: 'space', size: 4 }), bullet)).toBe(
+      ['- one', '    - inner', '- two'].join('\n'),
+    )
+  })
+
+  it('leaves bullet lists on tab indentation', () => {
+    expect(roundTrip(manager({ style: 'tab', size: 1 }), bullet)).toBe(
+      ['- one', '\t- inner', '- two'].join('\n'),
+    )
+  })
+})