Merge branch 'master' into feature/client-side-redirects

.prettierignore

@@ -6,6 +6,7 @@ packages/docusaurus-utils/lib/
 packages/docusaurus/lib/
 packages/docusaurus-init/lib/
 packages/docusaurus-plugin-client-redirects/lib/
+packages/docusaurus-init/templates/**/*.md
 packages/docusaurus-plugin-content-blog/lib/
 packages/docusaurus-plugin-content-docs/lib/
 packages/docusaurus-plugin-content-pages/lib/

admin/testing-changes-on-Docusaurus-itself.md

@@ -30,9 +30,8 @@ Use the following code in VSCode to enable breakpoints. Please ensure you have a
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}/website",
-      "runtimeExecutable": "npm",
-      "runtimeArgs": ["run", "start-debug"],
-      "port": 9229
+      "program": "${workspaceFolder}/website/node_modules/@docusaurus/core/bin/docusaurus.js",
+      "args": ["start"]
     }
   ]
 }

docs/guides-search.md

@@ -17,6 +17,7 @@ const siteConfig = {
   algolia: {
     apiKey: 'my-api-key',
     indexName: 'my-index-name',
+    appId: 'app-id', // Optional, if you run the DocSearch crawler on your own
     algoliaOptions: {} // Optional, if provided by Algolia
   },
   ...

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

@@ -28,9 +28,9 @@ To serve as an example page when styling markdown based Docusaurus sites.
 
 ## Emphasis
 
-Emphasis, aka italics, with _asterisks_ or _underscores_.
+Emphasis, aka italics, with *asterisks* or _underscores_.
 
-Strong emphasis, aka bold, with **asterisks** or **underscores**.
+Strong emphasis, aka bold, with **asterisks** or __underscores__.
 
 Combined emphasis with **asterisks and _underscores_**.
 
@@ -41,27 +41,25 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 ## Lists
 
 1. First ordered list item
-1. Another item ⋅⋅\* Unordered sub-list.
-1. Actual numbers don't matter, just that it's a number ⋅⋅1. Ordered sub-list
+1. Another item
+   - Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+   1. Ordered sub-list
 1. And another item.
 
-⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).
+* Unordered list can use asterisks
 
-⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅ ⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅ ⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)
+- Or minuses
 
-- Unordered list can use asterisks
-
-* Or minuses
-
-- Or pluses
++ Or pluses
 
 ---
 
 ## Links
 
