[GH-ISSUE #1902] MD055 add fixes

kerem commented

2026-03-03 01:29:46 +03:00

Owner

Originally created by @non-zero-sum on GitHub (Dec 28, 2025).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1902

Current state as at v0.40.0: MD055 provides detection, but no fixes.

Proposal: Add the following behaviour

On expectedLeadingPipe && !actualLeadingPipe: insert | ahead of leading token in first cell of row
On !expectedLeadingPipe && actualLeadingPipe: remove | and any leading whitespace from first cell of row
On expectedTrailingPipe && !actualTrailingPipe: insert | after trailing token in last cell of row
On !expectedTrailingPipe && actualTrailingPipe: remove | and any trailing whitespace from last cell of row

Note: this would not guarantee passing MD060 (table-column-style), which would need a seperate fix.

Originally created by @non-zero-sum on GitHub (Dec 28, 2025). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1902 Current state as at v0.40.0: `MD055` provides detection, but no fixes. Proposal: Add the following behaviour - On `expectedLeadingPipe && !actualLeadingPipe`: insert `|` ahead of leading token in first cell of row - On `!expectedLeadingPipe && actualLeadingPipe`: remove `|` and any leading whitespace from first cell of row - On `expectedTrailingPipe && !actualTrailingPipe`: insert `|` after trailing token in last cell of row - On `!expectedTrailingPipe && actualTrailingPipe`: remove `|` and any trailing whitespace from last cell of row Note: this would not guarantee passing `MD060` (`table-column-style`), which would need a seperate fix.

kerem added the

enhancement

label

2026-03-03 01:29:46 +03:00

kerem commented

2026-03-03 01:29:47 +03:00

Author

Owner

@non-zero-sum commented on GitHub (Dec 28, 2025):

As per comments in the PR regarding MD060 compatibility:

rules typically work independently, so this strategy may need more thinking

My initial thoughts on this are:

Option 0: do nothing

Leave the rule as-is without a fix

Option 1: Add/remove pipes (and whitespace) naively (as per PR)

Apply initial suggested logic.

Pros:

simpler code
maintains rule independence

Cons:

add leading:
- right shifts all row content by 1 likely causing MD060 error when aligned (or aligned_delimiter)
- conformance with tight or compact configuration for MD060 would depend on leading spaces already in the cell content
add-trailing:
- conformance with tight or compact configuration for MD060 would depend on trailing spaces in the cell content (and MD009)
- would likely cause MD060 errors with aligned (or aligned_delimiter) especially if fixing multiple rows of different content length
remove leading (including whitespace)
- left shifts all row content by 1 likely causing MD060 error if aligned or aligned_delimiter

Neutral:

remove leading and trailing (including whitespace) would be compatible with MD060 compact and tight

Implication: the user (or an fix for MD060) would need to take care of the alignment

Option 2: add an explicit parameter

Add parameters to the rule (e.g. fix_style, with values matching MD060's style parameter) to allow the user to set the behaviour.

Pros:

avoids the complexity of detecting required behaviour
explicit user choice
would only cause conflict with MD060 if the user chose that behaviour

Cons:

to support any or aligned_delimiter would require more significant refactoring as MD055 is not currently "table aware" as it acts on rows independently (except for first header row when using consistent)
Creates implicit coupling between MD055 and MD060 requiring the settings to be kept in sync

Option 3: apply spacing "consistently" with first table header

Apply the same approach to spaces as is currently done with consistent (default) configuration for pipe presence/absence.

Pros:

avoids added complexity of detecting format for each table
provides compatibility with compact and tight configuration of MD060

Cons:

would not guarantee compatibility with aligned (or aligned_delimiter) configuration of MD060 (as option 1)
would not guarantee compatibility with any configuration of MD060

Implication: the user (or an fix for MD060) would need to take care of the alignment for unsupported scenarios

Option 4: apply spacing based on detection for each table

Use space around non-leading/trailing pipes to infer MD060 preference.

Pros:

maximum compatibility with MD060 without direct coupling

Cons:

would need to duplicate significant amounts of the logic in MD060
would make the rule "table aware" adding complexity that only adds value on fix
what is present in the markdown may not reflect the user configuration of MD060

Implication: the user (or an fix for MD060) would need to take care of the alignment for unsupported scenarios

Option 5: explicit coupling with `MD060` (included for completeness)

Pass the configuration for MD060 into MD055

Pros: as option 2

Cons:

breaks the independence rule
deviates from the current configuration passing approach

@non-zero-sum commented on GitHub (Dec 28, 2025): As per comments in the PR regarding MD060 compatibility: > rules typically work independently, so this strategy may need more thinking My initial thoughts on this are: ## Option 0: do nothing Leave the rule as-is without a fix ## Option 1: Add/remove pipes (and whitespace) naively (as per PR) Apply initial suggested logic. Pros: - simpler code - maintains rule independence Cons: - add leading: - right shifts all row content by 1 likely causing `MD060` error when `aligned` (or `aligned_delimiter`) - conformance with `tight` or `compact` configuration for `MD060` would depend on leading spaces already in the cell content - add-trailing: - conformance with `tight` or `compact` configuration for `MD060` would depend on trailing spaces in the cell content (and `MD009`) - would likely cause `MD060` errors with `aligned` (or `aligned_delimiter`) especially if fixing multiple rows of different content length - remove leading (including whitespace) - left shifts all row content by 1 likely causing `MD060` error if `aligned` or `aligned_delimiter` Neutral: - remove leading and trailing (including whitespace) would be compatible with `MD060` `compact` and `tight` **Implication**: the user (or an fix for `MD060`) would need to take care of the alignment ## Option 2: add an explicit parameter Add parameters to the rule (e.g. `fix_style`, with values matching `MD060`'s `style` parameter) to allow the user to set the behaviour. Pros: - avoids the complexity of detecting required behaviour - explicit user choice - would only cause conflict with `MD060` if the user chose that behaviour Cons: - to support `any` or `aligned_delimiter` would require more significant refactoring as `MD055` is not currently "table aware" as it acts on rows independently (except for first header row when using `consistent`) - Creates implicit coupling between `MD055` and `MD060` requiring the settings to be kept in sync ## Option 3: apply spacing "consistently" with first table header Apply the same approach to spaces as is currently done with `consistent` (default) configuration for pipe presence/absence. Pros: - avoids added complexity of detecting format for each table - provides compatibility with `compact` and `tight` configuration of `MD060` Cons: - would not guarantee compatibility with `aligned` (or `aligned_delimiter`) configuration of `MD060` (as option 1) - would not guarantee compatibility with `any` configuration of `MD060` **Implication**: the user (or an fix for `MD060`) would need to take care of the alignment for unsupported scenarios ## Option 4: apply spacing based on detection for each table Use space around non-leading/trailing pipes to infer `MD060` preference. Pros: - maximum compatibility with MD060 without direct coupling Cons: - would need to duplicate significant amounts of the logic in `MD060` - would make the rule "table aware" adding complexity that only adds value on `fix` - what is present in the markdown may not reflect the user configuration of `MD060` **Implication**: the user (or an fix for `MD060`) would need to take care of the alignment for unsupported scenarios ## Option 5: explicit coupling with `MD060` (included for completeness) Pass the configuration for `MD060` into `MD055` Pros: as option 2 Cons: - breaks the independence rule - deviates from the current configuration passing approach

kerem commented

2026-03-03 01:29:47 +03:00

Author

Owner

@DavidAnson commented on GitHub (Dec 29, 2025):

This is incredibly thorough, thank you! Without having thought much about this myself yet, aspects of each of 2/3/4/5 concern me. Of those, 3/4 seem the most attractive at the moment (for 4, a bit of refactoring would allow sharing the common code). But I worry about what happens to someone who applies both rules to a new table - I want to avoid a situation where they recommend conflicting and/or infinite looping "fixes".

That said, there are two parts to option 1 and they can be done separately. Specifically, although ADDING pipes is potentially ambiguous, REMOVING them seems deterministic. When removing a leading or trailing pipe, that pipe and all whitespace "inside" the cell can be removed - for every table style. You point out this may cause an error by breaking column alignment which is valid. But for a scenario where a table starts consistent, I'd expect all rows to be adjusted similarly such that overall alignment does not change. This may need some experimentation to confirm.

So this may be a starting point. It's not mandatory that fixable rules fix ALL scenarios - it could be that this rule only fixes removal scenarios if that's all we feel confident about.

@DavidAnson commented on GitHub (Dec 29, 2025): This is incredibly thorough, thank you! Without having thought much about this myself yet, aspects of each of 2/3/4/5 concern me. Of those, 3/4 seem the most attractive at the moment (for 4, a bit of refactoring would allow sharing the common code). But I worry about what happens to someone who applies both rules to a new table - I want to avoid a situation where they recommend conflicting and/or infinite looping "fixes". That said, there are two parts to option 1 and they can be done separately. Specifically, although ADDING pipes is potentially ambiguous, REMOVING them seems deterministic. When removing a leading or trailing pipe, that pipe and all whitespace "inside" the cell can be removed - for every table style. You point out this may cause an error by breaking column alignment which is valid. But for a scenario where a table starts consistent, I'd expect all rows to be adjusted similarly such that overall alignment does not change. This may need some experimentation to confirm. So this may be a starting point. It's not mandatory that fixable rules fix ALL scenarios - it could be that this rule only fixes removal scenarios if that's all we feel confident about.

kerem commented

2026-03-03 01:29:47 +03:00

Author

Owner

@non-zero-sum commented on GitHub (Jan 6, 2026):

I want to avoid a situation where they recommend conflicting and/or infinite looping "fixes".

To avoid clashes I would suggest:

MD060 fixes should be constrained to just adding/removing whitespace and never pipes
MD055 fixes should only add/remove whitespace when it is done alongside pipe addition/deletion

this would mean at worst

MD055 -> MD060
1. MD055 adds or removes a pipe and whitespace shifting table dividers in a way that isn't aligned to the users settings for MD060
2. MD060 fixes add/remove whitespace
MD060 -> MD055
1. MD060 adds/removes whitespace to achieve the users preference
2. scenario `MD055 -. MD0601 occurs, but cannot repeat

@non-zero-sum commented on GitHub (Jan 6, 2026): > I want to avoid a situation where they recommend conflicting and/or infinite looping "fixes". To avoid clashes I would suggest: - MD060 fixes should be constrained to just adding/removing whitespace and never pipes - MD055 fixes should only add/remove whitespace when it is done alongside pipe addition/deletion this would mean at worst - `MD055 -> MD060` 1. MD055 adds or removes a pipe and whitespace shifting table dividers in a way that isn't aligned to the users settings for MD060 2. MD060 fixes add/remove whitespace - `MD060 -> MD055` 1. MD060 adds/removes whitespace to achieve the users preference 2. scenario `MD055 -. MD0601 occurs, but cannot repeat

kerem commented

2026-03-03 01:29:47 +03:00

Author

Owner

@non-zero-sum commented on GitHub (Jan 6, 2026):

But for a scenario where a table starts consistent, I'd expect all rows to be adjusted similarly such that overall alignment does not change. This may need some experimentation to confirm.

So this may be a starting point. It's not mandatory that fixable rules fix ALL scenarios

The only scenario I can think of where this wouldn't be the case is MD060 aligned with non left-aligned cells.

@non-zero-sum commented on GitHub (Jan 6, 2026): > But for a scenario where a table starts consistent, I'd expect all rows to be adjusted similarly such that overall alignment does not change. This may need some experimentation to confirm. > > So this may be a starting point. It's not mandatory that fixable rules fix ALL scenarios The only scenario I can think of where this wouldn't be the case is MD060 `aligned` with non left-aligned cells.

kerem referenced this issue

2026-03-03 02:01:28 +03:00

[PR #772] [MERGED] Bump eslint-plugin-jsdoc from 40.3.0 to 41.1.1 #1007

kerem referenced this issue

2026-03-07 20:10:55 +03:00

[PR #772] [MERGED] Bump eslint-plugin-jsdoc from 40.3.0 to 41.1.1 #2852