Suggestion: add a quick-link that allows you to open a rule in the playground

[JoshuaKGoldberg]

What problem do you want to solve?

It'd be nice to have a quick way to jump from a rule's docs page to trying the rule out in the playground. For example, on https://eslint.org/docs/latest/rules/require-unicode-regexp, it'd be nice to have a quick way to jump to a playground enabling the rule.

What do you think is the correct solution?

How about a Try this rule in the playground ↗ link in each rule page linking to the playground with the rule enabled in the config?

For reference, we added this to typescript-eslint.io in typescript-eslint/typescript-eslint#6085 -> typescript-eslint/typescript-eslint#6317.

Participation

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

Additional comments

I would love to implement this if accepted! 😄

[Rec0iL99]

Hi @JoshuaKGoldberg, would love for this to be implemented in the docs. Would be super helpful!

Do you think we need to generate a playground link for each option of the rule or just for the basic configuration of the rule for the user to get started with? For example, the indent rule has different options for the user to use.

[JoshuaKGoldberg]

An individual link for each option would be awesome, but a bit more work. The rules or their docs pages would have to have some kind of metadata for each of the options to indicate what a good setting for each option would be. So I'd propose just starting with the base rule, and treating the options as a followup issue. How does that sound to you?

[harish-sethuraman]

That would be great to have quick links to try out rules in playgrounds. Would the rules be added via query params? while opening in playground? cc: @eslint/eslint-tsc need suggestions on this feature implementation.

[Rec0iL99]

An individual link for each option would be awesome, but a bit more work. The rules or their docs pages would have to have some kind of metadata for each of the options to indicate what a good setting for each option would be. So I'd propose just starting with the base rule, and treating the options as a followup issue. How does that sound to you?

That sounds reasonable to me 👍

[nzakas]

I like the idea. In order to move forward we would first need a design to evaluate. We actually did start out with a button "Open in Playground" on code samples, which is still commented out in the code:

eslint/docs/src/assets/js/main.js

Line 195 in a8d0a57

// add "Open in Playground" button to code blocks

The problem was that it didn't distinguish between rule code samples and others, so we just removed it. If we want to revive that we'd need to solve that problem.

Because you can use inline comments to configure options, all we really need to do is encode the text in a code sample to a playground URL.

(Moved this to the eslint repo, because this has to do with the documentation site and not the primary website.)

[JoshuaKGoldberg]

design to evaluate

How about floating to the right of the h1 on desktop, and below the rule categories on mobile?

Desktop	Mobile

I am not a designer 😄

[nzakas]

I just wonder if the "Open in Playground" on the examples is a better approach than a link at the top?

[JoshuaKGoldberg]

Ah, +1 to having the "Open in Playground" on the examples. I think I'd misinterpreted your comment on why it was removed.

distinguish between rule code samples and others

Do you have examples of what you mean by each? As in, what would a code block that you wouldn't want opened in the playground look like?

[nzakas]

Do you have examples of what you mean by each? As in, what would a code block that you wouldn't want opened in the playground look like?

Literally any code block on any page other than rule pages. :)

[harish-sethuraman]

Are we going to add these Open in Playground button to all codeblocks? or only on some(first) codeblocks? I feel like it would be good if we add this near the rule's heading 😅 .

[amareshsm]

Do you have examples of what you mean by each? As in, what would a code block that you wouldn't want opened in the playground look like?

Literally any code block on any page other than rule pages. :)

If we are going to add open in playground link to code samples then do we need a mini playground ?#16227 (comment)

[sam3k]

This is a really nice addition to the already great rules docs!

[JoshuaKGoldberg]

Literally any code block on any page other than rule pages. :)

Oh, great, my interpretation then is that all code blocks on rule pages are good to go for this. Can do!

If we are going to add open in playground link to code samples then do we need a mini playground ?#16227 (comment)

I'd suggest including both. A mini playground on the page isn't the same full experience as a shareable playground. Both are nice conveniences with overlapping but different sets of purposes IMO.

[nzakas]

Are we going to add these Open in Playground button to all codeblocks? or only on some(first) codeblocks? I feel like it would be good if we add this near the rule's heading 😅 .

@harish-sethuraman Sorry, I'm not sure what this means. Are you saying add a codeblock near the heading?

I don't think adding a button near the heading like @JoshuaKGoldberg suggested makes much sense, either design-wise (there's not enough room) or usability wise (not enough context).

If we are going to add open in playground link to code samples then do we need a mini playground ?#16227 (comment)

@amareshsm Definitely not. This would just link out to the current playground. At some point it would be great to have a mini playground; this button was seen as a stepping stone in that direction. The idea was to create a web component that anyone could use, but we just haven't been able to prioritize that work.

[sam3k]

Maybe this is something that can discuss in the next TSC meeting? Adding the label.

[nzakas]

@sam3k This discussion hasn't stalled out, so it's too early to add to the TSC meeting.

Also, when flagging something for the TSC meeting, please provide the TSC Summary summarizing the issue and explaining where conversation stalled, and also the TSC Question, which is what the TSC should decide. See: https://eslint.org/docs/latest/maintain/manage-issues#when-to-send-to-tsc

[sam3k]

That makes sense. Will do moving forward.

[mdjermanovic]

I agree it would be best to have an "Open in Playground" link on all correct and incorrect examples in rule docs. With that, I don't think we need an extra link at the top.

Those code blocks are already wrapped in ::: incorrect and ::: correct containers, which render as <div class="incorrect"> and <div class="correct"> so perhaps we could use that to locate them on the page. Or maybe add the links in build time.

[mdjermanovic]

Because you can use inline comments to configure options, all we really need to do is encode the text in a code sample to a playground URL.

We might still need some metadata. For instance, examples for no-restricted-imports need sourceType: "module", while this example for no-implicit-globals needs sourceType: "script" (it wouldn't be incorrect with sourceType: "module"):

eslint/docs/src/rules/no-implicit-globals.md

Lines 45 to 57 in d85efad

	Examples of **incorrect** code for this rule:
	::: incorrect
	```js
	/*eslint no-implicit-globals: "error"*/
	var foo = 1;
	function bar() {}
	```
	:::

[github-actions]

Oops! It looks like we lost track of this issue. What do we want to do here? This issue will auto-close in 7 days without an update.

[Rec0iL99]

Folks, looks like the discussion stalled a bit. How do we move forward here?

cc @eslint/eslint-team

[amareshsm]

Since most people like the idea and I also think the same it would be great if we have a link to open a rule in the playground. We can try it out and see. @mdjermanovic thoughts?

[mdjermanovic]

Since most people like the idea and I also think the same it would be great if we have a link to open a rule in the playground. We can try it out and see. @mdjermanovic thoughts?

I'm in favor of adding an "Open in Playground" button to code blocks that represent correct and incorrect examples for rules.

[amareshsm]

Conclusion: we can add an "open in playground" button to correct/incorrect code examples. @JoshuaKGoldberg would you like to start working on this?

[JoshuaKGoldberg]

Yes, I'd love to - thanks!

Very cool to see the open discussion in the thread here. If & when this lands, I'll try to bring it up with the other folks at typescript-eslint to see if we want to follow suit.

[mdjermanovic]

Implemented in #17306