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

package/src/sidebarItemsGenerator.ts

@@ -74,7 +74,7 @@ async function readCategoryMetadatasFile(
       } catch (e) {
         console.error(
           chalk.red(
-            `The docs sidebar category metadata file looks invalid!\nPath=${filePath}`,
+            `The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`,
           ),
         );
         throw e;
@@ -139,7 +139,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async functio
   ): string {
     if (!isInAutogeneratedDir(doc)) {
       throw new Error(
-        'getDocDirRelativeToAutogenDir() can only be called for  subdocs of the sidebar autogen dir',
+        'getDocDirRelativeToAutogenDir() can only be called for subdocs of the sidebar autogen dir.',
       );
     }
     // Is there a node API to compare 2 relative paths more easily?
@@ -160,7 +160,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async functio
   if (docs.length === 0) {
     console.warn(
       chalk.yellow(
-        `No docs found in dir ${item.dirName}: can't auto-generate a sidebar`,
+        `No docs found in dir ${item.dirName}: can't auto-generate a sidebar.`,
       ),
     );
   }

package/src/sidebars.ts

@@ -25,11 +25,13 @@ import {
   SidebarItemsGeneratorVersion,
   NumberPrefixParser,
   SidebarItemsGeneratorOption,
+  PluginOptions,
 } from './types';
 import {mapValues, flatten, flatMap, difference, pick, memoize} from 'lodash';
-import {getElementsAround} from '@docusaurus/utils';
+import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
 import combinePromises from 'combine-promises';
 import {DefaultSidebarItemsGenerator} from './sidebarItemsGenerator';
+import path from 'path';
 
 type SidebarItemCategoryJSON = SidebarItemBase & {
   type: 'category';
@@ -116,18 +118,21 @@ function assertIsCategory(
   assertItem(item, ['items', 'label', 'collapsed', 'customProps']);
   if (typeof item.label !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
+      `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.`,
+      `Error loading ${JSON.stringify(item)}: "items" must be an array.`,
     );
   }
   // "collapsed" is an optional property
-  if (item.hasOwnProperty('collapsed') && typeof item.collapsed !== 'boolean') {
+  if (
+    typeof item.collapsed !== 'undefined' &&
+    typeof item.collapsed !== 'boolean'
+  ) {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "collapsed" must be a boolean.`,
+      `Error loading ${JSON.stringify(item)}: "collapsed" must be a boolean.`,
     );
   }
 }
@@ -138,14 +143,14 @@ function assertIsAutogenerated(
   assertItem(item, ['dirName', 'customProps']);
   if (typeof item.dirName !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "dirName" must be a string.`,
+      `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 /`,
+      )}: "dirName" must be a dir path relative to the docs folder root, and should not start or end with slash`,
     );
   }
 }
@@ -156,13 +161,13 @@ function assertIsDoc(
   assertItem(item, ['id', 'label', 'customProps']);
   if (typeof item.id !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "id" must be a string.`,
+      `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.`,
+      `Error loading ${JSON.stringify(item)}: "label" must be a string.`,
     );
   }
 }
@@ -173,12 +178,12 @@ function assertIsLink(
   assertItem(item, ['href', 'label', 'customProps']);
   if (typeof item.href !== 'string') {
     throw new Error(
-      `Error loading ${JSON.stringify(item)}. "href" must be a string.`,
+      `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.`,
+      `Error loading ${JSON.stringify(item)}: "label" must be a string.`,
     );
   }
 }
@@ -222,12 +227,12 @@ function normalizeItem(item: SidebarItemJSON): UnprocessedSidebarItem[] {
     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 [${
+        `Unknown sidebar item type "${
           item.type
-        }]. Sidebar item=${JSON.stringify(item)} ${extraMigrationError}`,
+        }". Sidebar item is ${JSON.stringify(item)}.\n${extraMigrationError}`,
       );
     }
   }
