refactor(v2): docs plugin refactor (#3245)

* safe refactorings

* safe refactors

* add code to read versions more generically

* refactor docs plugin

* refactors

* stable docs refactor

* progress on refactor

* stable docs refactor

* stable docs refactor

* stable docs refactor

* attempt to fix admonition :(

* configureWebpack docs: better typing

* more refactors

* rename cli

* refactor docs metadata processing => move to pure function

* stable docs refactor

* stable docs refactor

* named exports

* basic sidebars refactor

* add getElementsAround utils

* refactor sidebar + ordering/navigation logic

* stable retrocompatible refactor

* add proper versions metadata tests

* fix docs metadata tests

* fix docs tests

* fix test due to absolute path

* fix webpack tests

* refactor linkify + add broken markdown links warning

* fix DOM warning due to forwarding legacy prop to div element

* add todo

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

@@ -0,0 +1,70 @@
+/**
+ * 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 {
+  LoadedVersion,
+  PropSidebars,
+  SidebarItemDoc,
+  SidebarItemLink,
+  PropVersionMetadata,
+  SidebarItem,
+  PropSidebarItem,
+} from './types';
+import {keyBy, mapValues} from 'lodash';
+
+export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
+  const docsById = keyBy(loadedVersion.docs, (doc) => doc.id);
+
+  const convertDocLink = (item: SidebarItemDoc): SidebarItemLink => {
+    const docId = item.id;
+    const docMetadata = docsById[docId];
+
+    if (!docMetadata) {
+      throw new Error(
+        `Bad sidebars file. The document id '${docId}' was used in the sidebar, but no document with this id could be found.
+Available document ids=
+- ${Object.keys(docsById).sort().join('\n- ')}`,
+      );
+    }
+
+    const {title, permalink, sidebar_label} = docMetadata;
+
+    return {
+      type: 'link',
+      label: sidebar_label || title,
+      href: permalink,
+    };
+  };
+
+  const normalizeItem = (item: SidebarItem): PropSidebarItem => {
+    switch (item.type) {
+      case 'category':
+        return {...item, items: item.items.map(normalizeItem)};
+      case 'ref':
+      case 'doc':
+        return convertDocLink(item);
+      case 'link':
+      default:
+        return item;
+    }
+  };
+
+  // Transform the sidebar so that all sidebar item will be in the
+  // form of 'link' or 'category' only.
+  // This is what will be passed as props to the UI component.
+  return mapValues(loadedVersion.sidebars, (items) => items.map(normalizeItem));
+}
+
+export function toVersionMetadataProp(
+  loadedVersion: LoadedVersion,
+): PropVersionMetadata {
+  return {
+    version: loadedVersion.versionName,
+    docsSidebars: toSidebarsProp(loadedVersion),
+    permalinkToSidebar: loadedVersion.permalinkToSidebar,
+  };
+}