@docusaurus/plugin-content-docs 2.0.0-beta.2 → 2.0.0-beta.22

package/src/props.ts

@@ -5,26 +5,33 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
+import _ from 'lodash';
+import {createDocsByIdIndex} from './docs';
+import type {VersionTag} from './types';
+import type {
   SidebarItemDoc,
-  SidebarItemLink,
   SidebarItem,
-} from './types';
-import {
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
+} from './sidebars/types';
+import type {
   PropSidebars,
   PropVersionMetadata,
   PropSidebarItem,
-} from '@docusaurus/plugin-content-docs-types';
-import {keyBy, mapValues} from 'lodash';
+  PropSidebarItemCategory,
+  PropTagDocList,
+  PropTagDocListDoc,
+  PropSidebarItemLink,
+  PropVersionDocs,
+  DocMetadata,
+  LoadedVersion,
+} from '@docusaurus/plugin-content-docs';
 
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
-  const docsById = keyBy(loadedVersion.docs, (doc) => doc.id);
+  const docsById = createDocsByIdIndex(loadedVersion.docs);
 
-  const convertDocLink = (item: SidebarItemDoc): SidebarItemLink => {
-    const docId = item.id;
+  function getDocById(docId: string): DocMetadata {
     const docMetadata = docsById[docId];
-
     if (!docMetadata) {
       throw new Error(
         `Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
@@ -32,25 +39,68 @@ Available document ids are:
 - ${Object.keys(docsById).sort().join('\n- ')}`,
       );
     }
+    return docMetadata;
+  }
 
+  const convertDocLink = (item: SidebarItemDoc): PropSidebarItemLink => {
+    const docMetadata = getDocById(item.id);
     const {
       title,
       permalink,
       frontMatter: {sidebar_label: sidebarLabel},
     } = docMetadata;
-
     return {
       type: 'link',
-      label: sidebarLabel || item.label || title,
+      label: sidebarLabel ?? item.label ?? title,
       href: permalink,
-      customProps: item.customProps,
+      className: item.className,
+      customProps:
+        item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
+      docId: docMetadata.unversionedId,
     };
   };
 
-  const normalizeItem = (item: SidebarItem): PropSidebarItem => {
+  function getCategoryLinkHref(
+    link: SidebarItemCategoryLink | undefined,
+  ): string | undefined {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).permalink;
+      case 'generated-index':
+        return link.permalink;
+      default:
+        return undefined;
+    }
+  }
+
+  function getCategoryLinkCustomProps(
+    link: SidebarItemCategoryLink | undefined,
+  ) {
+    switch (link?.type) {
+      case 'doc':
+        return getDocById(link.id).frontMatter.sidebar_custom_props;
+      default:
+        return undefined;
+    }
+  }
+
+  function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
+    const {link, ...rest} = item;
+    const href = getCategoryLinkHref(link);
+    const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
+
+    return {
+      ...rest,
+      items: item.items.map(normalizeItem),
+      ...(href && {href}),
+      ...(customProps && {customProps}),
+    };
+  }
+
+  function normalizeItem(item: SidebarItem): PropSidebarItem {
     switch (item.type) {
       case 'category':
-        return {...item, items: item.items.map(normalizeItem)};
+        return convertCategory(item);
       case 'ref':
       case 'doc':
         return convertDocLink(item);
@@ -58,12 +108,28 @@ Available document ids are:
       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));
