Skip to content

Bug: Incorrect blank line formatting for nested Markdown lists inside JSDoc #264

@astrochemx

Description

@astrochemx

Bug Description

There is a discrepancy in how prettier-plugin-jsdoc formats nested Markdown lists compared to native Prettier.

When formatting a JSDoc block containing a loose Markdown list with nested items, the plugin improperly injects blank lines before the nested items and simultaneously strips the intended blank lines between the top-level list items.

Native Prettier formats the raw markdown version of this correctly, but prettier-plugin-jsdoc breaks the spacing rules.

Input

/**
 * Spaced Repetition
 *
 * - If Correct (Quality >= 3):
 *   - If repetitions == 0: interval = 1.
 *   - If repetitions == 1: interval = 6.
 *
 * - If Incorrect (Quality < 3):
 *   - repetitions = 0.
 *   - interval = 1.
 */

Expected Behavior (Matches Native Prettier)

The blank line separating the top-level list items should be preserved, and no extra blank lines should be forcefully injected before the nested children:

/**
 * Spaced Repetition
 *
 * - If Correct (Quality >= 3):
 *   - If repetitions == 0: interval = 1.
 *   - If repetitions == 1: interval = 6.
 *
 * - If Incorrect (Quality < 3):
 *   - repetitions = 0.
 *   - interval = 1.
 */

Actual Behavior

The plugin removes the blank line before - If Incorrect and forcefully injects blank lines before the nested items:

/**
 * Spaced Repetition
 *
 * - If Correct (Quality >= 3):
 *
 *   - If repetitions == 0: interval = 1.
 *   - If repetitions == 1: interval = 6.
 * - If Incorrect (Quality < 3):
 *
 *   - repetitions = 0.
 *   - interval = 1.
 */

Steps to Reproduce

  1. Create a JavaScript/TypeScript file with the provided input JSDoc comment.
  2. Run Prettier against the file with prettier-plugin-jsdoc enabled.
  3. Observe that the nested list spacing is incorrectly mangled.

Environment

  • Prettier Version: 3.8.3
  • prettier-plugin-jsdoc Version: 1.8.0
  • Node.js Version: 26.1.0
  • OS: Windows 11 x64

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions