feat(v2): support comments for code highlighting

packages/docusaurus-theme-classic/src/theme/CodeBlock/index.js

@@ -17,6 +17,73 @@ import useThemeContext from '@theme/hooks/useThemeContext';
 import styles from './styles.module.css';
 
 const highlightLinesRangeRegex = /{([\d,-]+)}/;
+const getHighlightDirectiveRegex = (
+  languages = ['js', 'jsBlock', 'jsx', 'python', 'html'],
+) => {
+  // supported types of comments
+  const comments = {
+    js: {
+      start: '\\/\\/',
+      end: '',
+    },
+    jsBlock: {
+      start: '\\/\\*',
+      end: '\\*\\/',
+    },
+    jsx: {
+      start: '\\{\\s*\\/\\*',
+      end: '\\*\\/\\s*\\}',
+    },
+    python: {
+      start: '#',
+      end: '',
+    },
+    html: {
+      start: '<!--',
+      end: '-->',
+    },
+  };
+  // supported directives
+  const directives = [
+    'highlight-next-line',
+    'highlight-start',
+    'highlight-end',
+  ].join('|');
+  // to be more reliable, the opening and closing comment must match
+  const commentPattern = languages
+    .map(
+      lang =>
+        `(?:${comments[lang].start}\\s*(${directives})\\s*${comments[lang].end})`,
+    )
+    .join('|');
+  // white space is allowed, but otherwise it should be on it's own line
+  return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
+};
+// select comment styles based on language
+const highlightDirectiveRegex = lang => {
+  switch (lang) {
+    case 'js':
+    case 'javascript':
+    case 'ts':
+    case 'typescript':
+      return getHighlightDirectiveRegex(['js', 'jsBlock']);
+
+    case 'jsx':
+    case 'tsx':
+      return getHighlightDirectiveRegex(['js', 'jsBlock', 'jsx']);
+
+    case 'html':
+      return getHighlightDirectiveRegex(['js', 'jsBlock', 'html']);
+
+    case 'python':
+    case 'py':
+      return getHighlightDirectiveRegex(['python']);
+
+    default:
+      // all comment types
+      return getHighlightDirectiveRegex();
+  }
+};
 const codeBlockTitleRegex = /title=".*"/;
 
 export default ({children, className: languageClassName, metastring}) => {
@@ -84,6 +151,50 @@ export default ({children, className: languageClassName, metastring}) => {
     language = prism.defaultLanguage;
   }
 
+  // only declaration OR directive highlight can be used for a block
+  let code = children.replace(/\n$/, '');
+  if (highlightLines.length === 0 && language !== undefined) {
+    let range = '';
+    const directiveRegex = highlightDirectiveRegex(language);
+    // go through line by line
+    const lines = children.replace(/\n$/, '').split('\n');
+    let blockStart;
+    // loop through lines
+    for (let index = 0; index < lines.length; ) {
+      const line = lines[index];
+      // adjust for 0-index
+      const lineNumber = index + 1;
+      const match = line.match(directiveRegex);
+      if (match !== null) {
+        const directive = match
+          .slice(1)
+          .reduce((final, item) => final || item, undefined);
+        switch (directive) {
+          case 'highlight-next-line':
+            range += `${lineNumber},`;
+            break;
+
+          case 'highlight-start':
+            blockStart = lineNumber;
+            break;
+
+          case 'highlight-end':
+            range += `${blockStart}-${lineNumber - 1},`;
+            break;
+
+          default:
+            break;
+        }
+        lines.splice(index, 1);
+      } else {
+        // lines without directives are unchanged
+        index += 1;
+      }
+    }
+    highlightLines = rangeParser.parse(range);
+    code = lines.join('\n');
+  }
+
   const handleCopyCode = () => {
     window.getSelection().empty();
     setShowCopied(true);
@@ -96,7 +207,7 @@ export default ({children, className: languageClassName, metastring}) => {
       {...defaultProps}
       key={mounted}
       theme={prismTheme}
-      code={children.replace(/\n$/, '')}
+      code={code}
       language={language}>
       {({className, style, tokens, getLineProps, getTokenProps}) => (
         <>

website/docs/markdown-features.mdx

@@ -267,6 +267,51 @@ function HighlightSomeText(highlight) {
 }
 ```
 
+You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
+
+    ```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
+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';
+}
+```
+
+JS style (`/* */` and `//`), JSX style (`{ /* */ }`), Python style (`# `), and HTML style (`<!-- -->`) are supported.
+
 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