feat(v2): docs plugin initial work (#1327)

* feat(v2): pluginify docs

* feat(v2): implement docs plugin

* fix(v2): fix bugs in docs plugin for translation and versioning

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

@@ -0,0 +1,117 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`loadSidebars normal site with sidebars 1`] = `
+Object {
+  "docs": Array [
+    Object {
+      "items": Array [
+        Object {
+          "id": "foo/bar",
+          "type": "doc",
+        },
+        Object {
+          "id": "foo/baz",
+          "type": "doc",
+        },
+      ],
+      "label": "Test",
+      "type": "category",
+    },
+    Object {
+      "items": Array [
+        Object {
+          "id": "hello",
+          "type": "doc",
+        },
+      ],
+      "label": "Guides",
+      "type": "category",
+    },
+  ],
+}
+`;
+
+exports[`loadSidebars site with sidebars & versioned sidebars 1`] = `
+Object {
+  "docs": Array [
+    Object {
+      "items": Array [
+        Object {
+          "id": "foo/bar",
+          "type": "doc",
+        },
+        Object {
+          "id": "foo/baz",
+          "type": "doc",
+        },
+      ],
+      "label": "Test",
+      "type": "category",
+    },
+    Object {
+      "items": Array [
+        Object {
+          "id": "hello",
+          "type": "doc",
+        },
+      ],
+      "label": "Guides",
+      "type": "category",
+    },
+  ],
+  "version-1.0.0-docs": Array [
+    Object {
+      "items": Array [
+        Object {
+          "id": "version-1.0.0-foo/bar",
+          "type": "doc",
+        },
+        Object {
+          "id": "version-1.0.0-foo/baz",
+          "type": "doc",
+        },
+      ],
+      "label": "Test",
+      "type": "category",
+    },
+    Object {
+      "items": Array [
+        Object {
+          "id": "version-1.0.0-hello",
+          "type": "doc",
+        },
+      ],
+      "label": "Guides",
+      "type": "category",
+    },
+  ],
+  "version-1.0.1-docs": Array [
+    Object {
+      "items": Array [
+        Object {
+          "id": "version-1.0.1-foo/bar",
+          "type": "doc",
+        },
+        Object {
+          "id": "version-1.0.1-foo/baz",
+          "type": "doc",
+        },
+      ],
+      "label": "Test",
+      "type": "category",
+    },
+    Object {
+      "items": Array [
+        Object {
+          "id": "version-1.0.1-hello",
+          "type": "doc",
+        },
+      ],
+      "label": "Guides",
+      "type": "category",
+    },
+  ],
+}
+`;
+
+exports[`loadSidebars site without sidebars 1`] = `Object {}`;

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

