@docusaurus/plugin-content-docs 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/index.ts

@@ -6,60 +6,71 @@
  */
 
 import path from 'path';
-
-import {
-  STATIC_DIR_NAME,
-  DEFAULT_PLUGIN_ID,
-} from '@docusaurus/core/lib/constants';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
 import {
   normalizeUrl,
   docuHash,
   aliasedSitePath,
-  reportMessage,
+  getContentPathList,
   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 {getDocsDirPaths, readVersionsMetadata} from './versions';
-
+import {loadSidebars, resolveSidebarPathOption} from './sidebars';
+import {CategoryMetadataFilenamePattern} from './sidebars/generator';
 import {
-  PluginOptions,
-  LoadedContent,
-  SourceToPermalink,
-  DocMetadataBase,
-  DocMetadata,
-  GlobalPluginData,
-  VersionMetadata,
-  DocNavLink,
-  LoadedVersion,
-  DocFile,
-  DocsMarkdownOption,
-} from './types';
-import {RuleSetRule} from 'webpack';
+  readVersionDocs,
+  processDocMetadata,
+  addDocNavigation,
+  type DocEnv,
+} from './docs';
+import {readVersionsMetadata} from './versions';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
-import {flatten, keyBy, compact, mapValues} from 'lodash';
 import {toGlobalDataVersion} from './globalData';
-import {toVersionMetadataProp} from './props';
+import {toTagDocListProp} from './props';
+import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
 import {
   translateLoadedContent,
   getLoadedContentTranslationFiles,
 } from './translations';
-import {CategoryMetadataFilenamePattern} from './sidebarItemsGenerator';
-import chalk from 'chalk';
+import {getVersionTags} from './tags';
+import {createVersionRoutes} from './routes';
+import {createSidebarsUtils} from './sidebars/utils';
+
+import type {
+  PropTagsListPage,
+  PluginOptions,
+  DocMetadataBase,
+  VersionMetadata,
+  DocFrontMatter,
+  LoadedContent,
+  LoadedVersion,
+} from '@docusaurus/plugin-content-docs';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {
+  SourceToPermalink,
+  DocFile,
+  DocsMarkdownOption,
+  VersionTag,
+  FullVersion,
+} from './types';
+import type {RuleSetRule} from 'webpack';
 
