Change Request: Fix or remove code examples that require tabs

[fasttime]

ESLint version

v8.51.0

What problem do you want to solve?

Some of our formatting rules have code examples that would have to contain tab characters in order to show the intended behavior. These code examples are currently messed up and it is not possible to fix them because Markdownlint forbids tabs and replaces them automatically with whitespaces in the lint-staged commit hook. The rules affected are at least:

• indent with option tab
• indent-legacy with option tab
• max-len with option tabWidth
• no-mixed-spaces-and-tabs
• no-tabs

Out of those, indent and indent-legacy are using a mix of whitespaces and comments like /*tab*/ to indicate a position where a tab is expected. max-len and no-tabs are using the sequence \t which is a syntax error outside of literals. no-mixed-spaces-and-tabs has whitespaces with explanatory comments on top. None of these workarounds behaves well in the Playground.

What do you think is the correct solution?

I don't think we want to allow tabs in Markdown files, and the problematic rules are all going to be deprecated (indent-legacy is already), so the simplest approach would be removing the code examples that cannot work because tabs are not available.

Alternatively we could selectively disable the Markdownlint rule that forbids tabs (MD010/no-hard-tabs) for some code examples, so we could put real tabs into them.

Or we could keep the broken code examples, declare them pseudocode, and remove the :::correct/:::incorrect fences. This would remove the "Open in Playground" buttons and exempt the code blocks from validation when we will start to validate code examples.

There are clearly other ways to address this, and there are possibly aspects I haven't considered, so I would like to hear what the team suggests.

Participation

• I am willing to submit a pull request for this change.

Additional comments

No response

[mdjermanovic]

Maybe we could represent tabs with something like <TAB> and replace it with real tabs in the code we're passing to the playground?

[fasttime]

Good idea, but a search for <TAB> finds this:

eslint/docs/src/rules/no-control-regex.md

Line 70 in 68f1288

new RegExp("\t"); // disallowed since the pattern is: <TAB>

So maybe better something like <<TAB>>, [TAB], <HT>, etc. ?

[nzakas]

If the concern is just what happens when opened in the playground, we could also add an option that hides the "Open in Playground" button.

[mdjermanovic]

I think it's good to have a consistent visual presentation of tabs (e.g., <<TAB>>) in our documentation anyways, and with that it looks simple to replace it with real tab characters in the code we're passing to the playground.

[nzakas]

Okay, I don't feel strongly about this, so happy to defer to what you're thinking.

[JoshuaKGoldberg]

it is not possible to fix them because Markdownlint forbids tabs and replaces them automatically with whitespaces in the lint-staged commit hook

Err, what about ignoring with <!-- markdownlint-disable --> or similar? https://github.com/DavidAnson/markdownlint#configuration

Edit: just to be clear, this is what @fasttime proposed in the OP 😄 I was confused why it wasn't being considered.

[fasttime]

Err, what about ignoring with <!-- markdownlint-disable --> or similar? https://github.com/DavidAnson/markdownlint#configuration

That's what I had in mind when I suggested to selectively disable MD010/no-hard-tabs for some of the code examples, but there seems to be an argument that <<TAB>> in place of a tab character would provide a more consistent visual presentation?

[fasttime]

Thanks everybody for sharing your ideas. I have drafted a PR to show on different pages how things would look like after each of the suggested solutions, hopefully this will help us to better evaluate the results and take a decision.

• no-tabs uses an option to remove "Open in Playground" buttons, as originally indicated by @nzakas.
• no-mixed-spaces-and-tabs uses <<TAB>> to represent tab characters, suggested by @mdjermanovic.
• max-len with option tabWidth uses <!-- markdownlint-disable --> comments to allow tabs in code blocks as per @JoshuaKGoldberg's suggestion.

Opinions?

[nzakas]

Thanks for putting those together! I'm definitely not a fan of the <<TAB>> approach, and it seems like the markdown-disable ones gives us everything we need, so I think that's my favorite.

[mdjermanovic]

I'm in favor of visible characters as, in my opinion, examples would look better on the docs site, and there would be no problems with formatting markdown files. If <<TAB>> doesn't look good, then maybe a right arrow character. The examples we have with ⏎ look nice to me.

Though, if others are strongly in favor of <!-- markdownlint-disable -->, I'm fine with that approach too.

[fasttime]

I'm in favor of visible characters as, in my opinion, examples would look better on the docs site, and there would be no problems with formatting markdown files. If <<TAB>> doesn't look good, then maybe a right arrow character. The examples we have with ⏎ look nice to me.

@mdjermanovic Can you show an example of a line with a right arrow character so I can update the PR?

[nzakas]

@mdjermanovic keep in mind that all of the rules where this matters will be deprecated, so I'm less concerned about them than I would otherwise.

[mdjermanovic]

I'm fine with the <!-- markdownlint-disable --> approach.

Just for reference, I was thinking about something like this:

function add(x, y) {
➝return x + y;
}

Examples with different arrows and horizontal tabulation symbol

[fasttime]

It looks like there's agreement on using tab characters with <!-- markdownlint-disable --> comments. I have updated PR #17653 to use this approach. This change will also fix the last syntax errors left in our rule examples.