refactor(v2): load sidebars from docs plugin (#1328)

* refactor(v2): load sidebars from docs plugin

* fix(v2): update tests

* fix(v2): change to sidebarPath

packages/docusaurus-plugin-content-docs/__tests__/index.test.js

@@ -11,11 +11,13 @@ import loadSetup from '../../docusaurus/test/loadSetup';
 import DocusaurusPluginContentDocs from '../index';
 
 describe('loadDocs', () => {
-  test.only('simple website', async () => {
+  test('simple website', async () => {
     const {env, siteDir, siteConfig} = await loadSetup('simple');
+    const sidebarPath = path.join(siteDir, 'sidebars.json');
     const plugin = new DocusaurusPluginContentDocs(
       {
         path: '../docs',
+        sidebarPath,
       },
       {
         env,
@@ -60,9 +62,11 @@ describe('loadDocs', () => {
     const {env, siteDir, siteConfig, versionedDir} = await loadSetup(
       'versioned',
     );
+    const sidebarPath = path.join(siteDir, 'sidebars.json');
     const plugin = new DocusaurusPluginContentDocs(
       {
         path: '../docs',
+        sidebarPath,
       },
       {
         env,
@@ -111,9 +115,11 @@ describe('loadDocs', () => {
       translatedDir,
       versionedDir,
     } = await loadSetup('transversioned');
+    const sidebarPath = path.join(siteDir, 'sidebars.json');
     const plugin = new DocusaurusPluginContentDocs(
       {
         path: '../docs',
+        sidebarPath,
       },
       {
         env,
@@ -175,9 +181,11 @@ describe('loadDocs', () => {
     const {env, siteDir, siteConfig, translatedDir} = await loadSetup(
       'translated',
     );
+    const sidebarPath = path.join(siteDir, 'sidebars.json');
     const plugin = new DocusaurusPluginContentDocs(
       {
         path: '../docs',
+        sidebarPath,
       },
       {
         env,
@@ -225,15 +233,19 @@ describe('loadDocs', () => {
     const {env, siteDir, siteConfig, versionedDir} = await loadSetup(
       'versioned',
     );
+    const sidebarPath = path.join(siteDir, 'sidebars.json');
     const plugin = new DocusaurusPluginContentDocs(
       {
         path: '../docs',
+        sidebarPath,
       },
       {
+        cliOptions: {
+          skipNextRelease: true,
+        },
         env,
         siteDir,
         siteConfig,
-        cliOptions: {skipNextRelease: true},
       },
     );
     const {docs: docsMetadata} = await plugin.loadContent();

packages/docusaurus-plugin-content-docs/__tests__/sidebars.test.js

@@ -9,24 +9,29 @@ import path from 'path';
 import loadSidebars from '../src/sidebars';
 import loadSetup from '../../docusaurus/test/loadSetup';
 
+/* eslint-disable global-require, import/no-dynamic-require */
+
 describe('loadSidebars', () => {
   const fixtures = path.join(__dirname, '..', '__fixtures__');
+
   test('normal site with sidebars', async () => {
     const {env, siteDir} = await loadSetup('simple');
-    const result = loadSidebars({siteDir, env});
+    const sidebar = require(path.join(siteDir, 'sidebars.json'));
+    const result = loadSidebars({siteDir, env, sidebar});
     expect(result).toMatchSnapshot();
   });
 
   test('site without sidebars', () => {
     const env = {};
     const siteDir = path.join(fixtures, 'bad-site');
-    const result = loadSidebars({siteDir, env});
+    const result = loadSidebars({siteDir, env, sidebar: {}});
     expect(result).toMatchSnapshot();
   });
 
   test('site with sidebars & versioned sidebars', async () => {
     const {env, siteDir} = await loadSetup('versioned');
-    const result = loadSidebars({siteDir, env});
+    const sidebar = require(path.join(siteDir, 'sidebars.json'));
+    const result = loadSidebars({siteDir, env, sidebar});
     expect(result).toMatchSnapshot();
   });
 
@@ -39,7 +44,7 @@ describe('loadSidebars', () => {
     };
     const {siteDir} = await loadSetup('versioned');
     expect(() => {
-      loadSidebars({siteDir, env});
+      loadSidebars({siteDir, env, sidebar: {}});
     }).toThrowErrorMatchingInlineSnapshot(
       `"Failed to load versioned_sidebars/version-2.0.0-sidebars.json. It does not exist."`,
     );

packages/docusaurus-plugin-content-docs/index.js

@@ -5,9 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-const path = require('path');
 const globby = require('globby');
+const importFresh = require('import-fresh');
+const path = require('path');
 const {getSubFolder, idx, normalizeUrl} = require('@docusaurus/utils');
+
 const createOrder = require('./src/order');
 const loadSidebars = require('./src/sidebars');
 const processMetadata = require('./src/metadata');
@@ -18,8 +20,8 @@ const DEFAULT_OPTIONS = {
   path: 'docs', // Path to data on filesystem, relative to site dir.
   routeBasePath: 'docs', // URL Route.
   include: ['**/*.md', '**/*.mdx'], // Extensions to include.
-  // TODO: Read from props rather than hardcoded sidebar.json.
+  // TODO: Change format to array.
-  sidebar: [], // Sidebar configuration for showing a list of documentation pages.
+  sidebarPath: '', // Path to sidebar configuration for showing a list of markdown pages.
   // TODO: Settle themeing.
   docLayoutComponent: '@theme/Doc',
   docItemComponent: '@theme/DocBody',
@@ -37,18 +39,19 @@ class DocusaurusPluginContentDocs {
   }
 
   getPathsToWatch() {
-    return [this.contentPath];
+    return [this.contentPath, this.options.sidebarPath];
   }
 
   // Fetches blog contents and returns metadata for the contents.
   async loadContent() {
-    const {include, routeBasePath} = this.options;
+    const {include, routeBasePath, sidebarPath} = this.options;
     const {siteDir, env, siteConfig, cliOptions = {}} = this.context;
     const {skipNextRelease} = cliOptions;
     const docsDir = this.contentPath;
 
-    // @tested - load all sidebars including versioned sidebars
+    // We don't want sidebars to be cached because of hotreloading.
-    const docsSidebars = loadSidebars({siteDir, env});
+    const sidebar = importFresh(sidebarPath);
+    const docsSidebars = loadSidebars({siteDir, env, sidebar});
 
     // @tested - build the docs ordering such as next, previous, category and sidebar
     const order = createOrder(docsSidebars);

packages/docusaurus-plugin-content-docs/package.json

@@ -8,7 +8,8 @@
     "@babel/polyfill": "^7.4.0",
     "@docusaurus/utils": "^1.0.0",
     "fs-extra": "^7.0.1",
-    "globby": "^9.1.0"
+    "globby": "^9.1.0",
+    "import-fresh": "^3.0.0"
   },
   "peerDependencies": {
     "@docusaurus/core": "^2.0.0"

packages/docusaurus-plugin-content-docs/src/sidebars.js

@@ -113,19 +113,10 @@ function normalizeSidebar(sidebars) {
   }, {});
 }
 
-module.exports = function loadSidebars({siteDir, env}, deleteCache = true) {
+module.exports = function loadSidebars({siteDir, env, sidebar}) {
-  let allSidebars = {};
+  const allSidebars = sidebar;
 
-  // current sidebars
+  // Versioned sidebars.
-  const sidebarsJSONFile = path.join(siteDir, 'sidebars.json');
-  if (deleteCache) {
-    delete require.cache[sidebarsJSONFile];
-  }
-  if (fs.existsSync(sidebarsJSONFile)) {
-    allSidebars = require(sidebarsJSONFile); // eslint-disable-line
-  }
-
-  // versioned sidebars
   if (idx(env, ['versioning', 'enabled'])) {
     const versions = idx(env, ['versioning', 'versions']);
     if (Array.isArray(versions)) {

packages/docusaurus/CHANGES.md

@@ -4,5 +4,6 @@
 
 - `siteConfig.js` renamed to `docusaurus.config.js`.
 - Removed the following config options:
-  - `docsUrl`. Use the plugin option on `docusaurus-plugin-content-blog` instead.
+  - `docsUrl`. Use the plugin option on `docusaurus-plugin-content-docs` instead.
-  - `customDocsPath`. Use the plugin option on `docusaurus-plugin-content-blog` instead.
+  - `customDocsPath`. Use the plugin option on `docusaurus-plugin-content-docs` instead.
+  - `sidebars.json` now has to be explicitly loaded by users and passed into the the plugin option on `docusaurus-plugin-content-docs`.

packages/docusaurus/lib/commands/start.js

@@ -54,7 +54,7 @@ module.exports = async function start(siteDir, cliOptions = {}) {
       ),
     );
     const fsWatcher = chokidar.watch(
-      [...pluginPaths, loadConfig.configFileName, 'sidebars.json'],
+      [...pluginPaths, loadConfig.configFileName],
       {
         cwd: siteDir,
         ignoreInitial: true,

packages/docusaurus/test/__fixtures__/custom-site/docusaurus.config.js

@@ -23,6 +23,7 @@ module.exports = {
       name: '@docusaurus/plugin-content-docs',
       options: {
         path: '../docs',
+        sidebarPath: require.resolve('./sidebars.json'),
       },
     },
     {

packages/docusaurus/test/__fixtures__/simple-site/docusaurus.config.js

@@ -23,6 +23,7 @@ module.exports = {
       name: '@docusaurus/plugin-content-docs',
       options: {
         path: '../docs',
+        sidebarPath: require.resolve('./sidebars.json'),
       },
     },
     {

packages/docusaurus/test/__fixtures__/translated-site/docusaurus.config.js

@@ -24,6 +24,7 @@ module.exports = {
       name: '@docusaurus/plugin-content-docs',
       options: {
         path: '../docs',
+        sidebarPath: require.resolve('./sidebars.json'),
       },
     },
     {

packages/docusaurus/test/__fixtures__/transversioned-site/docusaurus.config.js

@@ -24,6 +24,7 @@ module.exports = {
       name: '@docusaurus/plugin-content-docs',
       options: {
         path: '../docs',
+        sidebarPath: require.resolve('./sidebars.json'),
       },
     },
     {

packages/docusaurus/test/__fixtures__/versioned-site/docusaurus.config.js

@@ -23,6 +23,7 @@ module.exports = {
       name: '@docusaurus/plugin-content-docs',
       options: {
         path: '../docs',
+        sidebarPath: require.resolve('./sidebars.json'),
       },
     },
     {

packages/docusaurus/test/load/config.test.js

@@ -13,7 +13,11 @@ describe('loadConfig', () => {
   test('website with valid siteConfig', async () => {
     const {siteDir} = await loadSetup('simple');
     const config = loadConfig(siteDir);
-    expect(config).toMatchInlineSnapshot(`
+    expect(config).toMatchInlineSnapshot(
+      {
+        plugins: expect.any(Array),
+      },
+      `
 Object {
   "baseUrl": "/",
   "favicon": "img/docusaurus.ico",
@@ -32,23 +36,14 @@ Object {
     },
   ],
   "organizationName": "endiliey",
-  "plugins": Array [
+  "plugins": Any<Array>,
-    Object {
-      "name": "@docusaurus/plugin-content-docs",
-      "options": Object {
-        "path": "../docs",
-      },
-    },
-    Object {
-      "name": "@docusaurus/plugin-content-pages",
-    },
-  ],
   "projectName": "hello",
   "tagline": "Hello World",
   "title": "Hello",
   "url": "https://docusaurus.io",
 }
-`);
+`,
+    );
     expect(config).not.toEqual({});
   });
 

website/docusaurus.config.js

@@ -33,6 +33,7 @@ module.exports = {
       name: '@docusaurus/plugin-content-docs',
       options: {
         path: '../docs',
+        sidebarPath: require.resolve('./sidebars.json'),
       },
     },
     {

yarn.lock

@@ -6698,6 +6698,14 @@ import-fresh@^2.0.0:
     caller-path "^2.0.0"
     resolve-from "^3.0.0"
 
+import-fresh@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/import-fresh/-/import-fresh-3.0.0.tgz#a3d897f420cab0e671236897f75bc14b4885c390"
+  integrity sha512-pOnA9tfM3Uwics+SaBLCNyZZZbK+4PTu0OPZtLlMIrv17EdBoC15S9Kn8ckJ9TZTyKb3ywNE5y1yeDxxGA7nTQ==
+  dependencies:
+    parent-module "^1.0.0"
+    resolve-from "^4.0.0"
+
 import-lazy@^3.1.0:
   version "3.1.0"
   resolved "https://registry.yarnpkg.com/import-lazy/-/import-lazy-3.1.0.tgz#891279202c8a2280fdbd6674dbd8da1a1dfc67cc"
@@ -9772,6 +9780,13 @@ param-case@2.1.x, param-case@^2.1.0:
   dependencies:
     no-case "^2.2.0"
 
+parent-module@^1.0.0:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/parent-module/-/parent-module-1.0.1.tgz#691d2709e78c79fae3a156622452d00762caaaa2"
+  integrity sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==
+  dependencies:
+    callsites "^3.0.0"
+
 parse-asn1@^5.0.0:
   version "5.1.4"
   resolved "https://registry.yarnpkg.com/parse-asn1/-/parse-asn1-5.1.4.tgz#37f6628f823fbdeb2273b4d540434a22f3ef1fcc"