docs: recommend highlighting with comments than number range

packages/docusaurus-utils/src/markdownLinks.ts

@@ -45,9 +45,16 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
 
   // Replace internal markdown linking (except in fenced blocks).
   let fencedBlock = false;
+  let lastCodeFence = '';
   const lines = fileString.split('\n').map((line) => {
     if (line.trim().startsWith('```')) {
-      fencedBlock = !fencedBlock;
+      if (!fencedBlock) {
+        fencedBlock = true;
+        [lastCodeFence] = line.trim().match(/^`+/)!;
+        // If we are in a ````-fenced block, all ``` would be plain text instead of fences
+      } else if (line.trim().match(/^`+/)![0].length >= lastCodeFence.length) {
+        fencedBlock = false;
+      }
     }
     if (fencedBlock) {
       return line;

website/docs/docusaurus-core.md

@@ -526,7 +526,7 @@ This is the most convenient hook to access plugin global data and should be used
 `pluginId` is optional if you don't use multi-instance plugins.
 
 ```ts
-usePluginData(pluginName: string, pluginId?: string)
+function usePluginData(pluginName: string, pluginId?: string);
 ```
 
 Usage example:

website/docs/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -109,28 +109,63 @@ You can refer to [Prism's official language definitions](https://github.com/Pris
 
 ## Line highlighting {#line-highlighting}
 
-You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
+### Highlighting with comments {#highlighting-with-comments}
+
+You can use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
 
-    ```jsx {3}
+    ```jsx
     function HighlightSomeText(highlight) {
       if (highlight) {
+        // highlight-next-line
         return 'This text is highlighted!';
       }
 
       return 'Nothing highlighted';
     }
+
+    function HighlightMoreText(highlight) {
+      // highlight-start
+      if (highlight) {
+        return 'This range is highlighted!';
+      }
+      // highlight-end
+
+      return 'Nothing highlighted';
+    }
     ```
 
-```jsx {3}
+```jsx
 function HighlightSomeText(highlight) {
   if (highlight) {
+    // highlight-next-line
     return 'This text is highlighted!';
   }
 
   return 'Nothing highlighted';
 }
+
+function HighlightMoreText(highlight) {
+  // highlight-start
+  if (highlight) {
+    return 'This range is highlighted!';
+  }
+  // highlight-end
+
+  return 'Nothing highlighted';
+}
 ```
 
+Supported commenting syntax:
+
+| Language   | Syntax                   |
+| ---------- | ------------------------ |
+| JavaScript | `/* ... */` and `// ...` |
+| JSX        | `{/* ... */}`            |
+| Python     | `# ...`                  |
+| HTML       | `<!-- ... -->`           |
+
+If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
+
 To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
 
 ```css title="/src/css/custom.css"
@@ -148,9 +183,9 @@ html[data-theme='dark'] .docusaurus-highlight-code-line {
 }
 ```
 
-### Multiple-line highlighting {#multiple-line-highlighting}
+### Highlighting with metadata string
 
-To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
+You can also specify highlighted line ranges within the language meta string (leave a space after the language). To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
 
     ```jsx {1,4-6,11}
     import React from 'react';
@@ -180,62 +215,27 @@ function MyComponent(props) {
 export default MyComponent;
 ```
 
-### Highlighting with comments {#highlighting-with-comments}
+:::tip prefer comments
 
-You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
+Prefer highlighting with comments where you can. By inlining highlight in the code, you don't have to manually count the lines if your code block becomes long. If you add/remove lines, you also don't have to offset your line ranges.
 
-    ```jsx
-    function HighlightSomeText(highlight) {
-      if (highlight) {
-        // highlight-next-line
-        return 'This text is highlighted!';
-      }
-
-      return 'Nothing highlighted';
-    }
-
-    function HighlightMoreText(highlight) {
-      // highlight-start
-      if (highlight) {
-        return 'This range is highlighted!';
-      }
-      // highlight-end
-
-      return 'Nothing highlighted';
+````diff
+- ```jsx {3}
++ ```jsx {4}
+  function HighlightSomeText(highlight) {
+    if (highlight) {
++     console.log('Highlighted text found');
+      return 'This text is highlighted!';
     }
-    ```
 
-```jsx
-function HighlightSomeText(highlight) {
-  if (highlight) {
-    // highlight-next-line
-    return 'This text is highlighted!';
+    return 'Nothing highlighted';
   }
+  ```
+````
 
-  return 'Nothing highlighted';
-}
-
-function HighlightMoreText(highlight) {
-  // highlight-start
-  if (highlight) {
-    return 'This range is highlighted!';
-  }
-  // highlight-end
-
-  return 'Nothing highlighted';
-}
-```
-
-Supported commenting syntax:
-
-| Language   | Syntax                   |
-| ---------- | ------------------------ |
-| JavaScript | `/* ... */` and `// ...` |
-| JSX        | `{/* ... */}`            |
-| Python     | `# ...`                  |
-| HTML       | `<!-- ... -->`           |
+In the future, we may extend the magic comment system and let you define custom directives and their functionalities. The magic comments would only be parsed if a highlight metastring is not present.
 
-If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
+:::
 
 ## Interactive code editor {#interactive-code-editor}