@docusaurus/plugin-content-docs 2.0.0-beta.138b4c997 → 2.0.0-beta.14

package/lib/categoryGeneratedIndex.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { CategoryGeneratedIndexMetadata, DocMetadataBase } from './types';
+import { SidebarsUtils } from './sidebars/utils';
+export declare function getCategoryGeneratedIndexMetadataList({ docs, sidebarsUtils, }: {
+    sidebarsUtils: SidebarsUtils;
+    docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[];

package/lib/categoryGeneratedIndex.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCategoryGeneratedIndexMetadataList = void 0;
+const utils_1 = require("./sidebars/utils");
+const docs_1 = require("./docs");
+function getCategoryGeneratedIndexMetadata({ category, sidebarsUtils, docsById, }) {
+    var _a;
+    const { sidebarName, previous, next } = sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+    if (!sidebarName) {
+        throw new Error('unexpected');
+    }
+    return {
+        title: (_a = category.link.title) !== null && _a !== void 0 ? _a : category.label,
+        description: category.link.description,
+        slug: category.link.slug,
+        permalink: category.link.permalink,
+        sidebar: sidebarName,
+        previous: (0, utils_1.toNavigationLink)(previous, docsById),
+        next: (0, utils_1.toNavigationLink)(next, docsById),
+    };
+}
+function getCategoryGeneratedIndexMetadataList({ docs, sidebarsUtils, }) {
+    const docsById = (0, docs_1.createDocsByIdIndex)(docs);
+    const categoryGeneratedIndexItems = sidebarsUtils.getCategoryGeneratedIndexList();
+    return categoryGeneratedIndexItems.map((category) => getCategoryGeneratedIndexMetadata({
+        category,
+        sidebarsUtils,
+        docsById,
+    }));
+}
+exports.getCategoryGeneratedIndexMetadataList = getCategoryGeneratedIndexMetadataList;

package/lib/cli.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { PathOptions } from './types';
-export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions): void;
+import type { PathOptions, SidebarOptions } from './types';
+export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions & SidebarOptions): void;

package/lib/cli.js

@@ -9,50 +9,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cliDocsVersionCommand = void 0;
 const tslib_1 = require("tslib");
 const versions_1 = require("./versions");
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const path_1 = tslib_1.__importDefault(require("path"));
+const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const sidebars_1 = require("./sidebars");
-const constants_1 = require("@docusaurus/core/lib/constants");
+const utils_1 = require("@docusaurus/utils");
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
 function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
     // Load current sidebar and create a new versioned sidebars file (if needed).
-    const loadedSidebars = sidebars_1.loadSidebars(sidebarPath);
+    // 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)
-    const shouldCreateVersionedSidebarFile = Object.keys(loadedSidebars).length > 0;
+    const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
     if (shouldCreateVersionedSidebarFile) {
-        // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
-        // TODO try to get rid of it
-        // Transform id in original sidebar to versioned id.
-        const normalizeItem = (item) => {
-            switch (item.type) {
-                case 'category':
-                    return { ...item, items: item.items.map(normalizeItem) };
-                case 'ref':
-                case 'doc':
-                    return {
-                        type: item.type,
-                        id: `version-${version}/${item.id}`,
-                    };
-                default:
-                    return item;
-            }
-        };
-        const versionedSidebar = Object.entries(loadedSidebars).reduce((acc, [sidebarId, sidebarItems]) => {
-            const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-            acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-            return acc;
-        }, {});
-        const versionedSidebarsDir = versions_1.getVersionedSidebarsDirPath(siteDir, pluginId);
+        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(versionedSidebar, null, 2)}\n`, 'utf8');
+        fs_extra_1.default.writeFileSync(newSidebarFile, `${JSON.stringify(sidebars, null, 2)}\n`, 'utf8');
     }
 }
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
 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 === constants_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
+    const pluginIdLogPrefix = pluginId === utils_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
     if (!version) {
         throw new Error(`${pluginIdLogPrefix}: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0.`);
     }
@@ -73,7 +52,7 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     }
     // Load existing versions.
     let versions = [];
-    const versionsJSONFile = versions_1.getVersionsFilePath(siteDir, pluginId);
+    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'));
     }
@@ -85,7 +64,7 @@ function cliDocsVersionCommand(version, siteDir, pluginId, 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) {
-        const versionedDir = versions_1.getVersionedDocsDirPath(siteDir, pluginId);
+        const versionedDir = (0, versions_1.getVersionedDocsDirPath)(siteDir, pluginId);
         const newVersionDir = path_1.default.join(versionedDir, `version-${version}`);
         fs_extra_1.default.copySync(docsDir, newVersionDir);
     }
@@ -96,12 +75,12 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
         siteDir,
         pluginId,
         version,
-        sidebarPath: sidebars_1.resolveSidebarPathOption(siteDir, sidebarPath),
+        sidebarPath: (0, sidebars_1.resolveSidebarPathOption)(siteDir, sidebarPath),
     });
     // 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`);
