@docusaurus/plugin-content-docs 2.0.0-beta.15 → 2.0.0-beta.16

package/lib/cli.d.ts

@@ -5,4 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { PathOptions, SidebarOptions } from '@docusaurus/plugin-content-docs';
-export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions & SidebarOptions): void;
+export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions & SidebarOptions): Promise<void>;

package/lib/cli.js

@@ -14,21 +14,24 @@ const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const sidebars_1 = require("./sidebars");
 const utils_1 = require("@docusaurus/utils");
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
+async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
     // Load current sidebar and create a new versioned sidebars file (if needed).
-    // Note: we don't need the sidebars file to be normalized: it's ok to let plugin option changes to impact older, versioned sidebars
-    const sidebars = (0, sidebars_1.loadSidebarsFile)(sidebarPath);
-    // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
+    // Note: we don't need the sidebars file to be normalized: it's ok to let
+    // plugin option changes to impact older, versioned sidebars
+    // We don't validate here, assuming the user has already built the version
+    const sidebars = await (0, sidebars_1.loadSidebarsFileUnsafe)(sidebarPath);
+    // Do not create a useless versioned sidebars file if sidebars file is empty
+    // or sidebars are disabled/false)
     const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
     if (shouldCreateVersionedSidebarFile) {
         const versionedSidebarsDir = (0, versions_1.getVersionedSidebarsDirPath)(siteDir, pluginId);
         const newSidebarFile = path_1.default.join(versionedSidebarsDir, `version-${version}-sidebars.json`);
-        fs_extra_1.default.ensureDirSync(path_1.default.dirname(newSidebarFile));
-        fs_extra_1.default.writeFileSync(newSidebarFile, `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(newSidebarFile));
+        await fs_extra_1.default.writeFile(newSidebarFile, `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
     }
 }
 // Tests depend on non-default export for mocking.
