docs: add playground links to correct and incorrect code blocks (#17306)

* docs: add playground links to correct and incorrect code blocks * Added info options and used existing styles * Switch options to parserOptions * Use context-based prefix for playground URLs * Tweaked styles for more padding, and overlaid vertically in thin screens * Reset md files to main * Removed icon and increased bottom padding
eslint · Jul 14, 2023 · 89f3225 · 89f3225
1 parent f8892b5
commit 89f3225
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 53 deletions.
diff --git a/docs/.eleventy.js b/docs/.eleventy.js
@@ -179,14 +179,63 @@ module.exports = function(eleventyConfig) {
         `.trim();
     }
 
+    /**
+     * Encodes text in the base 64 format used in playground URL params.
+     * @param {string} text Text to be encoded to base 64.
+     * @see https://github.com/eslint/eslint.org/blob/1b2f2aabeac2955a076d61788da8a0008bca6fb6/src/playground/utils/unicode.js
+     * @returns {string} The base 64 encoded equivalent of the text.
+     */
+    function encodeToBase64(text) {
+        /* global btoa -- It does exist, and is what the playground uses. */
+        return btoa(unescape(encodeURIComponent(text)));
+    }
+
+    /**
+     * Creates markdownItContainer settings for a playground-linked codeblock.
+     * @param {string} name Plugin name and class name to add to the code block.
+     * @returns {[string, object]} Plugin name and options for markdown-it.
+     */
+    function withPlaygroundRender(name) {
+        return [
+            name,
+            {
+                render(tokens, index) {
+                    if (tokens[index].nesting !== 1) {
+                        return "</div>";
+                    }
+
+                    // See https://github.com/eslint/eslint.org/blob/ac38ab41f99b89a8798d374f74e2cce01171be8b/src/playground/App.js#L44
+                    const parserOptions = tokens[index].info?.split("correct ")[1]?.trim();
+                    const { content } = tokens[index + 1];
+                    const state = encodeToBase64(
+                        JSON.stringify({
+                            ...(parserOptions && { options: { parserOptions: JSON.parse(parserOptions) } }),
+                            text: content
+                        })
+                    );
+                    const prefix = process.env.CONTEXT && process.env.CONTEXT !== "deploy-preview"
+                        ? ""
+                        : "https://eslint.org";
+
+                    return `
+                        <div class="${name}">
+                            <a class="c-btn c-btn--secondary c-btn--playground" href="${prefix}/play#${state}" target="_blank">
+                                Open in Playground
+                            </a>
+                    `.trim();
+                }
+            }
+        ];
+    }
+
     const markdownIt = require("markdown-it");
     const md = markdownIt({ html: true, linkify: true, typographer: true, highlight: (str, lang) => highlighter(md, str, lang) })
         .use(markdownItAnchor, {
             slugify: s => slug(s)
         })
         .use(markdownItContainer, "img-container", {})
-        .use(markdownItContainer, "correct", {})
-        .use(markdownItContainer, "incorrect", {})
+        .use(markdownItContainer, ...withPlaygroundRender("correct"))
+        .use(markdownItContainer, ...withPlaygroundRender("incorrect"))
         .use(markdownItContainer, "warning", {
             render(tokens, idx) {
                 return generateAlertMarkup("warning", tokens, idx);

diff --git a/docs/src/assets/js/main.js b/docs/src/assets/js/main.js
@@ -192,24 +192,6 @@
     }
 })();
 
-// add "Open in Playground" button to code blocks
-// (function() {
-//     let blocks = document.querySelectorAll('pre[class*="language-"]');
-//     if (blocks) {
-//         blocks.forEach(function(block) {
-//             let button = document.createElement("a");
-//             button.classList.add('c-btn--playground');
-//             button.classList.add('c-btn');
-//             button.classList.add('c-btn--secondary');
-//             button.setAttribute("href", "#");
-//             button.innerText = "Open in Playground";
-//             block.appendChild(button);
-//         });
-//     }
-// })();
-
-
-
 // add utilities
 var util = {
     keyCodes: {

diff --git a/docs/src/assets/scss/docs.scss b/docs/src/assets/scss/docs.scss
@@ -142,13 +142,14 @@ pre[class*="language-"] {
 .c-btn.c-btn--playground {
     position: absolute;
     font-size: var(--step--1);
-    bottom: 0.5rem;
-    right: 0.5rem;
+    bottom: -1rem;
+    right: 1rem;
     offset-block-end: 0.5rem;
     offset-inline-end: 0.5rem;
+    z-index: 1;
 
-    @media all and (max-width: 768px) {
-        display: none;
+    @media all and (min-width: 768px) {
+        bottom: 1.5rem;
     }
 }
 

diff --git a/docs/src/rules/no-implicit-globals.md b/docs/src/rules/no-implicit-globals.md
@@ -44,7 +44,7 @@ This rule disallows `var` and `function` declarations at the top-level script sc
 
 Examples of **incorrect** code for this rule:
 
-::: incorrect
+::: incorrect { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: "error"*/
@@ -58,7 +58,7 @@ function bar() {}
 
 Examples of **correct** code for this rule:
 
-::: correct
+::: correct { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: "error"*/
@@ -79,7 +79,7 @@ window.bar = function() {};
 
 Examples of **correct** code for this rule with `"parserOptions": { "sourceType": "module" }` in the ESLint configuration:
 
-::: correct
+::: correct { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: "error"*/
@@ -100,7 +100,7 @@ This does not apply to ES modules since the module code is implicitly in `strict
 
 Examples of **incorrect** code for this rule:
 
-::: incorrect
+::: incorrect { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: "error"*/
@@ -127,7 +127,7 @@ or in a `/*global */` comment.
 
 Examples of **incorrect** code for this rule:
 
-::: incorrect
+::: incorrect { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: "error"*/
@@ -155,7 +155,7 @@ If the variable is intended to be local to the script, wrap the code with a bloc
 
 Examples of **correct** code for this rule with `"lexicalBindings"` option set to `false` (default):
 
-::: correct
+::: correct { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: ["error", {"lexicalBindings": false}]*/
@@ -171,7 +171,7 @@ class Bar {}
 
 Examples of **incorrect** code for this rule with `"lexicalBindings"` option set to `true`:
 
-::: incorrect
+::: incorrect { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/
@@ -187,7 +187,7 @@ class Bar {}
 
 Examples of **correct** code for this rule with `"lexicalBindings"` option set to `true`:
 
-::: correct
+::: correct { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/
@@ -221,7 +221,7 @@ Even the `typeof` check is not safe from TDZ reference exceptions.
 
 Examples of **incorrect** code for this rule with `"lexicalBindings"` option set to `true`:
 
-::: incorrect
+::: incorrect { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/
@@ -239,7 +239,7 @@ const MyGlobalFunction = (function() {
 
 Examples of **correct** code for this rule with `"lexicalBindings"` option set to `true`:
 
-::: correct
+::: correct { "sourceType": "script" }
 
 ```js
 /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/
@@ -261,7 +261,7 @@ You can use `/* exported variableName */` block comments in the same way as in [
 
 Examples of **correct** code for `/* exported variableName */` operation:
 
-::: correct
+::: correct { "sourceType": "script" }
 
 ```js
 /* exported global_var */

diff --git a/docs/src/rules/no-restricted-imports.md b/docs/src/rules/no-restricted-imports.md
@@ -130,7 +130,7 @@ To restrict the use of all Node.js core imports (via <https://github.com/nodejs/
 
 Examples of **incorrect** code for this rule:
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", "fs"]*/
@@ -140,7 +140,7 @@ import fs from 'fs';
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", "fs"]*/
@@ -150,7 +150,7 @@ export { fs } from 'fs';
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", "fs"]*/
@@ -160,7 +160,7 @@ export * from 'fs';
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { "paths": ["cluster"] }]*/
@@ -170,7 +170,7 @@ import cluster from 'cluster';
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { "patterns": ["lodash/*"] }]*/
@@ -180,7 +180,7 @@ import pick from 'lodash/pick';
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { paths: [{
@@ -194,7 +194,7 @@ import DisallowedObject from "foo";
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { paths: [{
@@ -212,7 +212,7 @@ import { "DisallowedObject" as AllowedObject } from "foo";
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { paths: [{
@@ -226,7 +226,7 @@ import * as Foo from "foo";
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { patterns: [{
@@ -239,7 +239,7 @@ import pick from 'lodash/pick';
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { patterns: [{
@@ -252,7 +252,7 @@ import pick from 'fooBar';
 
 :::
 
-::: incorrect
+::: incorrect { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { patterns: [{
@@ -268,7 +268,7 @@ import { isEmpty } from 'utils/collection-utils';
 
 Examples of **correct** code for this rule:
 
-::: correct
+::: correct { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", "fs"]*/
@@ -279,7 +279,7 @@ export { foo } from "bar";
 
 :::
 
-::: correct
+::: correct { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { "paths": ["fs"], "patterns": ["eslint/*"] }]*/
@@ -291,7 +291,7 @@ export * from "path";
 
 :::
 
-::: correct
+::: correct { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { paths: [{ name: "foo", importNames: ["DisallowedObject"] }] }]*/
@@ -301,7 +301,7 @@ import DisallowedObject from "foo"
 
 :::
 
-::: correct
+::: correct { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { paths: [{
@@ -315,7 +315,7 @@ import { AllowedObject as DisallowedObject } from "foo";
 
 :::
 
-::: correct
+::: correct { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { patterns: [{
@@ -328,7 +328,7 @@ import lodash from 'lodash';
 
 :::
 
-::: correct
+::: correct { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { patterns: [{
@@ -341,7 +341,7 @@ import pick from 'food';
 
 :::
 
-::: correct
+::: correct { "sourceType": "module" }
 
 ```js
 /*eslint no-restricted-imports: ["error", { patterns: [{