-    console.log(`${pluginIdLogPrefix}: version ${version} created!`);
+    logger_1.default.success `name=${pluginIdLogPrefix}: version name=${version} created!`;
 }
 exports.cliDocsVersionCommand = cliDocsVersionCommand;

package/lib/client/docsClientUtils.d.ts

@@ -14,9 +14,6 @@ export declare type ActivePlugin = {
 export declare type GetActivePluginOptions = {
     failfast?: boolean;
 };
-export declare function getActivePlugin(allPluginDatas: Record<string, GlobalPluginData>, pathname: string, options: {
-    failfast: true;
-}): ActivePlugin;
 export declare function getActivePlugin(allPluginDatas: Record<string, GlobalPluginData>, pathname: string, options?: GetActivePluginOptions): ActivePlugin | undefined;
 export declare type ActiveDocContext = {
     activeVersion?: Version;

package/lib/client/docsClientUtils.js

@@ -8,14 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDocVersionSuggestions = exports.getActiveDocContext = exports.getActiveVersion = exports.getLatestVersion = exports.getActivePlugin = void 0;
 const router_1 = require("@docusaurus/router");
+// get the data of the plugin that is currently "active"
+// ie the docs of that plugin are currently browsed
+// it is useful to support multiple docs plugin instances
 function getActivePlugin(allPluginDatas, pathname, options = {}) {
-    const activeEntry = Object.entries(allPluginDatas).find(([_id, pluginData]) => {
-        return !!router_1.matchPath(pathname, {
-            path: pluginData.path,
-            exact: false,
-            strict: false,
-        });
-    });
+    const activeEntry = Object.entries(allPluginDatas).find(([_id, pluginData]) => !!(0, router_1.matchPath)(pathname, {
+        path: pluginData.path,
+        exact: false,
+        strict: false,
+    }));
     const activePlugin = activeEntry
         ? { pluginId: activeEntry[0], pluginData: activeEntry[1] }
         : undefined;
@@ -27,32 +28,28 @@ function getActivePlugin(allPluginDatas, pathname, options = {}) {
     return activePlugin;
 }
 exports.getActivePlugin = getActivePlugin;
-const getLatestVersion = (data) => {
-    return data.versions.find((version) => version.isLast);
-};
+const getLatestVersion = (data) => data.versions.find((version) => version.isLast);
 exports.getLatestVersion = getLatestVersion;
 // Note: return undefined on doc-unrelated pages,
 // because there's no version currently considered as active
 const getActiveVersion = (data, pathname) => {
-    const lastVersion = exports.getLatestVersion(data);
+    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
     const orderedVersionsMetadata = [
         ...data.versions.filter((version) => version !== lastVersion),
         lastVersion,
     ];
-    return orderedVersionsMetadata.find((version) => {
-        return !!router_1.matchPath(pathname, {
-            path: version.path,
-            exact: false,
-            strict: false,
-        });
-    });
+    return orderedVersionsMetadata.find((version) => !!(0, router_1.matchPath)(pathname, {
+        path: version.path,
+        exact: false,
+        strict: false,
+    }));
 };
 exports.getActiveVersion = getActiveVersion;
 const getActiveDocContext = (data, pathname) => {
-    const activeVersion = exports.getActiveVersion(data, pathname);
-    const activeDoc = activeVersion === null || activeVersion === void 0 ? void 0 : activeVersion.docs.find((doc) => !!router_1.matchPath(pathname, {
+    const activeVersion = (0, exports.getActiveVersion)(data, pathname);
+    const activeDoc = activeVersion === null || activeVersion === void 0 ? void 0 : activeVersion.docs.find((doc) => !!(0, router_1.matchPath)(pathname, {
         path: doc.path,
         exact: true,
         strict: false,
@@ -79,8 +76,8 @@ const getActiveDocContext = (data, pathname) => {
 };
 exports.getActiveDocContext = getActiveDocContext;
 const getDocVersionSuggestions = (data, pathname) => {
-    const latestVersion = exports.getLatestVersion(data);
-    const activeDocContext = exports.getActiveDocContext(data, pathname);
+    const latestVersion = (0, exports.getLatestVersion)(data);
+    const activeDocContext = (0, exports.getActiveDocContext)(data, pathname);
     const latestDocSuggestion = activeDocContext === null || activeDocContext === void 0 ? void 0 : activeDocContext.alternateDocVersions[latestVersion.name];
     return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
 };

package/lib/docFrontMatter.d.ts

@@ -4,5 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { DocFrontMatter } from './types';
+import type { DocFrontMatter } from './types';
 export declare function validateDocFrontMatter(frontMatter: Record<string, unknown>): DocFrontMatter;

package/lib/docFrontMatter.js

@@ -7,10 +7,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateDocFrontMatter = void 0;
-/* eslint-disable camelcase */
 const utils_validation_1 = require("@docusaurus/utils-validation");
 // NOTE: we don't add any default value on purpose here
-// We don't want default values to magically appear in doc metadatas and props
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
@@ -23,12 +22,17 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     description: utils_validation_1.JoiFrontMatter.string().allow(''),
     slug: utils_validation_1.JoiFrontMatter.string(),
     sidebar_label: utils_validation_1.JoiFrontMatter.string(),
-    sidebar_position: utils_validation_1.JoiFrontMatter.number().min(0),
+    sidebar_position: utils_validation_1.JoiFrontMatter.number(),
+    sidebar_class_name: utils_validation_1.JoiFrontMatter.string(),
+    tags: utils_validation_1.FrontMatterTagsSchema,
     pagination_label: utils_validation_1.JoiFrontMatter.string(),
     custom_edit_url: utils_validation_1.URISchema.allow('', null),
     parse_number_prefixes: utils_validation_1.JoiFrontMatter.boolean(),
+    pagination_next: utils_validation_1.JoiFrontMatter.string().allow(null),
+    pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
+    ...utils_validation_1.FrontMatterTOCHeadingLevels,
 }).unknown();
 function validateDocFrontMatter(frontMatter) {
-    return utils_validation_1.validateFrontMatter(frontMatter, DocFrontMatterSchema);
+    return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);
 }
 exports.validateDocFrontMatter = validateDocFrontMatter;

package/lib/docs.d.ts

@@ -4,15 +4,37 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { LoadContext } from '@docusaurus/types';
-import { DocFile, DocMetadataBase, MetadataOptions, PluginOptions, VersionMetadata } from './types';
+import type { LoadContext } from '@docusaurus/types';
+import { DocFile, DocMetadataBase, MetadataOptions, PluginOptions, VersionMetadata, LoadedVersion } from './types';
+import { SidebarsUtils } from './sidebars/utils';
 declare type LastUpdateOptions = Pick<PluginOptions, 'showLastUpdateAuthor' | 'showLastUpdateTime'>;
 export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string, options: LastUpdateOptions): Promise<DocFile>;
-export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
+export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
 export declare function processDocMetadata(args: {
     docFile: DocFile;
     versionMetadata: VersionMetadata;
     context: LoadContext;
     options: MetadataOptions;
 }): DocMetadataBase;
+export declare function addDocNavigation(docsBase: DocMetadataBase[], sidebarsUtils: SidebarsUtils, sidebarFilePath: string): LoadedVersion['docs'];
+/**
+ * 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 declare function getMainDocId({ docs, sidebarsUtils, }: {
+    docs: DocMetadataBase[];
+    sidebarsUtils: SidebarsUtils;
+}): string;
+export declare function isConventionalDocIndex(doc: {
+    source: DocMetadataBase['slug'];
+    sourceDirName: DocMetadataBase['sourceDirName'];
+}): boolean;
+export declare function getDocIds(doc: DocMetadataBase): [string, string];
+export declare function createDocsByIdIndex<Doc extends {
+    id: string;
+    unversionedId: string;
+}>(docs: Doc[]): Record<string, Doc>;
 export {};

package/lib/docs.js

@@ -6,25 +6,26 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+exports.createDocsByIdIndex = exports.getDocIds = exports.isConventionalDocIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
 const tslib_1 = require("tslib");
-const path_1 = tslib_1.__importDefault(require("path"));
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+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 = tslib_1.__importDefault(require("./slug"));
+const slug_1 = (0, tslib_1.__importDefault)(require("./slug"));
 const constants_1 = require("./constants");
-const globby_1 = tslib_1.__importDefault(require("globby"));
 const versions_1 = require("./versions");
 const numberPrefix_1 = require("./numberPrefix");
 const docFrontMatter_1 = require("./docFrontMatter");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const utils_2 = require("./sidebars/utils");
 async function readLastUpdateData(filePath, options) {
     const { showLastUpdateAuthor, showLastUpdateTime } = options;
     if (showLastUpdateAuthor || showLastUpdateTime) {
         // Use fake data in dev for faster development.
         const fileLastUpdateData = process.env.NODE_ENV === 'production'
-            ? await lastUpdate_1.getFileLastUpdate(filePath)
+            ? await (0, lastUpdate_1.getFileLastUpdate)(filePath)
             : {
                 author: 'Author',
                 timestamp: 1539502055,
@@ -40,7 +41,7 @@ async function readLastUpdateData(filePath, options) {
     return {};
 }
 async function readDocFile(versionMetadata, source, options) {
-    const contentPath = await utils_1.getFolderContainingFile(versions_1.getDocsDirPaths(versionMetadata), source);
+    const contentPath = await (0, utils_1.getFolderContainingFile)((0, versions_1.getDocsDirPaths)(versionMetadata), source);
     const filePath = path_1.default.join(contentPath, source);
     const [content, lastUpdate] = await Promise.all([
         fs_extra_1.default.readFile(filePath, 'utf-8'),
@@ -50,8 +51,9 @@ async function readDocFile(versionMetadata, source, options) {
 }
 exports.readDocFile = readDocFile;
 async function readVersionDocs(versionMetadata, options) {
-    const sources = await globby_1.default(options.include, {
+    const sources = await (0, utils_1.Globby)(options.include, {
         cwd: versionMetadata.contentPath,
+        ignore: options.exclude,
     });
     return Promise.all(sources.map((source) => readDocFile(versionMetadata, source, options)));
 }
@@ -59,23 +61,20 @@ exports.readVersionDocs = readVersionDocs;
 function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     var _a, _b, _c, _d, _e, _f;
     const { source, content, lastUpdate, contentPath, filePath } = docFile;
-    const { homePageId } = options;
     const { siteDir, i18n } = context;
-    const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = utils_1.parseMarkdownString(content);
-    const frontMatter = docFrontMatter_1.validateDocFrontMatter(unsafeFrontMatter);
+    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,
-    // but allow to disable this behavior with frontmatterr
-    // eslint-disable-next-line camelcase
-    parse_number_prefixes = true, } = frontMatter;
+    // but allow to disable this behavior with frontmatter
+    parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
     // ex: api/plugins/myDoc -> myDoc
     // ex: myDoc -> myDoc
     const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
     // ex: api/plugins/myDoc -> api/plugins
     // ex: myDoc -> .
     const sourceDirName = path_1.default.dirname(source);
-    // eslint-disable-next-line camelcase
-    const { filename: unprefixedFileName, numberPrefix } = parse_number_prefixes
+    const { filename: unprefixedFileName, numberPrefix } = parseNumberPrefixes
         ? options.numberPrefixParser(sourceFileNameWithoutExtension)
         : { filename: sourceFileNameWithoutExtension, numberPrefix: undefined };
     const baseID = (_a = frontMatter.id) !== null && _a !== void 0 ? _a : unprefixedFileName;
@@ -97,9 +96,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
             return undefined;
         }
         // Eventually remove the number prefixes from intermediate directories
-        // eslint-disable-next-line camelcase
-        return parse_number_prefixes
-            ? numberPrefix_1.stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
+        return parseNumberPrefixes
+            ? (0, numberPrefix_1.stripPathNumberPrefixes)(sourceDirName, options.numberPrefixParser)
             : sourceDirName;
     }
     const unversionedId = [computeDirNameIdPrefix(), baseID]
@@ -108,32 +106,26 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     // TODO is versioning the id very useful in practice?
     // legacy versioned id, requires a breaking change to modify this
     const id = [versionIdPrefix, unversionedId].filter(Boolean).join('/');
-    // TODO remove soon, deprecated homePageId
-    const isDocsHomePage = unversionedId === (homePageId !== null && homePageId !== void 0 ? homePageId : '_index');
-    if (frontMatter.slug && isDocsHomePage) {
-        throw new Error(`The docs homepage (homePageId=${homePageId}) is not allowed to have a frontmatter slug=${frontMatter.slug} => you have to choose either homePageId or slug, not both`);
-    }
-    const docSlug = isDocsHomePage
-        ? '/'
-        : slug_1.default({
-            baseID,
-            dirName: sourceDirName,
-            frontmatterSlug: frontMatter.slug,
-            stripDirNumberPrefixes: parse_number_prefixes,
-            numberPrefixParser: options.numberPrefixParser,
-        });
+    const docSlug = (0, slug_1.default)({
+        baseID,
+        source,
+        sourceDirName,
+        frontmatterSlug: frontMatter.slug,
+        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)
     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 = utils_1.normalizeUrl([versionMetadata.versionPath, docSlug]);
+    const permalink = (0, utils_1.normalizeUrl)([versionMetadata.versionPath, docSlug]);
     function getDocEditUrl() {
         const relativeFilePath = path_1.default.relative(contentPath, filePath);
         if (typeof options.editUrl === 'function') {
             return options.editUrl({
                 version: versionMetadata.versionName,
-                versionDocsDirPath: utils_1.posixPath(path_1.default.relative(siteDir, versionMetadata.contentPath)),
-                docPath: utils_1.posixPath(relativeFilePath),
+                versionDocsDirPath: (0, utils_1.posixPath)(path_1.default.relative(siteDir, versionMetadata.contentPath)),
+                docPath: (0, utils_1.posixPath)(relativeFilePath),
                 permalink,
                 locale: context.i18n.currentLocale,
             });
@@ -143,7 +135,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
             const baseVersionEditUrl = isLocalized && options.editLocalizedFiles
                 ? versionMetadata.versionEditUrlLocalized
                 : versionMetadata.versionEditUrl;
-            return utils_1.getEditUrl(relativeFilePath, baseVersionEditUrl);
+            return (0, utils_1.getEditUrl)(relativeFilePath, baseVersionEditUrl);
         }
         else {
             return undefined;
@@ -156,14 +148,14 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     return {
         unversionedId,
         id,
-        isDocsHomePage,
         title,
         description,
-        source: utils_1.aliasedSitePath(filePath, siteDir),
+        source: (0, utils_1.aliasedSitePath)(filePath, siteDir),
         sourceDirName,
         slug: docSlug,
         permalink,
         editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
+        tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
         version: versionMetadata.versionName,
         lastUpdatedBy: lastUpdate.lastUpdatedBy,
         lastUpdatedAt: lastUpdate.lastUpdatedAt,
@@ -179,8 +171,101 @@ function processDocMetadata(args) {
         return doProcessDocMetadata(args);
     }
     catch (e) {
-        console.error(chalk_1.default.red(`Can't process doc metadatas for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`));
+        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;
     }
 }
 exports.processDocMetadata = processDocMetadata;
+function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
+    const docsById = createDocsByIdIndex(docsBase);
+    sidebarsUtils.checkSidebarsDocIds(docsBase.flatMap(getDocIds), sidebarFilePath);
+    // Add sidebar/next/previous to the docs
+    function addNavData(doc) {
+        const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id);
+        const toNavigationLinkByDocId = (docId, type) => {
+            if (!docId) {
+                return undefined;
+            }
+            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}.`);
+            }
+            return (0, utils_2.toDocNavigationLink)(navDoc);
+        };
+        const previous = doc.frontMatter.pagination_prev !== undefined
+            ? toNavigationLinkByDocId(doc.frontMatter.pagination_prev, 'prev')
+            : (0, utils_2.toNavigationLink)(navigation.previous, docsById);
+        const next = doc.frontMatter.pagination_next !== undefined
+            ? toNavigationLinkByDocId(doc.frontMatter.pagination_next, 'next')
+            : (0, utils_2.toNavigationLink)(navigation.next, docsById);
+        return { ...doc, sidebar: navigation.sidebarName, previous, next };
+    }
+    const docsWithNavigation = docsBase.map(addNavData);
+    // sort to ensure consistent output for tests
+    docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
+    return docsWithNavigation;
+}
+exports.addDocNavigation = addDocNavigation;
+/**
+ * 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 getMainDocId({ docs, sidebarsUtils, }) {
+    function getMainDoc() {
+        const versionHomeDoc = docs.find((doc) => doc.slug === '/');
+        const firstDocIdOfFirstSidebar = sidebarsUtils.getFirstDocIdOfFirstSidebar();
+        if (versionHomeDoc) {
+            return versionHomeDoc;
+        }
+        else if (firstDocIdOfFirstSidebar) {
+            return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar ||
+                doc.unversionedId === firstDocIdOfFirstSidebar);
+        }
+        else {
+            return docs[0];
+        }
+    }
+    return getMainDoc().unversionedId;
+}
+exports.getMainDocId = getMainDocId;
+function getLastPathSegment(str) {
+    return (0, lodash_1.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
+function isConventionalDocIndex(doc) {
+    // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
+    const docName = path_1.default.parse(doc.source).name;
+    // "folder/subFolder/subSubFolder" => "subSubFolder"
+    const lastDirName = getLastPathSegment(doc.sourceDirName);
+    const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
+    return eligibleDocIndexNames.includes(docName.toLowerCase());
+}
+exports.isConventionalDocIndex = isConventionalDocIndex;
+// 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")
+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")
+function createDocsByIdIndex(docs) {
+    return {
+        ...(0, lodash_1.keyBy)(docs, (doc) => doc.unversionedId),
+        ...(0, lodash_1.keyBy)(docs, (doc) => doc.id),
+    };
+}
+exports.createDocsByIdIndex = createDocsByIdIndex;

package/lib/globalData.d.ts

@@ -4,6 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
+import type { DocMetadata, GlobalDoc, LoadedVersion, GlobalVersion } from './types';
 export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
 export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { LoadContext, Plugin } from '@docusaurus/types';
+import type { LoadContext, Plugin } from '@docusaurus/types';
 import { PluginOptions, LoadedContent } from './types';
 export default function pluginContentDocs(context: LoadContext, options: PluginOptions): Plugin<LoadedContent>;
 export { validateOptions } from './options';