-[I'm an inline-style link](https://www.google.com)
+[I'm an inline-style link](https://www.google.com/)
 
-[I'm an inline-style link with title](https://www.google.com "Google's Homepage")
+[I'm an inline-style link with title](https://www.google.com/ "Google's Homepage")
 
 [I'm a reference-style link][arbitrary case-insensitive reference text]
 
@@ -71,13 +69,13 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 
 Or leave it empty and use the [link text itself].
 
-URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com or <http://www.example.com> and sometimes example.com (but not on Github, for example).
+URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com/ or <http://www.example.com/> and sometimes example.com (but not on GitHub, for example).
 
 Some text to show that the reference links can follow later.
 
-[arbitrary case-insensitive reference text]: https://www.mozilla.org
-[1]: http://slashdot.org
-[link text itself]: http://www.reddit.com
+[arbitrary case-insensitive reference text]: https://www.mozilla.org/
+[1]: http://slashdot.org/
+[link text itself]: http://www.reddit.com/
 
 ---
 

packages/docusaurus-init/templates/bootstrap/docs/doc2.md

@@ -3,4 +3,4 @@ id: doc2
 title: Document Number 2
 ---
 
-This is a link to [another document.](doc3.md) This is a link to an [external page.](http://www.example.com)
+This is a link to [another document.](doc3.md) This is a link to an [external page.](http://www.example.com/)

packages/docusaurus-init/templates/bootstrap/docs/mdx.md

@@ -10,7 +10,7 @@ export const Highlight = ({children, color}) => ( <span style={{
       borderRadius: '2px',
       color: '#fff',
       padding: '0.2rem',
-    }}> {children} </span> );
+    }}>{children}</span> );
 
 <Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
 

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

@@ -28,9 +28,9 @@ To serve as an example page when styling markdown based Docusaurus sites.
 
 ## Emphasis
 
-Emphasis, aka italics, with _asterisks_ or _underscores_.
+Emphasis, aka italics, with *asterisks* or _underscores_.
 
-Strong emphasis, aka bold, with **asterisks** or **underscores**.
+Strong emphasis, aka bold, with **asterisks** or __underscores__.
 
 Combined emphasis with **asterisks and _underscores_**.
 
@@ -41,27 +41,25 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 ## Lists
 
 1. First ordered list item
-1. Another item ⋅⋅\* Unordered sub-list.
-1. Actual numbers don't matter, just that it's a number ⋅⋅1. Ordered sub-list
+1. Another item
+   - Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+   1. Ordered sub-list
 1. And another item.
 
-⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).
+* Unordered list can use asterisks
 
-⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅ ⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅ ⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)
+- Or minuses
 
-- Unordered list can use asterisks
-
-* Or minuses
-
-- Or pluses
++ Or pluses
 
 ---
 
 ## Links
 
-[I'm an inline-style link](https://www.google.com)
+[I'm an inline-style link](https://www.google.com/)
 
-[I'm an inline-style link with title](https://www.google.com "Google's Homepage")
+[I'm an inline-style link with title](https://www.google.com/ "Google's Homepage")
 
 [I'm a reference-style link][arbitrary case-insensitive reference text]
 
@@ -71,13 +69,13 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 
 Or leave it empty and use the [link text itself].
 
-URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com or <http://www.example.com> and sometimes example.com (but not on Github, for example).
+URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com/ or <http://www.example.com/> and sometimes example.com (but not on GitHub, for example).
 
 Some text to show that the reference links can follow later.
 
-[arbitrary case-insensitive reference text]: https://www.mozilla.org
-[1]: http://slashdot.org
-[link text itself]: http://www.reddit.com
+[arbitrary case-insensitive reference text]: https://www.mozilla.org/
+[1]: http://slashdot.org/
+[link text itself]: http://www.reddit.com/
 
 ---
 

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

@@ -3,4 +3,4 @@ id: doc2
 title: Document Number 2
 ---
 
-This is a link to [another document.](doc3.md) This is a link to an [external page.](http://www.example.com)
+This is a link to [another document.](doc3.md) This is a link to an [external page.](http://www.example.com/)

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

@@ -10,7 +10,7 @@ export const Highlight = ({children, color}) => ( <span style={{
       borderRadius: '2px',
       color: '#fff',
       padding: '0.2rem',
-    }}> {children} </span> );
+    }}>{children}</span> );
 
 <Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
 

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

@@ -28,9 +28,9 @@ To serve as an example page when styling markdown based Docusaurus sites.
 
 ## Emphasis
 
-Emphasis, aka italics, with _asterisks_ or _underscores_.
+Emphasis, aka italics, with *asterisks* or _underscores_.
 
-Strong emphasis, aka bold, with **asterisks** or **underscores**.
+Strong emphasis, aka bold, with **asterisks** or __underscores__.
 
 Combined emphasis with **asterisks and _underscores_**.
 
@@ -41,27 +41,25 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 ## Lists
 
 1. First ordered list item
-1. Another item ⋅⋅\* Unordered sub-list.
-1. Actual numbers don't matter, just that it's a number ⋅⋅1. Ordered sub-list
+1. Another item
+   - Unordered sub-list.
+1. Actual numbers don't matter, just that it's a number
+   1. Ordered sub-list
 1. And another item.
 
-⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we'll use three here to also align the raw Markdown).
+* Unordered list can use asterisks
 
-⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅ ⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅ ⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)
+- Or minuses
 
-- Unordered list can use asterisks
-
-* Or minuses
-
-- Or pluses
++ Or pluses
 
 ---
 
 ## Links
 
-[I'm an inline-style link](https://www.google.com)
+[I'm an inline-style link](https://www.google.com/)
 
-[I'm an inline-style link with title](https://www.google.com "Google's Homepage")
+[I'm an inline-style link with title](https://www.google.com/ "Google's Homepage")
 
 [I'm a reference-style link][arbitrary case-insensitive reference text]
 
@@ -71,13 +69,13 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 
 Or leave it empty and use the [link text itself].
 
-URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com or <http://www.example.com> and sometimes example.com (but not on Github, for example).
+URLs and URLs in angle brackets will automatically get turned into links. http://www.example.com/ or <http://www.example.com/> and sometimes example.com (but not on GitHub, for example).
 
 Some text to show that the reference links can follow later.
 
-[arbitrary case-insensitive reference text]: https://www.mozilla.org
-[1]: http://slashdot.org
-[link text itself]: http://www.reddit.com
+[arbitrary case-insensitive reference text]: https://www.mozilla.org/
+[1]: http://slashdot.org/
+[link text itself]: http://www.reddit.com/
 
 ---
 
@@ -102,7 +100,7 @@ alert(s);
 
 ```python
 s = "Python syntax highlighting"
-print s
+print(s)
 ```
 
 ```

packages/docusaurus-init/templates/facebook/docs/doc2.md

@@ -3,4 +3,4 @@ id: doc2
 title: Document Number 2
 ---
 
-This is a link to [another document.](doc3.md) This is a link to an [external page.](http://www.example.com)
+This is a link to [another document.](doc3.md) This is a link to an [external page.](http://www.example.com/)

packages/docusaurus-init/templates/facebook/docs/mdx.md

@@ -10,7 +10,7 @@ export const Highlight = ({children, color}) => ( <span style={{
       borderRadius: '2px',
       color: '#fff',
       padding: '0.2rem',
-    }}> {children} </span> );
+    }}>{children}</span> );
 
 <Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
 

packages/docusaurus-mdx-loader/src/index.js

@@ -27,10 +27,12 @@ module.exports = async function (fileString) {
   const options = {
     ...reqOptions,
     remarkPlugins: [
+      ...(reqOptions.beforeDefaultRemarkPlugins || []),
       ...DEFAULT_OPTIONS.remarkPlugins,
       ...(reqOptions.remarkPlugins || []),
     ],
     rehypePlugins: [
+      ...(reqOptions.beforeDefaultRehypePlugins || []),
       ...DEFAULT_OPTIONS.rehypePlugins,
       ...(reqOptions.rehypePlugins || []),
     ],

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -102,7 +102,7 @@ export default function pluginContentBlog(
       const modules = [];
 
       if (options.admonitions) {
-        modules.push('remark-admonitions/styles/infima.css');
+        modules.push(require.resolve('remark-admonitions/styles/infima.css'));
       }
 
       return modules;
@@ -396,7 +396,7 @@ export default function pluginContentBlog(
                 getCacheLoader(isServer),
                 getBabelLoader(isServer),
                 {
-                  loader: '@docusaurus/mdx-loader',
+                  loader: require.resolve('@docusaurus/mdx-loader'),
                   options: {
                     remarkPlugins,
                     rehypePlugins,

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -142,7 +142,7 @@ export default function pluginContentDocs(
       const modules = [];
 
       if (options.admonitions) {
-        modules.push('remark-admonitions/styles/infima.css');
+        modules.push(require.resolve('remark-admonitions/styles/infima.css'));
       }
 
       return modules;
@@ -342,7 +342,7 @@ export default function pluginContentDocs(
         const versionsRegex = new RegExp(versionsNames.join('|'), 'i');
 
         const routes = await Promise.all(
-          metadataItems.map(async (metadataItem, i) => {
+          metadataItems.map(async (metadataItem) => {
             const isDocsHomePage =
               metadataItem.id.replace(versionsRegex, '').replace(/^\//, '') ===
               options.homePageId;
@@ -353,10 +353,6 @@ export default function pluginContentDocs(
                   ? ''
                   : metadataItem.version!) ?? '';
 
-              // To show the sidebar, get the sidebar key of available sibling item.
-              metadataItem.sidebar = (
-                metadataItems[i - 1] ?? metadataItems[i + 1]
-              ).sidebar;
               const docsBaseMetadata = createDocsBaseMetadata(
                 metadataItem.version!,
               );
@@ -526,7 +522,7 @@ export default function pluginContentDocs(
                 getCacheLoader(isServer),
                 getBabelLoader(isServer),
                 {
-                  loader: '@docusaurus/mdx-loader',
+                  loader: require.resolve('@docusaurus/mdx-loader'),
                   options: {
                     remarkPlugins,
                     rehypePlugins,

packages/docusaurus-plugin-ideal-image/src/index.ts

@@ -27,9 +27,9 @@ export default function (_context: LoadContext, options: PluginOptions) {
             {
               test: /\.(png|jpe?g|gif)$/i,
               use: [
-                '@docusaurus/lqip-loader',
+                require.resolve('@docusaurus/lqip-loader'),
                 {
-                  loader: '@endiliey/responsive-loader',
+                  loader: require.resolve('@endiliey/responsive-loader'),
                   options: {
                     emitFile: !isServer, // don't emit for server-side rendering
                     disable: !isProd,

packages/docusaurus-preset-bootstrap/package.json

@@ -14,7 +14,9 @@
     "@docusaurus/theme-bootstrap": "^2.0.0-alpha.55"
   },
   "peerDependencies": {
-    "@docusaurus/core": "^2.0.0"
+    "@docusaurus/core": "^2.0.0",
+    "react": "^16.8.4",
+    "react-dom": "^16.8.4"
   },
   "engines": {
     "node": ">=10.9.0"

packages/docusaurus-preset-bootstrap/src/index.js

@@ -7,11 +7,11 @@
 
 module.exports = function preset(context, opts = {}) {
   return {
-    themes: [['@docusaurus/theme-bootstrap', opts.theme]],
+    themes: [[require.resolve('@docusaurus/theme-bootstrap'), opts.theme]],
     plugins: [
-      ['@docusaurus/plugin-content-pages', opts.pages],
-      ['@docusaurus/plugin-content-blog', opts.blog],
-      ['@docusaurus/plugin-content-docs', opts.docs],
+      [require.resolve('@docusaurus/plugin-content-pages'), opts.pages],
+      [require.resolve('@docusaurus/plugin-content-blog'), opts.blog],
+      [require.resolve('@docusaurus/plugin-content-docs'), opts.docs],
     ],
   };
 };

packages/docusaurus-preset-classic/package.json

@@ -18,7 +18,9 @@
     "@docusaurus/theme-search-algolia": "^2.0.0-alpha.55"
   },
   "peerDependencies": {
-    "@docusaurus/core": "^2.0.0"
+    "@docusaurus/core": "^2.0.0",
+    "react": "^16.8.4",
+    "react-dom": "^16.8.4"
   },
   "engines": {
     "node": ">=10.9.0"

packages/docusaurus-preset-classic/src/index.js

@@ -13,17 +13,19 @@ module.exports = function preset(context, opts = {}) {
 
   return {
     themes: [
-      ['@docusaurus/theme-classic', opts.theme],
+      [require.resolve('@docusaurus/theme-classic'), opts.theme],
       // Don't add this if algolia config is not defined.
-      algolia && '@docusaurus/theme-search-algolia',
+      algolia && require.resolve('@docusaurus/theme-search-algolia'),
     ],
     plugins: [
-      ['@docusaurus/plugin-content-docs', opts.docs],
-      ['@docusaurus/plugin-content-blog', opts.blog],
-      ['@docusaurus/plugin-content-pages', opts.pages],
-      isProd && googleAnalytics && '@docusaurus/plugin-google-analytics',
-      isProd && gtag && '@docusaurus/plugin-google-gtag',
-      isProd && ['@docusaurus/plugin-sitemap', opts.sitemap],
+      [require.resolve('@docusaurus/plugin-content-docs'), opts.docs],
+      [require.resolve('@docusaurus/plugin-content-blog'), opts.blog],
+      [require.resolve('@docusaurus/plugin-content-pages'), opts.pages],
+      isProd &&
+        googleAnalytics &&
+        require.resolve('@docusaurus/plugin-google-analytics'),
+      isProd && gtag && require.resolve('@docusaurus/plugin-google-gtag'),
+      isProd && [require.resolve('@docusaurus/plugin-sitemap'), opts.sitemap],
     ],
   };
 };

packages/docusaurus-theme-bootstrap/package.json

@@ -17,8 +17,7 @@
   "peerDependencies": {
     "@docusaurus/core": "^2.0.0",
     "react": "^16.8.4",
-    "react-dom": "^16.8.4",
-    "webpack": "^4.41.2"
+    "react-dom": "^16.8.4"
   },
   "engines": {
     "node": ">=10.9.0"

packages/docusaurus-theme-bootstrap/src/index.js

@@ -14,7 +14,7 @@ module.exports = function () {
       return path.resolve(__dirname, './theme');
     },
     getClientModules() {
-      return ['bootstrap/dist/css/bootstrap.min.css'];
+      return [require.resolve('bootstrap/dist/css/bootstrap.min.css')];
     },
   };
 };

packages/docusaurus-theme-classic/package.json

@@ -16,14 +16,14 @@
     "parse-numeric-range": "^0.0.2",
     "prism-react-renderer": "^1.1.0",
     "prismjs": "^1.20.0",
+    "prop-types": "^15.7.2",
     "react-router-dom": "^5.1.2",
     "react-toggle": "^4.1.1"
   },
   "peerDependencies": {
     "@docusaurus/core": "^2.0.0",
     "react": "^16.8.4",
-    "react-dom": "^16.8.4",
-    "webpack": "^4.41.2"
+    "react-dom": "^16.8.4"
   },
   "engines": {
     "node": ">=10.9.0"

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

@@ -6,7 +6,15 @@
  */
 
 const path = require('path');
-const ContextReplacementPlugin = require('webpack/lib/ContextReplacementPlugin');
+const Module = require('module');
+
+const createRequire = Module.createRequire || Module.createRequireFromPath;
+const requireFromDocusaurusCore = createRequire(
+  require.resolve('@docusaurus/core/package.json'),
+);
+const ContextReplacementPlugin = requireFromDocusaurusCore(
+  'webpack/lib/ContextReplacementPlugin',
+);
 
 // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
@@ -57,7 +65,7 @@ module.exports = function (context, options) {
 
     getClientModules() {
       const modules = [
-        'infima/dist/css/default/default.css',
+        require.resolve('infima/dist/css/default/default.css'),
         path.resolve(__dirname, './prism-include-languages'),
       ];
 

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

@@ -5,44 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState, useEffect} from 'react';
+import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useAnnouncementBarContext from '@theme/hooks/useAnnouncementBarContext';
 
 import styles from './styles.module.css';
 
-const STORAGE_DISMISS_KEY = 'docusaurus.announcement.dismiss';
-const STORAGE_ID_KEY = 'docusaurus.announcement.id';
-
 function AnnouncementBar() {
   const {
     siteConfig: {themeConfig: {announcementBar = {}}} = {},
   } = useDocusaurusContext();
-  const {id, content, backgroundColor, textColor} = announcementBar;
-  const [isClosed, setClosed] = useState(true);
-  const handleClose = () => {
-    localStorage.setItem(STORAGE_DISMISS_KEY, true);
-    setClosed(true);
-  };
+  const {content, backgroundColor, textColor} = announcementBar;
+  const {
+    isAnnouncementBarClosed,
+    closeAnnouncementBar,
+  } = useAnnouncementBarContext();
 
-  useEffect(() => {
-    const viewedId = localStorage.getItem(STORAGE_ID_KEY);
-    const isNewAnnouncement = id !== viewedId;
-
-    localStorage.setItem(STORAGE_ID_KEY, id);
-
-    if (isNewAnnouncement) {
-      localStorage.setItem(STORAGE_DISMISS_KEY, false);
-    }
-
-    if (
-      isNewAnnouncement ||
-      localStorage.getItem(STORAGE_DISMISS_KEY) === 'false'
-    ) {
-      setClosed(false);
-    }
-  }, []);
-
-  if (!content || isClosed) {
+  if (!content || isAnnouncementBarClosed) {
     return null;
   }
 
@@ -59,7 +38,7 @@ function AnnouncementBar() {
       <button
         type="button"
         className={styles.announcementBarClose}
-        onClick={handleClose}
+        onClick={closeAnnouncementBar}
         aria-label="Close">
         <span aria-hidden="true">&times;</span>
       </button>

packages/docusaurus-theme-classic/src/theme/AnnouncementBar/styles.module.css

@@ -5,13 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+:root {
+  --docusaurus-announcement-bar-height: auto;
+}
+
 .announcementBar {
   position: relative;
   width: 100%;
+  height: var(--docusaurus-announcement-bar-height);
   background-color: var(--ifm-color-primary);
   color: var(--ifm-color-black);
 }
 
+@media screen and (min-width: 1024px) {
+  :root {
+    --docusaurus-announcement-bar-height: 30px;
+  }
+}
+
 .announcementBarClose {
   position: absolute;
   right: 0;

packages/docusaurus-theme-classic/src/theme/AnnouncementBarContext.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {createContext} from 'react';
+
+const AnnouncementBarContext = createContext({
+  isAnnouncementBarClosed: false,
+  closeAnnouncementBar: () => {},
+});
+
+export default AnnouncementBarContext;

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

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+import AnnouncementBarContext from '@theme/AnnouncementBarContext';
+import useAnnouncementBar from '@theme/hooks/useAnnouncementBar';
+
+function AnnouncementBarProvider(props) {
+  const {isAnnouncementBarClosed, closeAnnouncementBar} = useAnnouncementBar();
+
+  return (
+    <AnnouncementBarContext.Provider
+      value={{isAnnouncementBarClosed, closeAnnouncementBar}}>
+      {props.children}
+    </AnnouncementBarContext.Provider>
+  );
+}
+
+export default AnnouncementBarProvider;

packages/docusaurus-theme-classic/src/theme/DocItem/styles.module.css

@@ -7,14 +7,7 @@
 
 .docTitle {
   font-size: 3rem;
-  margin-bottom: 3rem;
-}
-
-@media only screen and (max-width: 996px) {
-  .docTitle {
-    font-size: 2rem;
-    margin-bottom: 2rem;
-  }
+  margin-bottom: calc(var(--ifm-leading-desktop) * var(--ifm-leading));
 }
 
 .docItemContainer {

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

@@ -8,8 +8,10 @@
 import React, {useState, useCallback} from 'react';
 import classnames from 'classnames';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useAnnouncementBarContext from '@theme/hooks/useAnnouncementBarContext';
 import useLockBodyScroll from '@theme/hooks/useLockBodyScroll';
 import useLogo from '@theme/hooks/useLogo';
+import useScrollPosition from '@theme/hooks/useScrollPosition';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 
@@ -134,6 +136,8 @@ function DocSidebar(props) {
     isClient,
   } = useDocusaurusContext();
   const {logoLink, logoLinkProps, logoImageUrl, logoAlt} = useLogo();
+  const {isAnnouncementBarClosed} = useAnnouncementBarContext();
+  const {scrollY} = useScrollPosition();
 
   const {
     docsSidebars,
@@ -163,7 +167,10 @@ function DocSidebar(props) {
   }
 
   return (
-    <div className={styles.sidebar}>
+    <div
+      className={classnames(styles.sidebar, {
+        [styles.sidebarWithHideableNavbar]: hideOnScroll,
+      })}>
       {hideOnScroll && (
         <Link
           tabIndex="-1"
@@ -179,6 +186,8 @@ function DocSidebar(props) {
       <div
         className={classnames('menu', 'menu--responsive', styles.menu, {
           'menu--show': showResponsiveSidebar,
+          [styles.menuWithAnnouncementBar]:
+            !isAnnouncementBarClosed && scrollY === 0,
         })}>
         <button
           aria-label={showResponsiveSidebar ? 'Close Menu' : 'Open Menu'}

packages/docusaurus-theme-classic/src/theme/DocSidebar/styles.module.css

@@ -7,6 +7,8 @@
 
 @media (min-width: 997px) {
   .sidebar {
+    display: flex;
+    flex-direction: column;
     height: 100vh;
     overflow-y: auto;
     position: sticky;
@@ -14,6 +16,10 @@
     padding-top: var(--ifm-navbar-height);
   }
 
+  .sidebarWithHideableNavbar {
+    padding-top: 0;
+  }
+
   .sidebar::-webkit-scrollbar {
     width: 7px;
   }
@@ -35,10 +41,9 @@
   .sidebarLogo {
     display: flex !important;
     align-items: center;
-    position: absolute;
-    top: 0;
     margin: 0 var(--ifm-navbar-padding-horizontal);
-    height: var(--ifm-navbar-height);
+    min-height: var(--ifm-navbar-height);
+    max-height: var(--ifm-navbar-height);
     color: inherit !important;
     text-decoration: none !important;
   }
@@ -49,8 +54,13 @@
   }
 
   .menu {
+    flex-grow: 1;
     padding: 0.5rem;
   }
+
+  .menuWithAnnouncementBar {
+    margin-bottom: var(--docusaurus-announcement-bar-height);
+  }
 }
 
 .sidebarLogo {

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

@@ -13,6 +13,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 import ThemeProvider from '@theme/ThemeProvider';
 import TabGroupChoiceProvider from '@theme/TabGroupChoiceProvider';
+import AnnouncementBarProvider from '@theme/AnnouncementBarProvider';
 import AnnouncementBar from '@theme/AnnouncementBar';
 import Navbar from '@theme/Navbar';
 import Footer from '@theme/Footer';
@@ -50,38 +51,43 @@ function Layout(props) {
   return (
     <ThemeProvider>
       <TabGroupChoiceProvider>
-        <Head>
-          {/* TODO: Do not assume that it is in english language */}
-          <html lang="en" />
+        <AnnouncementBarProvider>
+          <Head>
+            {/* TODO: Do not assume that it is in english language */}
+            <html lang="en" />
 
-          {metaTitle && <title>{metaTitle}</title>}
-          {metaTitle && <meta property="og:title" content={metaTitle} />}
-          {favicon && <link rel="shortcut icon" href={faviconUrl} />}
-          {description && <meta name="description" content={description} />}
-          {description && (
-            <meta property="og:description" content={description} />
-          )}
-          {version && <meta name="docsearch:version" content={version} />}
-          {keywords && keywords.length && (
-            <meta name="keywords" content={keywords.join(',')} />
-          )}
-          {metaImage && <meta property="og:image" content={metaImageUrl} />}
-          {metaImage && (
-            <meta property="twitter:image" content={metaImageUrl} />
-          )}
-          {metaImage && (
-            <meta name="twitter:image:alt" content={`Image for ${metaTitle}`} />
-          )}
-          {permalink && (
-            <meta property="og:url" content={siteUrl + permalink} />
-          )}
-          {permalink && <link rel="canonical" href={siteUrl + permalink} />}
-          <meta name="twitter:card" content="summary_large_image" />
-        </Head>
-        <AnnouncementBar />
-        <Navbar />
-        <div className="main-wrapper">{children}</div>
-        {!noFooter && <Footer />}
+            {metaTitle && <title>{metaTitle}</title>}
+            {metaTitle && <meta property="og:title" content={metaTitle} />}
+            {favicon && <link rel="shortcut icon" href={faviconUrl} />}
+            {description && <meta name="description" content={description} />}
+            {description && (
+              <meta property="og:description" content={description} />
+            )}
+            {version && <meta name="docsearch:version" content={version} />}
+            {keywords && keywords.length && (
+              <meta name="keywords" content={keywords.join(',')} />
+            )}
+            {metaImage && <meta property="og:image" content={metaImageUrl} />}
+            {metaImage && (
+              <meta property="twitter:image" content={metaImageUrl} />
+            )}
+            {metaImage && (
+              <meta
+                name="twitter:image:alt"
+                content={`Image for ${metaTitle}`}
+              />
+            )}
+            {permalink && (
+              <meta property="og:url" content={siteUrl + permalink} />
+            )}
+            {permalink && <link rel="canonical" href={siteUrl + permalink} />}
+            <meta name="twitter:card" content="summary_large_image" />
+          </Head>
+          <AnnouncementBar />
+          <Navbar />
+          <div className="main-wrapper">{children}</div>
+          {!noFooter && <Footer />}
+        </AnnouncementBarProvider>
       </TabGroupChoiceProvider>
     </ThemeProvider>
   );

packages/docusaurus-theme-classic/src/theme/Navbar/styles.module.css

@@ -11,7 +11,7 @@
   }
 }
 
-@media (max-width: 360px) {
+@media (max-width: 768px) {
   .hideLogoText {
     display: none;
   }

packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBar.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useState, useEffect} from 'react';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+const STORAGE_DISMISS_KEY = 'docusaurus.announcement.dismiss';
+const STORAGE_ID_KEY = 'docusaurus.announcement.id';
+
+const useAnnouncementBar = () => {
+  const {
+    siteConfig: {
+      themeConfig: {
+        announcementBar: {id},
+      },
+    } = {},
+  } = useDocusaurusContext();
+  const [isClosed, setClosed] = useState(true);
+  const handleClose = () => {
+    localStorage.setItem(STORAGE_DISMISS_KEY, true);
+    setClosed(true);
+  };
+
+  useEffect(() => {
+    const viewedId = localStorage.getItem(STORAGE_ID_KEY);
+    const isNewAnnouncement = id !== viewedId;
+
+    localStorage.setItem(STORAGE_ID_KEY, id);
+
+    if (isNewAnnouncement) {
+      localStorage.setItem(STORAGE_DISMISS_KEY, false);
+    }
+
+    if (
+      isNewAnnouncement ||
+      localStorage.getItem(STORAGE_DISMISS_KEY) === 'false'
+    ) {
+      setClosed(false);
+    }
+  }, []);
+
+  return {
+    isAnnouncementBarClosed: isClosed,
+    closeAnnouncementBar: handleClose,
+  };
+};
+
+export default useAnnouncementBar;

packages/docusaurus-theme-classic/src/theme/hooks/useAnnouncementBarContext.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useContext} from 'react';
+import AnnouncementBarContext from '@theme/AnnouncementBarContext';
+
+function useAnnouncementBarContext() {
+  return useContext(AnnouncementBarContext);
+}
+
+export default useAnnouncementBarContext;

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.js

@@ -12,9 +12,9 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useHistory} from '@docusaurus/router';
 import useSearchQuery from '@theme/hooks/useSearchQuery';
 
-import './styles.css';
+import styles from './styles.module.css';
 
-const Search = (props) => {
+const Search = ({handleSearchBarToggle, isSearchBarExpanded}) => {
   const [algoliaLoaded, setAlgoliaLoaded] = useState(false);
   const searchBarRef = useRef(null);
   const {siteConfig = {}} = useDocusaurusContext();
@@ -35,6 +35,7 @@ const Search = (props) => {
         openOnFocus: true,
         autoselect: false,
         hint: false,
+        tabAutocomplete: false,
       },
       // Override algolia's default selection event, allowing us to do client-side
       // navigation and avoiding a full page refresh.
@@ -76,19 +77,19 @@ const Search = (props) => {
     );
   };
 
-  const handleSearchIcon = useCallback(() => {
+  const toggleSearchInput = useCallback(() => {
     loadAlgolia();
 
     if (algoliaLoaded) {
       searchBarRef.current.focus();
     }
 
-    props.handleSearchBarToggle(!props.isSearchBarExpanded);
-  }, [props.isSearchBarExpanded]);
+    handleSearchBarToggle(!isSearchBarExpanded);
+  }, [isSearchBarExpanded]);
 
   const handleSearchInputBlur = useCallback(() => {
-    props.handleSearchBarToggle(!props.isSearchBarExpanded);
-  }, [props.isSearchBarExpanded]);
+    handleSearchBarToggle(!isSearchBarExpanded);
+  }, [isSearchBarExpanded]);
 
   const handleSearchInput = useCallback((e) => {
     const needFocus = e.type !== 'mouseover';
@@ -104,32 +105,33 @@ const Search = (props) => {
 
   return (
     <div className="navbar__search" key="search-box">
-      <span
-        aria-label="expand searchbar"
-        role="button"
-        className={classnames('search-icon', {
-          'search-icon-hidden': props.isSearchBarExpanded,
-        })}
-        onClick={handleSearchIcon}
-        onKeyDown={handleSearchIcon}
-        tabIndex={0}
-      />
-      <input
-        id="search_input_react"
-        type="search"
-        placeholder="Search"
-        aria-label="Search"
-        className={classnames(
-          'navbar__search-input',
-          {'search-bar-expanded': props.isSearchBarExpanded},
-          {'search-bar': !props.isSearchBarExpanded},
-        )}
-        onMouseOver={handleSearchInput}
-        onFocus={handleSearchInput}
-        onBlur={handleSearchInputBlur}
-        onKeyDown={handleSearchInputPressEnter}
-        ref={searchBarRef}
-      />
+      <div className={styles.searchWrapper}>
+        <span
+          aria-label="expand searchbar"
+          role="button"
+          className={classnames(styles.searchIconButton, {
+            [styles.searchIconButtonHidden]: isSearchBarExpanded,
+          })}
+          onClick={toggleSearchInput}
+          onKeyDown={toggleSearchInput}
+          tabIndex={0}
+        />
+
+        <input
+          id="search_input_react"
+          type="search"
+          placeholder="Search"
+          aria-label="Search"
+          className={classnames('navbar__search-input', styles.searchInput, {
+            [styles.searchInputExpanded]: isSearchBarExpanded,
+          })}
+          onMouseOver={handleSearchInput}
+          onFocus={handleSearchInput}
+          onBlur={handleSearchInputBlur}
+          onKeyDown={handleSearchInputPressEnter}
+          ref={searchBarRef}
+        />
+      </div>
     </div>
   );
 };

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/styles.css

@@ -1,40 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-.search-icon {
-  background-image: var(--ifm-navbar-search-input-icon);
-  height: auto;
-  width: 24px;
-  cursor: pointer;
-  padding: 8px;
-  line-height: 32px;
-  background-repeat: no-repeat;
-  background-position: center;
-  display: none;
-}
-
-.search-icon-hidden {
-  visibility: hidden;
-}
-
-@media (max-width: 360px) {
-  .search-bar {
-    width: 0 !important;
-    background: none !important;
-    padding: 0 !important;
-    transition: none !important;
-  }
-
-  .search-bar-expanded {
-    width: 9rem !important;
-  }
-
-  .search-icon {
-    display: inline;
-    vertical-align: sub;
-  }
-}

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/styles.module.css

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.searchIconButton {
+  display: none;
+}
+
+@media (min-width: 769px) and (max-width: 996px) {
+  :global(.navbar__search),
+  :global(.navbar__search-input) {
+    width: 100%;
+  }
+}
+
+@media (max-width: 768px) {
+  .searchIconButton {
+    display: block;
+    position: absolute;
+    right: 0;
+    width: 2.75rem;
+    height: 2rem;
+    z-index: 1;
+  }
+
+  .searchIconButtonHidden {
+    visibility: hidden;
+  }
+
+  :global(.navbar__items:first-of-type) {
+    flex: 0 1 auto;
+  }
+
+  :global(.navbar__inner) {
+    position: relative;
+  }
+
+  :global(.navbar__search) {
+    position: relative;
+    flex: 1 1 auto;
+    padding-left: 0;
+  }
+
+  .searchWrapper {
+    position: absolute;
+    top: calc(var(--ifm-navbar-padding-vertical) * 2 * -1);
+    width: 100%;
+    display: flex;
+    justify-content: flex-end;
+  }
+
+  .searchInput {
+    width: 0;
+    transition: width 0.3s ease-in-out;
+  }
+
+  .searchInputExpanded {
+    width: 100%;
+  }
+}
+
+:global(.algolia-autocomplete) {
+  width: 100%;
+  display: flex !important;
+  justify-content: flex-end;
+}

packages/docusaurus/package.json

@@ -69,6 +69,7 @@
     "nprogress": "^0.2.0",
     "null-loader": "^3.0.0",
     "optimize-css-assets-webpack-plugin": "^5.0.3",
+    "pnp-webpack-plugin": "^1.6.4",
     "portfinder": "^1.0.25",
     "postcss-loader": "^3.0.0",
     "postcss-preset-env": "^6.7.0",

packages/docusaurus/src/client/exports/Link.tsx

@@ -84,7 +84,11 @@ function Link({isNavLink, ...props}: Props) {
 
   return !targetLink || !isInternal || targetLink.startsWith('#') ? (
     // eslint-disable-next-line jsx-a11y/anchor-has-content
-    <a {...props} href={targetLink} />
+    <a
+      href={targetLink}
+      {...(!isInternal && {target: '_blank', rel: 'noopener noreferrer'})}
+      {...props}
+    />
   ) : (
     <LinkComponent
       {...props}

packages/docusaurus/src/server/plugins/init.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import Module from 'module';
 import importFresh from 'import-fresh';
 import {LoadContext, Plugin, PluginConfig} from '@docusaurus/types';
 
@@ -15,9 +16,16 @@ export function initPlugins({
   pluginConfigs: PluginConfig[];
   context: LoadContext;
 }): Plugin<any>[] {
+  // We need to resolve plugins from the perspective of the siteDir, since the siteDir's package.json
+  // declares the dependency on these plugins.
+  // We need to fallback to createRequireFromPath since createRequire is only available in node v12.
+  // See: https://nodejs.org/api/modules.html#modules_module_createrequire_filename
+  const createRequire = Module.createRequire || Module.createRequireFromPath;
+  const pluginRequire = createRequire(context.siteDir);
+
   const plugins: Plugin<any>[] = pluginConfigs
     .map((pluginItem) => {
-      let pluginModuleImport;
+      let pluginModuleImport: string | undefined;
       let pluginOptions = {};
 
       if (!pluginItem) {
@@ -37,7 +45,9 @@ export function initPlugins({
 
       // The pluginModuleImport value is any valid
       // module identifier - npm package or locally-resolved path.
-      const pluginModule: any = importFresh(pluginModuleImport);
+      const pluginModule: any = importFresh(
+        pluginRequire.resolve(pluginModuleImport),
+      );
       return (pluginModule.default || pluginModule)(context, pluginOptions);
     })
     .filter(Boolean);

packages/docusaurus/src/webpack/base.ts

@@ -8,6 +8,7 @@
 import fs from 'fs-extra';
 import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import OptimizeCSSAssetsPlugin from 'optimize-css-assets-webpack-plugin';
+import PnpWebpackPlugin from 'pnp-webpack-plugin';
 import path from 'path';
 import TerserPlugin from 'terser-webpack-plugin';
 import {Configuration, Loader} from 'webpack';
@@ -74,6 +75,10 @@ export function createBaseConfig(
         'node_modules',
         path.resolve(fs.realpathSync(process.cwd()), 'node_modules'),
       ],
+      plugins: [PnpWebpackPlugin],
+    },
+    resolveLoader: {
+      plugins: [PnpWebpackPlugin.moduleLoader(module)],
     },
     optimization: {
       removeAvailableModules: false,

packages/docusaurus/src/webpack/utils.ts

@@ -100,7 +100,7 @@ export function getBabelLoader(isServer: boolean, babelOptions?: {}): Loader {
         presets: [
           isServer
             ? [
-                '@babel/env',
+                require.resolve('@babel/preset-env'),
                 {
                   targets: {
                     node: 'current',
@@ -108,7 +108,7 @@ export function getBabelLoader(isServer: boolean, babelOptions?: {}): Loader {
                 },
               ]
             : [
-                '@babel/env',
+                require.resolve('@babel/preset-env'),
                 {
                   useBuiltIns: 'usage',
                   loose: true,
@@ -119,14 +119,14 @@ export function getBabelLoader(isServer: boolean, babelOptions?: {}): Loader {
                   exclude: ['transform-typeof-symbol'],
                 },
               ],
-          '@babel/react',
-          '@babel/preset-typescript',
+          require.resolve('@babel/preset-react'),
+          require.resolve('@babel/preset-typescript'),
         ],
         plugins: [
           // Polyfills the runtime needed for async/await, generators, and friends
           // https://babeljs.io/docs/en/babel-plugin-transform-runtime
           [
-            '@babel/plugin-transform-runtime',
+            require.resolve('@babel/plugin-transform-runtime'),
             {
               corejs: false,
               helpers: true,
@@ -143,7 +143,9 @@ export function getBabelLoader(isServer: boolean, babelOptions?: {}): Loader {
             },
           ],
           // Adds syntax support for import()
-          isServer ? 'dynamic-import-node' : '@babel/syntax-dynamic-import',
+          isServer
+            ? require.resolve('babel-plugin-dynamic-import-node')
+            : require.resolve('@babel/plugin-syntax-dynamic-import'),
         ],
       },
       babelOptions,

website/docs/contributing.md

@@ -3,7 +3,7 @@ id: contributing
 title: Contributing
 ---
 
-[Docusaurus 2](https://v2.docusaurus.io) is currently under alpha development. We have [early adopters who already started using it](/showcase). We are now welcoming contributors to collaborate on the next Docusaurus.
+[Docusaurus 2](https://v2.docusaurus.io/) is currently under alpha development. We have [early adopters who already started using it](/showcase). We are now welcoming contributors to collaborate on the next Docusaurus.
 
 The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful:
 
@@ -48,7 +48,7 @@ We use [GitHub Issues](https://github.com/facebook/docusaurus/issues) for our pu
 
 If you have questions about using Docusaurus, contact the Docusaurus Twitter account at [@docusaurus](https://twitter.com/docusaurus), and we will do our best to answer your questions.
 
-You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md)
+You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md/)
 
 ### Reporting security bugs
 
@@ -97,7 +97,7 @@ Use lower case not title case!
 
 #### Style guide
 
-[Prettier](https://prettier.io) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`.
+[Prettier](https://prettier.io/) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`.
 
 However, there are still some styles that Prettier cannot pick up.
 
@@ -124,7 +124,7 @@ We have a list of [beginner friendly issues](https://github.com/facebook/docusau
 
 ### Proposing a change
 
-If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md).
+If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md/).
 
 If you intend to change the public API (e.g., something in `docusaurus.config.js`), or make any non-trivial changes to the implementation, we recommend filing an issue with [proposal template](https://github.com/facebook/docusaurus/issues/new?template=proposal.md) and including `[Proposal]` in the title. This lets us reach an agreement on your proposal before you put significant effort into it. These types of issues should be rare.
 
@@ -138,7 +138,7 @@ Please make sure the following is done when submitting a pull request:
 
 1. Fork [the repository](https://github.com/facebook/docusaurus) and create your branch from `master`.
 1. Add the copyright notice to the top of any code new files you've added.
-1. Describe your [test plan](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md)!
+1. Describe your [test plan](#test-plan) in your pull request description. Make sure to [test your changes](https://github.com/facebook/docusaurus/blob/master/admin/testing-changes-on-Docusaurus-itself.md/)!
 1. Make sure your code lints (`yarn prettier && yarn lint`).
 1. Make sure your Jest tests pass (`yarn test`).
 1. If you haven't already, [sign the CLA](https://code.facebook.com/cla).

website/docs/docusaurus-core.md

@@ -73,7 +73,7 @@ const Page = () => (
       Check out my <Link to="/blog">blog</Link>!
     </p>
     <p>
-      {/* Note that external links still use `a` tags. */}
+      {/* Note that external links still use `a` tags, but automatically opens in new tab. */}
       Follow me on <a href="https://twitter.com/docusaurus">Twitter</a>!
     </p>
   </div>

website/docs/markdown-features.mdx

@@ -140,7 +140,7 @@ One benefit of this approach is that the links to external files will still work
 
 ## Embedding React components with MDX
 
-Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components.
+Docusaurus has built-in support for [MDX](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components.
 
 **Note 1:** While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. Let's rename the previous file to `greeting.mdx`.
 

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

@@ -456,8 +456,8 @@ Please refer to [creating pages](creating-pages.md) to learn how Docusaurus 2 pa
 
 The following code could be helpful for migration of various pages:
 
-- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js)
-- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js), [Flux](http://facebook.github.io/flux/support)
+- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/)
+- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support)
 
 ## Content
 

website/docs/presets.md

@@ -40,8 +40,11 @@ Presets in some way are a shorthand function to add plugins and themes to your d
 ```js
 module.exports = function preset(context, opts = {}) {
   return {
-    themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
-    plugins: ['@docusaurus/plugin-blog'],
+    themes: [
+      require.resolve('@docusaurus/themes-cool'),
+      require.resolve('@docusaurus/themes-bootstrap'),
+    ],
+    plugins: [require.resolve('@docusaurus/plugin-blog')],
   };
 };
 ```

website/docs/resources.md

@@ -9,6 +9,10 @@ A curated list of interesting Docusaurus community projects.
 
 - [F8 2019: Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE)
 
+## Articles
+
+- [Live code editing in Docusaurus](https://dev.to/mrmuhammadali/live-code-editing-in-docusaurus-28k)
+
 ## Showcase
 
 See the <a href={require('@docusaurus/useBaseUrl').default('showcase')}>showcase</a>.

website/docs/using-plugins.md

@@ -145,36 +145,42 @@ module.exports = {
       '@docusaurus/plugin-content-blog',
       {
         /**
-         * Path to data on filesystem
-         * relative to site dir
+         * Path to data on filesystem relative to site dir.
          */
         path: 'blog',
         /**
-         * URL for editing a blog post, example: 'https://github.com/facebook/docusaurus/edit/master/website/blog/'
+         * URL for editing a blog post.
+         * Example: 'https://github.com/facebook/docusaurus/edit/master/website/blog/'
          */
         editUrl:
           'https://github.com/facebook/docusaurus/edit/master/website/blog/',
         /**
-         * URL route for the blog section of your site
-         * do not include trailing slash
+         * URL route for the blog section of your site.
+         * *DO NOT* include a trailing slash.
          */
         routeBasePath: 'blog',
         include: ['*.md', '*.mdx'],
         postsPerPage: 10,
         /**
-         * Theme components used by the blog pages
+         * Theme components used by the blog pages.
          */
         blogListComponent: '@theme/BlogListPage',
         blogPostComponent: '@theme/BlogPostPage',
         blogTagsListComponent: '@theme/BlogTagsListPage',
         blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
         /**
-         * Remark and Rehype plugins passed to MDX
+         * Remark and Rehype plugins passed to MDX.
          */
         remarkPlugins: [
           /* require('remark-math') */
         ],
         rehypePlugins: [],
+        /**
+         * Custom Remark and Rehype plugins passed to MDX before
+         * the default Docusaurus Remark and Rehype plugins.
+         */
+        beforeDefaultRemarkPlugins: [],
+        beforeDefaultRehypePlugins: [],
         /**
          * Truncate marker, can be a regex or string.
          */
@@ -184,8 +190,8 @@ module.exports = {
          */
         showReadingTime: true,
         /**
-         * Blog feed
-         * If feedOptions is undefined, no rss feed will be generated
+         * Blog feed.
+         * If feedOptions is undefined, no rss feed will be generated.
          */
         feedOptions: {
           type: '', // required. 'rss' | 'feed' | 'all'
@@ -223,17 +229,17 @@ module.exports = {
       '@docusaurus/plugin-content-docs',
       {
         /**
-         * Path to data on filesystem
-         * relative to site dir
+         * Path to data on filesystem relative to site dir.
          */
         path: 'docs',
         /**
-         * URL for editing website repo, example: 'https://github.com/facebook/docusaurus/edit/master/website/'
+         * URL for editing a doc in the website repo.
+         * Example: 'https://github.com/facebook/docusaurus/edit/master/website/'
          */
         editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
         /**
-         * URL route for the blog section of your site
-         * do not include trailing slash
+         * URL route for the blog section of your site.
+         * *DO NOT* include a trailing slash.
          */
         routeBasePath: 'docs',
         homePageId: '_index', // Document id for docs home page.
@@ -255,6 +261,12 @@ module.exports = {
           /* require('remark-math') */
         ],
         rehypePlugins: [],
+        /**
+         * Custom Remark and Rehype plugins passed to MDX before
+         * the default Docusaurus Remark and Rehype plugins.
+         */
+        beforeDefaultRemarkPlugins: [],
+        beforeDefaultRehypePlugins: [],
         /**
          * Whether to display the author who last updated the doc.
          */

website/package.json

@@ -10,6 +10,7 @@
   },
   "dependencies": {
     "@docusaurus/core": "^2.0.0-alpha.55",
+    "@docusaurus/theme-live-codeblock": "^2.0.0-alpha.55",
     "@docusaurus/plugin-ideal-image": "^2.0.0-alpha.55",
     "@docusaurus/plugin-client-redirects": "^2.0.0-alpha.55",
     "@docusaurus/preset-classic": "^2.0.0-alpha.55",

yarn.lock

@@ -13045,6 +13045,13 @@ pngjs@^3.0.0, pngjs@^3.3.3:
   resolved "https://registry.yarnpkg.com/pngjs/-/pngjs-3.4.0.tgz#99ca7d725965fb655814eaf65f38f12bbdbf555f"
   integrity sha512-NCrCHhWmnQklfH4MtJMRjZ2a8c80qXeMlQMv2uVp9ISJMTt562SbGd6n2oq0PaPgKm7Z6pL9E2UlLIhC+SHL3w==
 
+pnp-webpack-plugin@^1.6.4:
+  version "1.6.4"
+  resolved "https://registry.yarnpkg.com/pnp-webpack-plugin/-/pnp-webpack-plugin-1.6.4.tgz#c9711ac4dc48a685dabafc86f8b6dd9f8df84149"
+  integrity sha512-7Wjy+9E3WwLOEL30D+m8TSTF7qJJUJLONBnwQp0518siuMxUQUbgZwssaFX+QKlZkjHZcw/IpZCt/H0srrntSg==
+  dependencies:
+    ts-pnp "^1.1.6"
+
 popper.js@^1.14.4:
   version "1.16.1"
   resolved "https://registry.yarnpkg.com/popper.js/-/popper.js-1.16.1.tgz#2a223cb3dc7b6213d740e40372be40de43e65b1b"
@@ -16973,6 +16980,11 @@ tryer@^1.0.1:
   resolved "https://registry.yarnpkg.com/tryer/-/tryer-1.0.1.tgz#f2c85406800b9b0f74c9f7465b81eaad241252f8"
   integrity sha512-c3zayb8/kWWpycWYg87P71E1S1ZL6b6IJxfb5fvsUgsf0S2MVGaDhDXXjDMpdCpfWXqptc+4mXwmiy1ypXqRAA==
 
+ts-pnp@^1.1.6:
+  version "1.2.0"
+  resolved "https://registry.yarnpkg.com/ts-pnp/-/ts-pnp-1.2.0.tgz#a500ad084b0798f1c3071af391e65912c86bca92"
+  integrity sha512-csd+vJOb/gkzvcCHgTGSChYpy5f1/XKNsmvBGO4JXS+z1v2HobugDz4s1IeFXM3wZB44uczs+eazB5Q/ccdhQw==
+
 tslib@^1.10.0, tslib@^1.9.0:
   version "1.11.1"
   resolved "https://registry.yarnpkg.com/tslib/-/tslib-1.11.1.tgz#eb15d128827fbee2841549e171f45ed338ac7e35"