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

package/src/cli.ts

@@ -17,7 +17,7 @@ import {
   UnprocessedSidebarItem,
   UnprocessedSidebars,
 } from './types';
-import {loadSidebars} from './sidebars';
+import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
 
 function createVersionedSidebarFile({
@@ -92,23 +92,23 @@ export function cliDocsVersionCommand(
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
   const pluginIdLogPrefix =
-    pluginId === DEFAULT_PLUGIN_ID ? '[docs] ' : `[${pluginId}] `;
+    pluginId === 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`,
+      `${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`,
+      `${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`,
+      `${pluginIdLogPrefix}: invalid version tag specified! Length cannot exceed 32 characters. Try something like: 1.0.0.`,
     );
   }
 
@@ -117,13 +117,13 @@ export function cliDocsVersionCommand(
   // 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`,
+      `${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`,
+      `${pluginIdLogPrefix}: invalid version tag specified! Do not name your version "." or "..". Try something like: 1.0.0.`,
     );
   }
 
@@ -137,7 +137,7 @@ export function cliDocsVersionCommand(
   // 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.`,
+      `${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`,
     );
   }
 
@@ -145,20 +145,26 @@ export function cliDocsVersionCommand(
 
   // Copy docs files.
   const docsDir = path.join(siteDir, docsPath);
+
   if (fs.existsSync(docsDir) && fs.readdirSync(docsDir).length > 0) {
     const versionedDir = getVersionedDocsDirPath(siteDir, pluginId);
     const newVersionDir = path.join(versionedDir, `version-${version}`);
     fs.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: resolveSidebarPathOption(siteDir, sidebarPath),
+  });
 
   // Update versions.json file.
   versions.unshift(version);
   fs.ensureDirSync(path.dirname(versionsJSONFile));
   fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
 
-  console.log(`${pluginIdLogPrefix}Version ${version} created!`);
+  console.log(`${pluginIdLogPrefix}: version ${version} created!`);
 }

package/src/client/__tests__/docsClientUtils.test.ts

@@ -35,12 +35,12 @@ describe('docsClientUtils', () => {
     expect(() =>
       getActivePlugin(data, '/', {failfast: true}),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Can't find active docs plugin for 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: /ios, /android"`,
+      `"Can't find active docs plugin for \\"/\\" 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: /ios, /android"`,
     );
     expect(() =>
       getActivePlugin(data, '/xyz', {failfast: true}),
     ).toThrowErrorMatchingInlineSnapshot(
-      `"Can't find active docs plugin for pathname=/xyz, 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: /ios, /android"`,
+      `"Can't find active docs plugin for \\"/xyz\\" 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: /ios, /android"`,
     );
 
     const activePluginIos: ActivePlugin = {
@@ -350,14 +350,13 @@ describe('docsClientUtils', () => {
       latestVersionSuggestion: version2,
     });
 
-    // nothing to suggest, we are already on latest version
     expect(getDocVersionSuggestions(data, '/docs/')).toEqual({
-      latestDocSuggestion: undefined,
-      latestVersionSuggestion: undefined,
+      latestDocSuggestion: version2.docs[0],
+      latestVersionSuggestion: version2,
     });
     expect(getDocVersionSuggestions(data, '/docs/doc2')).toEqual({
-      latestDocSuggestion: undefined,
-      latestVersionSuggestion: undefined,
+      latestDocSuggestion: version2.docs[1],
+      latestVersionSuggestion: version2,
     });
 
     expect(getDocVersionSuggestions(data, '/docs/version1/')).toEqual({

package/src/client/docsClientUtils.ts

@@ -57,7 +57,7 @@ export function getActivePlugin(
 
   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(
+      `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)
@@ -140,10 +140,10 @@ export const getActiveDocContext = (
 };
 
 export type DocVersionSuggestions = {
+  // suggest the latest version
+  latestVersionSuggestion: GlobalVersion;
   // suggest the same doc, in latest version (if exist)
   latestDocSuggestion?: GlobalDoc;
-  // suggest the latest version
-  latestVersionSuggestion?: GlobalVersion;
 };
 
 export const getDocVersionSuggestions = (
@@ -152,17 +152,7 @@ export const getDocVersionSuggestions = (
 ): DocVersionSuggestions => {
   const latestVersion = getLatestVersion(data);
   const activeDocContext = getActiveDocContext(data, pathname);
-
-  // We only suggest another doc/version if user is not using the latest version
-  const isNotOnLatestVersion = activeDocContext.activeVersion !== latestVersion;
-
-  const latestDocSuggestion: GlobalDoc | undefined = isNotOnLatestVersion
-    ? activeDocContext?.alternateDocVersions[latestVersion.name]
-    : undefined;
-
-  const latestVersionSuggestion = isNotOnLatestVersion
-    ? latestVersion
-    : undefined;
-
-  return {latestDocSuggestion, latestVersionSuggestion};
+  const latestDocSuggestion: GlobalDoc | undefined =
+    activeDocContext?.alternateDocVersions[latestVersion.name];
+  return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
 };

package/src/docFrontMatter.ts

@@ -9,23 +9,10 @@
 
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
+  URISchema,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
-
-export 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';
 
 // 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
@@ -37,12 +24,13 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   hide_title: Joi.boolean(),
   hide_table_of_contents: Joi.boolean(),
   keywords: Joi.array().items(Joi.string().required()),
-  image: Joi.string().uri({allowRelative: false}),
+  image: URISchema,
   description: Joi.string().allow(''), // see  https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number().min(0),
-  custom_edit_url: Joi.string().uri({allowRelative: true}).allow('', null),
+  pagination_label: Joi.string(),
+  custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
 }).unknown();
 

package/src/docs.ts

@@ -32,6 +32,7 @@ import globby from 'globby';
 import {getDocsDirPaths} from './versions';
 import {stripPathNumberPrefixes} from './numberPrefix';
 import {validateDocFrontMatter} from './docFrontMatter';
+import chalk from 'chalk';
 
 type LastUpdateOptions = Pick<
   PluginOptions,
@@ -102,7 +103,7 @@ export async function readVersionDocs(
   );
 }
 
-export function processDocMetadata({
+function doProcessDocMetadata({
   docFile,
   versionMetadata,
   context,
@@ -125,11 +126,11 @@ export function processDocMetadata({
   const frontMatter = validateDocFrontMatter(unsafeFrontMatter);
 
   const {
-    sidebar_label: sidebarLabel,
     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;
 
@@ -144,13 +145,14 @@ export function processDocMetadata({
   // ex: myDoc -> .
   const sourceDirName = path.dirname(source);
 
+  // eslint-disable-next-line camelcase
   const {filename: unprefixedFileName, numberPrefix} = parse_number_prefixes
     ? options.numberPrefixParser(sourceFileNameWithoutExtension)
     : {filename: sourceFileNameWithoutExtension, numberPrefix: undefined};
 
   const baseID: string = frontMatter.id ?? 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
@@ -172,6 +174,7 @@ export function processDocMetadata({
       return undefined;
     }
     // Eventually remove the number prefixes from intermediate directories
+    // eslint-disable-next-line camelcase
     return parse_number_prefixes
       ? stripPathNumberPrefixes(sourceDirName, options.numberPrefixParser)
       : sourceDirName;
@@ -203,11 +206,9 @@ export function processDocMetadata({
         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: string = contentTitle ?? frontMatter.title ?? baseID;
-  // const metaTitle: string = frontMatter.title ?? contentTitle  ?? baseID;
+  // 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: string = frontMatter.title ?? contentTitle ?? baseID;
 
   const description: string = frontMatter.description ?? excerpt ?? '';
 
@@ -246,7 +247,7 @@ export function processDocMetadata({
     unversionedId,
     id,
     isDocsHomePage,
-    title: headingTitle,
+    title,
     description,
     source: aliasedSitePath(filePath, siteDir),
     sourceDirName,
@@ -261,8 +262,25 @@ export function processDocMetadata({
           lastUpdate.lastUpdatedAt * 1000,
         )
       : undefined,
-    sidebar_label: sidebarLabel,
     sidebarPosition,
     frontMatter,
   };
 }
+
+export function processDocMetadata(args: {
+  docFile: DocFile;
+  versionMetadata: VersionMetadata;
+  context: LoadContext;
+  options: MetadataOptions;
+}): DocMetadataBase {
+  try {
+    return doProcessDocMetadata(args);
+  } catch (e) {
+    console.error(
+      chalk.red(
+        `Can't process doc metadatas for doc at path "${args.docFile.filePath}" in version "${args.versionMetadata.versionName}"`,
+      ),
+    );
+    throw e;
+  }
+}

package/src/index.ts

@@ -41,7 +41,7 @@ import {PermalinkToSidebar} from '@docusaurus/plugin-content-docs-types';
 import {RuleSetRule} from 'webpack';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
-import {flatten, keyBy, compact} from 'lodash';
+import {flatten, keyBy, compact, mapValues} from 'lodash';
 import {toGlobalDataVersion} from './globalData';
 import {toVersionMetadataProp} from './props';
 import {
@@ -49,6 +49,7 @@ import {
   getLoadedContentTranslationFiles,
 } from './translations';
 import {CategoryMetadataFilenamePattern} from './sidebarItemsGenerator';
+import chalk from 'chalk';
 
 export default function pluginContentDocs(
   context: LoadContext,
@@ -58,7 +59,6 @@ export default function pluginContentDocs(
 
   const versionsMetadata = readVersionsMetadata({context, options});
 
-  const sourceToPermalink: SourceToPermalink = {};
   const pluginId = options.id ?? DEFAULT_PLUGIN_ID;
 
   const pluginDataDirRoot = path.join(
@@ -144,12 +144,12 @@ export default function pluginContentDocs(
         const docFiles = await readVersionDocs(versionMetadata, options);
         if (docFiles.length === 0) {
           throw new Error(
-            `Docs version ${
+            `Docs version "${
               versionMetadata.versionName
-            } has no docs! At least one doc should exist at path=[${path.relative(
+            }" has no docs! At least one doc should exist at "${path.relative(
               siteDir,
               versionMetadata.contentPath,
-            )}]`,
+            )}".`,
           );
         }
         async function processVersionDoc(docFile: DocFile) {
@@ -163,7 +163,7 @@ export default function pluginContentDocs(
         return Promise.all(docFiles.map(processVersionDoc));
       }
 
-      async function loadVersion(
+      async function doLoadVersion(
         versionMetadata: VersionMetadata,
       ): Promise<LoadedVersion> {
         const unprocessedSidebars = loadSidebars(
@@ -189,7 +189,10 @@ export default function pluginContentDocs(
         const sidebarsUtils = createSidebarsUtils(sidebars);
 
         const validDocIds = Object.keys(docsBaseById);
-        sidebarsUtils.checkSidebarsDocIds(validDocIds);
+        sidebarsUtils.checkSidebarsDocIds(
+          validDocIds,
+          versionMetadata.sidebarFilePath as string,
+        );
 
         // Add sidebar/next/previous to the docs
         function addNavData(doc: DocMetadataBase): DocMetadata {
@@ -198,10 +201,16 @@ export default function pluginContentDocs(
             previousId,
             nextId,
           } = sidebarsUtils.getDocNavigation(doc.id);
-          const toDocNavLink = (navDocId: string): DocNavLink => ({
-            title: docsBaseById[navDocId].title,
-            permalink: docsBaseById[navDocId].permalink,
-          });
+          const toDocNavLink = (navDocId: string): DocNavLink => {
+            const {title, permalink, frontMatter} = docsBaseById[navDocId];
+            return {
+              title:
+                frontMatter.pagination_label ??
+                frontMatter.sidebar_label ??
+                title,
+              permalink,
+            };
+          };
           return {
             ...doc,
             sidebar: sidebarName,
@@ -215,12 +224,6 @@ export default function pluginContentDocs(
         // 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: PermalinkToSidebar = {};
         Object.values(docs).forEach((doc) => {
@@ -258,6 +261,19 @@ export default function pluginContentDocs(
         };
       }
 
+      async function loadVersion(versionMetadata: VersionMetadata) {
+        try {
+          return await doLoadVersion(versionMetadata);
+        } catch (e) {
+          console.error(
+            chalk.red(
+              `Loading of version failed for version "${versionMetadata.versionName}"`,
+            ),
+          );
+          throw e;
+        }
+      }
+
       return {
         loadedVersions: await Promise.all(versionsMetadata.map(loadVersion)),
       };
@@ -298,7 +314,7 @@ export default function pluginContentDocs(
         return routes.sort((a, b) => a.path.localeCompare(b.path));
       };
 
-      async function handleVersion(loadedVersion: LoadedVersion) {
+      async function doCreateVersionRoutes(loadedVersion: LoadedVersion) {
         const versionMetadataPropPath = await createData(
           `${docuHash(
             `version-${loadedVersion.versionName}-metadata-prop`,
@@ -325,7 +341,20 @@ export default function pluginContentDocs(
         });
       }
 
-      await Promise.all(loadedVersions.map(handleVersion));
+      async function createVersionRoutes(loadedVersion: LoadedVersion) {
+        try {
+          return await doCreateVersionRoutes(loadedVersion);
+        } catch (e) {
+          console.error(
+            chalk.red(
+              `Can't create version routes for version "${loadedVersion.versionName}"`,
+            ),
+          );
+          throw e;
+        }
+      }
+
+      await Promise.all(loadedVersions.map(createVersionRoutes));
 
       setGlobalData<GlobalPluginData>({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
@@ -333,7 +362,7 @@ export default function pluginContentDocs(
       });
     },
 
-    configureWebpack(_config, isServer, utils) {
+    configureWebpack(_config, isServer, utils, content) {
       const {getJSLoader} = utils;
       const {
         rehypePlugins,
@@ -342,9 +371,17 @@ export default function pluginContentDocs(
         beforeDefaultRemarkPlugins,
       } = options;
 
+      function getSourceToPermalink(): SourceToPermalink {
+        const allDocs = flatten(content.loadedVersions.map((v) => v.docs));
+        return mapValues(
+          keyBy(allDocs, (d) => d.source),
+          (d) => d.permalink,
+        );
+      }
+
       const docsMarkdownOptions: DocsMarkdownOption = {
         siteDir,
-        sourceToPermalink,
+        sourceToPermalink: getSourceToPermalink(),
         versionsMetadata,
         onBrokenMarkdownLink: (brokenMarkdownLink) => {
           if (siteConfig.onBrokenMarkdownLinks === 'ignore') {

package/src/lastUpdate.ts

@@ -7,6 +7,7 @@
 
 import shell from 'shelljs';
 import execa from 'execa';
+import path from 'path';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
@@ -43,12 +44,15 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const {stdout} = await execa('git', [
-      'log',
-      '-1',
-      '--format=%ct, %an',
-      filePath,
-    ]);
+    const fileBasename = path.basename(filePath);
+    const fileDirname = path.dirname(filePath);
+    const {stdout} = await execa(
+      'git',
+      ['log', '-1', '--format=%ct, %an', fileBasename],
+      {
+        cwd: fileDirname,
+      },
+    );
     return getTimestampAndAuthor(stdout);
   } catch (error) {
     console.error(error);

package/src/markdown/linkify.ts

@@ -17,7 +17,7 @@ function getVersion(filePath: string, options: DocsMarkdownOption) {
   );
   if (!versionFound) {
     throw new Error(
-      `Unexpected, markdown file does not belong to any docs version! file=${filePath}`,
+      `Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`,
     );
   }
   return versionFound;

package/src/options.ts

@@ -37,7 +37,6 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
   admonitions: {},
-  excludeNextVersionDocs: false,
   includeCurrentVersion: true,
   disableVersioning: false,
   lastVersion: undefined,
@@ -49,6 +48,7 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
 const VersionOptionsSchema = Joi.object({
   path: Joi.string().allow('').optional(),
   label: Joi.string().optional(),
+  banner: Joi.string().equal('none', 'unreleased', 'unmaintained').optional(),
 });
 
 const VersionsOptionsSchema = Joi.object()
@@ -101,9 +101,6 @@ export const OptionsSchema = Joi.object({
   showLastUpdateAuthor: Joi.bool().default(
     DEFAULT_OPTIONS.showLastUpdateAuthor,
   ),
-  excludeNextVersionDocs: Joi.bool().default(
-    DEFAULT_OPTIONS.excludeNextVersionDocs,
-  ),
   includeCurrentVersion: Joi.bool().default(
     DEFAULT_OPTIONS.includeCurrentVersion,
   ),
@@ -127,17 +124,6 @@ export function validateOptions({
     );
   }
 
-  if (typeof options.excludeNextVersionDocs !== 'undefined') {
-    console.log(
-      chalk.red(
-        `The docs plugin option excludeNextVersionDocs=${
-          options.excludeNextVersionDocs
-        } is deprecated. Use the includeCurrentVersion=${!options.excludeNextVersionDocs} option instead!"`,
-      ),
-    );
-    options.includeCurrentVersion = !options.excludeNextVersionDocs;
-  }
-
   const normalizedOptions = validate(OptionsSchema, options);
 
   if (normalizedOptions.admonitions) {

package/src/plugin-content-docs.d.ts

@@ -8,6 +8,8 @@
 /* eslint-disable camelcase */
 
 declare module '@docusaurus/plugin-content-docs-types' {
+  import type {VersionBanner} from './types';
+
   export type PermalinkToSidebar = {
     [permalink: string]: string;
   };
@@ -16,6 +18,7 @@ declare module '@docusaurus/plugin-content-docs-types' {
     pluginId: string;
     version: string;
     label: string;
+    banner: VersionBanner;
     isLast: boolean;
     docsSidebars: PropSidebars;
     permalinkToSidebar: PermalinkToSidebar;
@@ -43,6 +46,11 @@ declare module '@docusaurus/plugin-content-docs-types' {
   export type PropSidebars = {
     [sidebarId: string]: PropSidebarItem[];
   };
+
+  export type {
+    GlobalVersion as GlobalDataVersion,
+    GlobalDoc as GlobalDataDoc,
+  } from './types';
 }
 
 declare module '@theme/DocItem' {
@@ -78,10 +86,12 @@ declare module '@theme/DocItem' {
 
   export type Props = {
     readonly route: DocumentRoute;
+    readonly versionMetadata: PropVersionMetadata;
     readonly content: {
       readonly frontMatter: FrontMatter;
       readonly metadata: Metadata;
       readonly toc: readonly TOCItem[];
+      readonly contentTitle: string | undefined;
       (): JSX.Element;
     };
   };
@@ -90,6 +100,17 @@ declare module '@theme/DocItem' {
   export default DocItem;
 }
 
+declare module '@theme/DocVersionBanner' {
+  import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
+
+  export type Props = {
+    readonly versionMetadata: PropVersionMetadata;
+  };
+
+  const DocVersionBanner: (props: Props) => JSX.Element;
+  export default DocVersionBanner;
+}
+
 declare module '@theme/DocPage' {
   import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types';
   import type {DocumentRoute} from '@theme/DocItem';

package/src/props.ts

@@ -27,13 +27,17 @@ export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
 
     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=
+        `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',
@@ -70,6 +74,7 @@ export function toVersionMetadataProp(
     pluginId,
     version: loadedVersion.versionName,
     label: loadedVersion.versionLabel,
+    banner: loadedVersion.versionBanner,
     isLast: loadedVersion.isLast,
     docsSidebars: toSidebarsProp(loadedVersion),
     permalinkToSidebar: loadedVersion.permalinkToSidebar,