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

Author: yangshun

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';