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

package/lib/cli.js

@@ -52,24 +52,24 @@ function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }
 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 === constants_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. Ex: 1.0.0`);
+        throw new Error(`${pluginIdLogPrefix}: no version tag specified! Pass the version you wish to create as an argument, for example: 1.0.0.`);
     }
     if (version.includes('/') || version.includes('\\')) {
-        throw new Error(`${pluginIdLogPrefix}Invalid version tag specified! Do not include slash (/) or (\\). Try something like: 1.0.0`);
+        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Do not include slash (/) or backslash (\\). Try something like: 1.0.0.`);
     }
     if (version.length > 32) {
-        throw new Error(`${pluginIdLogPrefix}Invalid version tag specified! Length must <= 32 characters. Try something like: 1.0.0`);
+        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`);
     }
     // Since we are going to create `version-${version}` folder, we need to make
     // sure it's a valid pathname.
     // eslint-disable-next-line no-control-regex
     if (/[<>:"|?*\x00-\x1F]/g.test(version)) {
-        throw new Error(`${pluginIdLogPrefix}Invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0`);
+        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Please ensure its a valid pathname too. Try something like: 1.0.0.`);
     }
     if (/^\.\.?$/.test(version)) {
-        throw new Error(`${pluginIdLogPrefix}Invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0`);
+        throw new Error(`${pluginIdLogPrefix}: invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0.`);
     }
     // Load existing versions.
     let versions = [];
@@ -79,7 +79,7 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     }
     // Check if version already exists.
     if (versions.includes(version)) {
-        throw new Error(`${pluginIdLogPrefix}This version already exists!. Use a version tag that does not already exist.`);
+        throw new Error(`${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`);
     }
     const { path: docsPath, sidebarPath } = options;
     // Copy docs files.
@@ -90,13 +90,18 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
         fs_extra_1.default.copySync(docsDir, newVersionDir);
     }
     else {
-        throw new Error(`${pluginIdLogPrefix}There is no docs to version !`);
+        throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
     }
-    createVersionedSidebarFile({ siteDir, pluginId, version, sidebarPath });
+    createVersionedSidebarFile({
+        siteDir,
+        pluginId,
+        version,
+        sidebarPath: 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!`);
+    console.log(`${pluginIdLogPrefix}: version ${version} created!`);
 }
 exports.cliDocsVersionCommand = cliDocsVersionCommand;

package/lib/client/docsClientUtils.d.ts

@@ -27,8 +27,8 @@ export declare const getLatestVersion: (data: GlobalPluginData) => Version;
 export declare const getActiveVersion: (data: GlobalPluginData, pathname: string) => Version | undefined;
 export declare const getActiveDocContext: (data: GlobalPluginData, pathname: string) => ActiveDocContext;
 export declare type DocVersionSuggestions = {
+    latestVersionSuggestion: GlobalVersion;
     latestDocSuggestion?: GlobalDoc;
-    latestVersionSuggestion?: GlobalVersion;
 };
 export declare const getDocVersionSuggestions: (data: GlobalPluginData, pathname: string) => DocVersionSuggestions;
 export {};

package/lib/client/docsClientUtils.js

@@ -20,7 +20,7 @@ function getActivePlugin(allPluginDatas, pathname, options = {}) {
         ? { pluginId: activeEntry[0], pluginData: activeEntry[1] }
         : undefined;
     if (!activePlugin && options.failfast) {
-        throw new Error(`Can't find active docs plugin for pathname=${pathname}, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(allPluginDatas)
+        throw new Error(`Can't find active docs plugin for "${pathname}" pathname, while it was expected to be found. Maybe you tried to use a docs feature that can only be used on a docs-related page? Existing docs plugin paths are: ${Object.values(allPluginDatas)
             .map((plugin) => plugin.path)
             .join(', ')}`);
     }
@@ -81,14 +81,7 @@ exports.getActiveDocContext = getActiveDocContext;
 const getDocVersionSuggestions = (data, pathname) => {
     const latestVersion = exports.getLatestVersion(data);
     const activeDocContext = exports.getActiveDocContext(data, pathname);
-    // We only suggest another doc/version if user is not using the latest version
-    const isNotOnLatestVersion = activeDocContext.activeVersion !== latestVersion;
-    const latestDocSuggestion = isNotOnLatestVersion
-        ? activeDocContext === null || activeDocContext === void 0 ? void 0 : activeDocContext.alternateDocVersions[latestVersion.name]
-        : undefined;
-    const latestVersionSuggestion = isNotOnLatestVersion
-        ? latestVersion
-        : undefined;
-    return { latestDocSuggestion, latestVersionSuggestion };
+    const latestDocSuggestion = activeDocContext === null || activeDocContext === void 0 ? void 0 : activeDocContext.alternateDocVersions[latestVersion.name];
+    return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
 };
 exports.getDocVersionSuggestions = getDocVersionSuggestions;

package/lib/docFrontMatter.d.ts

@@ -4,18 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export declare type DocFrontMatter = {
-    id?: string;
-    title?: string;
-    hide_title?: boolean;
-    hide_table_of_contents?: boolean;
-    keywords?: string[];
-    image?: string;
-    description?: string;
-    slug?: string;
-    sidebar_label?: string;
-    sidebar_position?: number;
-    custom_edit_url?: string | null;
-    parse_number_prefixes?: boolean;
-};
+import { DocFrontMatter } from './types';
 export declare function validateDocFrontMatter(frontMatter: Record<string, unknown>): DocFrontMatter;

package/lib/docFrontMatter.js

@@ -19,12 +19,13 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     hide_title: utils_validation_1.JoiFrontMatter.boolean(),
     hide_table_of_contents: utils_validation_1.JoiFrontMatter.boolean(),
     keywords: utils_validation_1.JoiFrontMatter.array().items(utils_validation_1.JoiFrontMatter.string().required()),
-    image: utils_validation_1.JoiFrontMatter.string().uri({ allowRelative: false }),
+    image: utils_validation_1.URISchema,
     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),