+  return _.mapValues(loadedVersion.sidebars, (items) =>
+    items.map(normalizeItem),
+  );
+}
+
+function toVersionDocsProp(loadedVersion: LoadedVersion): PropVersionDocs {
+  return Object.fromEntries(
+    loadedVersion.docs.map((doc) => [
+      doc.unversionedId,
+      {
+        id: doc.unversionedId,
+        title: doc.title,
+        description: doc.description,
+        sidebar: doc.sidebar,
+      },
+    ]),
+  );
 }
 
 export function toVersionMetadataProp(
@@ -73,10 +139,44 @@ export function toVersionMetadataProp(
   return {
     pluginId,
     version: loadedVersion.versionName,
-    label: loadedVersion.versionLabel,
-    banner: loadedVersion.versionBanner,
+    label: loadedVersion.label,
+    banner: loadedVersion.banner,
+    badge: loadedVersion.badge,
+    className: loadedVersion.className,
     isLast: loadedVersion.isLast,
     docsSidebars: toSidebarsProp(loadedVersion),
-    permalinkToSidebar: loadedVersion.permalinkToSidebar,
+    docs: toVersionDocsProp(loadedVersion),
+  };
+}
+
+export function toTagDocListProp({
+  allTagsPath,
+  tag,
+  docs,
+}: {
+  allTagsPath: string;
+  tag: VersionTag;
+  docs: DocMetadata[];
+}): PropTagDocList {
+  function toDocListProp(): PropTagDocListDoc[] {
+    const list = _.compact(
+      tag.docIds.map((id) => docs.find((doc) => doc.id === id)),
+    );
+    // Sort docs by title
+    list.sort((doc1, doc2) => doc1.title.localeCompare(doc2.title));
+    return list.map((doc) => ({
+      id: doc.id,
+      title: doc.title,
+      description: doc.description,
+      permalink: doc.permalink,
+    }));
+  }
+
+  return {
+    label: tag.label,
+    permalink: tag.permalink,
+    allTagsPath,
+    count: tag.docIds.length,
+    items: toDocListProp(),
   };
 }

package/src/routes.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 logger from '@docusaurus/logger';
+import {docuHash, createSlugger} from '@docusaurus/utils';
+import {toVersionMetadataProp} from './props';
+import type {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
+import type {FullVersion} from './types';
+import type {
+  CategoryGeneratedIndexMetadata,
+  DocMetadata,
+} from '@docusaurus/plugin-content-docs';
+
+export async function createCategoryGeneratedIndexRoutes({
+  version,
+  actions,
+  docCategoryGeneratedIndexComponent,
+  aliasedSource,
+}: {
+  version: FullVersion;
+  actions: PluginContentLoadedActions;
+  docCategoryGeneratedIndexComponent: string;
+  aliasedSource: (str: string) => string;
+}): Promise<RouteConfig[]> {
+  const slugs = createSlugger();
+
+  async function createCategoryGeneratedIndexRoute(
+    categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
+  ): Promise<RouteConfig> {
+    const {sidebar, ...prop} = categoryGeneratedIndex;
+
+    const propFileName = slugs.slug(
+      `${version.path}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`,
+    );
+
+    const propData = await actions.createData(
+      `${docuHash(`category/${propFileName}`)}.json`,
+      JSON.stringify(prop, null, 2),
+    );
+
+    return {
+      path: categoryGeneratedIndex.permalink,
+      component: docCategoryGeneratedIndexComponent,
+      exact: true,
+      modules: {
+        categoryGeneratedIndex: aliasedSource(propData),
+      },
+      // Same as doc, this sidebar route attribute permits to associate this
+      // subpage to the given sidebar
+      ...(sidebar && {sidebar}),
+    };
+  }
+
+  return Promise.all(
+    version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute),
+  );
+}
+
+export async function createDocRoutes({
+  docs,
+  actions,
+  docItemComponent,
+}: {
+  docs: DocMetadata[];
+  actions: PluginContentLoadedActions;
+  docItemComponent: string;
+}): Promise<RouteConfig[]> {
+  return Promise.all(
+    docs.map(async (metadataItem) => {
+      await actions.createData(
+        // Note that this created data path must be in sync with
+        // metadataPath provided to mdx-loader.
+        `${docuHash(metadataItem.source)}.json`,
+        JSON.stringify(metadataItem, null, 2),
+      );
+
+      const docRoute: RouteConfig = {
+        path: metadataItem.permalink,
+        component: docItemComponent,
+        exact: true,
+        modules: {
+          content: metadataItem.source,
+        },
+        // Because the parent (DocPage) comp need to access it easily
+        // This permits to render the sidebar once without unmount/remount when
+        // navigating (and preserve sidebar state)
+        ...(metadataItem.sidebar && {
+          sidebar: metadataItem.sidebar,
+        }),
+      };
+
+      return docRoute;
+    }),
+  );
+}
+
+export async function createVersionRoutes({
+  version,
+  actions,
+  docItemComponent,
+  docLayoutComponent,
+  docCategoryGeneratedIndexComponent,
+  pluginId,
+  aliasedSource,
+}: {
+  version: FullVersion;
+  actions: PluginContentLoadedActions;
+  docLayoutComponent: string;
+  docItemComponent: string;
+  docCategoryGeneratedIndexComponent: string;
+  pluginId: string;
+  aliasedSource: (str: string) => string;
+}): Promise<void> {
+  async function doCreateVersionRoutes(): Promise<void> {
+    const versionMetadata = toVersionMetadataProp(pluginId, version);
+    const versionMetadataPropPath = await actions.createData(
+      `${docuHash(`version-${version.versionName}-metadata-prop`)}.json`,
+      JSON.stringify(versionMetadata, null, 2),
+    );
+
+    async function createVersionSubRoutes() {
+      const [docRoutes, sidebarsRoutes] = await Promise.all([
+        createDocRoutes({docs: version.docs, actions, docItemComponent}),
+        createCategoryGeneratedIndexRoutes({
+          version,
+          actions,
+          docCategoryGeneratedIndexComponent,
+          aliasedSource,
+        }),
+      ]);
+
+      const routes = [...docRoutes, ...sidebarsRoutes];
+      return routes.sort((a, b) => a.path.localeCompare(b.path));
+    }
+
+    actions.addRoute({
+      path: version.path,
+      // Allow matching /docs/* since this is the wrapping route
+      exact: false,
+      component: docLayoutComponent,
+      routes: await createVersionSubRoutes(),
+      modules: {
+        versionMetadata: aliasedSource(versionMetadataPropPath),
+      },
+      priority: version.routePriority,
+    });
+  }
+
+  try {
+    return await doCreateVersionRoutes();
+  } catch (err) {
+    logger.error`Can't create version routes for version name=${version.versionName}`;
+    throw err;
+  }
+}

package/src/server-export.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+
+// APIs available to Node.js
+export {
+  CURRENT_VERSION_NAME,
+  VERSIONED_DOCS_DIR,
+  VERSIONED_SIDEBARS_DIR,
+  VERSIONS_JSON_FILE,
+} from './constants';
+
+export {
+  filterVersions,
+  getDefaultVersionBanner,
+  getVersionBadge,
+  getVersionBanner,
+} from './versions';
+export {readVersionNames} from './versions/files';

package/src/sidebars/README.md

@@ -0,0 +1,10 @@
+# Sidebars
+
+This part is very complicated and hard to navigate. Sidebars are loaded through the following steps:
+
+1. **Loading**. The sidebars file is read. Returns `SidebarsConfig`.
+2. **Normalization**. The shorthands are expanded. This step is very lenient about the sidebars' shapes. Returns `NormalizedSidebars`.
+3. **Validation**. The normalized sidebars are validated. This step happens after normalization, because the normalized sidebars are easier to validate, and allows us to repeatedly validate & generate in the future.
+4. **Generation**. This step is done through the "processor" (naming is hard). The `autogenerated` items are unwrapped. In the future, steps 3 and 4 may be repeatedly done until all autogenerated items are unwrapped. Returns `ProcessedSidebars`.
+   - **Important**: this step should only care about unwrapping autogenerated items, not filtering them, writing additional metadata, applying defaults, etc.—everything will be handled in the post-processor. Important because the generator is exposed to the end-user and we want it to be easy to be reasoned about.
+5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.

package/src/sidebars/generator.ts

@@ -0,0 +1,292 @@
+/**
+ * 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 path from 'path';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {addTrailingSlash} from '@docusaurus/utils';
+import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
+import type {
+  SidebarItemDoc,
+  SidebarItemsGenerator,
+  SidebarItemsGeneratorDoc,
+  NormalizedSidebarItemCategory,
+  NormalizedSidebarItem,
+  SidebarItemCategoryLinkConfig,
+} from './types';
+
+const BreadcrumbSeparator = '/';
+
+// Just an alias to the make code more explicit
+function getLocalDocId(docId: string): string {
+  return _.last(docId.split('/'))!;
+}
+
+export const CategoryMetadataFilenameBase = '_category_';
+export const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
+
+type WithPosition<T> = T & {
+  position?: number;
+  /** The source is the file/folder name */
+  source?: string;
+};
+
+/**
+ * A representation of the fs structure. For each object entry:
+ * If it's a folder, the key is the directory name, and value is the directory
+ * content; If it's a doc file, the key is the doc's source file name, and value
+ * is the doc ID
+ */
+type Dir = {
+  [item: string]: Dir | string;
+};
+
+// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
+  numberPrefixParser,
+  isCategoryIndex,
+  docs: allDocs,
+  item: {dirName: autogenDir},
+  categoriesMetadata,
+}) => {
+  const docsById = createDocsByIdIndex(allDocs);
+  const findDoc = (docId: string): SidebarItemsGeneratorDoc | undefined =>
+    docsById[docId];
+  const getDoc = (docId: string): SidebarItemsGeneratorDoc => {
+    const doc = findDoc(docId);
+    if (!doc) {
+      throw new Error(
+        `Can't find any doc with ID ${docId}.
+Available doc IDs:
+- ${Object.keys(docsById).join('\n- ')}`,
+      );
+    }
+    return doc;
+  };
+
+  /**
+   * Step 1. Extract the docs that are in the autogen dir.
+   */
+  function getAutogenDocs(): SidebarItemsGeneratorDoc[] {
+    function isInAutogeneratedDir(doc: SidebarItemsGeneratorDoc) {
+      return (
+        // Doc at the root of the autogenerated sidebar dir
+        doc.sourceDirName === autogenDir ||
+        // Autogen dir is . and doc is in subfolder
+        autogenDir === '.' ||
+        // Autogen dir is not . and doc is in subfolder
+        // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
+        doc.sourceDirName.startsWith(addTrailingSlash(autogenDir))
+      );
+    }
+    const docs = allDocs.filter(isInAutogeneratedDir);
+
+    if (docs.length === 0) {
+      logger.warn`No docs found in path=${autogenDir}: can't auto-generate a sidebar.`;
+    }
+    return docs;
+  }
+
+  /**
+   * Step 2. Turn the linear file list into a tree structure.
+   */
+  function treeify(docs: SidebarItemsGeneratorDoc[]): Dir {
+    // Get the category breadcrumb of a doc (relative to the dir of the
+    // autogenerated sidebar item)
+    // autogenDir=a/b and docDir=a/b/c/d => returns [c, d]
+    // autogenDir=a/b and docDir=a/b => returns []
+    // TODO: try to use path.relative()
+    function getRelativeBreadcrumb(doc: SidebarItemsGeneratorDoc): string[] {
+      return autogenDir === doc.sourceDirName
+        ? []
+        : doc.sourceDirName
+            .replace(addTrailingSlash(autogenDir), '')
+            .split(BreadcrumbSeparator);
+    }
+    const treeRoot: Dir = {};
+    docs.forEach((doc) => {
+      const breadcrumb = getRelativeBreadcrumb(doc);
+      // We walk down the file's path to generate the fs structure
+      let currentDir = treeRoot;
+      breadcrumb.forEach((dir) => {
+        if (typeof currentDir[dir] === 'undefined') {
+          currentDir[dir] = {}; // Create new folder.
+        }
+        currentDir = currentDir[dir] as Dir; // Go into the subdirectory.
+      });
+      // We've walked through the path. Register the file in this directory.
+      currentDir[path.basename(doc.source)] = doc.id;
+    });
+    return treeRoot;
+  }
+
+  /**
+   * Step 3. Recursively transform the tree-like structure to sidebar items.
+   * (From a record to an array of items, akin to normalizing shorthand)
+   */
+  function generateSidebar(
+    fsModel: Dir,
+  ): WithPosition<NormalizedSidebarItem>[] {
+    function createDocItem(
+      id: string,
+      fullPath: string,
+      fileName: string,
+    ): WithPosition<SidebarItemDoc> {
+      const {
+        sidebarPosition: position,
+        frontMatter: {sidebar_label: label, sidebar_class_name: className},
+      } = getDoc(id);
+      return {
+        type: 'doc',
+        id,
+        position,
+        source: fileName,
+        // We don't want these fields to magically appear in the generated
+        // sidebar
+        ...(label !== undefined && {label}),
+        ...(className !== undefined && {className}),
+      };
+    }
+    function createCategoryItem(
+      dir: Dir,
+      fullPath: string,
+      folderName: string,
+    ): WithPosition<NormalizedSidebarItemCategory> {
+      const categoryMetadata =
+        categoriesMetadata[path.posix.join(autogenDir, fullPath)];
+      const allItems = Object.entries(dir).map(([key, content]) =>
+        dirToItem(content, key, `${fullPath}/${key}`),
+      );
+
+      // Try to match a doc inside the category folder,
+      // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
+      function findDocByLocalId(localId: string): SidebarItemDoc | undefined {
+        return allItems.find(
+          (item): item is SidebarItemDoc =>
+            item.type === 'doc' && getLocalDocId(item.id) === localId,
+        );
+      }
+
+      function findConventionalCategoryDocLink(): SidebarItemDoc | undefined {
+        return allItems.find((item): item is SidebarItemDoc => {
+          if (item.type !== 'doc') {
+            return false;
+          }
+          const doc = getDoc(item.id);
+          return isCategoryIndex(toCategoryIndexMatcherParam(doc));
+        });
+      }
+
+      // In addition to the ID, this function also retrieves metadata of the
+      // linked doc that could be used as fallback values for category metadata
+      function getCategoryLinkedDocMetadata():
+        | {
+            id: string;
+            position?: number;
+            label?: string;
+            customProps?: {[key: string]: unknown};
+            className?: string;
+          }
+        | undefined {
+        const link = categoryMetadata?.link;
+        if (link !== undefined && link?.type !== 'doc') {
+          // If a link is explicitly specified, we won't apply conventions
+          return undefined;
+        }
+        const id = link
+          ? findDocByLocalId(link.id)?.id ?? getDoc(link.id).id
+          : findConventionalCategoryDocLink()?.id;
+        if (!id) {
+          return undefined;
+        }
+        const doc = getDoc(id);
+        return {
+          id,
+          position: doc.sidebarPosition,
+          label: doc.frontMatter.sidebar_label ?? doc.title,
+          customProps: doc.frontMatter.sidebar_custom_props,
+          className: doc.frontMatter.sidebar_class_name,
+        };
+      }
+      const categoryLinkedDoc = getCategoryLinkedDocMetadata();
+      const link: SidebarItemCategoryLinkConfig | null | undefined =
+        categoryLinkedDoc
+          ? {
+              type: 'doc',
+              id: categoryLinkedDoc.id, // We "remap" a potentially "local id" to a "qualified id"
+            }
+          : categoryMetadata?.link;
+      // If a doc is linked, remove it from the category subItems
+      const items = allItems.filter(
+        (item) => !(item.type === 'doc' && item.id === categoryLinkedDoc?.id),
+      );
+
+      const className =
+        categoryMetadata?.className ?? categoryLinkedDoc?.className;
+      const customProps =
+        categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
+      const {filename, numberPrefix} = numberPrefixParser(folderName);
+
+      return {
+        type: 'category',
+        label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
+        collapsible: categoryMetadata?.collapsible,
+        collapsed: categoryMetadata?.collapsed,
+        position:
+          categoryMetadata?.position ??
+          categoryLinkedDoc?.position ??
+          numberPrefix,
+        source: folderName,
+        ...(customProps !== undefined && {customProps}),
+        ...(className !== undefined && {className}),
+        items,
+        ...(link && {link}),
+      };
+    }
+    function dirToItem(
+      dir: Dir | string, // The directory item to be transformed.
+      itemKey: string, // File/folder name; for categories, it's used to generate the next `relativePath`.
+      fullPath: string, // `dir`'s full path relative to the autogen dir.
+    ): WithPosition<NormalizedSidebarItem> {
+      return typeof dir === 'object'
+        ? createCategoryItem(dir, fullPath, itemKey)
+        : createDocItem(dir, fullPath, itemKey);
+    }
+    return Object.entries(fsModel).map(([key, content]) =>
+      dirToItem(content, key, key),
+    );
+  }
+
+  /**
+   * Step 4. Recursively sort the categories/docs + remove the "position"
+   * attribute from final output. Note: the "position" is only used to sort
+   * "inside" a sidebar slice. It is not used to sort across multiple
+   * consecutive sidebar slices (i.e. a whole category composed of multiple
+   * autogenerated items)
+   */
+  function sortItems(
+    sidebarItems: WithPosition<NormalizedSidebarItem>[],
+  ): NormalizedSidebarItem[] {
+    const processedSidebarItems = sidebarItems.map((item) => {
+      if (item.type === 'category') {
+        return {...item, items: sortItems(item.items)};
+      }
+      return item;
+    });
+    const sortedSidebarItems = _.sortBy(processedSidebarItems, [
+      'position',
+      'source',
+    ]);
+    return sortedSidebarItems.map(({position, source, ...item}) => item);
+  }
+  // TODO: the whole code is designed for pipeline operator
+  const docs = getAutogenDocs();
+  const fsModel = treeify(docs);
+  const sidebarWithPosition = generateSidebar(fsModel);
+  const sortedSidebar = sortItems(sidebarWithPosition);
+  return sortedSidebar;
+};