docs(v2): code block line highlighting (#1904)

* docs(v2): code block line highlighting

* misc: update CHANGELOG

* misc: respond to review

* docs: add line highlighting to the template

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)
+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.
-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
+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).
-[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
+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.
-[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'],
   ...
 }
 ```

website/docs/migrating-from-v1-to-v2.md

@@ -49,13 +49,14 @@ Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docus
 
 The `"scripts"` section of your `package.json` should be updated as follows:
 
-```json
+```json {3-6}
 {
   "scripts": {
     "start": "docusaurus start",
     "build": "docusaurus build",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy"
+    ...
   }
 }
 ```
@@ -125,7 +126,7 @@ No actions needed.
 
 Deprecated. We wrote a custom CSS framework for Docusaurus 2 called Infima which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima' CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`:
 
-```diff
+```js {8-10}
 // docusaurus.config.js
 module.exports = {
   // ...
@@ -133,9 +134,9 @@ module.exports = {
     [
       '@docusaurus/preset-classic',
       {
-+       theme: {
+        theme: {
-+         customCss: require.resolve('./src/css/custom.css'),
+          customCss: require.resolve('./src/css/custom.css'),
-+       },
+        },
       },
     ],
   ],
@@ -168,6 +169,7 @@ Site meta info such as assets, SEO, copyright info are now handled by themes. To
 ```jsx
 // docusaurus.config.js
 module.exports = {
+  // ...
   themeConfig: {
     footer: {
       logo: {
@@ -179,7 +181,7 @@ module.exports = {
     image: 'img/docusaurus.png',
     // Equivalent to `docsSideNavCollapsible`
     sidebarCollapsible: false,
-    ...
+    // ...
   },
 };
 ```
@@ -200,9 +202,10 @@ headerLinks: [
 
 Now, these two fields are both handled by the theme:
 
-```jsx
+```jsx {7-20}
 // docusaurus.config.js
 module.exports = {
+  // ...
   themeConfig: {
     navbar: {
       title: 'Docusaurus',
@@ -221,23 +224,24 @@ module.exports = {
         {to: 'blog', label: 'Blog', position: 'left'},
       ],
     },
-    ...
+    // ...
   },
 };
 ```
 
 #### `algolia`
 
-```jsx
+```jsx {5-9}
 // docusaurus.config.js
 module.exports = {
+  // ...
   themeConfig: {
     algolia: {
       apiKey: '47ecd3b21be71c5822571b9f59e52544',
       indexName: 'docusaurus-2',
       algoliaOptions: { ... },
     },
-    ...
+    // ...
   },
 };
 ```
@@ -246,9 +250,10 @@ module.exports = {
 
 Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead:
 
-```jsx
+```jsx {9}
 // docusaurus.config.js
 module.exports = {
+  // ...
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -256,7 +261,7 @@ module.exports = {
         blog: {
           postsPerPage: 10,
         },
-        ...
+        // ...
       },
     ],
   ],
@@ -271,9 +276,10 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust
 
 Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
 
-```jsx
+```jsx {9-22}
 // docusaurus.config.js
 module.exports = {
+  // ...
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -282,7 +288,8 @@ module.exports = {
           // Equivalent to `customDocsPath`.
           path: 'docs',
           // Equivalent to `editUrl`
-          editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/docs/',
+          editUrl:
+            'https://github.com/facebook/docusaurus/edit/master/website/docs/',
           // Equivalent to `docsUrl`.
           routeBasePath: 'docs',
           // Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
@@ -293,7 +300,7 @@ module.exports = {
           // Equivalent to `enableUpdateTime`.
           showLastUpdateTime: true,
         },
-        ...
+        // ...
       },
     ],
   ],
@@ -302,26 +309,30 @@ module.exports = {
 
 #### `gaTrackingId`
 
-```jsx
+```jsx {6}
 // docusaurus.config.js
 module.exports = {
+  // ...
   themeConfig: {
     googleAnalytics: {
       trackingID: 'UA-141789564-1',
     },
+    // ...
   },
 };
 ```
 
 #### `gaGtag`
 
-```jsx
+```jsx {6}
 // docusaurus.config.js
 module.exports = {
+  // ...
   themeConfig: {
     gtag: {
       trackingID: 'UA-141789564-1',
     },
+    // ...
   },
 };
 ```

website/docs/presets.md

@@ -15,20 +15,22 @@ npm install --save docusaurus-preset-name
 
 Then, add it in your site's `docusaurus.config.js`'s `presets` option:
 
-```jsx
+```jsx {4}
 // docusaurus.config.js
 module.exports = {
+  // ...
   presets: ['@docusaurus/preset-xxxx'],
 };
 ```
 
 To load presets from your local directory, specify how to resolve them:
 
-```jsx
+```jsx {6}
 // docusaurus.config.js
 const path = require('path');
 
 module.exports = {
+  // ...
   presets: [path.resolve(__dirname, '/path/to/docusaurus-local-presets')],
 };
 ```
@@ -48,9 +50,10 @@ module.exports = function preset(context, opts = {}) {
 
 then in your Docusaurus config, you may configure the preset instead:
 
-```jsx
+```jsx {4}
 // docusaurus.config.js
 module.exports = {
+  // ...
   presets: ['@docusaurus/preset-a'],
 };
 ```

website/docs/search.md

@@ -18,7 +18,7 @@ Algolia DocSearch works by crawling the content of your website every 24 hours a
 
 To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. Note that you will need algolia API key and algolia index. You can [apply for DocSearch here](https://community.algolia.com/docsearch/).
 
-```jsx
+```jsx {4-8}
 // docusaurus.config.js
 themeConfig: {
     // ....

website/docs/sidebar.md

@@ -5,7 +5,7 @@ title: Sidebar
 
 To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
 
-```js
+```js {9-10}
 // docusaurus.config.js
 module.exports = {
   // ...
@@ -83,8 +83,8 @@ For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/he
 
 ```bash
 website # root directory of your site
-├── docs
+└── docs
-   └── greeting.md
+   ├── greeting.md
    └── guide
       └── hello.md
 ```

website/docs/styling-layout.md

@@ -8,7 +8,7 @@ description: A Docusaurus site is a pre-rendered single-page React application.
 
 If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing it as an option into the preset.
 
-```diff
+```js {8-10}
 // docusaurus.config.js
 module.exports = {
   // ...
@@ -16,9 +16,9 @@ module.exports = {
     [
       '@docusaurus/preset-classic',
       {
-+       theme: {
+        theme: {
-+         customCss: require.resolve('./src/css/custom.css'),
+          customCss: require.resolve('./src/css/custom.css'),
-+       },
+        },
       },
     ],
   ],

website/docs/using-plugins.md

@@ -18,20 +18,22 @@ npm install --save docusaurus-plugin-name
 
 Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
 
-```jsx
+```jsx {4}
 // docusaurus.config.js
 module.exports = {
+  // ...
   plugins: ['@docusaurus/plugin-content-pages'],
 };
 ```
 
 Docusaurus can also load plugins from your local directory, you can do something like the following:
 
-```jsx
+```jsx {6}
 // docusaurus.config.js
 const path = require('path');
 
 module.exports = {
+  // ...
   plugins: [path.resolve(__dirname, '/path/to/docusaurus-local-plugin')],
 };
 ```
@@ -42,9 +44,10 @@ For the most basic usage of plugins, you can provide just the plugin name or the
 
 However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called `Babel Style`.
 
-```js
+```js {5-10}
 // docusaurus.config.js
 module.exports = {
+  // ...
   plugins: [
     [
       '@docusaurus/plugin-xxx',

website/docs/using-themes.md

@@ -10,9 +10,10 @@ Like plugins, themes are designed to add functionality to your Docusaurus site.
 
 To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes:
 
-```js
+```js {4}
 // docusaurus.config.js
 module.exports = {
+  // ...
   themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
 };
 ```
@@ -60,7 +61,7 @@ For example, a Docusaurus blog consists of a blog plugin and a blog theme.
 }
 ```
 
-and if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap`:
+and if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (fictitious non-existing theme):
 
 ```js
 // docusaurus.config.js

website/src/css/custom.css

@@ -31,3 +31,10 @@ html[data-theme='dark'] {
     --ifm-font-size-base: 17px;
   }
 }
+
+.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);
+}