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

package/src/sidebars/types.ts

@@ -5,14 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {Optional} from 'utility-types';
+import type {Optional, Required} from 'utility-types';
+import type {DocMetadataBase, VersionMetadata} from '../types';
 import type {
-  DocMetadataBase,
-  VersionMetadata,
   NumberPrefixParser,
   SidebarOptions,
-} from '../types';
-import {Required} from 'utility-types';
+  CategoryIndexMatcher,
+} from '@docusaurus/plugin-content-docs';
 
 // Makes all properties visible when hovering over the type
 type Expand<T extends Record<string, unknown>> = {[P in keyof T]: T[P]};
@@ -53,6 +52,8 @@ export type SidebarItemCategoryLinkGeneratedIndexConfig = {
   slug?: string;
   title?: string;
   description?: string;
+  image?: string;
+  keywords?: string | readonly string[];
 };
 export type SidebarItemCategoryLinkGeneratedIndex = {
   type: 'generated-index';
@@ -60,6 +61,8 @@ export type SidebarItemCategoryLinkGeneratedIndex = {
   permalink: string;
   title?: string;
   description?: string;
+  image?: string;
+  keywords?: string | readonly string[];
 };
 
 export type SidebarItemCategoryLinkConfig =
@@ -193,6 +196,7 @@ export type SidebarItemsGeneratorArgs = {
   version: SidebarItemsGeneratorVersion;
   docs: SidebarItemsGeneratorDoc[];
   numberPrefixParser: NumberPrefixParser;
+  isCategoryIndex: CategoryIndexMatcher;
   options: SidebarOptions;
 };
 export type SidebarItemsGenerator = (

package/src/sidebars/utils.ts

@@ -15,17 +15,15 @@ import type {
   SidebarItemType,
   SidebarCategoriesShorthand,
   SidebarItemConfig,
-} from './types';
-
-import {mapValues, difference, uniq} from 'lodash';
-import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
-import {DocMetadataBase, DocNavLink} from '../types';
-import {
   SidebarItemCategoryWithGeneratedIndex,
   SidebarItemCategoryWithLink,
   SidebarNavigationItem,
 } from './types';
 
+import {mapValues, difference, uniq} from 'lodash';
+import {getElementsAround, toMessageRelativeFilePath} from '@docusaurus/utils';
+import type {DocMetadataBase, DocNavLink} from '../types';
+
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
 ): item is SidebarCategoriesShorthand {
@@ -133,11 +131,24 @@ export type SidebarsUtils = {
   getDocNavigation: (
     unversionedId: string,
     versionedId: string,
+    displayedSidebar: string | null | undefined,
   ) => SidebarNavigation;
   getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
   ) => SidebarNavigation;
+  getFirstLink: (sidebarId: string) =>
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+      }
+    | undefined;
 
   checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
 };
