@docusaurus/plugin-content-docs 2.0.0-beta.1 → 2.0.0-beta.10

package/src/index.ts

@@ -7,10 +7,6 @@
 
 import path from 'path';
 
-import {
-  STATIC_DIR_NAME,
-  DEFAULT_PLUGIN_ID,
-} from '@docusaurus/core/lib/constants';
 import {
   normalizeUrl,
   docuHash,
@@ -18,10 +14,19 @@ import {
   reportMessage,
   posixPath,
   addTrailingPathSeparator,
+  createAbsoluteFilePathMatcher,
+  createSlugger,
+  DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
-import {LoadContext, Plugin, RouteConfig} from '@docusaurus/types';
-import {loadSidebars, createSidebarsUtils, processSidebars} from './sidebars';
-import {readVersionDocs, processDocMetadata} from './docs';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import {loadSidebars} from './sidebars';
+import {CategoryMetadataFilenamePattern} from './sidebars/generator';
+import {
+  readVersionDocs,
+  processDocMetadata,
+  addDocNavigation,
+  getMainDocId,
+} from './docs';
 import {getDocsDirPaths, readVersionsMetadata} from './versions';
 
 import {
@@ -29,27 +34,29 @@ import {
   LoadedContent,
   SourceToPermalink,
   DocMetadataBase,
-  DocMetadata,
   GlobalPluginData,
   VersionMetadata,
-  DocNavLink,
   LoadedVersion,
   DocFile,
   DocsMarkdownOption,
+  VersionTag,
 } from './types';
-import {PermalinkToSidebar} from '@docusaurus/plugin-content-docs-types';
-import {RuleSetRule} from 'webpack';
+import type {RuleSetRule} from 'webpack';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
-import {flatten, keyBy, compact} from 'lodash';
+import {keyBy, mapValues} from 'lodash';
 import {toGlobalDataVersion} from './globalData';
-import {toVersionMetadataProp} from './props';
+import {toTagDocListProp} from './props';
 import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
 } from './translations';
-import {CategoryMetadataFilenamePattern} from './sidebarItemsGenerator';
 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,
@@ -59,7 +66,6 @@ export default function pluginContentDocs(
 
   const versionsMetadata = readVersionsMetadata({context, options});
 
-  const sourceToPermalink: SourceToPermalink = {};
   const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
 
   const pluginDataDirRoot = path.join(
@@ -101,6 +107,8 @@ export default function pluginContentDocs(
           cliDocsVersionCommand(version, siteDir, pluginId, {
             path: options.path,
             sidebarPath: options.sidebarPath,
+            sidebarCollapsed: options.sidebarCollapsed,
+            sidebarCollapsible: options.sidebarCollapsible,
           });
         });
     },
@@ -109,22 +117,12 @@ export default function pluginContentDocs(
       return getLoadedContentTranslationFiles(content);
     },
 
-    getClientModules() {
-      const modules = [];
-      if (options.admonitions) {
-        modules.push(require.resolve('remark-admonitions/styles/infima.css'));
-      }
-      return modules;
-    },
-
     getPathsToWatch() {
       function getVersionPathsToWatch(version: VersionMetadata): string[] {
         const result = [
-          ...flatten(
-            options.include.map((pattern) =>
-              getDocsDirPaths(version).map(
-                (docsDirPath) => `${docsDirPath}/${pattern}`,
-              ),
+          ...options.include.flatMap((pattern) =>
+            getDocsDirPaths(version).map(
+              (docsDirPath) => `${docsDirPath}/${pattern}`,
             ),
           ),
           `${version.contentPath}/**/${CategoryMetadataFilenamePattern}`,
@@ -135,7 +133,7 @@ export default function pluginContentDocs(
         return result;
       }
 
-      return flatten(versionsMetadata.map(getVersionPathsToWatch));
+      return versionsMetadata.flatMap(getVersionPathsToWatch);
     },
 
     async loadContent() {
@@ -167,104 +165,37 @@ export default function pluginContentDocs(
       async function doLoadVersion(
         versionMetadata: VersionMetadata,
       ): Promise<LoadedVersion> {
-        const unprocessedSidebars = loadSidebars(
-          versionMetadata.sidebarFilePath,
-        );
-
-        const docsBase: DocMetadataBase[] = await loadVersionDocsBase(
+        const docs: DocMetadataBase[] = await loadVersionDocsBase(
           versionMetadata,
         );
-        const docsBaseById: Record<string, DocMetadataBase> = keyBy(
-          docsBase,
-          (doc) => doc.id,
-        );
 
-        const sidebars = await processSidebars({
+        const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
           sidebarItemsGenerator: options.sidebarItemsGenerator,
           numberPrefixParser: options.numberPrefixParser,
-          unprocessedSidebars,
-          docs: docsBase,
+          docs,
           version: versionMetadata,
+          sidebarOptions: {
+            sidebarCollapsed: options.sidebarCollapsed,
+            sidebarCollapsible: options.sidebarCollapsible,
+          },
+          categoryLabelSlugger: createSlugger(),
         });
 
         const sidebarsUtils = createSidebarsUtils(sidebars);
 
-        const validDocIds = Object.keys(docsBaseById);
-        sidebarsUtils.checkSidebarsDocIds(
-          validDocIds,
-          versionMetadata.sidebarFilePath as string,
-        );
-
-        // Add sidebar/next/previous to the docs
-        function addNavData(doc: DocMetadataBase): DocMetadata {
-          const {
-            sidebarName,
-            previousId,
-            nextId,
-          } = sidebarsUtils.getDocNavigation(doc.id);
-          const toDocNavLink = (navDocId: string): DocNavLink => {
-            const {title, permalink, frontMatter} = docsBaseById[navDocId];
-            return {
-              title:
-                frontMatter.pagination_label ??
-                frontMatter.sidebar_label ??
-                title,
-              permalink,
-            };
-          };
-          return {
-            ...doc,
-            sidebar: sidebarName,
-            previous: previousId ? toDocNavLink(previousId) : undefined,
-            next: nextId ? toDocNavLink(nextId) : undefined,
-          };
-        }
-
-        const docs = docsBase.map(addNavData);
-
-        // sort to ensure consistent output for tests
-        docs.sort((a, b) => a.id.localeCompare(b.id));
-
-        // TODO annoying side effect!
-        Object.values(docs).forEach((loadedDoc) => {
-          const {source, permalink} = loadedDoc;
-          sourceToPermalink[source] = permalink;
-        });
-
-        // TODO really useful? replace with global state logic?
-        const permalinkToSidebar: PermalinkToSidebar = {};
-        Object.values(docs).forEach((doc) => {
-          if (doc.sidebar) {
-            permalinkToSidebar[doc.permalink] = doc.sidebar;
-          }
-        });
-
-        // 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)
-        function getMainDoc(): DocMetadata {
-          const versionHomeDoc = docs.find(
-            (doc) =>
-              doc.unversionedId === options.homePageId || doc.slug === '/',
-          );
-          const firstDocIdOfFirstSidebar = sidebarsUtils.getFirstDocIdOfFirstSidebar();
-          if (versionHomeDoc) {
-            return versionHomeDoc;
-          } else if (firstDocIdOfFirstSidebar) {
-            return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar)!;
-          } else {
-            return docs[0];
-          }
-        }
-
         return {
           ...versionMetadata,
-          mainDocId: getMainDoc().unversionedId,
+          docs: addDocNavigation(
+            docs,
+            sidebarsUtils,
+            versionMetadata.sidebarFilePath as string,
+          ),
           sidebars,
-          permalinkToSidebar,
-          docs: docs.map(addNavData),
+          mainDocId: getMainDocId({docs, sidebarsUtils}),
+          categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
+            docs,
+            sidebarsUtils,
+          }),
         };
       }
 
@@ -292,76 +223,84 @@ 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),
+      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,
+          ).map((tagValue) => ({
+            name: tagValue.name,
+            permalink: tagValue.permalink,
+            count: tagValue.docIds.length,
+          }));
+
+          // Only create /tags page if there are tags.
+          if (Object.keys(tagsProp).length > 0) {
+            const tagsPropPath = await createData(
+              `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
+              JSON.stringify(tagsProp, null, 2),
             );
-
-            return {
-              path: metadataItem.permalink,
-              component: docItemComponent,
+            addRoute({
+              path: version.tagsPath,
               exact: true,
+              component: options.docTagsListComponent,
               modules: {
-                content: metadataItem.source,
+                tags: aliasedSource(tagsPropPath),
               },
-            };
-          }),
-        );
-
-        return routes.sort((a, b) => a.path.localeCompare(b.path));
-      };
-
-      async function doCreateVersionRoutes(loadedVersion: LoadedVersion) {
-        const versionMetadataPropPath = await createData(
-          `${docuHash(
-            `version-${loadedVersion.versionName}-metadata-prop`,
-          )}.json`,
-          JSON.stringify(
-            toVersionMetadataProp(pluginId, loadedVersion),
-            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) {
-        try {
-          return await doCreateVersionRoutes(loadedVersion);
-        } catch (e) {
-          console.error(
-            chalk.red(
-              `Can't create version routes for version "${loadedVersion.versionName}"`,
-            ),
+        // TODO tags should be a sub route of the version route
+        async function createTagDocListPage(tag: VersionTag) {
+          const tagProps = toTagDocListProp({
+            allTagsPath: version.tagsPath,
+            tag,
+            docs: version.docs,
+          });
+          const tagPropPath = await createData(
+            `${docuHash(`tag-${tag.permalink}`)}.json`,
+            JSON.stringify(tagProps, null, 2),
           );
-          throw e;
+          addRoute({
+            path: tag.permalink,
+            component: options.docTagDocListComponent,
+            exact: true,
+            modules: {
+              tag: aliasedSource(tagPropPath),
+            },
+          });
         }
+
+        await createTagsListPage();
+        await Promise.all(Object.values(versionTags).map(createTagDocListPage));
       }
 
-      await Promise.all(loadedVersions.map(createVersionRoutes));
+      await Promise.all(
+        loadedVersions.map((loadedVersion) =>
+          createVersionRoutes({
+            loadedVersion,
+            docItemComponent,
+            docLayoutComponent,
+            docCategoryGeneratedIndexComponent,
+            pluginId,
+            aliasedSource,
+            actions,
+          }),
+        ),
+      );
+
+      // TODO tags should be a sub route of the version route
+      await Promise.all(loadedVersions.map(createVersionTagsRoutes));
 
       setGlobalData<GlobalPluginData>({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
@@ -369,7 +308,7 @@ export default function pluginContentDocs(
       });
     },
 
-    configureWebpack(_config, isServer, utils) {
+    configureWebpack(_config, isServer, utils, content) {
       const {getJSLoader} = utils;
       const {
         rehypePlugins,
@@ -378,9 +317,17 @@ export default function pluginContentDocs(
         beforeDefaultRemarkPlugins,
       } = options;
 
+      function getSourceToPermalink(): SourceToPermalink {
+        const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+        return mapValues(
+          keyBy(allDocs, (d) => d.source),
+          (d) => d.permalink,
+        );
+      }
+
       const docsMarkdownOptions: DocsMarkdownOption = {
         siteDir,
-        sourceToPermalink,
+        sourceToPermalink: getSourceToPermalink(),
         versionsMetadata,
         onBrokenMarkdownLink: (brokenMarkdownLink) => {
           if (siteConfig.onBrokenMarkdownLinks === 'ignore') {
@@ -394,12 +341,13 @@ export default function pluginContentDocs(
       };
 
       function createMDXLoaderRule(): RuleSetRule {
+        const contentDirs = versionsMetadata.flatMap(getDocsDirPaths);
         return {
           test: /(\.mdx?)$/,
-          include: flatten(versionsMetadata.map(getDocsDirPaths))
+          include: contentDirs
             // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
             .map(addTrailingPathSeparator),
-          use: compact([
+          use: [
             getJSLoader({isServer}),
             {
               loader: require.resolve('@docusaurus/mdx-loader'),
@@ -408,7 +356,14 @@ export default function pluginContentDocs(
                 rehypePlugins,
                 beforeDefaultRehypePlugins,
                 beforeDefaultRemarkPlugins,
-                staticDir: path.join(siteDir, STATIC_DIR_NAME),
+                staticDirs: siteConfig.staticDirectories.map((dir) =>
+                  path.resolve(siteDir, dir),
+                ),
+                siteDir,
+                isMDXPartial: createAbsoluteFilePathMatcher(
+                  options.exclude,
+                  contentDirs,
+                ),
                 metadataPath: (mdxPath: string) => {
                   // Note that metadataPath must be the same/in-sync as
                   // the path from createData for each MDX.
@@ -421,7 +376,7 @@ export default function pluginContentDocs(
               loader: path.resolve(__dirname, './markdown/index.js'),
               options: docsMarkdownOptions,
             },
-          ]),
+          ].filter(Boolean),
         };
       }
 

package/src/lastUpdate.ts

@@ -6,11 +6,10 @@
  */
 
 import shell from 'shelljs';
-import execa from 'execa';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+), (.+)$/;
+const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+),(.+)$/;
 
 let showedGitRequirementError = false;
 
@@ -43,13 +42,15 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const {stdout} = await execa('git', [
-      'log',
-      '-1',
-      '--format=%ct, %an',
-      filePath,
-    ]);
-    return getTimestampAndAuthor(stdout);
+    const result = shell.exec(`git log -1 --format=%ct,%an ${filePath}`, {
+      silent: true,
+    });
+    if (result.code !== 0) {
+      throw new Error(
+        `Retrieval of git history failed at ${filePath} with exit code ${result.code}: ${result.stderr}`,
+      );
+    }
+    return getTimestampAndAuthor(result.stdout.trim());
   } catch (error) {
     console.error(error);
   }

package/src/markdown/index.ts

@@ -7,20 +7,16 @@
 
 import {linkify} from './linkify';
 import {DocsMarkdownOption} from '../types';
+import type {LoaderContext} from 'webpack';
 
-// TODO temporary until Webpack5 export this type
-// see https://github.com/webpack/webpack/issues/11630
-interface Loader extends Function {
-  (this: any, source: string): string | Buffer | void | undefined;
-}
-
-const markdownLoader: Loader = function (source) {
-  const fileString = source as string;
+export default function markdownLoader(
+  this: LoaderContext<DocsMarkdownOption>,
+  source: string,
+): void {
+  const fileString = source;
   const callback = this.async();
-  const options = this.getOptions() as DocsMarkdownOption;
+  const options = this.getOptions();
   return (
     callback && callback(null, linkify(fileString, this.resourcePath, options))
   );
-};
-
-export default markdownLoader;
+}

package/src/numberPrefix.ts

@@ -5,12 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {NumberPrefixParser} from './types';
+import type {NumberPrefixParser} from './types';
 
 // Best-effort to avoid parsing some patterns as number prefix
 const IgnoredPrefixPatterns = (function () {
   // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
-  const DateLikePrefixRegex = /^((\d{2}|\d{4})[-_.]\d{2}([-_.](\d{2}|\d{4}))?)(.*)$/;
+  const DateLikePrefixRegex =
+    /^((\d{2}|\d{4})[-_.]\d{2}([-_.](\d{2}|\d{4}))?)(.*)$/;
 
   // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
   // note: we could try to parse float numbers in filenames but that is probably not worth it
@@ -23,7 +24,8 @@ const IgnoredPrefixPatterns = (function () {
   );
 })();
 
-const NumberPrefixRegex = /^(?<numberPrefix>\d+)(?<separator>\s*[-_.]+\s*)(?<suffix>.*)$/;
+const NumberPrefixRegex =
+  /^(?<numberPrefix>\d+)(?<separator>\s*[-_.]+\s*)(?<suffix>.*)$/;
 
 // 0-myDoc => {filename: myDoc, numberPrefix: 0}
 // 003 - myDoc => {filename: myDoc, numberPrefix: 3}