docs: use custom diff code blocks (#5099)

typescript-eslint · Jun 10, 2022 · 331ff3b · 331ff3b
1 parent cb2d446
commit 331ff3b
Show file tree

Hide file tree

Showing 10 changed files with 344 additions and 80 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -73,8 +73,10 @@
     "linebreaks",
     "lzstring",
     "markdownlint",
+    "metastring",
     "necroing",
     "nocheck",
+    "noninteractive",
     "nullish",
     "OOM",
     "OOMs",

diff --git a/docs/linting/MONOREPO.md b/docs/linting/MONOREPO.md
@@ -18,22 +18,24 @@ Earlier in our docs on [typed linting](./TYPED_LINTING.md), we showed you how to
 
 For example, this is how we specify all of our `tsconfig.json` within this repo.
 
-```diff title=".eslintrc.js"
- module.exports = {
-   root: true,
-   parser: '@typescript-eslint/parser',
-   parserOptions: {
-     tsconfigRootDir: __dirname,
--    project: ['./tsconfig.json'],
-+    project: ['./tsconfig.eslint.json', './packages/*/tsconfig.json'],
-   },
-   plugins: ['@typescript-eslint'],
-   extends: [
-     'eslint:recommended',
-     'plugin:@typescript-eslint/recommended',
-     'plugin:@typescript-eslint/recommended-requiring-type-checking',
-   ],
- };
+```js title=".eslintrc.js"
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    // Remove this line
+    project: ['./tsconfig.json'],
+    // Add this line
+    project: ['./tsconfig.eslint.json', './packages/*/tsconfig.json'],
+  },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+  ],
+};
 ```
 
 If you're looking for an example of what the `.eslintrc.js`, and referenced `tsconfig.json` might look like in a real example, look no further than this very repo. We're a multi-package monorepo that uses one `tsconfig.json` per package, that also uses typed linting.

diff --git a/docs/linting/README.md b/docs/linting/README.md
@@ -136,19 +136,18 @@ If you use [`prettier`](https://www.npmjs.com/package/prettier), there is also a
 
 Using this config by adding it to the end of your `extends`:
 
-```diff title=".eslintrc.js"
-  module.exports = {
-    root: true,
-    parser: '@typescript-eslint/parser',
-    plugins: [
-      '@typescript-eslint',
-    ],
-    extends: [
-      'eslint:recommended',
-      'plugin:@typescript-eslint/recommended',
-+     'prettier',
-    ],
-  };
+```js title=".eslintrc.js"
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    // Add this line
+    'prettier',
+  ],
+};
 ```
 
 ### Community Configs
@@ -163,19 +162,20 @@ A few popular all-in-one configs are:
 To use one of these complete config packages, you would replace the `extends` with the package name.
 For example:
 
-```diff title=".eslintrc.js"
-  module.exports = {
-    root: true,
-    parser: '@typescript-eslint/parser',
-    plugins: [
-      '@typescript-eslint',
-    ],
-    extends: [
--     'eslint:recommended',
--     'plugin:@typescript-eslint/recommended',
-+     'airbnb-typescript',
-    ],
-  };
+```js title=".eslintrc.js"
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  extends: [
+    // Removed lines start
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    // Removed lines end
+    // Add this line
+    'airbnb-typescript',
+  ],
+};
 ```
 
 <!-- markdownlint-disable MD044 -->
@@ -196,20 +196,22 @@ Below are just a few examples:
 Every plugin that is out there includes documentation on the various configurations and rules they offer.
 A typical plugin might be used like:
 
-```diff title=".eslintrc.js"
-  module.exports = {
-    root: true,
-    parser: '@typescript-eslint/parser',
-    plugins: [
-      '@typescript-eslint',
-+     'jest',
-    ],
-    extends: [
-      'eslint:recommended',
-      'plugin:@typescript-eslint/recommended',
-+     'plugin:jest/recommended',
-    ],
-  };
+```js title=".eslintrc.js"
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  plugins: [
+    '@typescript-eslint',
+    // Add this line
+    'jest',
+  ],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    // Add this line
+    'plugin:jest/recommended',
+  ],
+};
 ```
 
 <!-- markdownlint-disable MD044 -->