-export default function pluginContentDocs(
+export default async function pluginContentDocs(
   context: LoadContext,
   options: PluginOptions,
-): Plugin<LoadedContent> {
+): Promise<Plugin<LoadedContent>> {
   const {siteDir, generatedFilesDir, baseUrl, siteConfig} = context;
+  // Mutate options to resolve sidebar path according to siteDir
+  options.sidebarPath = resolveSidebarPathOption(siteDir, options.sidebarPath);
 
-  const versionsMetadata = readVersionsMetadata({context, options});
+  const versionsMetadata = await readVersionsMetadata({context, options});
 
-  const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
+  const pluginId = options.id;
 
   const pluginDataDirRoot = path.join(
     generatedFilesDir,
@@ -72,14 +83,6 @@ export default function pluginContentDocs(
   return {
     name: 'docusaurus-plugin-content-docs',
 
-    getThemePath() {
-      return path.resolve(__dirname, './theme');
-    },
-
-    getTypeScriptThemePath() {
-      return path.resolve(__dirname, '..', 'src', 'theme');
-    },
-
     extendCli(cli) {
       const isDefaultPluginId = pluginId === DEFAULT_PLUGIN_ID;
 
@@ -96,28 +99,21 @@ export default function pluginContentDocs(
         .command(command)
         .arguments('<version>')
         .description(commandDescription)
-        .action((version) => {
-          cliDocsVersionCommand(version, siteDir, pluginId, {
-            path: options.path,
-            sidebarPath: options.sidebarPath,
-            sidebarCollapsed: options.sidebarCollapsed,
-            sidebarCollapsible: options.sidebarCollapsible,
-          });
-        });
+        .action((version: unknown) =>
+          cliDocsVersionCommand(version, options, context),
+        );
     },
 
-    async getTranslationFiles({content}) {
+    getTranslationFiles({content}) {
       return getLoadedContentTranslationFiles(content);
     },
 
     getPathsToWatch() {
       function getVersionPathsToWatch(version: VersionMetadata): string[] {
         const result = [
-          ...flatten(
-            options.include.map((pattern) =>
-              getDocsDirPaths(version).map(
-                (docsDirPath) => `${docsDirPath}/${pattern}`,
-              ),
+          ...options.include.flatMap((pattern) =>
+            getContentPathList(version).map(
+              (docsDirPath) => `${docsDirPath}/${pattern}`,
             ),
           ),
           `${version.contentPath}/**/${CategoryMetadataFilenamePattern}`,
@@ -128,7 +124,7 @@ export default function pluginContentDocs(
         return result;
       }
 
-      return flatten(versionsMetadata.map(getVersionPathsToWatch));
+      return versionsMetadata.flatMap(getVersionPathsToWatch);
     },
 
     async loadContent() {
@@ -146,12 +142,13 @@ export default function pluginContentDocs(
             )}".`,
           );
         }
-        async function processVersionDoc(docFile: DocFile) {
+        function processVersionDoc(docFile: DocFile) {
           return processDocMetadata({
             docFile,
             versionMetadata,
             context,
             options,
+            env: process.env.NODE_ENV as DocEnv,
           });
         }
         return Promise.all(docFiles.map(processVersionDoc));
@@ -160,110 +157,45 @@ export default function pluginContentDocs(
       async function doLoadVersion(
         versionMetadata: VersionMetadata,
       ): Promise<LoadedVersion> {
-        const unprocessedSidebars = loadSidebars(
-          versionMetadata.sidebarFilePath,
-          {
-            sidebarCollapsed: options.sidebarCollapsed,
-            sidebarCollapsible: options.sidebarCollapsible,
-          },
-        );
-
         const docsBase: DocMetadataBase[] = await loadVersionDocsBase(
           versionMetadata,
         );
-        const docsBaseById: Record<string, DocMetadataBase> = keyBy(
-          docsBase,
-          (doc) => doc.id,
-        );
 
-        const sidebars = await processSidebars({
+        const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
+
+        const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
           sidebarItemsGenerator: options.sidebarItemsGenerator,
           numberPrefixParser: options.numberPrefixParser,
-          unprocessedSidebars,
-          docs: docsBase,
+          docs,
+          drafts,
           version: versionMetadata,
-          options: {
+          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));
-
-        // 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,
+          ),
+          drafts,
           sidebars,
-          docs: docs.map(addNavData),
         };
       }
 
       async function loadVersion(versionMetadata: VersionMetadata) {
         try {
           return await doLoadVersion(versionMetadata);
-        } catch (e) {
-          console.error(
-            chalk.red(
-              `Loading of version failed for version "${versionMetadata.versionName}"`,
-            ),
-          );
-          throw e;
+        } catch (err) {
+          logger.error`Loading of version failed for version name=${versionMetadata.versionName}`;
+          throw err;
         }
       }
 
@@ -278,88 +210,101 @@ export default function pluginContentDocs(
 
     async contentLoaded({content, actions}) {
       const {loadedVersions} = content;
-      const {docLayoutComponent, docItemComponent} = options;
+      const {
+        docLayoutComponent,
+        docItemComponent,
+        docCategoryGeneratedIndexComponent,
+        breadcrumbs,
+      } = options;
       const {addRoute, createData, setGlobalData} = actions;
+      const versions: FullVersion[] = loadedVersions.map((version) => {
+        const sidebarsUtils = createSidebarsUtils(version.sidebars);
+        return {
+          ...version,
+          sidebarsUtils,
+          categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({
+            docs: version.docs,
+            sidebarsUtils,
+          }),
+        };
+      });
 
-      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: FullVersion) {
+        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) => ({
+            label: tagValue.label,
+            permalink: tagValue.permalink,
+            count: tagValue.docIds.length,
+          }));
+
+          // Only create /tags page if there are tags.
+          if (tagsProp.length > 0) {
+            const tagsPropPath = await createData(
+              `${docuHash(`tags-list-${version.versionName}-prop`)}.json`,
+              JSON.stringify(tagsProp, null, 2),
             );
-
-            const docRoute: RouteConfig = {
-              path: metadataItem.permalink,
-              component: docItemComponent,
+            addRoute({
+              path: version.tagsPath,
               exact: true,
+              component: options.docTagsListComponent,
               modules: {
-                content: metadataItem.source,
+                tags: aliasedSource(tagsPropPath),
               },
-              // 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 doCreateVersionRoutes(
-        loadedVersion: LoadedVersion,
-      ): Promise<void> {
-        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}"`,
-            ),
+        // 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(
+        versions.map((version) =>
+          createVersionRoutes({
+            version,
+            docItemComponent,
+            docLayoutComponent,
+            docCategoryGeneratedIndexComponent,
+            pluginId,
+            aliasedSource,
+            actions,
+          }),
+        ),
+      );
+
+      // TODO tags should be a sub route of the version route
+      await Promise.all(versions.map(createVersionTagsRoutes));
 
-      setGlobalData<GlobalPluginData>({
+      setGlobalData({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
-        versions: loadedVersions.map(toGlobalDataVersion),
+        versions: versions.map(toGlobalDataVersion),
+        breadcrumbs,
       });
     },
 
@@ -373,10 +318,9 @@ export default function pluginContentDocs(
       } = options;
 
       function getSourceToPermalink(): SourceToPermalink {
-        const allDocs = flatten(content.loadedVersions.map((v) => v.docs));
-        return mapValues(
-          keyBy(allDocs, (d) => d.source),
-          (d) => d.permalink,
+        const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+        return Object.fromEntries(
+          allDocs.map(({source, permalink}) => [source, permalink]),
         );
       }
 
@@ -385,33 +329,33 @@ export default function pluginContentDocs(
         sourceToPermalink: getSourceToPermalink(),
         versionsMetadata,
         onBrokenMarkdownLink: (brokenMarkdownLink) => {
-          if (siteConfig.onBrokenMarkdownLinks === 'ignore') {
-            return;
-          }
-          reportMessage(
-            `Docs markdown link couldn't be resolved: (${brokenMarkdownLink.link}) in ${brokenMarkdownLink.filePath} for version ${brokenMarkdownLink.contentPaths.versionName}`,
+          logger.report(
             siteConfig.onBrokenMarkdownLinks,
-          );
+          )`Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
         },
       };
 
       function createMDXLoaderRule(): RuleSetRule {
-        const contentDirs = flatten(versionsMetadata.map(getDocsDirPaths));
+        const contentDirs = versionsMetadata.flatMap(getContentPathList);
         return {
-          test: /(\.mdx?)$/,
+          test: /\.mdx?$/i,
           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'),
               options: {
+                admonitions: options.admonitions,
                 remarkPlugins,
                 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,
@@ -422,13 +366,22 @@ export default function pluginContentDocs(
                   const aliasedPath = aliasedSitePath(mdxPath, siteDir);
                   return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
                 },
+                // Assets allow to convert some relative images paths to
+                // require(...) calls
+                createAssets: ({
+                  frontMatter,
+                }: {
+                  frontMatter: DocFrontMatter;
+                }) => ({
+                  image: frontMatter.image,
+                }),
               },
             },
             {
               loader: path.resolve(__dirname, './markdown/index.js'),
               options: docsMarkdownOptions,
             },
-          ]),
+          ].filter(Boolean),
         };
       }
 

package/src/lastUpdate.ts

@@ -5,58 +5,47 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import shell from 'shelljs';
-import execa from 'execa';
-import path from 'path';
-
-type FileLastUpdateData = {timestamp?: number; author?: string};
-
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+), (.+)$/;
+import logger from '@docusaurus/logger';
+import {
+  getFileCommitDate,
+  FileNotTrackedError,
+  GitNotFoundError,
+} from '@docusaurus/utils';
 
 let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
 
 export async function getFileLastUpdate(
-  filePath?: string,
-): Promise<FileLastUpdateData | null> {
+  filePath: string,
+): Promise<{timestamp: number; author: string} | null> {
   if (!filePath) {
     return null;
   }
-  function getTimestampAndAuthor(str: string): FileLastUpdateData | null {
-    if (!str) {
-      return null;
-    }
-
-    const temp = str.match(GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX);
-    return !temp || temp.length < 3
-      ? null
-      : {timestamp: +temp[1], author: temp[2]};
-  }
 
   // Wrap in try/catch in case the shell commands fail
   // (e.g. project doesn't use Git, etc).
   try {
-    if (!shell.which('git')) {
+    const result = getFileCommitDate(filePath, {
+      age: 'newest',
+      includeAuthor: true,
+    });
+    return {timestamp: result.timestamp, author: result.author};
+  } catch (err) {
+    if (err instanceof GitNotFoundError) {
       if (!showedGitRequirementError) {
+        logger.warn('Sorry, the docs plugin last update options require Git.');
         showedGitRequirementError = true;
-        console.warn('Sorry, the docs plugin last update options require Git.');
       }
-
-      return null;
+    } else if (err instanceof FileNotTrackedError) {
+      if (!showedFileNotTrackedError) {
+        logger.warn(
+          'Cannot infer the update date for some files, as they are not tracked by git.',
+        );
+        showedFileNotTrackedError = true;
+      }
+    } else {
+      logger.warn(err);
     }
-
-    const fileBasename = path.basename(filePath);
-    const fileDirname = path.dirname(filePath);
-    const {stdout} = await execa(
-      'git',
-      ['log', '-1', '--format=%ct, %an', fileBasename],
-      {
-        cwd: fileDirname,
-      },
-    );
-    return getTimestampAndAuthor(stdout);
-  } catch (error) {
-    console.error(error);
+    return null;
   }
-
-  return null;
 }

package/src/markdown/index.ts

@@ -6,21 +6,15 @@
  */
 
 import {linkify} from './linkify';
-import {DocsMarkdownOption} from '../types';
+import type {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;
-  return (
-    callback && callback(null, linkify(fileString, this.resourcePath, options))
-  );
-};
-
-export default markdownLoader;
+  const options = this.getOptions();
+  return callback(null, linkify(fileString, this.resourcePath, options));
+}