docs(v2): code block line highlighting

CHANGELOG-2.x.md

@@ -8,8 +8,8 @@
 - Significantly reduce main bundle size and initial HTML payload on production build. Generated JS files from webpack is also shorter in name.
 - Refactor dark toggle into a hook.
 - Changed the way we read the `USE_SSH` env variable during deployment to be the same as in v1.
-- Add highlight specific lines in code blocks.
 - Fix accessing `docs/` or `/docs/xxxx` that does not match any existing doc page should return 404 (Not found) page, not blank page.
+- Added code block line highlighting feature (thanks @lex111)! If you have previously swizzled the `CodeBlock` theme component, it is recommended to update your source code to have this feature.
 
 ## 2.0.0-alpha.31
 

packages/docusaurus-init/templates/classic/docs/doc1.md

@@ -110,6 +110,12 @@ No language indicated, so no syntax highlighting.
 But let's throw in a <b>tag</b>.
 ```
 
+```js {2}
+function highlightMe() {
+  console.log('This line can be highlighted!');
+}
+```
+
 ---
 
 ## Tables

packages/docusaurus-init/templates/classic/src/css/custom.css

@@ -21,3 +21,10 @@
   --ifm-color-primary-lighter: rgb(102, 212, 189);
   --ifm-color-primary-lightest: rgb(146, 224, 208);
 }
+
+.docusaurus-highlight-code-line {
+  background-color: rgb(72, 77, 91);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}

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

@@ -31,6 +31,7 @@ export default ({children, className: languageClassName, metastring}) => {
     const highlightLinesRange = metastring.match(highlightLinesRangeRegex)[1];
     highlightLines = rangeParser.parse(highlightLinesRange).filter(n => n > 0);
   }
+
   useEffect(() => {
     let clipboard;
 
@@ -73,7 +74,7 @@ export default ({children, className: languageClassName, metastring}) => {
               const lineProps = getLineProps({line, key: i});
 
               if (highlightLines.includes(i + 1)) {
-                lineProps.className = `${lineProps.className} highlight-line`;
+                lineProps.className = `${lineProps.className} docusaurus-highlight-code-line`;
               }
 
               return (

packages/docusaurus-theme-live-codeblock/src/theme/CodeBlock/index.js

@@ -92,7 +92,7 @@ export default ({
               const lineProps = getLineProps({line, key: i});
 
               if (highlightLines.includes(i + 1)) {
-                lineProps.className = `${lineProps.className} highlight-line`;
+                lineProps.className = `${lineProps.className} docusaurus-highlight-code-line`;
               }
 
               return (

website/docs/advanced-themes.md

@@ -19,10 +19,10 @@ To summarize:
 
 ## Writing customized Docusaurus themes
 
-A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside with a `theme/` directory of components. A typical Docusaurus theme folder looks like this:
+A Docusaurus theme normally includes an `index.js` file where you hook up to the lifecycle methods, alongside with a `theme/` directory of components. A typical Docusaurus `theme` folder looks like this:
 
-```shell
-.
+```shell {5-7}
+website
 ├── package.json
 └── src
     ├── index.js
@@ -32,6 +32,7 @@ A Docusaurus theme normally includes an `index.js` file where you hook up to the
 ```
 
 There are two lifecycle methods that are essential to theme implementation:
+
 - [getThemePath](lifecycle-apis.md#getthemepath)
 - [getClientModules](lifecycle-apis.md#getclientmodules)
 

website/docs/blog.md

@@ -56,7 +56,7 @@ The only required field is `title`; however, we provide options to add author in
 
 Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
 
-```md
+```md {9}
 ---
 title: Truncation Example
 ---
@@ -82,7 +82,7 @@ You can run your Docusaurus 2 site without a landing page and instead have your
 
 **Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!
 
-```js
+```js {10}
 // docusaurus.config.js
 module.exports = {
   // ...

website/docs/configuration.md

@@ -36,8 +36,6 @@ It is recommended to check the [deployment docs](deployment.md) for more informa
 
 ### Themes, Plugins, and Presets configurations
 
-
-
 _This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
 
 <!--
@@ -59,7 +57,7 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi
 
 Example:
 
-```js
+```js {3-6}
 // docusaurus.config.js
 module.exports = {
   customFields: {
@@ -75,7 +73,7 @@ Your configuration object will be made available to all the components of your s
 
 Basic Example:
 
-```jsx
+```jsx {2,5-6}
 import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 

website/docs/deployment.md

@@ -56,7 +56,7 @@ You may refer to GitHub Pages' documentation [User, Organization, and Project Pa
 
 Example:
 
-```jsx
+```jsx {3-6}
 module.exports = {
   ...
   url: 'https://endiliey.github.io', // Your website URL
@@ -102,7 +102,7 @@ References:
 
 To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
 
-```js
+```js {3-4}
 // docusaurus.config.js
 module.exports = {
   url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash

website/docs/docusaurus-core.md

@@ -11,7 +11,7 @@ This reusable React component will manage all of your changes to the document he
 
 Usage Example:
 
-```jsx
+```jsx {2,6,11}
 import React from 'react';
 import Head from '@docusaurus/Head';
 
@@ -29,7 +29,7 @@ const MySEO = () => (
 
 Nested or latter components will override duplicate usages:
 
-```jsx
+```jsx {2,5,8,11}
 <Parent>
   <Head>
     <title>My Title</title>
@@ -60,7 +60,7 @@ This component enables linking to internal pages as well as a powerful performan
 
 The component is a wrapper around react-router’s `<NavLink>` component that adds useful enhancements specific to Docusaurus. All props are passed through to react-router’s `<NavLink>` component.
 
-```jsx
+```jsx {2,7}
 import React from 'react';
 import Link from '@docusaurus/Link';
 
@@ -89,7 +89,7 @@ The target location to navigate to. Example: `/docs/introduction`.
 
 The class to give the `<Link>` when it is active. The default given class is `active`. This will be joined with the `className` prop.
 
-```jsx
+```jsx {1}
 <Link to="/faq" activeClassName="selected">
   FAQs
 </Link>
@@ -107,7 +107,7 @@ interface DocusaurusContext {
 
 Usage example:
 
-```jsx
+```jsx {2,5}
 import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
@@ -126,7 +126,7 @@ React Hook to automatically append `baseUrl` to a string automatically. This is
 
 Example usage:
 
-```jsx
+```jsx {3,11}
 import React, {useEffect} from 'react';
 import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';

website/docs/lifecycle-apis.md

@@ -125,7 +125,7 @@ Example:
 
 ```js
 async postBuild({siteConfig = {}, routesPaths = [], outDir}) {
-  // Print out to console all the rendered routes 
+  // Print out to console all the rendered routes
   routesPaths.map(route => {
     console.log(route);
   })
@@ -157,8 +157,8 @@ If you use the folder directory above, your `getThemePath` can be:
 
 ```js
 // my-theme/src/index.js
-
 const path = require('path');
+
 module.exports = function(context, options) {
   return {
     name: 'name-of-my-theme',
@@ -177,8 +177,8 @@ As an example, to make your theme load a `customCss` object from `options` passe
 
 ```js
 // my-theme/src/index.js
-
 const path = require('path');
+
 module.exports = function(context, options) {
   const {customCss} = options || {};
   return {

website/docs/markdown-features.mdx

@@ -120,7 +120,6 @@ keywords:
   - docusaurus
 image: https://i.imgur.com/mErPwqL.png
 ---
-
 ```
 
 ### Embedding React components
@@ -202,13 +201,11 @@ Use the matching language meta string for your code block, and Docusaurus will p
 console.log('Every repo must come with a mascot.');
 ```
 
-By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming)
-we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js).
-You can change this to another theme by passing `prismTheme` as `themeConfig` in your docusaurus.config.js.
+By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `prismTheme` as `themeConfig` in your docusaurus.config.js.
 
 For example, if you prefer to use the `dracula` highlighting theme:
 
-```js
+```js {4}
 // docusaurus.config.js
 module.exports = {
   themeConfig: {
@@ -217,13 +214,9 @@ module.exports = {
 };
 ```
 
-By default, Docusaurus comes with this subset of
-[commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
+By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
 
-To add syntax highlighting for any of the other
-[Prism supported languages](https://prismjs.com/#supported-languages),
-install the `prismjs` npm package, then swizzle the `CodeBlock`
-component and add the desired language(s) there.
+To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages), install the `prismjs` npm package, then swizzle the `CodeBlock` component and add the desired language(s) there.
 
 For example, if you want to add highlighting for the `powershell` language:
 
@@ -234,6 +227,72 @@ import Prism from 'prism-react-renderer/prism';
 require('prismjs/components/prism-powershell');
 ```
 
+### 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).
+
+    ```jsx {3}
+    function HighlightSomeText(highlight) {
+      if (highlight) {
+        return 'This text is highlighted!';
+      }
+
+      return 'Nothing highlighted';
+    }
+    ```
+
+```jsx {3}
+function HighlightSomeText(highlight) {
+  if (highlight) {
+    return 'This text is highlighted!';
+  }
+
+  return 'Nothing highlighted';
+}
+```
+
+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 will have to tweak the color accordingly.
+
+```css
+/* /src/css/custom.css */
+.docusaurus-highlight-code-line {
+  background-color: rgb(72, 77, 91);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+```
+
+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';
+
+    function MyComponent(props) {
+      if (props.isBar) {
+        return <div>Bar</div>;
+      }
+
+      return <div>Foo</div>;
+    }
+
+    export default MyComponent;
+    ```
+
+```jsx {1,4-6,11}
+import React from 'react';
+
+function MyComponent(props) {
+  if (props.isBar) {
+    return <div>Bar</div>;
+  }
+
+  return <div>Foo</div>;
+}
+
+export default MyComponent;
+```
+
 ### Interactive code editor
 
 (Powered by [React Live](https://github.com/FormidableLabs/react-live))
@@ -248,10 +307,10 @@ npm i @docusaurus/theme-live-codeblock
 
 You will also need to add the plugin to your `docusaurus.config.js`.
 
-```diff
+```js {3}
 module.exports = {
   ...
-+ themes: ['@docusaurus/theme-live-codeblock'],
+  themes: ['@docusaurus/theme-live-codeblock'],
   ...
 }
 ```