@docusaurus/plugin-content-docs 0.0.0-4240 → 0.0.0-4244

package/src/docs.ts

@@ -8,7 +8,7 @@
 import path from 'path';
 import fs from 'fs-extra';
 import chalk from 'chalk';
-import {keyBy} from 'lodash';
+import {keyBy, last} from 'lodash';
 import {
   aliasedSitePath,
   getEditUrl,
@@ -38,8 +38,11 @@ import {CURRENT_VERSION_NAME} from './constants';
 import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './docFrontMatter';
-import type {Sidebars} from './sidebars/types';
-import {createSidebarsUtils} from './sidebars/utils';
+import {
+  SidebarsUtils,
+  toDocNavigationLink,
+  toNavigationLink,
+} from './sidebars/utils';
 
 type LastUpdateOptions = Pick<
   PluginOptions,
@@ -205,7 +208,8 @@ function doProcessDocMetadata({
     ? '/'
     : getSlug({
         baseID,
-        dirName: sourceDirName,
+        source,
+        sourceDirName,
         frontmatterSlug: frontMatter.slug,
         stripDirNumberPrefixes: parseNumberPrefixes,
         numberPrefixParser: options.numberPrefixParser,
@@ -291,68 +295,76 @@ export function processDocMetadata(args: {
   }
 }
 
-export function handleNavigation(
+export function addDocNavigation(
   docsBase: DocMetadataBase[],
-  sidebars: Sidebars,
+  sidebarsUtils: SidebarsUtils,
   sidebarFilePath: string,
-): Pick<LoadedVersion, 'mainDocId' | 'docs'> {
-  const docsBaseById = keyBy(docsBase, (doc) => doc.id);
-  const {checkSidebarsDocIds, getDocNavigation, getFirstDocIdOfFirstSidebar} =
-    createSidebarsUtils(sidebars);
+): LoadedVersion['docs'] {
+  const docsById = createDocsByIdIndex(docsBase);
 
-  const validDocIds = Object.keys(docsBaseById);
-  checkSidebarsDocIds(validDocIds, sidebarFilePath);
+  sidebarsUtils.checkSidebarsDocIds(
+    docsBase.flatMap(getDocIds),
+    sidebarFilePath,
+  );
 
   // Add sidebar/next/previous to the docs
   function addNavData(doc: DocMetadataBase): DocMetadata {
-    const {sidebarName, previousId, nextId} = getDocNavigation(doc.id);
-    const toDocNavLink = (
+    const navigation = sidebarsUtils.getDocNavigation(
+      doc.unversionedId,
+      doc.id,
+    );
+
+    const toNavigationLinkByDocId = (
       docId: string | null | undefined,
       type: 'prev' | 'next',
     ): DocNavLink | undefined => {
       if (!docId) {
         return undefined;
       }
-      if (!docsBaseById[docId]) {
+      const navDoc = docsById[docId];
+      if (!navDoc) {
         // This could only happen if user provided the ID through front matter
         throw new Error(
           `Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`,
         );
       }
-      const {
-        title,
-        permalink,
-        frontMatter: {
-          pagination_label: paginationLabel,
-          sidebar_label: sidebarLabel,
-        },
-      } = docsBaseById[docId];
-      return {title: paginationLabel ?? sidebarLabel ?? title, permalink};
+      return toDocNavigationLink(navDoc);
     };
-    const {
-      frontMatter: {
-        pagination_next: paginationNext = nextId,
-        pagination_prev: paginationPrev = previousId,
-      },
-    } = doc;
-    const previous = toDocNavLink(paginationPrev, 'prev');
-    const next = toDocNavLink(paginationNext, 'next');
-    return {...doc, sidebar: sidebarName, previous, next};
+
+    const previous: DocNavLink | undefined = doc.frontMatter.pagination_prev
+      ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+      : toNavigationLink(navigation.previous, docsById);
+    const next: DocNavLink | undefined = doc.frontMatter.pagination_next
+      ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
+      : toNavigationLink(navigation.next, docsById);
+
+    return {...doc, sidebar: navigation.sidebarName, previous, next};
   }
-  const docs = docsBase.map(addNavData);
+
+  const docsWithNavigation = docsBase.map(addNavData);
   // sort to ensure consistent output for tests
-  docs.sort((a, b) => a.id.localeCompare(b.id));
-
-  /**
-   * The "main doc" is the "version entry point"
-   * We browse this doc by clicking on a version:
-   * - the "home" doc (at '/docs/')
-   * - the first doc of the first sidebar
-   * - a random doc (if no docs are in any sidebar... edge case)
-   */
+  docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
+  return docsWithNavigation;
+}
+
+/**
+ * The "main doc" is the "version entry point"
+ * We browse this doc by clicking on a version:
+ * - the "home" doc (at '/docs/')
+ * - the first doc of the first sidebar
+ * - a random doc (if no docs are in any sidebar... edge case)
+ */
+export function getMainDocId({
+  docs,
+  sidebarsUtils,
+}: {
+  docs: DocMetadataBase[];
+  sidebarsUtils: SidebarsUtils;
+}): string {
   function getMainDoc(): DocMetadata {
     const versionHomeDoc = docs.find((doc) => doc.slug === '/');
-    const firstDocIdOfFirstSidebar = getFirstDocIdOfFirstSidebar();
+    const firstDocIdOfFirstSidebar =
+      sidebarsUtils.getFirstDocIdOfFirstSidebar();
     if (versionHomeDoc) {
       return versionHomeDoc;
     } else if (firstDocIdOfFirstSidebar) {
@@ -362,5 +374,51 @@ export function handleNavigation(
     }
   }
 
-  return {mainDocId: getMainDoc().unversionedId, docs};
+  return getMainDoc().unversionedId;
+}
+
+function getLastPathSegment(str: string): string {
+  return last(str.split('/'))!;
+}
+
+// By convention, Docusaurus considers some docs are "indexes":
+// - index.md
+// - readme.md
+// - <folder>/<folder>.md
+//
+// Those index docs produce a different behavior
+// - Slugs do not end with a weird "/index" suffix
+// - Auto-generated sidebar categories link to them as intro
+export function isConventionalDocIndex(doc: {
+  source: DocMetadataBase['slug'];
+  sourceDirName: DocMetadataBase['sourceDirName'];
+}): boolean {
+  // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
+  const docName = path.parse(doc.source).name;
+
+  // "folder/subFolder/subSubFolder" => "subSubFolder"
+  const lastDirName = getLastPathSegment(doc.sourceDirName);
+
+  const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
+
+  return eligibleDocIndexNames.includes(docName.toLowerCase());
+}
+
+// Return both doc ids
+// TODO legacy retro-compatibility due to old versioned sidebars using versioned doc ids
+// ("id" should be removed & "versionedId" should be renamed to "id")
+export function getDocIds(doc: DocMetadataBase): [string, string] {
+  return [doc.unversionedId, doc.id];
+}
+
+// docs are indexed by both versioned and unversioned ids at the same time
+// TODO legacy retro-compatibility due to old versioned sidebars using versioned doc ids
+// ("id" should be removed & "versionedId" should be renamed to "id")
+export function createDocsByIdIndex<
+  Doc extends {id: string; unversionedId: string},
+>(docs: Doc[]): Record<string, Doc> {
+  return {
+    ...keyBy(docs, (doc) => doc.unversionedId),
+    ...keyBy(docs, (doc) => doc.id),
+  };
 }

package/src/index.ts

@@ -16,11 +16,17 @@ import {
   posixPath,
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
+  createSlugger,
 } from '@docusaurus/utils';
-import type {LoadContext, Plugin, RouteConfig} from '@docusaurus/types';
+import type {LoadContext, Plugin} from '@docusaurus/types';
 import {loadSidebars} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
-import {readVersionDocs, processDocMetadata, handleNavigation} from './docs';
+import {
+  readVersionDocs,
+  processDocMetadata,
+  addDocNavigation,
+  getMainDocId,
+} from './docs';
 import {getDocsDirPaths, readVersionsMetadata} from './versions';
 
 import {
@@ -28,7 +34,6 @@ import {
   LoadedContent,
   SourceToPermalink,
   DocMetadataBase,
-  DocMetadata,
   GlobalPluginData,
   VersionMetadata,
   LoadedVersion,
@@ -41,14 +46,17 @@ import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {keyBy, mapValues} from 'lodash';
 import {toGlobalDataVersion} from './globalData';
-import {toTagDocListProp, toVersionMetadataProp} from './props';
+import {toTagDocListProp} from './props';
 import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
 } from './translations';
 import chalk from 'chalk';
 import {getVersionTags} from './tags';
+import {createVersionRoutes} from './routes';
 import type {PropTagsListPage} from '@docusaurus/plugin-content-docs';
+import {createSidebarsUtils} from './sidebars/utils';
+import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
 
 export default function pluginContentDocs(
   context: LoadContext,
@@ -157,28 +165,37 @@ export default function pluginContentDocs(
       async function doLoadVersion(
         versionMetadata: VersionMetadata,
       ): Promise<LoadedVersion> {
-        const docsBase: DocMetadataBase[] = await loadVersionDocsBase(
+        const docs: DocMetadataBase[] = await loadVersionDocsBase(
           versionMetadata,
         );
 
         const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
           sidebarItemsGenerator: options.sidebarItemsGenerator,
           numberPrefixParser: options.numberPrefixParser,
-          docs: docsBase,
+          docs,
           version: versionMetadata,
-          options: {
+          sidebarOptions: {
             sidebarCollapsed: options.sidebarCollapsed,
             sidebarCollapsible: options.sidebarCollapsible,
           },
+          categoryLabelSlugger: createSlugger(),
         });
+
+        const sidebarsUtils = createSidebarsUtils(sidebars);
+
         return {
           ...versionMetadata,
-          ...handleNavigation(
-            docsBase,
-            sidebars,
+          docs: addDocNavigation(
+            docs,
+            sidebarsUtils,
             versionMetadata.sidebarFilePath as string,
           ),
           sidebars,
+          mainDocId: getMainDocId({docs, sidebarsUtils}),
+          categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
+            docs,
+            sidebarsUtils,
+          }),
         };
       }
 
@@ -206,45 +223,17 @@ export default function pluginContentDocs(
 
     async contentLoaded({content, actions}) {
       const {loadedVersions} = content;
-      const {docLayoutComponent, docItemComponent} = options;
+      const {
+        docLayoutComponent,
+        docItemComponent,
+        docCategoryGeneratedIndexComponent,
+      } = options;
       const {addRoute, createData, setGlobalData} = actions;
 
-      const createDocRoutes = async (
-        docs: DocMetadata[],
-      ): Promise<RouteConfig[]> => {
-        const routes = await Promise.all(
-          docs.map(async (metadataItem) => {
-            await 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;
-          }),
-        );
-
-        return routes.sort((a, b) => a.path.localeCompare(b.path));
-      };
-
-      async function createVersionTagsRoutes(loadedVersion: LoadedVersion) {
-        const versionTags = getVersionTags(loadedVersion.docs);
+      async function createVersionTagsRoutes(version: LoadedVersion) {
+        const versionTags = getVersionTags(version.docs);
 
+        // TODO tags should be a sub route of the version route
         async function createTagsListPage() {
           const tagsProp: PropTagsListPage['tags'] = Object.values(
             versionTags,
@@ -257,11 +246,11 @@ export default function pluginContentDocs(
           // Only create /tags page if there are tags.
           if (Object.keys(tagsProp).length > 0) {
             const tagsPropPath = await createData(
-              `${docuHash(`tags-list-${loadedVersion.versionName}-prop`)}.json`,
+              `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
               JSON.stringify(tagsProp, null, 2),
             );
             addRoute({
-              path: loadedVersion.tagsPath,
+              path: version.tagsPath,
               exact: true,
               component: options.docTagsListComponent,
               modules: {
@@ -271,11 +260,12 @@ export default function pluginContentDocs(
           }
         }
 
+        // TODO tags should be a sub route of the version route
         async function createTagDocListPage(tag: VersionTag) {
           const tagProps = toTagDocListProp({
-            allTagsPath: loadedVersion.tagsPath,
+            allTagsPath: version.tagsPath,
             tag,
-            docs: loadedVersion.docs,
+            docs: version.docs,
           });
           const tagPropPath = await createData(
             `${docuHash(`tag-${tag.permalink}`)}.json`,
@@ -295,50 +285,22 @@ export default function pluginContentDocs(
         await Promise.all(Object.values(versionTags).map(createTagDocListPage));
       }
 
-      async function doCreateVersionRoutes(
-        loadedVersion: LoadedVersion,
-      ): Promise<void> {
-        await createVersionTagsRoutes(loadedVersion);
-
-        const versionMetadata = toVersionMetadataProp(pluginId, loadedVersion);
-        const versionMetadataPropPath = await createData(
-          `${docuHash(
-            `version-${loadedVersion.versionName}-metadata-prop`,
-          )}.json`,
-          JSON.stringify(versionMetadata, null, 2),
-        );
-
-        addRoute({
-          path: loadedVersion.versionPath,
-          // allow matching /docs/* as well
-          exact: false,
-          // main docs component (DocPage)
-          component: docLayoutComponent,
-          // sub-routes for each doc
-          routes: await createDocRoutes(loadedVersion.docs),
-          modules: {
-            versionMetadata: aliasedSource(versionMetadataPropPath),
-          },
-          priority: loadedVersion.routePriority,
-        });
-      }
-
-      async function createVersionRoutes(
-        loadedVersion: LoadedVersion,
-      ): Promise<void> {
-        try {
-          return await doCreateVersionRoutes(loadedVersion);
-        } catch (e) {
-          console.error(
-            chalk.red(
-              `Can't create version routes for version "${loadedVersion.versionName}"`,
-            ),
-          );
-          throw e;
-        }
-      }
+      await Promise.all(
+        loadedVersions.map((loadedVersion) =>
+          createVersionRoutes({
+            loadedVersion,
+            docItemComponent,
+            docLayoutComponent,
+            docCategoryGeneratedIndexComponent,
+            pluginId,
+            aliasedSource,
+            actions,
+          }),
+        ),
+      );
 
-      await Promise.all(loadedVersions.map(createVersionRoutes));
+      // TODO tags should be a sub route of the version route
+      await Promise.all(loadedVersions.map(createVersionTagsRoutes));
 
       setGlobalData<GlobalPluginData>({
         path: normalizeUrl([baseUrl, options.routeBasePath]),

package/src/options.ts

@@ -39,6 +39,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   docItemComponent: '@theme/DocItem',
   docTagDocListComponent: '@theme/DocTagDocListPage',
   docTagsListComponent: '@theme/DocTagsListPage',
+  docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
   remarkPlugins: [],
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
@@ -109,6 +110,9 @@ export const OptionsSchema = Joi.object({
   docTagDocListComponent: Joi.string().default(
     DEFAULT_OPTIONS.docTagDocListComponent,
   ),
+  docCategoryGeneratedIndexComponent: Joi.string().default(
+    DEFAULT_OPTIONS.docCategoryGeneratedIndexComponent,
+  ),
   remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
   rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
   beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(

package/src/plugin-content-docs.d.ts

@@ -15,6 +15,18 @@ declare module '@docusaurus/plugin-content-docs' {
 
   export type {GlobalDataVersion, GlobalDataDoc};
 
+  export type PropNavigationLink = {
+    readonly title: string;
+    readonly permalink: string;
+  };
+  export type PropNavigation = {
+    readonly previous?: PropNavigationLink;
+    readonly next?: PropNavigationLink;
+  };
+
+  export type PropVersionDoc = import('./sidebars/types').PropVersionDoc;
+  export type PropVersionDocs = import('./sidebars/types').PropVersionDocs;
+
   export type PropVersionMetadata = {
     pluginId: string;
     version: string;
@@ -24,12 +36,23 @@ declare module '@docusaurus/plugin-content-docs' {
     className: string;
     isLast: boolean;
     docsSidebars: PropSidebars;
+    docs: PropVersionDocs;
+  };
+
+  export type PropCategoryGeneratedIndex = {
+    title: string;
+    description?: string;
+    slug: string;
+    permalink: string;
+    navigation: PropNavigation;
   };
 
-  export type PropSidebarItemLink = import('./sidebars/types').SidebarItemLink;
+  export type PropSidebarItemLink =
+    import('./sidebars/types').PropSidebarItemLink;
   export type PropSidebarItemCategory =
     import('./sidebars/types').PropSidebarItemCategory;
   export type PropSidebarItem = import('./sidebars/types').PropSidebarItem;
+  export type PropSidebar = import('./sidebars/types').PropSidebar;
   export type PropSidebars = import('./sidebars/types').PropSidebars;
 
   export type PropTagDocListDoc = {
@@ -56,7 +79,10 @@ declare module '@docusaurus/plugin-content-docs' {
 
 declare module '@theme/DocItem' {
   import type {TOCItem} from '@docusaurus/types';
-  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
+  import type {
+    PropNavigationLink,
+    PropVersionMetadata,
+  } from '@docusaurus/plugin-content-docs';
 
   export type DocumentRoute = {
     readonly component: () => JSX.Element;
@@ -85,8 +111,8 @@ declare module '@theme/DocItem' {
     readonly formattedLastUpdatedAt?: string;
     readonly lastUpdatedBy?: string;
     readonly version?: string;
-    readonly previous?: {readonly permalink: string; readonly title: string};
-    readonly next?: {readonly permalink: string; readonly title: string};
+    readonly previous?: PropNavigationLink;
+    readonly next?: PropNavigationLink;
     readonly tags: readonly {
       readonly label: string;
       readonly permalink: string;
@@ -109,6 +135,38 @@ declare module '@theme/DocItem' {
   export default DocItem;
 }
 
+declare module '@theme/DocCard' {
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly item: PropSidebarItem;
+  }
+
+  export default function DocCard(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocCardList' {
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly items: PropSidebarItem[];
+  }
+
+  export default function DocCardList(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocCategoryGeneratedIndexPage' {
+  import type {PropCategoryGeneratedIndex} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly categoryGeneratedIndex: PropCategoryGeneratedIndex;
+  }
+
+  export default function DocCategoryGeneratedIndexPage(
+    props: Props,
+  ): JSX.Element;
+}
+
 declare module '@theme/DocItemFooter' {
   import type {Props} from '@theme/DocItem';
 
@@ -132,14 +190,19 @@ declare module '@theme/DocTagDocListPage' {
 }
 
 declare module '@theme/DocVersionBanner' {
-  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function DocVersionBanner(props: Props): JSX.Element;
+}
 
+declare module '@theme/DocVersionBadge' {
   export interface Props {
-    readonly versionMetadata: PropVersionMetadata;
+    readonly className?: string;
   }
 
-  const DocVersionBanner: (props: Props) => JSX.Element;
-  export default DocVersionBanner;
+  export default function DocVersionBadge(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocPage' {