From cddad1495fbc1750c26330f7aadc6647e2eebac3 Mon Sep 17 00:00:00 2001 From: "Nicholas C. Zakas" Date: Tue, 14 Jun 2022 15:14:06 -0700 Subject: [PATCH] docs: Add correct/incorrect containers (#15998) --- docs/.eleventy.js | 12 ++++++------ docs/package.json | 1 + docs/src/assets/scss/docs.scss | 8 ++++---- docs/src/library/code-blocks.md | 20 ++++++++++---------- docs/src/rules/semi.md | 28 ++++++++++++++++++++++++++++ 5 files changed, 49 insertions(+), 20 deletions(-) diff --git a/docs/.eleventy.js b/docs/.eleventy.js index 9652d84ebcc..87416ff3cc5 100644 --- a/docs/.eleventy.js +++ b/docs/.eleventy.js @@ -6,6 +6,7 @@ const pluginRss = require("@11ty/eleventy-plugin-rss"); const pluginTOC = require("eleventy-plugin-nesting-toc"); const slugify = require("slugify"); const markdownItAnchor = require("markdown-it-anchor"); +const markdownItContainer = require("markdown-it-container"); const Image = require("@11ty/eleventy-img"); const path = require("path"); @@ -141,12 +142,11 @@ module.exports = function(eleventyConfig) { const markdownIt = require("markdown-it"); eleventyConfig.setLibrary("md", - markdownIt({ - html: true, - linkify: true, - typographer: true - - }).use(markdownItAnchor, {}).disable("code")); + markdownIt({ html: true, linkify: true, typographer: true }) + .use(markdownItAnchor, {}) + .use(markdownItContainer, "correct", {}) + .use(markdownItContainer, "incorrect", {}) + .disable("code")); //------------------------------------------------------------------------------ // Shortcodes diff --git a/docs/package.json b/docs/package.json index a42c33aa68f..85ce93cb40e 100644 --- a/docs/package.json +++ b/docs/package.json @@ -33,6 +33,7 @@ "luxon": "^2.4.0", "markdown-it": "^12.2.0", "markdown-it-anchor": "^8.1.2", + "markdown-it-container": "^3.0.0", "netlify-cli": "^10.3.1", "npm-run-all": "^4.1.5", "rimraf": "^3.0.2", diff --git a/docs/src/assets/scss/docs.scss b/docs/src/assets/scss/docs.scss index eef51609b60..23ffec3e582 100644 --- a/docs/src/assets/scss/docs.scss +++ b/docs/src/assets/scss/docs.scss @@ -102,8 +102,8 @@ margin: 3rem 0; } -div[data-correct-code], -div[data-incorrect-code] { +div.correct, +div.incorrect { position: relative; &::after { @@ -115,13 +115,13 @@ div[data-incorrect-code] { } } -div[data-correct-code] { +div.correct { &::after { content: url("data:image/svg+xml,%3Csvg width='45' height='44' viewBox='0 0 45 44' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Crect x='1.5' y='1' width='42' height='42' rx='21' fill='%23ECFDF3'/%3E%3Cpath d='M30.5 16L19.5 27L14.5 22' stroke='%2312B76A' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3Crect x='1.5' y='1' width='42' height='42' rx='21' stroke='white' stroke-width='2'/%3E%3C/svg%3E%0A"); } } -div[data-incorrect-code] { +div.incorrect { &::after { content: url("data:image/svg+xml,%3Csvg width='45' height='44' viewBox='0 0 45 44' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Crect x='1.5' y='1' width='42' height='42' rx='21' fill='%23FFF1F3'/%3E%3Cpath d='M28.5 16L16.5 28M16.5 16L28.5 28' stroke='%23F63D68' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3Crect x='1.5' y='1' width='42' height='42' rx='21' stroke='white' stroke-width='2'/%3E%3C/svg%3E%0A"); } diff --git a/docs/src/library/code-blocks.md b/docs/src/library/code-blocks.md index 7db4d1ccfa6..222d3e68519 100644 --- a/docs/src/library/code-blocks.md +++ b/docs/src/library/code-blocks.md @@ -6,35 +6,35 @@ To indicate correct and incorrect code usage, some code blocks can have correct ## Usage -To indicate that a code block is correct or incorrect, wrap the code block in a `div` and provide the `data-correct-code` and `data-incorrect-code` attributes, repsectively. +To indicate that a code block is correct or incorrect, wrap the code block in a container labeled either `correct` or `incorrect`. Make sure to leave space above and below the markdown code block to ensure it is rendered correctly. -```html -
+```text +::: correct `` `js function() { const another = []; } `` ` -
+::: -
+::: incorrect `` `js function() { const another = []; } `` ` -
+::: ``` ## Examples Correct usage: -
+::: correct ```js const { ESLint } = require("eslint"); @@ -61,11 +61,11 @@ const { ESLint } = require("eslint"); }); ``` -
+::: Incorrect usage: -
+::: incorrect ```js const { ESLint } = require("eslint"); @@ -92,4 +92,4 @@ const { ESLint } = require("eslint"); }); ``` -
+::: diff --git a/docs/src/rules/semi.md b/docs/src/rules/semi.md index 10147935769..7b0cca31a92 100644 --- a/docs/src/rules/semi.md +++ b/docs/src/rules/semi.md @@ -98,6 +98,8 @@ Object option (when `"never"`): Examples of **incorrect** code for this rule with the default `"always"` option: +::: incorrect + ```js /*eslint semi: ["error", "always"]*/ @@ -112,8 +114,12 @@ class Foo { } ``` +::: + Examples of **correct** code for this rule with the default `"always"` option: +::: correct + ```js /*eslint semi: "error"*/ @@ -128,10 +134,14 @@ class Foo { } ``` +::: + ### never Examples of **incorrect** code for this rule with the `"never"` option: +::: incorrect + ```js /*eslint semi: ["error", "never"]*/ @@ -146,8 +156,12 @@ class Foo { } ``` +::: + Examples of **correct** code for this rule with the `"never"` option: +::: correct + ```js /*eslint semi: ["error", "never"]*/ @@ -178,10 +192,14 @@ class Foo { } ``` +::: + #### omitLastInOneLineBlock Examples of additional **correct** code for this rule with the `"always", { "omitLastInOneLineBlock": true }` options: +::: correct + ```js /*eslint semi: ["error", "always", { "omitLastInOneLineBlock": true}] */ @@ -198,10 +216,14 @@ class C { } ``` +::: + #### beforeStatementContinuationChars Examples of additional **incorrect** code for this rule with the `"never", { "beforeStatementContinuationChars": "always" }` options: +::: incorrect + ```js /*eslint semi: ["error", "never", { "beforeStatementContinuationChars": "always"}] */ import a from "a" @@ -211,8 +233,12 @@ import a from "a" })() ``` +::: + Examples of additional **incorrect** code for this rule with the `"never", { "beforeStatementContinuationChars": "never" }` options: +::: incorrect + ```js /*eslint semi: ["error", "never", { "beforeStatementContinuationChars": "never"}] */ import a from "a" @@ -222,6 +248,8 @@ import a from "a" })() ``` +::: + ## When Not To Use It If you do not want to enforce semicolon usage (or omission) in any particular way, then you can turn this rule off.