-function cliDocsVersionCommand(version, siteDir, pluginId, options) {
+async function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     // It wouldn't be very user-friendly to show a [default] log prefix,
     // so we use [docs] instead of [default]
     const pluginIdLogPrefix = pluginId === utils_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
@@ -53,8 +56,8 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     // Load existing versions.
     let versions = [];
     const versionsJSONFile = (0, versions_1.getVersionsFilePath)(siteDir, pluginId);
-    if (fs_extra_1.default.existsSync(versionsJSONFile)) {
-        versions = JSON.parse(fs_extra_1.default.readFileSync(versionsJSONFile, 'utf8'));
+    if (await fs_extra_1.default.pathExists(versionsJSONFile)) {
+        versions = JSON.parse(await fs_extra_1.default.readFile(versionsJSONFile, 'utf8'));
     }
     // Check if version already exists.
     if (versions.includes(version)) {
@@ -63,15 +66,16 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     const { path: docsPath, sidebarPath } = options;
     // Copy docs files.
     const docsDir = path_1.default.join(siteDir, docsPath);
-    if (fs_extra_1.default.existsSync(docsDir) && fs_extra_1.default.readdirSync(docsDir).length > 0) {
+    if ((await fs_extra_1.default.pathExists(docsDir)) &&
+        (await fs_extra_1.default.readdir(docsDir)).length > 0) {
         const versionedDir = (0, versions_1.getVersionedDocsDirPath)(siteDir, pluginId);
         const newVersionDir = path_1.default.join(versionedDir, `version-${version}`);
-        fs_extra_1.default.copySync(docsDir, newVersionDir);
+        await fs_extra_1.default.copy(docsDir, newVersionDir);
     }
     else {
         throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
     }
-    createVersionedSidebarFile({
+    await createVersionedSidebarFile({
         siteDir,
         pluginId,
         version,
@@ -79,8 +83,8 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     });
     // Update versions.json file.
     versions.unshift(version);
-    fs_extra_1.default.ensureDirSync(path_1.default.dirname(versionsJSONFile));
-    fs_extra_1.default.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(versionsJSONFile));
+    await fs_extra_1.default.writeFile(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
     logger_1.default.success `name=${pluginIdLogPrefix}: version name=${version} created!`;
 }
 exports.cliDocsVersionCommand = cliDocsVersionCommand;

package/lib/client/docsClientUtils.js

@@ -14,7 +14,7 @@ const router_1 = require("@docusaurus/router");
 // it is useful to support multiple docs plugin instances
 function getActivePlugin(allPluginDatas, pathname, options = {}) {
     const activeEntry = Object.entries(allPluginDatas)
-        // A quick route sorting: '/android/foo' should match '/android' instead of '/'
+        // Route sorting: '/android/foo' should match '/android' instead of '/'
         .sort((a, b) => b[1].path.localeCompare(a[1].path))
         .find(([, pluginData]) => !!(0, router_1.matchPath)(pathname, {
         path: pluginData.path,
@@ -39,7 +39,7 @@ exports.getLatestVersion = getLatestVersion;
 const getActiveVersion = (data, pathname) => {
     const lastVersion = (0, exports.getLatestVersion)(data);
     // Last version is a route like /docs/*,
-    // we need to try to match it last or it would match /docs/version-1.0/* as well
+    // we need to match it last or it would match /docs/version-1.0/* as well
     const orderedVersionsMetadata = [
         ...data.versions.filter((version) => version !== lastVersion),
         lastVersion,

package/lib/client/index.d.ts

@@ -4,4 +4,16 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './globalDataHooks';
+import type { GlobalPluginData, GlobalVersion, ActivePlugin, ActiveDocContext, DocVersionSuggestions, GetActivePluginOptions } from '@docusaurus/plugin-content-docs/client';
+export declare const useAllDocsData: () => Record<string, GlobalPluginData>;
+export declare const useDocsData: (pluginId: string | undefined) => GlobalPluginData;
+export declare const useActivePlugin: (options?: GetActivePluginOptions) => ActivePlugin | undefined;
+export declare const useActivePluginAndVersion: (options?: GetActivePluginOptions) => {
+    activePlugin: ActivePlugin;
+    activeVersion: GlobalVersion | undefined;
+} | undefined;
+export declare const useVersions: (pluginId: string | undefined) => GlobalVersion[];
+export declare const useLatestVersion: (pluginId: string | undefined) => GlobalVersion;
+export declare const useActiveVersion: (pluginId: string | undefined) => GlobalVersion | undefined;
+export declare const useActiveDocContext: (pluginId: string | undefined) => ActiveDocContext;
+export declare const useDocVersionSuggestions: (pluginId: string | undefined) => DocVersionSuggestions;

package/lib/client/index.js

@@ -6,5 +6,70 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDocVersionSuggestions = exports.useActiveDocContext = exports.useActiveVersion = exports.useLatestVersion = exports.useVersions = exports.useActivePluginAndVersion = exports.useActivePlugin = exports.useDocsData = exports.useAllDocsData = void 0;
 const tslib_1 = require("tslib");
-(0, tslib_1.__exportStar)(require("./globalDataHooks"), exports);
+const router_1 = require("@docusaurus/router");
+const useGlobalData_1 = (0, tslib_1.__importStar)(require("@docusaurus/useGlobalData"));
+const docsClientUtils_1 = require("./docsClientUtils");
+// Important to use a constant object to avoid React useEffect executions etc.
+// see https://github.com/facebook/docusaurus/issues/5089
+const StableEmptyObject = {};
+// Not using useAllPluginInstancesData() because in blog-only mode, docs hooks
+// are still used by the theme. We need a fail-safe fallback when the docs
+// plugin is not in use
+const useAllDocsData = () => { var _a; return (_a = (0, useGlobalData_1.default)()['docusaurus-plugin-content-docs']) !== null && _a !== void 0 ? _a : StableEmptyObject; };
+exports.useAllDocsData = useAllDocsData;
+const useDocsData = (pluginId) => (0, useGlobalData_1.usePluginData)('docusaurus-plugin-content-docs', pluginId);
+exports.useDocsData = useDocsData;
+// TODO this feature should be provided by docusaurus core
+const useActivePlugin = (options = {}) => {
+    const data = (0, exports.useAllDocsData)();
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getActivePlugin)(data, pathname, options);
+};
+exports.useActivePlugin = useActivePlugin;
+const useActivePluginAndVersion = (options = {}) => {
+    const activePlugin = (0, exports.useActivePlugin)(options);
+    const { pathname } = (0, router_1.useLocation)();
+    if (activePlugin) {
+        const activeVersion = (0, docsClientUtils_1.getActiveVersion)(activePlugin.pluginData, pathname);
+        return {
+            activePlugin,
+            activeVersion,
+        };
+    }
+    return undefined;
+};
+exports.useActivePluginAndVersion = useActivePluginAndVersion;
+// versions are returned ordered (most recent first)
+const useVersions = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    return data.versions;
+};
+exports.useVersions = useVersions;
+const useLatestVersion = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    return (0, docsClientUtils_1.getLatestVersion)(data);
+};
+exports.useLatestVersion = useLatestVersion;
+// Note: return undefined on doc-unrelated pages,
+// because there's no version currently considered as active
+const useActiveVersion = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getActiveVersion)(data, pathname);
+};
+exports.useActiveVersion = useActiveVersion;
+const useActiveDocContext = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getActiveDocContext)(data, pathname);
+};
+exports.useActiveDocContext = useActiveDocContext;
+// Useful to say "hey, you are not on the latest docs version, please switch"
+const useDocVersionSuggestions = (pluginId) => {
+    const data = (0, exports.useDocsData)(pluginId);
+    const { pathname } = (0, router_1.useLocation)();
+    return (0, docsClientUtils_1.getDocVersionSuggestions)(data, pathname);
+};
+exports.useDocVersionSuggestions = useDocVersionSuggestions;

package/lib/docFrontMatter.js

@@ -24,6 +24,7 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),
     sidebar_position: utils_validation_1.JoiFrontMatter.number(),
     sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
+    sidebar_custom_props: utils_validation_1.JoiFrontMatter.object().unknown(),
     displayed_sidebar: utils_validation_1.JoiFrontMatter.string().allow(null),
     tags: utils_validation_1.FrontMatterTagsSchema,
     pagination_label: utils_validation_1.JoiFrontMatter.string(),

package/lib/docs.d.ts

@@ -32,7 +32,8 @@ export declare function getMainDocId({ docs, sidebarsUtils, }: {
 export declare const isCategoryIndex: CategoryIndexMatcher;
 export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
 /**
- * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
 export declare function splitPath(str: string): {
     /**

package/lib/docs.js

@@ -11,7 +11,6 @@ const tslib_1 = require("tslib");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-const lodash_1 = require("lodash");
 const utils_1 = require("@docusaurus/utils");
 const lastUpdate_1 = require("./lastUpdate");
 const slug_1 = (0, tslib_1.__importDefault)(require("./slug"));
@@ -65,7 +64,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
     const frontMatter = (0, docFrontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
     const { custom_edit_url: customEditURL, 
-    // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
+    // Strip number prefixes by default
+    // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
     // ex: api/plugins/myDoc -> myDoc
@@ -81,7 +81,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     if (baseID.includes('/')) {
         throw new Error(`Document id "${baseID}" cannot include slash.`);
     }
-    // For autogenerated sidebars, sidebar position can come from filename number prefix or front matter
+    // For autogenerated sidebars, sidebar position can come from filename number
+    // prefix or front matter
     const sidebarPosition = (_b = frontMatter.sidebar_position) !== null && _b !== void 0 ? _b : numberPrefix;
     // TODO legacy retrocompatibility
     // The same doc in 2 distinct version could keep the same id,
@@ -114,8 +115,9 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         stripDirNumberPrefixes: parseNumberPrefixes,
         numberPrefixParser: options.numberPrefixParser,
     });
-    // Note: the title is used by default for page title, sidebar label, pagination buttons...
-    // frontMatter.title should be used in priority over contentTitle (because it can contain markdown/JSX syntax)
+    // Note: the title is used by default for page title, sidebar label,
+    // pagination buttons... frontMatter.title should be used in priority over
+    // contentTitle (because it can contain markdown/JSX syntax)
     const title = (_d = (_c = frontMatter.title) !== null && _c !== void 0 ? _c : contentTitle) !== null && _d !== void 0 ? _d : baseID;
     const description = (_f = (_e = frontMatter.description) !== null && _e !== void 0 ? _e : excerpt) !== null && _f !== void 0 ? _f : '';
     const permalink = (0, utils_1.normalizeUrl)([versionMetadata.versionPath, docSlug]);
@@ -137,9 +139,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
                 : versionMetadata.versionEditUrl;
             return (0, utils_1.getEditUrl)(relativeFilePath, baseVersionEditUrl);
         }
-        else {
-            return undefined;
-        }
+        return undefined;
     }
     // Assign all of object properties during instantiation (if possible) for
     // NodeJS optimization.
@@ -170,9 +170,9 @@ function processDocMetadata(args) {
     try {
         return doProcessDocMetadata(args);
     }
-    catch (e) {
+    catch (err) {
         logger_1.default.error `Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`;
-        throw e;
+        throw err;
     }
 }
 exports.processDocMetadata = processDocMetadata;
@@ -225,9 +225,7 @@ function getMainDocId({ docs, sidebarsUtils, }) {
             return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar ||
                 doc.unversionedId === firstDocIdOfFirstSidebar);
         }
-        else {
-            return docs[0];
-        }
+        return docs[0];
     }
     return getMainDoc().unversionedId;
 }
@@ -262,7 +260,8 @@ function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
 }
 exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
 /**
- * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
 function splitPath(str) {
     return {
@@ -273,19 +272,21 @@ function splitPath(str) {
 }
 exports.splitPath = splitPath;
 // 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")
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
 function getDocIds(doc) {
     return [doc.unversionedId, doc.id];
 }
 exports.getDocIds = getDocIds;
 // 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")
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
 function createDocsByIdIndex(docs) {
-    return {
-        ...(0, lodash_1.keyBy)(docs, (doc) => doc.unversionedId),
-        ...(0, lodash_1.keyBy)(docs, (doc) => doc.id),
-    };
+    return Object.fromEntries(docs.flatMap((doc) => [
+        [doc.unversionedId, doc],
+        [doc.id, doc],
+    ]));
 }
 exports.createDocsByIdIndex = createDocsByIdIndex;

package/lib/globalData.js

@@ -7,7 +7,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toGlobalDataVersion = exports.toGlobalSidebars = exports.toGlobalDataGeneratedIndex = exports.toGlobalDataDoc = void 0;
-const lodash_1 = require("lodash");
+const tslib_1 = require("tslib");
+const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 const utils_2 = require("./sidebars/utils");
 function toGlobalDataDoc(doc) {
@@ -28,7 +29,7 @@ function toGlobalDataGeneratedIndex(doc) {
 exports.toGlobalDataGeneratedIndex = toGlobalDataGeneratedIndex;
 function toGlobalSidebars(sidebars, version) {
     const { getFirstLink } = (0, utils_2.createSidebarsUtils)(sidebars);
-    return (0, lodash_1.mapValues)(sidebars, (sidebar, sidebarId) => {
+    return lodash_1.default.mapValues(sidebars, (sidebar, sidebarId) => {
         const firstLink = getFirstLink(sidebarId);
         if (!firstLink) {
             return {};

package/lib/index.js

@@ -16,7 +16,6 @@ const docs_1 = require("./docs");
 const versions_1 = require("./versions");
 const cli_1 = require("./cli");
 const constants_1 = require("./constants");
-const lodash_1 = require("lodash");
 const globalData_1 = require("./globalData");
 const props_1 = require("./props");
 const translations_1 = require("./translations");
@@ -119,9 +118,9 @@ async function pluginContentDocs(context, options) {
                 try {
                     return await doLoadVersion(versionMetadata);
                 }
-                catch (e) {
+                catch (err) {
                     logger_1.default.error `Loading of version failed for version name=${versionMetadata.versionName}`;
-                    throw e;
+                    throw err;
                 }
             }
             return {
@@ -133,7 +132,7 @@ async function pluginContentDocs(context, options) {
         },
         async contentLoaded({ content, actions }) {
             const { loadedVersions } = content;
-            const { docLayoutComponent, docItemComponent, docCategoryGeneratedIndexComponent, } = options;
+            const { docLayoutComponent, docItemComponent, docCategoryGeneratedIndexComponent, breadcrumbs, } = options;
             const { addRoute, createData, setGlobalData } = actions;
             async function createVersionTagsRoutes(version) {
                 const versionTags = (0, tags_1.getVersionTags)(version.docs);
@@ -191,6 +190,7 @@ async function pluginContentDocs(context, options) {
             setGlobalData({
                 path: (0, utils_1.normalizeUrl)([baseUrl, options.routeBasePath]),
                 versions: loadedVersions.map(globalData_1.toGlobalDataVersion),
+                breadcrumbs,
             });
         },
         configureWebpack(_config, isServer, utils, content) {
@@ -198,7 +198,7 @@ async function pluginContentDocs(context, options) {
             const { rehypePlugins, remarkPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
             function getSourceToPermalink() {
                 const allDocs = content.loadedVersions.flatMap((v) => v.docs);
-                return (0, lodash_1.mapValues)((0, lodash_1.keyBy)(allDocs, (d) => d.source), (d) => d.permalink);
+                return Object.fromEntries(allDocs.map(({ source, permalink }) => [source, permalink]));
             }
             const docsMarkdownOptions = {
                 siteDir,
@@ -214,7 +214,7 @@ async function pluginContentDocs(context, options) {
             function createMDXLoaderRule() {
                 const contentDirs = versionsMetadata.flatMap(versions_1.getDocsDirPaths);
                 return {
-                    test: /(\.mdx?)$/,
+                    test: /\.mdx?$/i,
                     include: contentDirs
                         // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                         .map(utils_1.addTrailingPathSeparator),
@@ -236,6 +236,11 @@ async function pluginContentDocs(context, options) {
                                     const aliasedPath = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
                                     return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
                                 },
+                                // Assets allow to convert some relative images paths to
+                                // require(...) calls
+                                createAssets: ({ frontMatter, }) => ({
+                                    image: frontMatter.image,
+                                }),
                             },
                         },
                         {

package/lib/lastUpdate.js

@@ -8,44 +8,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFileLastUpdate = void 0;
 const tslib_1 = require("tslib");
-const shelljs_1 = (0, tslib_1.__importDefault)(require("shelljs"));
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+),(.+)$/;
+const utils_1 = require("@docusaurus/utils");
 let showedGitRequirementError = false;
 async function getFileLastUpdate(filePath) {
     if (!filePath) {
         return null;
     }
-    function getTimestampAndAuthor(str) {
-        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 (!shelljs_1.default.which('git')) {
-            if (!showedGitRequirementError) {
-                showedGitRequirementError = true;
-                logger_1.default.warn('Sorry, the docs plugin last update options require Git.');
-            }
-            return null;
-        }
-        const result = shelljs_1.default.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
-            silent: true,
+        const result = (0, utils_1.getFileCommitDate)(filePath, {
+            age: 'newest',
+            includeAuthor: 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());
+        return { timestamp: result.timestamp, author: result.author };
     }
-    catch (e) {
-        logger_1.default.error(e);
+    catch (err) {
+        if (err instanceof utils_1.GitNotFoundError && !showedGitRequirementError) {
+            logger_1.default.warn('Sorry, the docs plugin last update options require Git.');
+            showedGitRequirementError = true;
+        }
+        else {
+            logger_1.default.error(err);
+        }
+        return null;
     }
-    return null;
 }
 exports.getFileLastUpdate = getFileLastUpdate;

package/lib/numberPrefix.js

@@ -8,14 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripPathNumberPrefixes = exports.stripNumberPrefix = exports.DisabledNumberPrefixParser = exports.DefaultNumberPrefixParser = void 0;
 // Best-effort to avoid parsing some patterns as number prefix
-const IgnoredPrefixPatterns = (function () {
+const IgnoredPrefixPatterns = (() => {
     // 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
-    // as a version such as "8.0" can be interpreted as both a version and a float
-    // User can configure his own NumberPrefixParser if he wants 8.0 to be interpreted as a float
-    const VersionLikePrefixRegex = /^(\d+[-_.]\d+)(.*)$/;
+    // note: we could try to parse float numbers in filenames but that is
+    // probably not worth it as a version such as "8.0" can be interpreted as both
+    // a version and a float. User can configure her own NumberPrefixParser if
+    // she wants 8.0 to be interpreted as a float
+    const VersionLikePrefixRegex = /^\d+[-_.]\d+.*$/;
     return new RegExp(`${DateLikePrefixRegex.source}|${VersionLikePrefixRegex.source}`);
 })();
 const NumberPrefixRegex = /^(?<numberPrefix>\d+)(?<separator>\s*[-_.]+\s*)(?<suffix>.*)$/;

package/lib/options.js

@@ -42,6 +42,7 @@ exports.DEFAULT_OPTIONS = {
     editLocalizedFiles: false,
     sidebarCollapsible: true,
     sidebarCollapsed: true,
+    breadcrumbs: true,
 };
 const VersionOptionsSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().allow('').optional(),
@@ -98,12 +99,14 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
     disableVersioning: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.disableVersioning),
     lastVersion: utils_validation_1.Joi.string().optional(),
     versions: VersionsOptionsSchema,
+    breadcrumbs: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.breadcrumbs),
 });
 function validateOptions({ validate, options: userOptions, }) {
     let options = userOptions;
     if (options.sidebarCollapsible === false) {
-        // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't want to have the inconsistency warning
-        // We let options.sidebarCollapsible become the default value for options.sidebarCollapsed
+        // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't
+        // want to have the inconsistency warning. We let options.sidebarCollapsible
+        // become the default value for options.sidebarCollapsed
         if (typeof options.sidebarCollapsed === 'undefined') {
             options = {
                 ...options,

package/lib/props.js

@@ -7,7 +7,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
-const lodash_1 = require("lodash");
+const tslib_1 = require("tslib");
+const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
 const docs_1 = require("./docs");
 function toSidebarsProp(loadedVersion) {
     const docsById = (0, docs_1.createDocsByIdIndex)(loadedVersion.docs);
@@ -21,6 +22,7 @@ Available document ids are:
         return docMetadata;
     }
     const convertDocLink = (item) => {
+        var _a;
         const docMetadata = getDocById(item.id);
         const { title, permalink, frontMatter: { sidebar_label: sidebarLabel }, } = docMetadata;
         return {
@@ -28,7 +30,7 @@ Available document ids are:
             label: sidebarLabel || item.label || title,
             href: permalink,
             className: item.className,
-            customProps: item.customProps,
+            customProps: (_a = item.customProps) !== null && _a !== void 0 ? _a : docMetadata.frontMatter.sidebar_custom_props,
             docId: docMetadata.unversionedId,
         };
     };
@@ -62,16 +64,19 @@ Available document ids are:
     // 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 (0, lodash_1.mapValues)(loadedVersion.sidebars, (items) => items.map(normalizeItem));
+    return lodash_1.default.mapValues(loadedVersion.sidebars, (items) => items.map(normalizeItem));
 }
 exports.toSidebarsProp = toSidebarsProp;
 function toVersionDocsProp(loadedVersion) {
-    return (0, lodash_1.mapValues)((0, lodash_1.keyBy)(loadedVersion.docs, (doc) => doc.unversionedId), (doc) => ({
-        id: doc.unversionedId,
-        title: doc.title,
-        description: doc.description,
-        sidebar: doc.sidebar,
-    }));
+    return Object.fromEntries(loadedVersion.docs.map((doc) => [
+        doc.unversionedId,
+        {
+            id: doc.unversionedId,
+            title: doc.title,
+            description: doc.description,
+            sidebar: doc.sidebar,
+        },
+    ]));
 }
 function toVersionMetadataProp(pluginId, loadedVersion) {
     return {
@@ -89,7 +94,7 @@ function toVersionMetadataProp(pluginId, loadedVersion) {
 exports.toVersionMetadataProp = toVersionMetadataProp;
 function toTagDocListProp({ allTagsPath, tag, docs, }) {
     function toDocListProp() {
-        const list = (0, lodash_1.compact)(tag.docIds.map((id) => docs.find((doc) => doc.id === id)));
+        const list = lodash_1.default.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) => ({

package/lib/routes.js

@@ -36,7 +36,8 @@ async function createCategoryGeneratedIndexRoutes({ version, actions, docCategor
             modules: {
                 categoryGeneratedIndex: aliasedSource(propData),
             },
-            // Same as doc, this sidebar route attribute permits to associate this subpage to the given sidebar
+            // Same as doc, this sidebar route attribute permits to associate this
+            // subpage to the given sidebar
             ...(sidebar && { sidebar }),
         };
     }
@@ -57,7 +58,8 @@ async function createDocRoutes({ docs, actions, docItemComponent, }) {
                 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)
+            // This permits to render the sidebar once without unmount/remount when
+            // navigating (and preserve sidebar state)
             ...(metadataItem.sidebar && {
                 sidebar: metadataItem.sidebar,
             }),
@@ -100,9 +102,9 @@ async function createVersionRoutes({ loadedVersion, actions, docItemComponent, d
     try {
         return await doCreateVersionRoutes(loadedVersion);
     }
-    catch (e) {
+    catch (err) {
         logger_1.default.error `Can't create version routes for version name=${loadedVersion.versionName}`;
-        throw e;
+        throw err;
     }
 }
 exports.createVersionRoutes = createVersionRoutes;

package/lib/server-export.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export { CURRENT_VERSION_NAME, VERSIONED_DOCS_DIR, VERSIONED_SIDEBARS_DIR, VERSIONS_JSON_FILE, } from './constants';
+export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, getVersionsFilePath, readVersionsFile, readVersionNames, } from './versions';