diff --git a/docs/linting/TROUBLESHOOTING.md b/docs/linting/TROUBLESHOOTING.md
@@ -42,12 +42,15 @@ See our docs on [type aware linting](./TYPED_LINTING.md#i-get-errors-telling-me-
 
 You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeScript extensions to allow, for example:
 
-```diff
- parserOptions: {
-   tsconfigRootDir: __dirname,
-   project: ['./tsconfig.json'],
-+  extraFileExtensions: ['.vue'],
- },
+```js title=".eslintrc.js"
+module.exports = {
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['./tsconfig.json'],
+    // Add this line
+    extraFileExtensions: ['.vue'],
+  },
+};
 ```
 
 ## One of my lint rules isn't working correctly on a pure JavaScript file

diff --git a/docs/linting/TYPED_LINTING.md b/docs/linting/TYPED_LINTING.md
@@ -8,21 +8,24 @@ Under the hood, the typescript-eslint parser uses TypeScript's compiler APIs to
 
 To tap into TypeScript's additional powers, there are two small changes you need to make to your config file:
 
-```diff title=".eslintrc.js"
- module.exports = {
-   root: true,
-   parser: '@typescript-eslint/parser',
-+  parserOptions: {
-+    tsconfigRootDir: __dirname,
-+    project: ['./tsconfig.json'],
-+  },
-   plugins: ['@typescript-eslint'],
-   extends: [
-     'eslint:recommended',
-     'plugin:@typescript-eslint/recommended',
-+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
-   ],
- };
+```js title=".eslintrc.js"
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  // Added lines start
+  parserOptions: {
+    tsconfigRootDir: __dirname,
+    project: ['./tsconfig.json'],
+  },
+  // Added lines end
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    // Add this line
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+  ],
+};
 ```
 
 In more detail:

diff --git a/packages/website/docusaurusConfig.ts b/packages/website/docusaurusConfig.ts
@@ -139,6 +139,23 @@ const themeConfig: ThemeCommonConfig & AlgoliaThemeConfig = {
       styles: [],
     },
     additionalLanguages: ['ignore'],
+    magicComments: [
+      {
+        className: 'theme-code-block-highlighted-line',
+        line: 'highlight-next-line',
+        block: { start: 'highlight-start', end: 'highlight-end' },
+      },
+      {
+        className: 'code-block-removed-line',
+        line: 'Remove this line',
+        block: { start: 'Removed lines start', end: 'Removed lines end' },
+      },
+      {
+        className: 'code-block-added-line',
+        line: 'Add this line',
+        block: { start: 'Added lines start', end: 'Added lines end' },
+      },
+    ],
   },
   tableOfContents: {
     maxHeadingLevel: 4,

diff --git a/packages/website/package.json b/packages/website/package.json
@@ -26,6 +26,7 @@
     "json5": "^2.2.1",
     "konamimojisplosion": "^0.5.1",
     "lzstring.ts": "^2.0.2",
+    "prism-react-renderer": "^1.3.3",
     "react": "^18.1.0",
     "react-dom": "^18.1.0",
     "remark-docusaurus-tabs": "^0.2.0",

diff --git a/packages/website/src/css/custom.css b/packages/website/src/css/custom.css
@@ -109,7 +109,39 @@ h6 {
   background-color: var(--code-line-decoration);
 }
 
-/* indent the nested checklist for the rule doc attributes */
-ul.contains-task-list > li > ul.contains-task-list {
-  padding-left: 24px;
+.code-block-removed-line::before {
+  content: '-';
+  display: inline-block;
+  width: 0px;
+  position: relative;
+  left: -0.7em;
+  color: red;
+}
+
+.code-block-removed-line {
+  background-color: #ff000020;
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+  user-select: none;
+}
+
+.code-block-added-line::before {
+  content: '+';
+  display: inline-block;
+  width: 0px;
+  position: relative;
+  left: -0.7em;
+  color: rgb(2, 164, 113);
+}
+
+.code-block-added-line {
+  background-color: #00ff9540;
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
+[data-theme='dark'] .code-block-added-line {
+  background-color: #00ff9510;
 }