@@ -0,0 +1,257 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import '@babel/polyfill';
+import path from 'path';
+import loadSetup from '../../docusaurus/test/loadSetup';
+import DocusaurusPluginContentDocs from '../index';
+
+describe('loadDocs', () => {
+  test.only('simple website', async () => {
+    const {env, siteDir, siteConfig} = await loadSetup('simple');
+    const plugin = new DocusaurusPluginContentDocs(
+      {
+        path: '../docs',
+      },
+      {
+        env,
+        siteDir,
+        siteConfig,
+      },
+    );
+    const {docs: docsMetadata} = await plugin.loadContent();
+    const docsDir = plugin.contentPath;
+
+    expect(docsMetadata.hello).toEqual({
+      category: 'Guides',
+      id: 'hello',
+      language: null,
+      localized_id: 'hello',
+      permalink: '/docs/hello',
+      previous: 'foo/baz',
+      previous_id: 'foo/baz',
+      previous_title: 'baz',
+      sidebar: 'docs',
+      source: path.join(docsDir, 'hello.md'),
+      title: 'Hello, World !',
+      version: null,
+    });
+    expect(docsMetadata['foo/bar']).toEqual({
+      category: 'Test',
+      id: 'foo/bar',
+      language: null,
+      localized_id: 'foo/bar',
+      next: 'foo/baz',
+      next_id: 'foo/baz',
+      next_title: 'baz',
+      permalink: '/docs/foo/bar',
+      sidebar: 'docs',
+      source: path.join(docsDir, 'foo', 'bar.md'),
+      title: 'Bar',
+      version: null,
+    });
+  });
+
+  test('versioned website', async () => {
+    const {env, siteDir, siteConfig, versionedDir} = await loadSetup(
+      'versioned',
+    );
+    const plugin = new DocusaurusPluginContentDocs(
+      {
+        path: '../docs',
+      },
+      {
+        env,
+        siteDir,
+        siteConfig,
+      },
+    );
+    const {docs: docsMetadata} = await plugin.loadContent();
+    const docsDir = plugin.contentPath;
+
+    expect(docsMetadata['version-1.0.0-foo/bar']).toEqual({
+      category: 'Test',
+      id: 'version-1.0.0-foo/bar',
+      language: null,
+      localized_id: 'version-1.0.0-foo/bar',
+      next: 'version-1.0.0-foo/baz',
+      next_id: 'version-1.0.0-foo/baz',
+      next_title: 'Baz',
+      permalink: '/docs/1.0.0/foo/bar',
+      sidebar: 'version-1.0.0-docs',
+      source: path.join(versionedDir, 'version-1.0.0/foo/bar.md'),
+      title: 'Bar',
+      version: '1.0.0',
+    });
+    expect(docsMetadata['foo/bar']).toEqual({
+      category: 'Test',
+      id: 'foo/bar',
+      language: null,
+      localized_id: 'foo/bar',
+      next: 'foo/baz',
+      next_id: 'foo/baz',
+      next_title: 'baz',
+      permalink: '/docs/next/foo/bar',
+      sidebar: 'docs',
+      source: path.join(docsDir, 'foo/bar.md'),
+      title: 'Bar',
+      version: 'next',
+    });
+  });
+
+  test('versioned & translated website', async () => {
+    const {
+      env,
+      siteDir,
+      siteConfig,
+      translatedDir,
+      versionedDir,
+    } = await loadSetup('transversioned');
+    const plugin = new DocusaurusPluginContentDocs(
+      {
+        path: '../docs',
+      },
+      {
+        env,
+        siteDir,
+        siteConfig,
+      },
+    );
+    const {docs: docsMetadata} = await plugin.loadContent();
+    const docsDir = plugin.contentPath;
+
+    expect(docsMetadata['ko-version-1.0.0-foo/bar']).toEqual({
+      category: 'Test',
+      id: 'ko-version-1.0.0-foo/bar',
+      language: 'ko',
+      localized_id: 'version-1.0.0-foo/bar',
+      next: 'ko-version-1.0.0-foo/baz',
+      next_id: 'version-1.0.0-foo/baz',
+      next_title: 'baz',
+      permalink: '/docs/ko/1.0.0/foo/bar',
+      sidebar: 'version-1.0.0-docs',
+      source: path.join(translatedDir, '/ko/version-1.0.0/foo/bar.md'),
+      title: 'Bar',
+      version: '1.0.0',
+    });
+    expect(docsMetadata['en-version-1.0.0-foo/baz']).toEqual({
+      category: 'Test',
+      id: 'en-version-1.0.0-foo/baz',
+      language: 'en',
+      localized_id: 'version-1.0.0-foo/baz',
+      next: 'en-version-1.0.0-hello',
+      next_id: 'version-1.0.0-hello',
+      next_title: 'Hello, World !',
+      permalink: '/docs/en/1.0.0/foo/baz',
+      previous: 'en-version-1.0.0-foo/bar',
+      previous_id: 'version-1.0.0-foo/bar',
+      previous_title: 'Bar',
+      sidebar: 'version-1.0.0-docs',
+      source: path.join(versionedDir, 'version-1.0.0/foo/baz.md'),
+      title: 'Baz',
+      version: '1.0.0',
+    });
+    expect(docsMetadata['en-hello']).toEqual({
+      category: 'Guides',
+      id: 'en-hello',
+      language: 'en',
+      localized_id: 'hello',
+      permalink: '/docs/en/next/hello',
+      previous: 'en-foo/baz',
+      previous_id: 'foo/baz',
+      previous_title: 'baz',
+      sidebar: 'docs',
+      source: path.join(docsDir, 'hello.md'),
+      title: 'Hello, World !',
+      version: 'next',
+    });
+  });
+
+  test('translated website', async () => {
+    const {env, siteDir, siteConfig, translatedDir} = await loadSetup(
+      'translated',
+    );
+    const plugin = new DocusaurusPluginContentDocs(
+      {
+        path: '../docs',
+      },
+      {
+        env,
+        siteDir,
+        siteConfig,
+      },
+    );
+    const {docs: docsMetadata} = await plugin.loadContent();
+    const docsDir = plugin.contentPath;
+
+    expect(docsMetadata['ko-foo/baz']).toEqual({
+      category: 'Test',
+      id: 'ko-foo/baz',
+      language: 'ko',
+      localized_id: 'foo/baz',
+      next: 'ko-hello',
+      next_id: 'hello',
+      next_title: 'Hello, World !',
+      permalink: '/docs/ko/foo/baz',
+      previous: 'ko-foo/bar',
+      previous_id: 'foo/bar',
+      previous_title: 'Bar',
+      sidebar: 'docs',
+      source: path.join(translatedDir, 'ko', 'foo', 'baz.md'),
+      title: 'baz',
+      version: null,
+    });
+    expect(docsMetadata['en-foo/bar']).toEqual({
+      category: 'Test',
+      id: 'en-foo/bar',
+      language: 'en',
+      localized_id: 'foo/bar',
+      next: 'en-foo/baz',
+      next_id: 'foo/baz',
+      next_title: 'baz',
+      permalink: '/docs/en/foo/bar',
+      sidebar: 'docs',
+      source: path.join(docsDir, 'foo', 'bar.md'),
+      title: 'Bar',
+      version: null,
+    });
+  });
+
+  test('versioned website with skip next release', async () => {
+    const {env, siteDir, siteConfig, versionedDir} = await loadSetup(
+      'versioned',
+    );
+    const plugin = new DocusaurusPluginContentDocs(
+      {
+        path: '../docs',
+      },
+      {
+        env,
+        siteDir,
+        siteConfig,
+        cliOptions: {skipNextRelease: true},
+      },
+    );
+    const {docs: docsMetadata} = await plugin.loadContent();
+
+    expect(docsMetadata['version-1.0.0-foo/bar']).toEqual({
+      category: 'Test',
+      id: 'version-1.0.0-foo/bar',
+      language: null,
+      localized_id: 'version-1.0.0-foo/bar',
+      next: 'version-1.0.0-foo/baz',
+      next_id: 'version-1.0.0-foo/baz',
+      next_title: 'Baz',
+      permalink: '/docs/1.0.0/foo/bar',
+      sidebar: 'version-1.0.0-docs',
+      source: path.join(versionedDir, 'version-1.0.0/foo/bar.md'),
+      title: 'Bar',
+      version: '1.0.0',
+    });
+    expect(docsMetadata['foo/bar']).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,381 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import '@babel/polyfill';
+import path from 'path';
+import processMetadata from '../src/metadata';
+import loadSetup from '../../docusaurus/test/loadSetup';
+
+describe('processMetadata', () => {
+  test('normal docs', async () => {
+    const props = await loadSetup('simple');
+    const {docsDir, env, siteConfig} = props;
+    const sourceA = path.join('foo', 'bar.md');
+    const sourceB = path.join('hello.md');
+    const dataA = await processMetadata(
+      sourceA,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataB = await processMetadata(
+      sourceB,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    expect(dataA).toEqual({
+      id: 'foo/bar',
+      language: null,
+      localized_id: 'foo/bar',
+      permalink: '/docs/foo/bar',
+      source: path.join(docsDir, sourceA),
+      title: 'Bar',
+      version: null,
+    });
+    expect(dataB).toEqual({
+      id: 'hello',
+      language: null,
+      localized_id: 'hello',
+      permalink: '/docs/hello',
+      source: path.join(docsDir, sourceB),
+      title: 'Hello, World !',
+      version: null,
+    });
+  });
+
+  test('docs with custom permalink', async () => {
+    const props = await loadSetup('simple');
+    const {docsDir, env, siteConfig} = props;
+    const source = path.join('permalink.md');
+    const data = await processMetadata(
+      source,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    expect(data).toEqual({
+      id: 'permalink',
+      language: null,
+      localized_id: 'permalink',
+      permalink: '/docs/endiliey/permalink',
+      source: path.join(docsDir, source),
+      title: 'Permalink',
+      version: null,
+    });
+  });
+
+  test('versioned docs (without translation)', async () => {
+    const props = await loadSetup('versioned');
+    const {siteDir, docsDir, env, siteConfig} = props;
+    const versionedDir = path.join(siteDir, 'versioned_docs');
+    const sourceA = path.join('version-1.0.0', 'foo', 'bar.md');
+    const sourceB = path.join('version-1.0.0', 'hello.md');
+    const sourceC = path.join('foo', 'bar.md');
+    const sourceD = path.join('hello.md');
+    const dataA = await processMetadata(
+      sourceA,
+      versionedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataB = await processMetadata(
+      sourceB,
+      versionedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataC = await processMetadata(
+      sourceC,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataD = await processMetadata(
+      sourceD,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    expect(dataA).toEqual({
+      id: 'version-1.0.0-foo/bar',
+      language: null,
+      localized_id: 'version-1.0.0-foo/bar',
+      permalink: '/docs/1.0.0/foo/bar',
+      source: path.join(versionedDir, sourceA),
+      title: 'Bar',
+      version: '1.0.0',
+    });
+    expect(dataB).toEqual({
+      id: 'version-1.0.0-hello',
+      language: null,
+      localized_id: 'version-1.0.0-hello',
+      permalink: '/docs/1.0.0/hello',
+      source: path.join(versionedDir, sourceB),
+      title: 'Hello, World !',
+      version: '1.0.0',
+    });
+    expect(dataC).toEqual({
+      id: 'foo/bar',
+      language: null,
+      localized_id: 'foo/bar',
+      permalink: '/docs/next/foo/bar',
+      source: path.join(docsDir, sourceC),
+      title: 'Bar',
+      version: 'next',
+    });
+    expect(dataD).toEqual({
+      id: 'hello',
+      language: null,
+      localized_id: 'hello',
+      permalink: '/docs/next/hello',
+      source: path.join(docsDir, sourceD),
+      title: 'Hello, World !',
+      version: 'next',
+    });
+  });
+
+  test('translated versioned docs', async () => {
+    const props = await loadSetup('transversioned');
+    const {docsDir, translatedDir, versionedDir, env, siteConfig} = props;
+    const sourceA = path.join('ko', 'version-1.0.0', 'foo', 'bar.md');
+    const sourceB = path.join('ko', 'version-1.0.0', 'hello.md');
+    const sourceC = path.join('ko', 'version-1.0.1', 'foo', 'bar.md');
+    const sourceD = path.join('ko', 'version-1.0.1', 'hello.md');
+    const sourceE = path.join('foo', 'bar.md');
+    const sourceF = path.join('hello.md');
+    const sourceG = path.join('version-1.0.0', 'foo', 'bar.md');
+    const sourceH = path.join('version-1.0.0', 'hello.md');
+    const dataA = await processMetadata(
+      sourceA,
+      translatedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataB = await processMetadata(
+      sourceB,
+      translatedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataC = await processMetadata(
+      sourceC,
+      translatedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataD = await processMetadata(
+      sourceD,
+      translatedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataE = await processMetadata(
+      sourceE,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataF = await processMetadata(
+      sourceF,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataG = await processMetadata(
+      sourceG,
+      versionedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataH = await processMetadata(
+      sourceH,
+      versionedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    expect(dataA).toEqual({
+      id: 'ko-version-1.0.0-foo/bar',
+      language: 'ko',
+      localized_id: 'version-1.0.0-foo/bar',
+      permalink: '/docs/ko/1.0.0/foo/bar',
+      source: path.join(translatedDir, sourceA),
+      title: 'Bar',
+      version: '1.0.0',
+    });
+    expect(dataB).toEqual({
+      id: 'ko-version-1.0.0-hello',
+      language: 'ko',
+      localized_id: 'version-1.0.0-hello',
+      permalink: '/docs/ko/1.0.0/hello',
+      source: path.join(translatedDir, sourceB),
+      title: 'Hello, World !',
+      version: '1.0.0',
+    });
+    expect(dataC).toEqual({
+      id: 'ko-version-1.0.1-foo/bar',
+      language: 'ko',
+      localized_id: 'version-1.0.1-foo/bar',
+      permalink: '/docs/ko/foo/bar',
+      source: path.join(translatedDir, sourceC),
+      title: 'Bar',
+      version: '1.0.1',
+    });
+    expect(dataD).toEqual({
+      id: 'ko-version-1.0.1-hello',
+      language: 'ko',
+      localized_id: 'version-1.0.1-hello',
+      permalink: '/docs/ko/hello',
+      source: path.join(translatedDir, sourceD),
+      title: 'Hello, World !',
+      version: '1.0.1',
+    });
+    expect(dataE).toEqual({
+      id: 'en-foo/bar',
+      language: 'en',
+      localized_id: 'foo/bar',
+      permalink: '/docs/en/next/foo/bar',
+      source: path.join(docsDir, sourceE),
+      title: 'Bar',
+      version: 'next',
+    });
+    expect(dataF).toEqual({
+      id: 'en-hello',
+      language: 'en',
+      localized_id: 'hello',
+      permalink: '/docs/en/next/hello',
+      source: path.join(docsDir, sourceF),
+      title: 'Hello, World !',
+      version: 'next',
+    });
+    expect(dataG).toEqual({
+      id: 'en-version-1.0.0-foo/bar',
+      language: 'en',
+      localized_id: 'version-1.0.0-foo/bar',
+      permalink: '/docs/en/1.0.0/foo/bar',
+      source: path.join(versionedDir, sourceG),
+      title: 'Bar',
+      version: '1.0.0',
+    });
+    expect(dataH).toEqual({
+      id: 'en-version-1.0.0-hello',
+      language: 'en',
+      localized_id: 'version-1.0.0-hello',
+      permalink: '/docs/en/1.0.0/hello',
+      source: path.join(versionedDir, sourceH),
+      title: 'Hello, World !',
+      version: '1.0.0',
+    });
+  });
+
+  test('translated docs only', async () => {
+    const props = await loadSetup('translated');
+    const {docsDir, translatedDir, env, siteConfig} = props;
+    const sourceA = path.join('ko', 'foo', 'bar.md');
+    const sourceB = path.join('ko', 'hello.md');
+    const sourceC = path.join('foo', 'bar.md');
+    const sourceD = path.join('hello.md');
+    const dataA = await processMetadata(
+      sourceA,
+      translatedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataB = await processMetadata(
+      sourceB,
+      translatedDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataC = await processMetadata(
+      sourceC,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    const dataD = await processMetadata(
+      sourceD,
+      docsDir,
+      env,
+      {},
+      siteConfig,
+      'docs',
+    );
+    expect(dataA).toEqual({
+      id: 'ko-foo/bar',
+      language: 'ko',
+      localized_id: 'foo/bar',
+      permalink: '/docs/ko/foo/bar',
+      source: path.join(translatedDir, sourceA),
+      title: 'Bar',
+      version: null,
+    });
+    expect(dataB).toEqual({
+      id: 'ko-hello',
+      language: 'ko',
+      localized_id: 'hello',
+      permalink: '/docs/ko/hello',
+      source: path.join(translatedDir, sourceB),
+      title: 'Hello, World !',
+      version: null,
+    });
+    expect(dataC).toEqual({
+      id: 'en-foo/bar',
+      language: 'en',
+      localized_id: 'foo/bar',
+      permalink: '/docs/en/foo/bar',
+      source: path.join(docsDir, sourceC),
+      title: 'Bar',
+      version: null,
+    });
+    expect(dataD).toEqual({
+      id: 'en-hello',
+      language: 'en',
+      localized_id: 'hello',
+      permalink: '/docs/en/hello',
+      source: path.join(docsDir, sourceD),
+      title: 'Hello, World !',
+      version: null,
+    });
+  });
+});

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

@@ -0,0 +1,260 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import createOrder from '../src/order';
+
+describe('createOrder', () => {
+  test('multiple sidebars with subcategory', () => {
+    const result = createOrder({
+      docs: [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [
+            {
+              type: 'category',
+              label: 'Subcategory 1',
+              items: [{type: 'doc', id: 'doc1'}],
+            },
+            {
+              type: 'category',
+              label: 'Subcategory 2',
+              items: [{type: 'doc', id: 'doc2'}],
+            },
+          ],
+        },
+        {
+          type: 'category',
+          label: 'Category2',
+          items: [{type: 'doc', id: 'doc3'}, {type: 'doc', id: 'doc4'}],
+        },
+      ],
+      otherDocs: [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [{type: 'doc', id: 'doc5'}],
+        },
+      ],
+    });
+    expect(result).toEqual({
+      doc1: {
+        category: 'Category1',
+        subCategory: 'Subcategory 1',
+        next: 'doc2',
+        previous: undefined,
+        sidebar: 'docs',
+      },
+      doc2: {
+        category: 'Category1',
+        subCategory: 'Subcategory 2',
+        next: 'doc3',
+        previous: 'doc1',
+        sidebar: 'docs',
+      },
+      doc3: {
+        category: 'Category2',
+        subCategory: undefined,
+        next: 'doc4',
+        previous: 'doc2',
+        sidebar: 'docs',
+      },
+      doc4: {
+        category: 'Category2',
+        subCategory: undefined,
+        next: undefined,
+        previous: 'doc3',
+        sidebar: 'docs',
+      },
+      doc5: {
+        category: 'Category1',
+        subCategory: undefined,
+        next: undefined,
+        previous: undefined,
+        sidebar: 'otherDocs',
+      },
+    });
+  });
+  test('multiple sidebars without subcategory', () => {
+    const result = createOrder({
+      docs: [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [{type: 'doc', id: 'doc1'}, {type: 'doc', id: 'doc2'}],
+        },
+        {
+          type: 'category',
+          label: 'Category2',
+          items: [{type: 'doc', id: 'doc3'}, {type: 'doc', id: 'doc4'}],
+        },
+      ],
+      otherDocs: [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [{type: 'doc', id: 'doc5'}],
+        },
+      ],
+    });
+    expect(result).toEqual({
+      doc1: {
+        category: 'Category1',
+        subCategory: undefined,
+        next: 'doc2',
+        previous: undefined,
+        sidebar: 'docs',
+      },
+      doc2: {
+        category: 'Category1',
+        subCategory: undefined,
+        next: 'doc3',
+        previous: 'doc1',
+        sidebar: 'docs',
+      },
+      doc3: {
+        category: 'Category2',
+        subCategory: undefined,
+        next: 'doc4',
+        previous: 'doc2',
+        sidebar: 'docs',
+      },
+      doc4: {
+        category: 'Category2',
+        subCategory: undefined,
+        next: undefined,
+        previous: 'doc3',
+        sidebar: 'docs',
+      },
+      doc5: {
+        category: 'Category1',
+        subCategory: undefined,
+        next: undefined,
+        previous: undefined,
+        sidebar: 'otherDocs',
+      },
+    });
+  });
+
+  test('versioned sidebars', () => {
+    const result = createOrder({
+      docs: [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [{type: 'doc', id: 'doc1'}],
+        },
+      ],
+      'version-1.2.3-docs': [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [{type: 'doc', id: 'version-1.2.3-doc2'}],
+        },
+        {
+          type: 'category',
+          label: 'Category2',
+          items: [{type: 'doc', id: 'version-1.2.3-doc1'}],
+        },
+      ],
+    });
+    expect(result).toEqual({
+      doc1: {
+        category: 'Category1',
+        subCategory: undefined,
+        next: undefined,
+        previous: undefined,
+        sidebar: 'docs',
+      },
+      'version-1.2.3-doc1': {
+        category: 'Category2',
+        subCategory: undefined,
+        next: undefined,
+        previous: 'version-1.2.3-doc2',
+        sidebar: 'version-1.2.3-docs',
+      },
+      'version-1.2.3-doc2': {
+        category: 'Category1',
+        subCategory: undefined,
+        next: 'version-1.2.3-doc1',
+        previous: undefined,
+        sidebar: 'version-1.2.3-docs',
+      },
+    });
+  });
+
+  test('multiple sidebars with subcategories, refs and external links', () => {
+    const result = createOrder({
+      docs: [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [
+            {
+              type: 'category',
+              label: 'Subcategory 1',
+              items: [{type: 'link', href: '//example.com', label: 'bar'}],
+            },
+            {
+              type: 'category',
+              label: 'Subcategory 2',
+              items: [{type: 'doc', id: 'doc2'}],
+            },
+            {
+              type: 'category',
+              label: 'Subcategory 1',
+              items: [{type: 'link', href: '//example2.com', label: 'baz'}],
+            },
+          ],
+        },
+        {
+          type: 'category',
+          label: 'Category2',
+          items: [{type: 'doc', id: 'doc3'}, {type: 'ref', id: 'doc4'}],
+        },
+      ],
+      otherDocs: [
+        {
+          type: 'category',
+          label: 'Category1',
+          items: [{type: 'doc', id: 'doc5'}],
+        },
+      ],
+    });
+    expect(result).toEqual({
+      doc2: {
+        category: 'Category1',
+        subCategory: 'Subcategory 2',
+        next: 'doc3',
+        previous: undefined,
+        sidebar: 'docs',
+      },
+      doc3: {
+        category: 'Category2',
+        subCategory: undefined,
+        next: undefined,
+        previous: 'doc2',
+        sidebar: 'docs',
+      },
+      doc5: {
+        category: 'Category1',
+        subCategory: undefined,
+        next: undefined,
+        previous: undefined,
+        sidebar: 'otherDocs',
+      },
+    });
+  });
+
+  test('edge cases', () => {
+    expect(createOrder({})).toEqual({});
+    expect(createOrder(undefined)).toEqual({});
+    expect(() => createOrder(null)).toThrowErrorMatchingInlineSnapshot(
+      `"Cannot convert undefined or null to object"`,
+    );
+  });
+});

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

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import path from 'path';
+import loadSidebars from '../src/sidebars';
+import loadSetup from '../../docusaurus/test/loadSetup';
+
+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});
+    expect(result).toMatchSnapshot();
+  });
+
+  test('site without sidebars', () => {
+    const env = {};
+    const siteDir = path.join(fixtures, 'bad-site');
+    const result = loadSidebars({siteDir, env});
+    expect(result).toMatchSnapshot();
+  });
+
+  test('site with sidebars & versioned sidebars', async () => {
+    const {env, siteDir} = await loadSetup('versioned');
+    const result = loadSidebars({siteDir, env});
+    expect(result).toMatchSnapshot();
+  });
+
+  test('site with missing versioned sidebars', async () => {
+    const env = {
+      versioning: {
+        enabled: true,
+        versions: ['2.0.0'],
+      },
+    };
+    const {siteDir} = await loadSetup('versioned');
+    expect(() => {
+      loadSidebars({siteDir, env});
+    }).toThrowErrorMatchingInlineSnapshot(
+      `"Failed to load versioned_sidebars/version-2.0.0-sidebars.json. It does not exist."`,
+    );
+  });
+});

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

@@ -0,0 +1,210 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const path = require('path');
+const globby = require('globby');
+const {getSubFolder, idx, normalizeUrl} = require('@docusaurus/utils');
+const createOrder = require('./src/order');
+const loadSidebars = require('./src/sidebars');
+const processMetadata = require('./src/metadata');
+
+const DEFAULT_OPTIONS = {
+  metadataKey: 'docsMetadata',
+  metadataFileName: 'docsMetadata.json',
+  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.
+  sidebar: [], // Sidebar configuration for showing a list of documentation pages.
+  // TODO: Settle themeing.
+  docLayoutComponent: '@theme/Doc',
+  docItemComponent: '@theme/DocBody',
+};
+
+class DocusaurusPluginContentDocs {
+  constructor(opts, context) {
+    this.options = {...DEFAULT_OPTIONS, ...opts};
+    this.context = context;
+    this.contentPath = path.resolve(this.context.siteDir, this.options.path);
+  }
+
+  getName() {
+    return 'docusaurus-plugin-content-docs';
+  }
+
+  getPathsToWatch() {
+    return [this.contentPath];
+  }
+
+  // Fetches blog contents and returns metadata for the contents.
+  async loadContent() {
+    const {include, routeBasePath} = this.options;
+    const {siteDir, env, siteConfig, cliOptions = {}} = this.context;
+    const {skipNextRelease} = cliOptions;
+    const docsDir = this.contentPath;
+
+    // @tested - load all sidebars including versioned sidebars
+    const docsSidebars = loadSidebars({siteDir, env});
+
+    // @tested - build the docs ordering such as next, previous, category and sidebar
+    const order = createOrder(docsSidebars);
+
+    // Settle versions & translations from environment.
+    const translationEnabled = idx(env, ['translation', 'enabled']);
+    const enabledLanguages =
+      translationEnabled && idx(env, ['translation', 'enabledLanguages']);
+    const enabledLangTags =
+      (enabledLanguages && enabledLanguages.map(lang => lang.tag)) || [];
+    const defaultLangTag = idx(env, ['translation', 'defaultLanguage', 'tag']);
+    const versioningEnabled = idx(env, ['versioning', 'enabled']);
+    const versions =
+      (versioningEnabled && idx(env, ['versioning', 'versions'])) || [];
+
+    // Prepare metadata container.
+    const docs = {};
+
+    if (!(versioningEnabled && skipNextRelease)) {
+      // Metadata for default docs files.
+      const docsFiles = await globby(include, {
+        cwd: docsDir,
+      });
+      await Promise.all(
+        docsFiles.map(async source => {
+          // Do not allow reserved version/ translated folder name in 'docs'
+          // e.g: 'docs/version-1.0.0/' should not be allowed as it can cause unwanted bug
+          const subFolder = getSubFolder(
+            path.resolve(docsDir, source),
+            docsDir,
+          );
+          const versionsFolders = versions.map(version => `version-${version}`);
+          if ([...enabledLangTags, ...versionsFolders].includes(subFolder)) {
+            throw new Error(
+              `You cannot have a folder named 'docs/${subFolder}/'`,
+            );
+          }
+
+          const metadata = await processMetadata(
+            source,
+            docsDir,
+            env,
+            order,
+            siteConfig,
+            routeBasePath,
+          );
+          docs[metadata.id] = metadata;
+        }),
+      );
+    }
+
+    // Metadata for non-default-language docs.
+    if (translationEnabled) {
+      const translatedDir = path.join(siteDir, 'translated_docs');
+      const translatedFiles = await globby(include, {
+        cwd: translatedDir,
+      });
+      await Promise.all(
+        translatedFiles.map(async source => {
+          /*
+            Do not process disabled & default languages folder in `translated_docs`
+            e.g: 'translated_docs/ja/**' should not be processed if lang 'ja' is disabled
+          */
+          const translatedFilePath = path.resolve(translatedDir, source);
+          const detectedLangTag = getSubFolder(
+            translatedFilePath,
+            translatedDir,
+          );
+          if (
+            detectedLangTag === defaultLangTag ||
+            !enabledLangTags.includes(detectedLangTag)
+          ) {
+            return;
+          }
+
+          const metadata = await processMetadata(
+            source,
+            translatedDir,
+            env,
+            order,
+            siteConfig,
+            routeBasePath,
+          );
+          docs[metadata.id] = metadata;
+        }),
+      );
+    }
+
+    // Metadata for versioned docs.
+    if (versioningEnabled) {
+      const versionedDir = path.join(siteDir, 'versioned_docs');
+      const versionedFiles = await globby(include, {
+        cwd: versionedDir,
+      });
+      await Promise.all(
+        versionedFiles.map(async source => {
+          const metadata = await processMetadata(
+            source,
+            versionedDir,
+            env,
+            order,
+            siteConfig,
+            routeBasePath,
+          );
+          docs[metadata.id] = metadata;
+        }),
+      );
+    }
+
+    // Get the titles of the previous and next ids so that we can use them.
+    Object.keys(docs).forEach(currentID => {
+      const previousID = idx(docs, [currentID, 'previous']);
+      if (previousID) {
+        const previousTitle = idx(docs, [previousID, 'title']);
+        docs[currentID].previous_title = previousTitle || 'Previous';
+      }
+      const nextID = idx(docs, [currentID, 'next']);
+      if (nextID) {
+        const nextTitle = idx(docs, [nextID, 'title']);
+        docs[currentID].next_title = nextTitle || 'Next';
+      }
+    });
+
+    // Create source to metadata mapping.
+    const sourceToMetadata = {};
+    Object.values(docs).forEach(({source, version, permalink, language}) => {
+      sourceToMetadata[source] = {
+        version,
+        permalink,
+        language,
+      };
+    });
+
+    return {
+      docs,
+      docsDir,
+      docsSidebars,
+      sourceToMetadata,
+    };
+  }
+
+  async contentLoaded({content, actions}) {
+    const {docLayoutComponent, docItemComponent, routeBasePath} = this.options;
+    const {addRoute} = actions;
+
+    addRoute({
+      path: normalizeUrl([this.context.siteConfig.baseUrl, routeBasePath]),
+      component: docLayoutComponent,
+      routes: Object.values(content.docs).map(metadataItem => ({
+        path: metadataItem.permalink,
+        component: docItemComponent,
+        metadata: metadataItem,
+        modules: [metadataItem.source],
+      })),
+    });
+  }
+}
+
+module.exports = DocusaurusPluginContentDocs;

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

@@ -0,0 +1,16 @@
+{
+  "name": "@docusaurus/plugin-content-docs",
+  "version": "1.0.0",
+  "description": "Documentation plugin for Docusaurus",
+  "main": "index.js",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/polyfill": "^7.4.0",
+    "@docusaurus/utils": "^1.0.0",
+    "fs-extra": "^7.0.1",
+    "globby": "^9.1.0"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": "^2.0.0"
+  }
+}

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

@@ -0,0 +1,179 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const {getSubFolder, idx, parse, normalizeUrl} = require('@docusaurus/utils');
+
+function getLanguage(filepath, refDir, env) {
+  const translationEnabled = idx(env, ['translation', 'enabled']);
+
+  if (translationEnabled) {
+    const detectedLangTag = getSubFolder(filepath, refDir);
+    const enabledLanguages = idx(env, ['translation', 'enabledLanguages']);
+    const langTags =
+      (enabledLanguages && enabledLanguages.map(lang => lang.tag)) || [];
+    if (langTags.includes(detectedLangTag)) {
+      return detectedLangTag;
+    }
+
+    const defaultLanguage = idx(env, ['translation', 'defaultLanguage']);
+    if (defaultLanguage && defaultLanguage.tag) {
+      return defaultLanguage.tag;
+    }
+  }
+
+  return null;
+}
+
+function getVersion(filepath, refDir, env) {
+  const versioningEnabled = idx(env, ['versioning', 'enabled']);
+
+  if (versioningEnabled) {
+    const subFolder = getSubFolder(filepath, refDir);
+
+    if (subFolder) {
+      const detectedVersion = subFolder.replace(/^version-/, '');
+      const versions = idx(env, ['versioning', 'versions']) || [];
+      if (versions.includes(detectedVersion)) {
+        return detectedVersion;
+      }
+    }
+
+    return 'next';
+  }
+
+  return null;
+}
+
+module.exports = async function processMetadata(
+  source,
+  refDir,
+  env,
+  order,
+  siteConfig,
+  docsBasePath,
+) {
+  const filepath = path.resolve(refDir, source);
+  const fileString = await fs.readFile(filepath, 'utf-8');
+  const {metadata} = parse(fileString);
+
+  // Default id is the file name.
+  if (!metadata.id) {
+    metadata.id = path.basename(source, path.extname(source));
+  }
+  if (metadata.id.includes('/')) {
+    throw new Error('Document id cannot include "/".');
+  }
+
+  // Default title is the id.
+  if (!metadata.title) {
+    metadata.title = metadata.id;
+  }
+
+  // Language.
+  const language = getLanguage(filepath, refDir, env);
+  metadata.language = language;
+  const langPart = (language && `${language}/`) || '';
+
+  // Version.
+  const defaultLangTag = idx(env, ['translation', 'defaultLanguage', 'tag']);
+  let versionRefDir = refDir;
+  if (language && language !== defaultLangTag) {
+    versionRefDir = path.join(refDir, language);
+  }
+  const version = getVersion(filepath, versionRefDir, env);
+  metadata.version = version;
+  const latestVersion = idx(env, ['versioning', 'latestVersion']);
+  const versionPart =
+    (version && version !== latestVersion && `${version}/`) || '';
+
+  // Convert temporarily metadata.id to the form of dirname/id without version/lang prefix.
+  // e.g.: file `versioned_docs/version-1.0.0/en/foo/bar.md` with id `version-1.0.0-bar` => `foo/bar`
+  if (language) {
+    metadata.id = metadata.id.replace(new RegExp(`^${language}-`), '');
+  }
+
+  if (version) {
+    metadata.id = metadata.id.replace(new RegExp(`^version-${version}-`), '');
+  }
+
+  const dirName = path.dirname(source);
+  if (dirName !== '.') {
+    let prefix = dirName;
+    if (language) {
+      prefix = prefix.replace(new RegExp(`^${language}`), '');
+    }
+    prefix = prefix.replace(/^\//, '');
+    if (version) {
+      prefix = prefix.replace(new RegExp(`^version-${version}`), '');
+    }
+    prefix = prefix.replace(/^\//, '');
+    if (prefix) {
+      metadata.id = `${prefix}/${metadata.id}`;
+    }
+  }
+
+  // The docs absolute file source.
+  // e.g: `/end/docs/hello.md` or `/end/website/versioned_docs/version-1.0.0/hello.md`
+  metadata.source = path.join(refDir, source);
+
+  // Build the permalink.
+  const {baseUrl} = siteConfig;
+
+  // If user has own custom permalink defined in frontmatter
+  // e.g: :baseUrl:docsUrl/:langPart/:versionPart/endiliey/:id
+  if (metadata.permalink) {
+    metadata.permalink = path.resolve(
+      metadata.permalink
+        .replace(/:baseUrl/, baseUrl)
+        .replace(/:docsUrl/, docsBasePath)
+        .replace(/:langPart/, langPart)
+        .replace(/:versionPart/, versionPart)
+        .replace(/:id/, metadata.id),
+    );
+  } else {
+    metadata.permalink = normalizeUrl([
+      baseUrl,
+      docsBasePath,
+      langPart,
+      versionPart,
+      metadata.id,
+    ]);
+  }
+
+  // If version.
+  if (version && version !== 'next') {
+    metadata.id = `version-${version}-${metadata.id}`;
+  }
+
+  // Save localized id before adding language on it.
+  metadata.localized_id = metadata.id;
+
+  // If language.
+  if (language) {
+    metadata.id = `${language}-${metadata.id}`;
+  }
+
+  // Determine order.
+  const id = metadata.localized_id;
+  if (order[id]) {
+    metadata.sidebar = order[id].sidebar;
+    metadata.category = order[id].category;
+    metadata.subCategory = order[id].subCategory;
+    if (order[id].next) {
+      metadata.next_id = order[id].next;
+      metadata.next = (language ? `${language}-` : '') + order[id].next;
+    }
+    if (order[id].previous) {
+      metadata.previous_id = order[id].previous;
+      metadata.previous = (language ? `${language}-` : '') + order[id].previous;
+    }
+  }
+
+  return metadata;
+};

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

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// Build the docs meta such as next, previous, category and sidebar.
+module.exports = function createOrder(allSidebars = {}) {
+  const order = {};
+
+  Object.keys(allSidebars).forEach(sidebarId => {
+    const sidebar = allSidebars[sidebarId];
+
+    const ids = [];
+    const categoryOrder = [];
+    const subCategoryOrder = [];
+    const indexItems = ({items, categoryLabel, subCategoryLabel}) => {
+      items.forEach(item => {
+        switch (item.type) {
+          case 'category':
+            indexItems({
+              items: item.items,
+              categoryLabel: categoryLabel || item.label,
+              subCategoryLabel: categoryLabel && item.label,
+            });
+            break;
+          case 'ref':
+          case 'link':
+            // Refs and links should not be shown in navigation.
+            break;
+          case 'doc':
+            ids.push(item.id);
+            categoryOrder.push(categoryLabel);
+            subCategoryOrder.push(subCategoryLabel);
+            break;
+          default:
+            throw new Error(
+              `Unknown item type: ${item.type}. Item: ${JSON.stringify(item)}`,
+            );
+        }
+      });
+    };
+
+    indexItems({items: sidebar});
+
+    // eslint-disable-next-line
+    for (let i = 0; i < ids.length; i++) {
+      const id = ids[i];
+      let previous;
+      let next;
+
+      if (i > 0) {
+        previous = ids[i - 1];
+      }
+
+      if (i < ids.length - 1) {
+        next = ids[i + 1];
+      }
+
+      order[id] = {
+        previous,
+        next,
+        sidebar: sidebarId,
+        category: categoryOrder[i],
+        subCategory: subCategoryOrder[i],
+      };
+    }
+  });
+
+  return order;
+};

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

@@ -0,0 +1,150 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const {idx} = require('@docusaurus/utils');
+
+/**
+ * Check that item contains only allowed keys
+ *
+ * @param {Object} item
+ * @param {Array<string>} keys
+ */
+function assertItem(item, keys) {
+  const unknownKeys = Object.keys(item).filter(
+    key => !keys.includes(key) && key !== 'type',
+  );
+
+  if (unknownKeys.length) {
+    throw new Error(
+      `Unknown sidebar item keys: ${unknownKeys}. Item: ${JSON.stringify(
+        item,
+      )}`,
+    );
+  }
+}
+
+/**
+ * Normalizes recursively category and all its children. Ensures, that at the end
+ * each item will be an object with the corresponding type
+ *
+ * @param {Array<Object>} category
+ * @param {number} [level=0]
+ *
+ * @return {Array<Object>}
+ */
+function normalizeCategory(category, level = 0) {
+  if (level === 2) {
+    throw new Error(
+      `Can not process ${
+        category.label
+      } category. Categories can be nested only one level deep.`,
+    );
+  }
+
+  assertItem(category, ['items', 'label']);
+
+  if (!Array.isArray(category.items)) {
+    throw new Error(
+      `Error loading ${category.label} category. Category items must be array.`,
+    );
+  }
+
+  const items = category.items.map(item => {
+    switch (item.type) {
+      case 'category':
+        return normalizeCategory(item, level + 1);
+      case 'link':
+        assertItem(item, ['href', 'label']);
+        break;
+      case 'ref':
+        assertItem(item, ['id', 'label']);
+        break;
+      default:
+        if (typeof item === 'string') {
+          return {
+            type: 'doc',
+            id: item,
+          };
+        }
+
+        if (item.type !== 'doc') {
+          throw new Error(`Unknown sidebar item type: ${item.type}`);
+        }
+
+        assertItem(item, ['id', 'label']);
+        break;
+    }
+
+    return item;
+  });
+
+  return {...category, items};
+}
+
+/**
+ * Converts sidebars object to mapping to arrays of sidebar item objects
+ *
+ * @param  {{[key: string]: Object}} sidebars
+ *
+ * @return {{[key: string]: Array<Object>}}
+ */
+function normalizeSidebar(sidebars) {
+  return Object.entries(sidebars).reduce((acc, [sidebarId, sidebar]) => {
+    let normalizedSidebar = sidebar;
+
+    if (!Array.isArray(sidebar)) {
+      // convert sidebar to a more generic structure
+      normalizedSidebar = Object.entries(sidebar).map(([label, items]) => ({
+        type: 'category',
+        label,
+        items,
+      }));
+    }
+
+    acc[sidebarId] = normalizedSidebar.map(item => normalizeCategory(item));
+
+    return acc;
+  }, {});
+}
+
+module.exports = function loadSidebars({siteDir, env}, deleteCache = true) {
+  let allSidebars = {};
+
+  // current 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)) {
+      versions.forEach(version => {
+        const versionedSidebarsJSONFile = path.join(
+          siteDir,
+          'versioned_sidebars',
+          `version-${version}-sidebars.json`,
+        );
+        if (fs.existsSync(versionedSidebarsJSONFile)) {
+          const sidebar = require(versionedSidebarsJSONFile); // eslint-disable-line
+          Object.assign(allSidebars, sidebar);
+        } else {
+          const missingFile = path.relative(siteDir, versionedSidebarsJSONFile);
+          throw new Error(`Failed to load ${missingFile}. It does not exist.`);
+        }
+      });
+    }
+  }
+
+  return normalizeSidebar(allSidebars);
+};