Add bulletOther option to use for adjacent lists

Closes GH-18.

Author: wooorm

lib/handle/list-item.js

@@ -17,7 +17,7 @@ import {indentLines} from '../util/indent-lines.js'
  */
 export function listItem(node, parent, context) {
   const listItemIndent = checkListItemIndent(context)
-  let bullet = context.currentBullet || checkBullet(context)
+  let bullet = context.bulletCurrent || checkBullet(context)
 
   // Add the marker value for ordered lists.
   if (parent && parent.type === 'list' && parent.ordered) {

lib/handle/list.js

@@ -5,27 +5,38 @@
 
 import {containerFlow} from '../util/container-flow.js'
 import {checkBullet} from '../util/check-bullet.js'
-import {checkOtherBullet} from '../util/check-other-bullet.js'
+import {checkBulletOther} from '../util/check-bullet-other.js'
 import {checkRule} from '../util/check-rule.js'
 
 /**
  * @type {Handle}
  * @param {List} node
  */
-export function list(node, _, context) {
+export function list(node, parent, context) {
   const exit = context.enter('list')
-  const currentBullet = context.currentBullet
+  const bulletCurrent = context.bulletCurrent
   /** @type {string} */
   let bullet = checkBullet(context)
-  const otherBullet = checkOtherBullet(context)
+  /** @type {string} */
+  const bulletOther = checkBulletOther(context)
+  const bulletLastUsed = context.bulletLastUsed
 
   if (node.ordered) {
     bullet = '.'
   } else {
     const firstListItem = node.children ? node.children[0] : undefined
     let useDifferentMarker = false
 
-    // If there’s an empty first list item, directly in two list items,
+    if (
+      parent &&
+      context.options.bulletOther &&
+      bulletLastUsed &&
+      bullet === bulletLastUsed
+    ) {
+      useDifferentMarker = true
+    }
+
+    // If there’s an empty first list item directly in two list items,
     // we have to use a different bullet:
     //
     // ```markdown
@@ -34,16 +45,22 @@ export function list(node, _, context) {
     //
     // …because otherwise it would become one big thematic break.
     if (
+      // Bullet could be used as a thematic break marker:
+      (bullet === '*' || bullet === '-') &&
+      // Empty first list item:
       firstListItem &&
-      // Empty list item:
       (!firstListItem.children || !firstListItem.children[0]) &&
       // Directly in two other list items:
+      context.stack[context.stack.length - 1] === 'list' &&
       context.stack[context.stack.length - 2] === 'listItem' &&
-      context.stack[context.stack.length - 4] === 'listItem'
+      context.stack[context.stack.length - 3] === 'list' &&
+      context.stack[context.stack.length - 4] === 'listItem' &&
+      // That are each the first child.
+      context.indexStack[context.indexStack.length - 1] === 0 &&
+      context.indexStack[context.indexStack.length - 2] === 0 &&
+      context.indexStack[context.indexStack.length - 3] === 0 &&
+      context.indexStack[context.indexStack.length - 4] === 0
     ) {
-      // Note: this is only needed for first children of first children,
-      // but the code checks for *children*, not *first*.
-      // So this might generate different bullets where not really needed.
       useDifferentMarker = true
     }
 
@@ -60,6 +77,7 @@ export function list(node, _, context) {
 
       while (++index < node.children.length) {
         const item = node.children[index]
+
         if (
           item &&
           item.type === 'listItem' &&
@@ -74,13 +92,14 @@ export function list(node, _, context) {
     }
 
     if (useDifferentMarker) {
-      bullet = otherBullet
+      bullet = bulletOther
     }
   }
 
-  context.currentBullet = bullet
+  context.bulletCurrent = bullet
   const value = containerFlow(node, context)
-  context.currentBullet = currentBullet
+  context.bulletLastUsed = bullet
+  context.bulletCurrent = bulletCurrent
   exit()
   return value
 }

lib/index.js

@@ -27,7 +27,8 @@ export function toMarkdown(tree, options = {}) {
     unsafe: [],
     join: [],
     handlers: {},
-    options: {}
+    options: {},
+    indexStack: []
   }
 
   configure(context, {unsafe, join, handlers: handle})

lib/join.js

@@ -10,16 +10,22 @@ export const join = [joinDefaults]
 
 /** @type {Join} */
 function joinDefaults(left, right, parent, context) {
+  // Indented code after list or another indented code.
   if (
-    // Two lists with the same marker.
-    (right.type === 'list' &&
-      right.type === left.type &&
-      Boolean(left.ordered) === Boolean(right.ordered)) ||
-    // Indented code after list or another indented code.
-    (right.type === 'code' &&
-      formatCodeAsIndented(right, context) &&
-      (left.type === 'list' ||
-        (left.type === right.type && formatCodeAsIndented(left, context))))
+    right.type === 'code' &&
+    formatCodeAsIndented(right, context) &&
+    (left.type === 'list' ||
+      (left.type === right.type && formatCodeAsIndented(left, context)))
+  ) {
+    return false
+  }
+
+  // Two lists with the same marker.
+  if (
+    left.type === 'list' &&
+    left.type === right.type &&
+    ((left.ordered && right.ordered) ||
+      (!left.ordered && !right.ordered && !context.options.bulletOther))
   ) {
     return false
   }

lib/types.js

@@ -25,14 +25,20 @@
 
 /**
  * @typedef Context
- * @property {Array.<string>} stack
+ * @property {string[]} stack
+ *   Stack of labels.
+ * @property {number[]} indexStack
+ *   Positions of children in their parents.
  * @property {Enter} enter
  * @property {Options} options
  * @property {Array.<Unsafe>} unsafe
  * @property {Array.<Join>} join
  * @property {Handle} handle
  * @property {Handlers} handlers
- * @property {string|undefined} currentBullet
+ * @property {string|undefined} bulletCurrent
+ *   The marker used by the current list.
+ * @property {string|undefined} bulletLastUsed
+ *   The marker used by the previous list.
  */
 
 /**
@@ -72,7 +78,7 @@
 /**
  * @typedef Options
  * @property {'-'|'*'|'+'} [bullet]
- * @property {'-'|'*'|'+'} [otherBullet]
+ * @property {'-'|'*'|'+'} [bulletOther]
  * @property {boolean} [closeAtx]
  * @property {'_'|'*'} [emphasis]
  * @property {'~'|'`'} [fence]

lib/util/check-other-bullet.js renamed to lib/util/check-bullet-other.js

@@ -9,31 +9,31 @@ import {checkBullet} from './check-bullet.js'
  * @param {Context} context
  * @returns {Exclude<Options['bullet'], undefined>}
  */
-export function checkOtherBullet(context) {
+export function checkBulletOther(context) {
   const bullet = checkBullet(context)
-  const otherBullet = context.options.otherBullet
+  const bulletOther = context.options.bulletOther
 
-  if (!otherBullet) {
+  if (!bulletOther) {
     return bullet === '*' ? '-' : '*'
   }
 
-  if (otherBullet !== '*' && otherBullet !== '+' && otherBullet !== '-') {
+  if (bulletOther !== '*' && bulletOther !== '+' && bulletOther !== '-') {
     throw new Error(
       'Cannot serialize items with `' +
-        otherBullet +
-        '` for `options.otherBullet`, expected `*`, `+`, or `-`'
+        bulletOther +
+        '` for `options.bulletOther`, expected `*`, `+`, or `-`'
     )
   }
 
-  if (otherBullet === bullet) {
+  if (bulletOther === bullet) {
     throw new Error(
       'Expected `bullet` (`' +
         bullet +
-        '`) and `otherBullet` (`' +
-        otherBullet +
+        '`) and `bulletOther` (`' +
+        bulletOther +
         '`) to be different'
     )
   }
 
-  return otherBullet
+  return bulletOther
 }

lib/util/container-flow.js

@@ -11,23 +11,34 @@
  * @returns {string}
  */
 export function containerFlow(parent, context) {
+  const indexStack = context.indexStack
   const children = parent.children || []
   /** @type {Array.<string>} */
   const results = []
   let index = -1
 
+  indexStack.push(-1)
+
   while (++index < children.length) {
     const child = children[index]
 
+    indexStack[indexStack.length - 1] = index
+
     results.push(
       context.handle(child, parent, context, {before: '\n', after: '\n'})
     )
 
+    if (child.type !== 'list') {
+      context.bulletLastUsed = undefined
+    }
+
     if (index < children.length - 1) {
       results.push(between(child, children[index + 1]))
     }
   }
 
+  indexStack.pop()
+
   return results.join('')
 
   /**
@@ -37,11 +48,9 @@ export function containerFlow(parent, context) {
    */
   function between(left, right) {
     let index = context.join.length
-    /** @type {ReturnType<Join>} */
-    let result
 
     while (index--) {
-      result = context.join[index](left, right, parent, context)
+      const result = context.join[index](left, right, parent, context)
 
       if (result === true || result === 1) {
         break

lib/util/container-phrasing.js

@@ -12,17 +12,22 @@
  * @returns {string}
  */
 export function containerPhrasing(parent, context, safeOptions) {
+  const indexStack = context.indexStack
   const children = parent.children || []
   /** @type {Array.<string>} */
   const results = []
   let index = -1
   let before = safeOptions.before
 
+  indexStack.push(-1)
+
   while (++index < children.length) {
     const child = children[index]
     /** @type {string} */
     let after
 
+    indexStack[indexStack.length - 1] = index
+
     if (index + 1 < children.length) {
       // @ts-expect-error: hush, it’s actually a `zwitch`.
       let handle = context.handle.handlers[children[index + 1].type]
@@ -60,5 +65,7 @@ export function containerPhrasing(parent, context, safeOptions) {
     before = results[results.length - 1].slice(-1)
   }
 
+  indexStack.pop()
+
   return results.join('')
 }

lib/util/format-heading-as-setext.js

@@ -17,7 +17,6 @@ export function formatHeadingAsSetext(node, context) {
   // Look for literals with a line break.
   // Note that this also
   visit(node, (node) => {
-    console.log('n:', node.type)
     if (
       ('value' in node && /\r?\n|\r/.test(node.value)) ||
       node.type === 'break'

readme.md

@@ -83,9 +83,35 @@ Serialize **[mdast][]** to markdown.
 
 ###### `options.bullet`
 
-Marker to use to for bullets of items in unordered lists (`'*'`, `'+'`, or `'-'`,
+Marker to use for bullets of items in unordered lists (`'*'`, `'+'`, or `'-'`,
 default: `'*'`).
 
+###### `options.bulletOther`
+
+Marker to use in certain cases where the primary bullet doesn’t work (`'*'`,
+`'+'`, or `'-'`, default: depends).
+
+There are three cases where the primary bullet can’t be used:
+
+*   When three list items are on their own, the last one is empty, and `bullet`
+    is also a valid `rule`: `* - +`.
+    This would turn into a thematic break if serialized with three primary
+    bullets.
+    As this is an edge case unlikely to appear in normal markdown, the last list
+    item will be given a different bullet.
+*   When a thematic break is the first child of one of the list items, and
+    `bullet` is the same character as `rule`: `- ***`.
+    This would turn into a single thematic break if serialized with primary
+    bullets.
+    As this is an edge case unlikely to appear in normal markdown this markup is
+    always fixed, even if `bulletOther` is not passed
+*   When two unordered lists appear next to each other: `* a\n- b`.
+    CommonMark sees different bullets as different lists, but several markdown
+    parsers parse it as one list.
+    To solve for both, we instead inject an empty comment between the two lists:
+    `* a\n<!---->\n* b`, but if `bulletOther` is given explicitly, it will be
+    used instead
+
 ###### `options.closeAtx`
 
 Whether to add the same number of number signs (`#`) at the end of an ATX