@@ -256,7 +261,19 @@ export const DefaultSidebars: UnprocessedSidebars = {
 
 export const DisabledSidebars: UnprocessedSidebars = {};
 
+// If a path is provided, make it absolute
+// use this before loadSidebars()
+export function resolveSidebarPathOption(
+  siteDir: string,
+  sidebarPathOption: PluginOptions['sidebarPath'],
+): PluginOptions['sidebarPath'] {
+  return sidebarPathOption
+    ? path.resolve(siteDir, sidebarPathOption)
+    : sidebarPathOption;
+}
+
 // TODO refactor: make async
+// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 export function loadSidebars(
   sidebarFilePath: string | false | undefined,
 ): UnprocessedSidebars {
@@ -279,6 +296,7 @@ export function loadSidebars(
 
   // We don't want sidebars to be cached because of hot reloading.
   const sidebarJson = importFresh(sidebarFilePath) as SidebarsJSON;
+
   return normalizeSidebars(sidebarJson);
 }
 
@@ -423,7 +441,20 @@ export function collectSidebarsDocIds(
   });
 }
 
-export function createSidebarsUtils(sidebars: Sidebars) {
+export function createSidebarsUtils(
+  sidebars: Sidebars,
+): {
+  getFirstDocIdOfFirstSidebar: () => string | undefined;
+  getSidebarNameByDocId: (docId: string) => string | undefined;
+  getDocNavigation: (
+    docId: string,
+  ) => {
+    sidebarName: string | undefined;
+    previousId: string | undefined;
+    nextId: string | undefined;
+  };
+  checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
+} {
   const sidebarNameToDocIds = collectSidebarsDocIds(sidebars);
 
   function getFirstDocIdOfFirstSidebar(): string | undefined {
@@ -465,16 +496,18 @@ export function createSidebarsUtils(sidebars: Sidebars) {
     }
   }
 
-  function checkSidebarsDocIds(validDocIds: string[]) {
+  function checkSidebarsDocIds(validDocIds: string[], sidebarFilePath: string) {
     const allSidebarDocIds = flatten(Object.values(sidebarNameToDocIds));
     const invalidSidebarDocIds = difference(allSidebarDocIds, validDocIds);
     if (invalidSidebarDocIds.length > 0) {
       throw new Error(
-        `Bad sidebars file.
+        `Invalid sidebar file at "${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- ')}`,
       );
     }

package/src/slug.ts

@@ -47,8 +47,8 @@ export default function getSlug({
 
   if (!isValidPathname(slug)) {
     throw new Error(
-      `We couldn't compute a valid slug for document with id=${baseID} in folder=${dirName}
-The slug we computed looks invalid: ${slug}
+      `We couldn't compute a valid slug for document with id "${baseID}" in "${dirName}" directory.
+The slug we computed looks invalid: ${slug}.
 Maybe your slug frontmatter is incorrect or you use weird chars in the file path?
 By using the slug frontmatter, you should be able to fix this error, by using the slug of your choice:
 

package/src/types.ts

@@ -30,6 +30,7 @@ export type VersionMetadata = ContentPaths & {
   versionPath: string; // /baseUrl/docs/1.0.0
   versionEditUrl?: string | undefined;
   versionEditUrlLocalized?: string | undefined;
+  versionBanner: VersionBanner;
   isLast: boolean;
   sidebarFilePath: string | false | undefined; // versioned_sidebars/1.0.0.json
   routePriority: number | undefined; // -1 for the latest docs
@@ -59,9 +60,13 @@ export type PathOptions = {
   sidebarPath?: string | false | undefined;
 };
 
+// TODO support custom version banner? {type: "error", content: "html content"}
+export type VersionBanner = 'none' | 'unreleased' | 'unmaintained';
+
 export type VersionOptions = {
   path?: string;
   label?: string;
+  banner?: VersionBanner;
 };
 
 export type VersionsOptions = {
@@ -80,7 +85,6 @@ export type PluginOptions = MetadataOptions &
     docItemComponent: string;
     admonitions: Record<string, unknown>;
     disableVersioning: boolean;
-    excludeNextVersionDocs?: boolean;
     includeCurrentVersion: boolean;
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
   };
@@ -181,9 +185,23 @@ export type LastUpdateData = {
   lastUpdatedBy?: string;
 };
 
-export type FrontMatter = {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  [key: string]: any;
+export type DocFrontMatter = {
+  // Front matter uses snake case
+  /* eslint-disable camelcase */
+  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;
+  pagination_label?: string;
+  custom_edit_url?: string | null;
+  parse_number_prefixes?: boolean;
+  /* eslint-enable camelcase */
 };
 
 export type DocMetadataBase = LastUpdateData & {
@@ -197,11 +215,9 @@ export type DocMetadataBase = LastUpdateData & {
   sourceDirName: string; // relative to the docs folder (can be ".")
   slug: string;
   permalink: string;
-  // eslint-disable-next-line camelcase
-  sidebar_label?: string;
   sidebarPosition?: number;
   editUrl?: string | null;
-  frontMatter: FrontMatter;
+  frontMatter: DocFrontMatter & Record<string, unknown>;
 };
 
 export type DocNavLink = {

package/src/versions.ts

@@ -9,6 +9,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import {
   PluginOptions,
+  VersionBanner,
   VersionMetadata,
   VersionOptions,
   VersionsOptions,
@@ -24,6 +25,7 @@ import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 import {LoadContext} from '@docusaurus/types';
 import {getPluginI18nPath, normalizeUrl, posixPath} from '@docusaurus/utils';
 import {difference} from 'lodash';
+import {resolveSidebarPathOption} from './sidebars';
 
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir: string, pluginId: string): string {
@@ -58,12 +60,12 @@ export function getVersionsFilePath(siteDir: string, pluginId: string): string {
 function ensureValidVersionString(version: unknown): asserts version is string {
   if (typeof version !== 'string') {
     throw new Error(
-      `versions should be strings. Found type=[${typeof version}] for version=[${version}]`,
+      `Versions should be strings. Found type "${typeof version}" for version "${version}".`,
     );
   }
   // Should we forbid versions with special chars like / ?
   if (version.trim().length === 0) {
-    throw new Error(`Invalid version=[${version}]`);
+    throw new Error(`Invalid version "${version}".`);
   }
 }
 
@@ -72,7 +74,7 @@ function ensureValidVersionArray(
 ): asserts versionArray is string[] {
   if (!(versionArray instanceof Array)) {
     throw new Error(
-      `The versions file should contain an array of versions! Found content=${JSON.stringify(
+      `The versions file should contain an array of versions! Found content: ${JSON.stringify(
         versionArray,
       )}`,
     );
@@ -105,7 +107,7 @@ function readVersionNames(
 
   if (!versionFileContent && options.disableVersioning) {
     throw new Error(
-      `Docs: using disableVersioning=${options.disableVersioning} option on a non-versioned site does not make sense`,
+      `Docs: using "disableVersioning=${options.disableVersioning}" option on a non-versioned site does not make sense.`,
     );
   }
 
@@ -123,7 +125,7 @@ function readVersionNames(
 
   if (versions.length === 0) {
     throw new Error(
-      `It is not possible to use docs without any version. Please check the configuration of these options: includeCurrentVersion=${options.includeCurrentVersion} disableVersioning=${options.disableVersioning}`,
+      `It is not possible to use docs without any version. Please check the configuration of these options: "includeCurrentVersion=${options.includeCurrentVersion}", "disableVersioning=${options.disableVersioning}".`,
     );
   }
 
@@ -184,9 +186,7 @@ function getVersionMetadataPaths({
 
   function getSidebarFilePath() {
     if (isCurrentVersion) {
-      return options.sidebarPath
-        ? path.resolve(context.siteDir, options.sidebarPath)
-        : options.sidebarPath;
+      return resolveSidebarPathOption(context.siteDir, options.sidebarPath);
     } else {
       return path.join(
         getVersionedSidebarsDirPath(context.siteDir, options.id),
@@ -256,14 +256,64 @@ function getVersionEditUrls({
   };
 }
 
+function getDefaultVersionBanner({
+  versionName,
+  versionNames,
+  lastVersionName,
+}: {
+  versionName: string;
+  versionNames: string[];
+  lastVersionName: string;
+}): VersionBanner {
+  // Current version: good, no banner
+  if (versionName === lastVersionName) {
+    return 'none';
+  }
+  // Upcoming versions: unreleased banner
+  else if (
+    versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)
+  ) {
+    return 'unreleased';
+  }
+  // Older versions: display unmaintained banner
+  else {
+    return 'unmaintained';
+  }
+}
+
+function getVersionBanner({
+  versionName,
+  versionNames,
+  lastVersionName,
+  options,
+}: {
+  versionName: string;
+  versionNames: string[];
+  lastVersionName: string;
+  options: Pick<PluginOptions, 'versions'>;
+}): VersionBanner {
+  const versionOptionBanner = options.versions[versionName]?.banner;
+
+  return (
+    versionOptionBanner ??
+    getDefaultVersionBanner({
+      versionName,
+      versionNames,
+      lastVersionName,
+    })
+  );
+}
+
 function createVersionMetadata({
   versionName,
-  isLast,
+  versionNames,
+  lastVersionName,
   context,
   options,
 }: {
   versionName: string;
-  isLast: boolean;
+  versionNames: string[];
+  lastVersionName: string;
   context: Pick<LoadContext, 'siteDir' | 'baseUrl' | 'i18n'>;
   options: Pick<
     PluginOptions,
@@ -286,14 +336,18 @@ function createVersionMetadata({
     options,
   });
 
+  const isLast = versionName === lastVersionName;
+
   // retro-compatible values
   const defaultVersionLabel =
     versionName === CURRENT_VERSION_NAME ? 'Next' : versionName;
-  const defaultVersionPathPart = isLast
-    ? ''
-    : versionName === CURRENT_VERSION_NAME
-    ? 'next'
-    : versionName;
+  function getDefaultVersionPathPart() {
+    if (isLast) {
+      return '';
+    }
+    return versionName === CURRENT_VERSION_NAME ? 'next' : versionName;
+  }
+  const defaultVersionPathPart = getDefaultVersionPathPart();
 
   const versionOptions: VersionOptions = options.versions[versionName] ?? {};
 
@@ -322,6 +376,12 @@ function createVersionMetadata({
     versionPath,
     versionEditUrl: versionEditUrls?.versionEditUrl,
     versionEditUrlLocalized: versionEditUrls?.versionEditUrlLocalized,
+    versionBanner: getVersionBanner({
+      versionName,
+      versionNames,
+      lastVersionName,
+      options,
+    }),
     isLast,
     routePriority,
     sidebarFilePath,
@@ -343,10 +403,10 @@ function checkVersionMetadataPaths({
 
   if (!fs.existsSync(contentPath)) {
     throw new Error(
-      `The docs folder does not exist for version [${versionName}]. A docs folder is expected to be found at ${path.relative(
+      `The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path.relative(
         siteDir,
         contentPath,
-      )}`,
+      )}.`,
     );
   }
 
@@ -359,11 +419,11 @@ function checkVersionMetadataPaths({
     typeof sidebarFilePath === 'string' &&
     !fs.existsSync(sidebarFilePath)
   ) {
-    throw new Error(`The path to the sidebar file does not exist at [${path.relative(
+    throw new Error(`The path to the sidebar file does not exist at "${path.relative(
       siteDir,
       sidebarFilePath,
-    )}].
-Please set the docs [sidebarPath] field in your config file to:
+    )}".
+Please set the docs "sidebarPath" field in your config file to:
 - a sidebars path that exists
 - false: to disable the sidebar
 - undefined: for Docusaurus generates it automatically`);
@@ -404,16 +464,16 @@ function checkVersionsOptions(
   );
   if (unknownVersionConfigNames.length > 0) {
     throw new Error(
-      `Bad docs options.versions: unknown versions found: ${unknownVersionConfigNames.join(
+      `Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(
         ',',
-      )}. ${availableVersionNamesMsg}`,
+      )}) found. ${availableVersionNamesMsg}`,
     );
   }
 
   if (options.onlyIncludeVersions) {
     if (options.onlyIncludeVersions.length === 0) {
       throw new Error(
-        `Bad docs options.onlyIncludeVersions: an empty array is not allowed, at least one version is needed`,
+        `Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`,
       );
     }
     const unknownOnlyIncludeVersionNames = difference(
@@ -422,9 +482,9 @@ function checkVersionsOptions(
     );
     if (unknownOnlyIncludeVersionNames.length > 0) {
       throw new Error(
-        `Bad docs options.onlyIncludeVersions: unknown versions found: ${unknownOnlyIncludeVersionNames.join(
+        `Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(
           ',',
-        )}. ${availableVersionNamesMsg}`,
+        )}) found. ${availableVersionNamesMsg}`,
       );
     }
     if (
@@ -432,7 +492,7 @@ function checkVersionsOptions(
       !options.onlyIncludeVersions.includes(options.lastVersion)
     ) {
       throw new Error(
-        `Bad docs options.lastVersion: if you use both the onlyIncludeVersions and lastVersion options, then lastVersion must be present in the provided onlyIncludeVersions array`,
+        `Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`,
       );
     }
   }
@@ -487,7 +547,8 @@ export function readVersionsMetadata({
   const versionsMetadata = versionNames.map((versionName) =>
     createVersionMetadata({
       versionName,
-      isLast: versionName === lastVersionName,
+      versionNames,
+      lastVersionName,
       context,
       options,
     }),