@@ -172,16 +183,25 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
   function getDocNavigation(
     unversionedId: string,
     versionedId: string,
+    displayedSidebar: string | null | undefined,
   ): SidebarNavigation {
     // TODO legacy id retro-compatibility!
     let docId = unversionedId;
-    let sidebarName = getSidebarNameByDocId(docId);
-    if (!sidebarName) {
+    let sidebarName =
+      displayedSidebar === undefined
+        ? getSidebarNameByDocId(docId)
+        : displayedSidebar;
+    if (sidebarName === undefined) {
       docId = versionedId;
       sidebarName = getSidebarNameByDocId(docId);
     }
 
     if (sidebarName) {
+      if (!sidebarNameToNavigationItems[sidebarName]) {
+        throw new Error(
+          `Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`,
+        );
+      }
       const navigationItems = sidebarNameToNavigationItems[sidebarName];
       const currentItemIndex = navigationItems.findIndex((item) => {
         if (item.type === 'doc') {
@@ -192,6 +212,9 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
         }
         return false;
       });
+      if (currentItemIndex === -1) {
+        return {sidebarName, next: undefined, previous: undefined};
+      }
 
       const {previous, next} = getElementsAround(
         navigationItems,
@@ -266,6 +289,50 @@ Available document ids are:
     }
   }
 
+  function getFirstLink(sidebar: Sidebar):
+    | {
+        type: 'doc';
+        id: string;
+        label: string;
+      }
+    | {
+        type: 'generated-index';
+        slug: string;
+        label: string;
+      }
+    | undefined {
+    // eslint-disable-next-line no-restricted-syntax
+    for (const item of sidebar) {
+      if (item.type === 'doc') {
+        return {
+          type: 'doc',
+          id: item.id,
+          label: item.label ?? item.id,
+        };
+      } else if (item.type === 'category') {
+        if (item.link?.type === 'doc') {
+          return {
+            type: 'doc',
+            id: item.link.id,
+            label: item.label,
+          };
+        } else if (item.link?.type === 'generated-index') {
+          return {
+            type: 'generated-index',
+            slug: item.link.slug,
+            label: item.label,
+          };
+        } else {
+          const firstSubItem = getFirstLink(item.items);
+          if (firstSubItem) {
+            return firstSubItem;
+          }
+        }
+      }
+    }
+    return undefined;
+  }
+
   return {
     sidebars,
     getFirstDocIdOfFirstSidebar,
@@ -274,6 +341,7 @@ Available document ids are:
     getCategoryGeneratedIndexList,
     getCategoryGeneratedIndexNavigation,
     checkSidebarsDocIds,
+    getFirstLink: (id) => getFirstLink(sidebars[id]),
   };
 }
 

package/src/sidebars/validation.ts

@@ -20,7 +20,10 @@ import type {
   SidebarItemCategoryLinkGeneratedIndex,
 } from './types';
 import {isCategoriesShorthand} from './utils';
-import {CategoryMetadataFile} from './generator';
+import type {CategoryMetadataFile} from './generator';
+
+// NOTE: we don't add any default values during validation on purpose!
+// Config types are exposed to users for typechecking and we use the same type in normalization
 
 const sidebarItemBaseSchema = Joi.object<SidebarItemBase>({
   className: Joi.string(),
@@ -70,6 +73,8 @@ const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
           // permalink: Joi.string().optional(), // No, this one is not in the user config, only in the normalized version
           title: Joi.string().optional(),
           description: Joi.string().optional(),
+          image: Joi.string().optional(),
+          keywords: [Joi.string(), Joi.array().items(Joi.string())],
         }),
       },
       {

package/src/slug.ts

@@ -15,20 +15,21 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import type {DocMetadataBase, NumberPrefixParser} from './types';
-import {isConventionalDocIndex} from './docs';
+import type {DocMetadataBase} from './types';
+import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs';
+import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
 
 export default function getSlug({
   baseID,
-  frontmatterSlug,
+  frontMatterSlug,
   source,
   sourceDirName,
   stripDirNumberPrefixes = true,
   numberPrefixParser = DefaultNumberPrefixParser,
 }: {
   baseID: string;
-  frontmatterSlug?: string;
-  source: DocMetadataBase['slug'];
+  frontMatterSlug?: string;
+  source: DocMetadataBase['source'];
   sourceDirName: DocMetadataBase['sourceDirName'];
   stripDirNumberPrefixes?: boolean;
   numberPrefixParser?: NumberPrefixParser;
@@ -45,14 +46,17 @@ export default function getSlug({
   }
 
   function computeSlug(): string {
-    if (frontmatterSlug?.startsWith('/')) {
-      return frontmatterSlug;
+    if (frontMatterSlug?.startsWith('/')) {
+      return frontMatterSlug;
     } else {
       const dirNameSlug = getDirNameSlug();
-      if (!frontmatterSlug && isConventionalDocIndex({source, sourceDirName})) {
+      if (
+        !frontMatterSlug &&
+        isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName}))
+      ) {
         return dirNameSlug;
       }
-      const baseSlug = frontmatterSlug || baseID;
+      const baseSlug = frontMatterSlug || baseID;
       return resolvePathname(baseSlug, getDirNameSlug());
     }
   }
@@ -62,8 +66,8 @@ export default function getSlug({
       throw new Error(
         `We couldn't compute a valid slug for document with id "${baseID}" in "${sourceDirName}" 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:
+Maybe your slug front matter is incorrect or you use weird chars in the file path?
+By using the slug front matter, you should be able to fix this error, by using the slug of your choice:
 
 Example =>
 ---

package/src/translations.ts

@@ -23,10 +23,10 @@ import type {
   TranslationFileContent,
   TranslationFile,
   TranslationFiles,
+  TranslationMessage,
 } from '@docusaurus/types';
 import {mergeTranslations} from '@docusaurus/utils';
 import {CURRENT_VERSION_NAME} from './constants';
-import {TranslationMessage} from '@docusaurus/types';
 
 function getVersionFileName(versionName: string): string {
   if (versionName === CURRENT_VERSION_NAME) {
@@ -57,7 +57,7 @@ function getNormalizedSidebarName({
 
 /*
 // Do we need to translate doc metadata?
-// It seems translating frontmatter labels is good enough
+// It seems translating front matter labels is good enough
 function getDocTranslations(doc: DocMetadata): TranslationFileContent {
   return {
     [`${doc.unversionedId}.title`]: {

package/src/types.ts

@@ -7,13 +7,16 @@
 
 /// <reference types="@docusaurus/module-type-aliases" />
 
-import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
+import type {Sidebars} from './sidebars/types';
 import type {Tag, FrontMatterTag, Slugger} from '@docusaurus/utils';
 import type {
   BrokenMarkdownLink as IBrokenMarkdownLink,
   ContentPaths,
 } from '@docusaurus/utils/lib/markdownLinks';
-import type {SidebarItemsGeneratorOption, Sidebars} from './sidebars/types';
+import type {
+  VersionBanner,
+  SidebarOptions,
+} from '@docusaurus/plugin-content-docs';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -23,10 +26,8 @@ export type DocFile = {
   lastUpdate: LastUpdateData;
 };
 
-export type VersionName = string;
-
 export type VersionMetadata = ContentPaths & {
-  versionName: VersionName; // 1.0.0
+  versionName: string; // 1.0.0
   versionLabel: string; // Version 1.0.0
   versionPath: string; // /baseUrl/docs/1.0.0
   tagsPath: string;
@@ -40,76 +41,11 @@ export type VersionMetadata = ContentPaths & {
   routePriority: number | undefined; // -1 for the latest docs
 };
 
-export type EditUrlFunction = (editUrlParams: {
-  version: string;
-  versionDocsDirPath: string;
-  docPath: string;
-  permalink: string;
-  locale: string;
-}) => string | undefined;
-
-export type MetadataOptions = {
-  routeBasePath: string;
-  editUrl?: string | EditUrlFunction;
-  editCurrentVersion: boolean;
-  editLocalizedFiles: boolean;
-  showLastUpdateTime?: boolean;
-  showLastUpdateAuthor?: boolean;
-  numberPrefixParser: NumberPrefixParser;
-};
-
-export type PathOptions = {
-  path: string;
-  sidebarPath?: string | false | undefined;
-};
-
-// TODO support custom version banner? {type: "error", content: "html content"}
-export type VersionBanner = 'unreleased' | 'unmaintained';
-
-export type VersionOptions = {
-  path?: string;
-  label?: string;
-  banner?: 'none' | VersionBanner;
-  badge?: boolean;
-  className?: string;
-};
-
-export type VersionsOptions = {
-  lastVersion?: string;
-  versions: Record<string, VersionOptions>;
-  onlyIncludeVersions?: string[];
-};
-
-export type SidebarOptions = {
-  sidebarCollapsible: boolean;
-  sidebarCollapsed: boolean;
-};
-
 export type NormalizeSidebarsParams = SidebarOptions & {
   version: VersionMetadata;
   categoryLabelSlugger: Slugger;
 };
 
-export type PluginOptions = MetadataOptions &
-  PathOptions &
-  VersionsOptions &
-  RemarkAndRehypePluginOptions &
-  SidebarOptions & {
-    id: string;
-    include: string[];
-    exclude: string[];
-    docLayoutComponent: string;
-    docItemComponent: string;
-    docTagDocListComponent: string;
-    docTagsListComponent: string;
-    docCategoryGeneratedIndexComponent: string;
-    admonitions: Record<string, unknown>;
-    disableVersioning: boolean;
-    includeCurrentVersion: boolean;
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-    tagsBasePath: string;
-  };
-
 export type LastUpdateData = {
   lastUpdatedAt?: number;
   formattedLastUpdatedAt?: string;
@@ -130,6 +66,7 @@ export type DocFrontMatter = {
   sidebar_label?: string;
   sidebar_position?: number;
   sidebar_class_name?: string;
+  displayed_sidebar?: string | null;
   pagination_label?: string;
   custom_edit_url?: string | null;
   parse_number_prefixes?: boolean;
@@ -142,11 +79,11 @@ export type DocFrontMatter = {
 export type DocMetadataBase = LastUpdateData & {
   id: string; // TODO legacy versioned id => try to remove
   unversionedId: string; // TODO new unversioned id => try to rename to "id"
-  version: VersionName;
+  version: string;
   title: string;
   description: string;
-  source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
-  sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
+  source: string; // @site aliased posix source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
+  sourceDirName: string; // posix path relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
   slug: string;
   permalink: string;
   sidebarPosition?: number;
@@ -174,6 +111,8 @@ export type CategoryGeneratedIndexMetadata = {
   sidebar: string;
   previous?: DocNavLink;
   next?: DocNavLink;
+  image?: string;
+  keywords?: string | readonly string[];
 };
 
 export type SourceToPermalink = {
@@ -201,26 +140,6 @@ export type LoadedContent = {
   loadedVersions: LoadedVersion[];
 };
 
-export type GlobalDoc = {
-  id: string;
-  path: string;
-  sidebar: string | undefined;
-};
-
-export type GlobalVersion = {
-  name: VersionName;
-  label: string;
-  isLast: boolean;
-  path: string;
-  mainDocId: string; // home doc (if docs homepage configured), or first doc
-  docs: GlobalDoc[];
-};
-
-export type GlobalPluginData = {
-  path: string;
-  versions: GlobalVersion[];
-};
-
 export type BrokenMarkdownLink = IBrokenMarkdownLink<VersionMetadata>;
 
 export type DocsMarkdownOption = {
@@ -229,8 +148,3 @@ export type DocsMarkdownOption = {
   sourceToPermalink: SourceToPermalink;
   onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void;
 };
-
-export type NumberPrefixParser = (filename: string) => {
-  filename: string;
-  numberPrefix?: number;
-};

package/src/versions.ts

@@ -7,19 +7,19 @@
 
 import path from 'path';
 import fs from 'fs-extra';
-import type {
-  PluginOptions,
-  VersionBanner,
-  VersionMetadata,
-  VersionOptions,
-  VersionsOptions,
-} from './types';
+import type {VersionMetadata} from './types';
 import {
   VERSIONS_JSON_FILE,
   VERSIONED_DOCS_DIR,
   VERSIONED_SIDEBARS_DIR,
   CURRENT_VERSION_NAME,
 } from './constants';
+import type {
+  PluginOptions,
+  VersionBanner,
+  VersionOptions,
+  VersionsOptions,
+} from '@docusaurus/plugin-content-docs';
 
 import type {LoadContext} from '@docusaurus/types';
 import {
@@ -87,11 +87,13 @@ function ensureValidVersionArray(
   versionArray.forEach(ensureValidVersionString);
 }
 
-// TODO not easy to make async due to many deps
-function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
+async function readVersionsFile(
+  siteDir: string,
+  pluginId: string,
+): Promise<string[] | null> {
   const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
-  if (fs.existsSync(versionsFilePath)) {
-    const content = JSON.parse(fs.readFileSync(versionsFilePath, 'utf8'));
+  if (await fs.pathExists(versionsFilePath)) {
+    const content = JSON.parse(await fs.readFile(versionsFilePath, 'utf8'));
     ensureValidVersionArray(content);
     return content;
   } else {
@@ -99,27 +101,26 @@ function readVersionsFile(siteDir: string, pluginId: string): string[] | null {
   }
 }
 
-// TODO not easy to make async due to many deps
-function readVersionNames(
+async function readVersionNames(
   siteDir: string,
   options: Pick<
     PluginOptions,
     'id' | 'disableVersioning' | 'includeCurrentVersion'
   >,
-): string[] {
-  const versionFileContent = readVersionsFile(siteDir, options.id);
+): Promise<string[]> {
+  const versionFileContent = await readVersionsFile(siteDir, options.id);
 
   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.`,
     );
   }
 
   const versions = options.disableVersioning ? [] : versionFileContent ?? [];
 
-  // We add the current version at the beginning, unless
-  // - user don't want to
-  // - it's been explicitly added to versions.json
+  // We add the current version at the beginning, unless:
+  // - user don't want to; or
+  // - it's already been explicitly added to versions.json
   if (
     options.includeCurrentVersion &&
     !versions.includes(CURRENT_VERSION_NAME)
@@ -129,7 +130,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}".`,
     );
   }
 
@@ -174,13 +175,6 @@ function getVersionMetadataPaths({
 > {
   const isCurrentVersion = versionName === CURRENT_VERSION_NAME;
 
-  const contentPath = isCurrentVersion
-    ? path.resolve(context.siteDir, options.path)
-    : path.join(
-        getVersionedDocsDirPath(context.siteDir, options.id),
-        `version-${versionName}`,
-      );
-
   const contentPathLocalized = getDocsDirPathLocalized({
     siteDir: context.siteDir,
     locale: context.i18n.currentLocale,
@@ -188,21 +182,27 @@ function getVersionMetadataPaths({
     versionName,
   });
 
-  function getSidebarFilePath() {
-    if (isCurrentVersion) {
-      return resolveSidebarPathOption(context.siteDir, options.sidebarPath);
-    } else {
-      return path.join(
-        getVersionedSidebarsDirPath(context.siteDir, options.id),
-        `version-${versionName}-sidebars.json`,
-      );
-    }
+  if (isCurrentVersion) {
+    return {
+      contentPath: path.resolve(context.siteDir, options.path),
+      contentPathLocalized,
+      sidebarFilePath: resolveSidebarPathOption(
+        context.siteDir,
+        options.sidebarPath,
+      ),
+    };
   }
 
   return {
-    contentPath,
+    contentPath: path.join(
+      getVersionedDocsDirPath(context.siteDir, options.id),
+      `version-${versionName}`,
+    ),
     contentPathLocalized,
-    sidebarFilePath: getSidebarFilePath(),
+    sidebarFilePath: path.join(
+      getVersionedSidebarsDirPath(context.siteDir, options.id),
+      `version-${versionName}-sidebars.json`,
+    ),
   };
 }
 
@@ -459,7 +459,7 @@ function checkVersionMetadataPaths({
 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`);
+- undefined: for Docusaurus to generate it automatically`);
   }
 }
 
@@ -488,7 +488,7 @@ function checkVersionsOptions(
     !availableVersionNames.includes(options.lastVersion)
   ) {
     throw new Error(
-      `Docs option lastVersion=${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
+      `Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`,
     );
   }
   const unknownVersionConfigNames = difference(
@@ -531,9 +531,11 @@ function checkVersionsOptions(
   }
 }
 
-// Filter versions according to provided options
-// Note: we preserve the order in which versions are provided
-// the order of the onlyIncludeVersions array does not matter
+/**
+ * Filter versions according to provided options.
+ * Note: we preserve the order in which versions are provided;
+ * the order of the onlyIncludeVersions array does not matter
+ */
 function filterVersions(
   versionNamesUnfiltered: string[],
   options: Pick<PluginOptions, 'onlyIncludeVersions'>,
@@ -547,8 +549,7 @@ function filterVersions(
   }
 }
 
-// TODO make this async (requires plugin init to be async)
-export function readVersionsMetadata({
+export async function readVersionsMetadata({
   context,
   options,
 }: {
@@ -568,8 +569,11 @@ export function readVersionsMetadata({
     | 'editUrl'
     | 'editCurrentVersion'
   >;
-}): VersionMetadata[] {
-  const versionNamesUnfiltered = readVersionNames(context.siteDir, options);
+}): Promise<VersionMetadata[]> {
+  const versionNamesUnfiltered = await readVersionNames(
+    context.siteDir,
+    options,
+  );
 
   checkVersionsOptions(versionNamesUnfiltered, options);