-    custom_edit_url: utils_validation_1.JoiFrontMatter.string().uri({ allowRelative: true }).allow('', null),
+    pagination_label: utils_validation_1.JoiFrontMatter.string(),
+    custom_edit_url: utils_validation_1.URISchema.allow('', null),
     parse_number_prefixes: utils_validation_1.JoiFrontMatter.boolean(),
 }).unknown();
 function validateDocFrontMatter(frontMatter) {

package/lib/docs.d.ts

@@ -9,7 +9,7 @@ import { DocFile, DocMetadataBase, MetadataOptions, PluginOptions, VersionMetada
 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 processDocMetadata({ docFile, versionMetadata, context, options, }: {
+export declare function processDocMetadata(args: {
     docFile: DocFile;
     versionMetadata: VersionMetadata;
     context: LoadContext;

package/lib/docs.js

@@ -18,6 +18,7 @@ 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"));
 async function readLastUpdateData(filePath, options) {
     const { showLastUpdateAuthor, showLastUpdateTime } = options;
     if (showLastUpdateAuthor || showLastUpdateTime) {
@@ -55,16 +56,17 @@ async function readVersionDocs(versionMetadata, options) {
     return Promise.all(sources.map((source) => readDocFile(versionMetadata, source, options)));
 }
 exports.readVersionDocs = readVersionDocs;
-function processDocMetadata({ docFile, versionMetadata, context, options, }) {
-    var _a, _b, _c, _d, _e;
+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 { sidebar_label: sidebarLabel, custom_edit_url: customEditURL, 
+    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;
     // ex: api/plugins/myDoc -> myDoc
     // ex: myDoc -> myDoc
@@ -72,12 +74,13 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
     // 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
         ? options.numberPrefixParser(sourceFileNameWithoutExtension)
         : { filename: sourceFileNameWithoutExtension, numberPrefix: undefined };
     const baseID = (_a = frontMatter.id) !== null && _a !== void 0 ? _a : unprefixedFileName;
     if (baseID.includes('/')) {
-        throw new Error(`Document id [${baseID}] cannot include "/".`);
+        throw new Error(`Document id "${baseID}" cannot include slash.`);
     }
     // For autogenerated sidebars, sidebar position can come from filename number prefix or frontmatter
     const sidebarPosition = (_b = frontMatter.sidebar_position) !== null && _b !== void 0 ? _b : numberPrefix;
@@ -94,6 +97,7 @@ function processDocMetadata({ 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)
             : sourceDirName;
@@ -118,12 +122,10 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
             stripDirNumberPrefixes: parse_number_prefixes,
             numberPrefixParser: options.numberPrefixParser,
         });
-    // TODO expose both headingTitle+metaTitle to theme?
-    // Different fallbacks order on purpose!
-    // See https://github.com/facebook/docusaurus/issues/4665#issuecomment-825831367
-    const headingTitle = (_c = contentTitle !== null && contentTitle !== void 0 ? contentTitle : frontMatter.title) !== null && _c !== void 0 ? _c : baseID;
-    // const metaTitle: string = frontMatter.title ?? contentTitle  ?? baseID;
-    const description = (_e = (_d = frontMatter.description) !== null && _d !== void 0 ? _d : excerpt) !== null && _e !== void 0 ? _e : '';
+    // 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]);
     function getDocEditUrl() {
         const relativeFilePath = path_1.default.relative(contentPath, filePath);
@@ -155,7 +157,7 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
         unversionedId,
         id,
         isDocsHomePage,
-        title: headingTitle,
+        title,
         description,
         source: utils_1.aliasedSitePath(filePath, siteDir),
         sourceDirName,
@@ -168,9 +170,17 @@ function processDocMetadata({ docFile, versionMetadata, context, options, }) {
         formattedLastUpdatedAt: lastUpdate.lastUpdatedAt
             ? new Intl.DateTimeFormat(i18n.currentLocale).format(lastUpdate.lastUpdatedAt * 1000)
             : undefined,
-        sidebar_label: sidebarLabel,
         sidebarPosition,
         frontMatter,
     };
 }
+function processDocMetadata(args) {
+    try {
+        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}"`));
+        throw e;
+    }
+}
 exports.processDocMetadata = processDocMetadata;

package/lib/index.js

@@ -21,11 +21,11 @@ const globalData_1 = require("./globalData");
 const props_1 = require("./props");
 const translations_1 = require("./translations");
 const sidebarItemsGenerator_1 = require("./sidebarItemsGenerator");
+const chalk_1 = tslib_1.__importDefault(require("chalk"));
 function pluginContentDocs(context, options) {
     var _a;
     const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
     const versionsMetadata = versions_1.readVersionsMetadata({ context, options });
-    const sourceToPermalink = {};
     const pluginId = (_a = options.id) !== null && _a !== void 0 ? _a : constants_1.DEFAULT_PLUGIN_ID;
     const pluginDataDirRoot = path_1.default.join(generatedFilesDir, 'docusaurus-plugin-content-docs');
     const dataDir = path_1.default.join(pluginDataDirRoot, pluginId);
@@ -86,7 +86,7 @@ function pluginContentDocs(context, options) {
             async function loadVersionDocsBase(versionMetadata) {
                 const docFiles = await docs_1.readVersionDocs(versionMetadata, options);
                 if (docFiles.length === 0) {
-                    throw new Error(`Docs version ${versionMetadata.versionName} has no docs! At least one doc should exist at path=[${path_1.default.relative(siteDir, versionMetadata.contentPath)}]`);
+                    throw new Error(`Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${path_1.default.relative(siteDir, versionMetadata.contentPath)}".`);
                 }
                 async function processVersionDoc(docFile) {
                     return docs_1.processDocMetadata({
@@ -98,7 +98,7 @@ function pluginContentDocs(context, options) {
                 }
                 return Promise.all(docFiles.map(processVersionDoc));
             }
-            async function loadVersion(versionMetadata) {
+            async function doLoadVersion(versionMetadata) {
                 const unprocessedSidebars = sidebars_1.loadSidebars(versionMetadata.sidebarFilePath);
                 const docsBase = await loadVersionDocsBase(versionMetadata);
                 const docsBaseById = lodash_1.keyBy(docsBase, (doc) => doc.id);
@@ -111,14 +111,18 @@ function pluginContentDocs(context, options) {
                 });
                 const sidebarsUtils = sidebars_1.createSidebarsUtils(sidebars);
                 const validDocIds = Object.keys(docsBaseById);
-                sidebarsUtils.checkSidebarsDocIds(validDocIds);
+                sidebarsUtils.checkSidebarsDocIds(validDocIds, versionMetadata.sidebarFilePath);
                 // Add sidebar/next/previous to the docs
                 function addNavData(doc) {
                     const { sidebarName, previousId, nextId, } = sidebarsUtils.getDocNavigation(doc.id);
-                    const toDocNavLink = (navDocId) => ({
-                        title: docsBaseById[navDocId].title,
-                        permalink: docsBaseById[navDocId].permalink,
-                    });
+                    const toDocNavLink = (navDocId) => {
+                        var _a, _b;
+                        const { title, permalink, frontMatter } = docsBaseById[navDocId];
+                        return {
+                            title: (_b = (_a = frontMatter.pagination_label) !== null && _a !== void 0 ? _a : frontMatter.sidebar_label) !== null && _b !== void 0 ? _b : title,
+                            permalink,
+                        };
+                    };
                     return {
                         ...doc,
                         sidebar: sidebarName,
@@ -129,11 +133,6 @@ function pluginContentDocs(context, options) {
                 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 = {};
                 Object.values(docs).forEach((doc) => {
@@ -167,6 +166,15 @@ function pluginContentDocs(context, options) {
                     docs: docs.map(addNavData),
                 };
             }
+            async function loadVersion(versionMetadata) {
+                try {
+                    return await doLoadVersion(versionMetadata);
+                }
+                catch (e) {
+                    console.error(chalk_1.default.red(`Loading of version failed for version "${versionMetadata.versionName}"`));
+                    throw e;
+                }
+            }
             return {
                 loadedVersions: await Promise.all(versionsMetadata.map(loadVersion)),
             };
@@ -195,7 +203,7 @@ function pluginContentDocs(context, options) {
                 }));
                 return routes.sort((a, b) => a.path.localeCompare(b.path));
             };
-            async function handleVersion(loadedVersion) {
+            async function doCreateVersionRoutes(loadedVersion) {
                 const versionMetadataPropPath = await createData(`${utils_1.docuHash(`version-${loadedVersion.versionName}-metadata-prop`)}.json`, JSON.stringify(props_1.toVersionMetadataProp(pluginId, loadedVersion), null, 2));
                 addRoute({
                     path: loadedVersion.versionPath,
@@ -211,18 +219,31 @@ function pluginContentDocs(context, options) {
                     priority: loadedVersion.routePriority,
                 });
             }
-            await Promise.all(loadedVersions.map(handleVersion));
+            async function createVersionRoutes(loadedVersion) {
+                try {
+                    return await doCreateVersionRoutes(loadedVersion);
+                }
+                catch (e) {
+                    console.error(chalk_1.default.red(`Can't create version routes for version "${loadedVersion.versionName}"`));
+                    throw e;
+                }
+            }
+            await Promise.all(loadedVersions.map(createVersionRoutes));
             setGlobalData({
                 path: utils_1.normalizeUrl([baseUrl, options.routeBasePath]),
                 versions: loadedVersions.map(globalData_1.toGlobalDataVersion),
             });
         },
-        configureWebpack(_config, isServer, utils) {
+        configureWebpack(_config, isServer, utils, content) {
             const { getJSLoader } = utils;
             const { rehypePlugins, remarkPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
+            function getSourceToPermalink() {
+                const allDocs = lodash_1.flatten(content.loadedVersions.map((v) => v.docs));
+                return lodash_1.mapValues(lodash_1.keyBy(allDocs, (d) => d.source), (d) => d.permalink);
+            }
             const docsMarkdownOptions = {
                 siteDir,
-                sourceToPermalink,
+                sourceToPermalink: getSourceToPermalink(),
                 versionsMetadata,
                 onBrokenMarkdownLink: (brokenMarkdownLink) => {
                     if (siteConfig.onBrokenMarkdownLinks === 'ignore') {

package/lib/lastUpdate.js

@@ -10,6 +10,7 @@ exports.getFileLastUpdate = void 0;
 const tslib_1 = require("tslib");
 const shelljs_1 = tslib_1.__importDefault(require("shelljs"));
 const execa_1 = tslib_1.__importDefault(require("execa"));
+const path_1 = tslib_1.__importDefault(require("path"));
 const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+), (.+)$/;
 let showedGitRequirementError = false;
 async function getFileLastUpdate(filePath) {
@@ -35,12 +36,11 @@ async function getFileLastUpdate(filePath) {
             }
             return null;
         }
-        const { stdout } = await execa_1.default('git', [
-            'log',
-            '-1',
-            '--format=%ct, %an',
-            filePath,
-        ]);
+        const fileBasename = path_1.default.basename(filePath);
+        const fileDirname = path_1.default.dirname(filePath);
+        const { stdout } = await execa_1.default('git', ['log', '-1', '--format=%ct, %an', fileBasename], {
+            cwd: fileDirname,
+        });
         return getTimestampAndAuthor(stdout);
     }
     catch (error) {

package/lib/markdown/linkify.js

@@ -12,7 +12,7 @@ const utils_1 = require("@docusaurus/utils");
 function getVersion(filePath, options) {
     const versionFound = options.versionsMetadata.find((version) => versions_1.getDocsDirPaths(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
     if (!versionFound) {
-        throw new Error(`Unexpected, markdown file does not belong to any docs version! file=${filePath}`);
+        throw new Error(`Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`);
     }
     return versionFound;
 }

package/lib/options.js

@@ -23,7 +23,6 @@ exports.DEFAULT_OPTIONS = {
     showLastUpdateTime: false,
     showLastUpdateAuthor: false,
     admonitions: {},
-    excludeNextVersionDocs: false,
     includeCurrentVersion: true,
     disableVersioning: false,
     lastVersion: undefined,
@@ -34,6 +33,7 @@ exports.DEFAULT_OPTIONS = {
 const VersionOptionsSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().allow('').optional(),
     label: utils_validation_1.Joi.string().optional(),
+    banner: utils_validation_1.Joi.string().equal('none', 'unreleased', 'unmaintained').optional(),
 });
 const VersionsOptionsSchema = utils_validation_1.Joi.object()
     .pattern(utils_validation_1.Joi.string().required(), VersionOptionsSchema)
@@ -69,7 +69,6 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         .default(exports.DEFAULT_OPTIONS.admonitions),
     showLastUpdateTime: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateTime),
     showLastUpdateAuthor: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateAuthor),
-    excludeNextVersionDocs: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.excludeNextVersionDocs),
     includeCurrentVersion: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.includeCurrentVersion),
     onlyIncludeVersions: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().required()).optional(),
     disableVersioning: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.disableVersioning),
@@ -82,10 +81,6 @@ function validateOptions({ validate, options, }) {
     if (options.homePageId) {
         console.log(chalk_1.default.red(`The docs plugin option homePageId=${options.homePageId} is deprecated. To make a doc the "home", prefer frontmatter: "slug: /"`));
     }
-    if (typeof options.excludeNextVersionDocs !== 'undefined') {
-        console.log(chalk_1.default.red(`The docs plugin option excludeNextVersionDocs=${options.excludeNextVersionDocs} is deprecated. Use the includeCurrentVersion=${!options.excludeNextVersionDocs} option instead!"`));
-        options.includeCurrentVersion = !options.excludeNextVersionDocs;
-    }
     const normalizedOptions = validate(exports.OptionsSchema, options);
     if (normalizedOptions.admonitions) {
         normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([

package/lib/props.js

@@ -14,11 +14,11 @@ function toSidebarsProp(loadedVersion) {
         const docId = item.id;
         const docMetadata = docsById[docId];
         if (!docMetadata) {
-            throw new Error(`Bad sidebars file. The document id '${docId}' was used in the sidebar, but no document with this id could be found.
-Available document ids=
+            throw new Error(`Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
+Available document ids are:
 - ${Object.keys(docsById).sort().join('\n- ')}`);
         }
-        const { title, permalink, sidebar_label: sidebarLabel } = docMetadata;
+        const { title, permalink, frontMatter: { sidebar_label: sidebarLabel }, } = docMetadata;
         return {
             type: 'link',
             label: sidebarLabel || item.label || title,
@@ -49,6 +49,7 @@ function toVersionMetadataProp(pluginId, loadedVersion) {
         pluginId,
         version: loadedVersion.versionName,
         label: loadedVersion.versionLabel,
+        banner: loadedVersion.versionBanner,
         isLast: loadedVersion.isLast,
         docsSidebars: toSidebarsProp(loadedVersion),
         permalinkToSidebar: loadedVersion.permalinkToSidebar,

package/lib/sidebarItemsGenerator.js

@@ -43,7 +43,7 @@ async function readCategoryMetadatasFile(categoryDirPath) {
                 return validateCategoryMetadataFile(unsafeContent);
             }
             catch (e) {
-                console.error(chalk_1.default.red(`The docs sidebar category metadata file looks invalid!\nPath=${filePath}`));
+                console.error(chalk_1.default.red(`The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`));
                 throw e;
             }
         }
@@ -85,7 +85,7 @@ const DefaultSidebarItemsGenerator = async function defaultSidebarItemsGenerator
     // autogenDir=a/b and docDir=a/b => returns .
     function getDocDirRelativeToAutogenDir(doc) {
         if (!isInAutogeneratedDir(doc)) {
-            throw new Error('getDocDirRelativeToAutogenDir() can only be called for  subdocs of the sidebar autogen dir');
+            throw new Error('getDocDirRelativeToAutogenDir() can only be called for subdocs of the sidebar autogen dir.');
         }
         // Is there a node API to compare 2 relative paths more easily?
         // path.relative() does not give good results
@@ -103,7 +103,7 @@ const DefaultSidebarItemsGenerator = async function defaultSidebarItemsGenerator
     // Sort by folder+filename at once
     const docs = lodash_1.sortBy(allDocs.filter(isInAutogeneratedDir), (d) => d.source);
     if (docs.length === 0) {
-        console.warn(chalk_1.default.yellow(`No docs found in dir ${item.dirName}: can't auto-generate a sidebar`));
+        console.warn(chalk_1.default.yellow(`No docs found in dir ${item.dirName}: can't auto-generate a sidebar.`));
     }
     function createDocSidebarItem(doc) {
         return {

package/lib/sidebars.d.ts

@@ -4,10 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { Sidebars, SidebarItem, SidebarItemLink, SidebarItemDoc, Sidebar, SidebarItemCategory, UnprocessedSidebars, UnprocessedSidebar, DocMetadataBase, VersionMetadata, SidebarItemsGeneratorDoc, SidebarItemsGeneratorVersion, NumberPrefixParser, SidebarItemsGeneratorOption } from './types';
+import { Sidebars, SidebarItem, SidebarItemLink, SidebarItemDoc, Sidebar, SidebarItemCategory, UnprocessedSidebars, UnprocessedSidebar, DocMetadataBase, VersionMetadata, SidebarItemsGeneratorDoc, SidebarItemsGeneratorVersion, NumberPrefixParser, SidebarItemsGeneratorOption, PluginOptions } from './types';
 export declare const DefaultCategoryCollapsedValue = true;
 export declare const DefaultSidebars: UnprocessedSidebars;
 export declare const DisabledSidebars: UnprocessedSidebars;
+export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];
 export declare function loadSidebars(sidebarFilePath: string | false | undefined): UnprocessedSidebars;
 export declare function toSidebarItemsGeneratorDoc(doc: DocMetadataBase): SidebarItemsGeneratorDoc;
 export declare function toSidebarItemsGeneratorVersion(version: VersionMetadata): SidebarItemsGeneratorVersion;
@@ -38,5 +39,5 @@ export declare function createSidebarsUtils(sidebars: Sidebars): {
         previousId: string | undefined;
         nextId: string | undefined;
     };
-    checkSidebarsDocIds: (validDocIds: string[]) => void;
+    checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };

package/lib/sidebars.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSidebarsUtils = exports.collectSidebarsDocIds = exports.transformSidebarItems = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.processSidebars = exports.processSidebar = exports.toSidebarItemsGeneratorVersion = exports.toSidebarItemsGeneratorDoc = exports.loadSidebars = exports.DisabledSidebars = exports.DefaultSidebars = exports.DefaultCategoryCollapsedValue = void 0;
+exports.createSidebarsUtils = exports.collectSidebarsDocIds = exports.transformSidebarItems = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.processSidebars = exports.processSidebar = exports.toSidebarItemsGeneratorVersion = exports.toSidebarItemsGeneratorDoc = exports.loadSidebars = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = exports.DefaultCategoryCollapsedValue = void 0;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const import_fresh_1 = tslib_1.__importDefault(require("import-fresh"));
@@ -14,6 +14,7 @@ const lodash_1 = require("lodash");
 const utils_1 = require("@docusaurus/utils");
 const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
 const sidebarItemsGenerator_1 = require("./sidebarItemsGenerator");
+const path_1 = tslib_1.__importDefault(require("path"));
 function isCategoryShorthand(item) {
     return typeof item !== 'string' && !item.type;
 }
@@ -44,41 +45,42 @@ function assertItem(item, keys) {
 function assertIsCategory(item) {
     assertItem(item, ['items', 'label', 'collapsed', 'customProps']);
     if (typeof item.label !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "label" must be a string.`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "label" must be a string.`);
     }
     if (!Array.isArray(item.items)) {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "items" must be an array.`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "items" must be an array.`);
     }
     // "collapsed" is an optional property
-    if (item.hasOwnProperty('collapsed') && typeof item.collapsed !== 'boolean') {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "collapsed" must be a boolean.`);
+    if (typeof item.collapsed !== 'undefined' &&
+        typeof item.collapsed !== 'boolean') {
+        throw new Error(`Error loading ${JSON.stringify(item)}: "collapsed" must be a boolean.`);
     }
 }
 function assertIsAutogenerated(item) {
     assertItem(item, ['dirName', 'customProps']);
     if (typeof item.dirName !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "dirName" must be a string.`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "dirName" must be a string.`);
     }
     if (item.dirName.startsWith('/') || item.dirName.endsWith('/')) {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "dirName" must be a dir path relative to the docs folder root, and should not start or end with /`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "dirName" must be a dir path relative to the docs folder root, and should not start or end with slash`);
     }
 }
 function assertIsDoc(item) {
     assertItem(item, ['id', 'label', 'customProps']);
     if (typeof item.id !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "id" must be a string.`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "id" must be a string.`);
     }
     if (item.label && typeof item.label !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "label" must be a string.`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "label" must be a string.`);
     }
 }
 function assertIsLink(item) {
     assertItem(item, ['href', 'label', 'customProps']);
     if (typeof item.href !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "href" must be a string.`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "href" must be a string.`);
     }
     if (typeof item.label !== 'string') {
-        throw new Error(`Error loading ${JSON.stringify(item)}. "label" must be a string.`);
+        throw new Error(`Error loading ${JSON.stringify(item)}: "label" must be a string.`);
     }
 }
 /**
@@ -119,9 +121,9 @@ function normalizeItem(item) {
             return [item];
         default: {
             const extraMigrationError = item.type === 'subcategory'
-                ? "Docusaurus v2: 'subcategory' has been renamed as 'category'"
+                ? 'Docusaurus v2: "subcategory" has been renamed as "category".'
                 : '';
-            throw new Error(`Unknown sidebar item type [${item.type}]. Sidebar item=${JSON.stringify(item)} ${extraMigrationError}`);
+            throw new Error(`Unknown sidebar item type "${item.type}". Sidebar item is ${JSON.stringify(item)}.\n${extraMigrationError}`);
         }
     }
 }
@@ -143,7 +145,16 @@ exports.DefaultSidebars = {
     ],
 };
 exports.DisabledSidebars = {};
+// If a path is provided, make it absolute
+// use this before loadSidebars()
+function resolveSidebarPathOption(siteDir, sidebarPathOption) {
+    return sidebarPathOption
+        ? path_1.default.resolve(siteDir, sidebarPathOption)
+        : sidebarPathOption;
+}
+exports.resolveSidebarPathOption = resolveSidebarPathOption;
 // TODO refactor: make async
+// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 function loadSidebars(sidebarFilePath) {
     // false => no sidebars
     if (sidebarFilePath === false) {
@@ -287,15 +298,15 @@ function createSidebarsUtils(sidebars) {
             };
         }
     }
-    function checkSidebarsDocIds(validDocIds) {
+    function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
         const allSidebarDocIds = lodash_1.flatten(Object.values(sidebarNameToDocIds));
         const invalidSidebarDocIds = lodash_1.difference(allSidebarDocIds, validDocIds);
         if (invalidSidebarDocIds.length > 0) {
-            throw new Error(`Bad sidebars file.
+            throw new Error(`Invalid sidebar file at "${utils_1.toMessageRelativeFilePath(sidebarFilePath)}".
 These sidebar document ids do not exist:
-- ${invalidSidebarDocIds.sort().join('\n- ')},
+- ${invalidSidebarDocIds.sort().join('\n- ')}
 
-Available document ids=
+Available document ids are:
 - ${validDocIds.sort().join('\n- ')}`);
         }
     }