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

package/src/translations.ts

@@ -5,24 +5,27 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
+import type {
   LoadedVersion,
-  Sidebar,
   LoadedContent,
+} from '@docusaurus/plugin-content-docs';
+import type {
+  Sidebar,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
   Sidebars,
-  SidebarItem,
-} from './types';
+} from './sidebars/types';
 
-import {chain, mapValues, flatten, keyBy} from 'lodash';
+import _ from 'lodash';
 import {
   collectSidebarCategories,
   transformSidebarItems,
   collectSidebarLinks,
-} from './sidebars';
-import {
+} from './sidebars/utils';
+import type {
   TranslationFileContent,
   TranslationFile,
-  TranslationFiles,
+  TranslationMessage,
 } from '@docusaurus/types';
 import {mergeTranslations} from '@docusaurus/utils';
 import {CURRENT_VERSION_NAME} from './constants';
@@ -30,11 +33,10 @@ import {CURRENT_VERSION_NAME} from './constants';
 function getVersionFileName(versionName: string): string {
   if (versionName === CURRENT_VERSION_NAME) {
     return versionName;
-  } else {
-    // I don't like this "version-" prefix,
-    // but it's for consistency with site/versioned_docs
-    return `version-${versionName}`;
   }
+  // I don't like this "version-" prefix,
+  // but it's for consistency with site/versioned_docs
+  return `version-${versionName}`;
 }
 
 // TODO legacy, the sidebar name is like "version-2.0.0-alpha.66/docs"
@@ -54,70 +56,61 @@ function getNormalizedSidebarName({
   return rest.join('/');
 }
 
-/*
-// Do we need to translate doc metadatas?
-// It seems translating frontmatter labels is good enough
-function getDocTranslations(doc: DocMetadata): TranslationFileContent {
-  return {
-    [`${doc.unversionedId}.title`]: {
-      message: doc.title,
-      description: `The title for doc with id=${doc.unversionedId}`,
-    },
-    ...(doc.sidebar_label
-      ? {
-          [`${doc.unversionedId}.sidebar_label`]: {
-            message: doc.sidebar_label,
-            description: `The sidebar label for doc with id=${doc.unversionedId}`,
-          },
-        }
-      : undefined),
-  };
-}
-function translateDoc(
-  doc: DocMetadata,
-  docsTranslations: TranslationFileContent,
-): DocMetadata {
-  return {
-    ...doc,
-    title: docsTranslations[`${doc.unversionedId}.title`]?.message ?? doc.title,
-    sidebar_label:
-      docsTranslations[`${doc.unversionedId}.sidebar_label`]?.message ??
-      doc.sidebar_label,
-  };
-}
-
-function getDocsTranslations(version: LoadedVersion): TranslationFileContent {
-  return mergeTranslations(version.docs.map(getDocTranslations));
-}
-function translateDocs(
-  docs: DocMetadata[],
-  docsTranslations: TranslationFileContent,
-): DocMetadata[] {
-  return docs.map((doc) => translateDoc(doc, docsTranslations));
-}
- */
-
 function getSidebarTranslationFileContent(
   sidebar: Sidebar,
   sidebarName: string,
 ): TranslationFileContent {
+  type TranslationMessageEntry = [string, TranslationMessage];
+
   const categories = collectSidebarCategories(sidebar);
-  const categoryContent: TranslationFileContent = chain(categories)
-    .keyBy((category) => `sidebar.${sidebarName}.category.${category.label}`)
-    .mapValues((category) => ({
-      message: category.label,
-      description: `The label for category ${category.label} in sidebar ${sidebarName}`,
-    }))
-    .value();
+
+  const categoryContent: TranslationFileContent = Object.fromEntries(
+    categories.flatMap((category) => {
+      const entries: TranslationMessageEntry[] = [];
+
+      entries.push([
+        `sidebar.${sidebarName}.category.${category.label}`,
+        {
+          message: category.label,
+          description: `The label for category ${category.label} in sidebar ${sidebarName}`,
+        },
+      ]);
+
+      if (category.link?.type === 'generated-index') {
+        if (category.link.title) {
+          entries.push([
+            `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`,
+            {
+              message: category.link.title,
+              description: `The generated-index page title for category ${category.label} in sidebar ${sidebarName}`,
+            },
+          ]);
+        }
+        if (category.link.description) {
+          entries.push([
+            `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`,
+            {
+              message: category.link.description,
+              description: `The generated-index page description for category ${category.label} in sidebar ${sidebarName}`,
+            },
+          ]);
+        }
+      }
+
+      return entries;
+    }),
+  );
 
   const links = collectSidebarLinks(sidebar);
-  const linksContent: TranslationFileContent = chain(links)
-    .keyBy((link) => `sidebar.${sidebarName}.link.${link.label}`)
-    .mapValues((link) => ({
-      message: link.label,
-      description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
-    }))
-    .value();
+  const linksContent: TranslationFileContent = Object.fromEntries(
+    links.map((link) => [
+      `sidebar.${sidebarName}.link.${link.label}`,
+      {
+        message: link.label,
+        description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
+      },
+    ]),
+  );
 
   return mergeTranslations([categoryContent, linksContent]);
 }
@@ -131,29 +124,51 @@ function translateSidebar({
   sidebarName: string;
   sidebarsTranslations: TranslationFileContent;
 }): Sidebar {
-  return transformSidebarItems(
-    sidebar,
-    (item: SidebarItem): SidebarItem => {
-      if (item.type === 'category') {
-        return {
-          ...item,
-          label:
-            sidebarsTranslations[
-              `sidebar.${sidebarName}.category.${item.label}`
-            ]?.message ?? item.label,
-        };
-      }
-      if (item.type === 'link') {
-        return {
-          ...item,
-          label:
-            sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
-              ?.message ?? item.label,
-        };
-      }
-      return item;
-    },
-  );
+  function transformSidebarCategoryLink(
+    category: SidebarItemCategory,
+  ): SidebarItemCategoryLink | undefined {
+    if (!category.link) {
+      return undefined;
+    }
+    if (category.link.type === 'generated-index') {
+      const title =
+        sidebarsTranslations[
+          `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`
+        ]?.message ?? category.link.title;
+      const description =
+        sidebarsTranslations[
+          `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`
+        ]?.message ?? category.link.description;
+      return {
+        ...category.link,
+        title,
+        description,
+      };
+    }
+    return category.link;
+  }
+
+  return transformSidebarItems(sidebar, (item) => {
+    if (item.type === 'category') {
+      const link = transformSidebarCategoryLink(item);
+      return {
+        ...item,
+        label:
+          sidebarsTranslations[`sidebar.${sidebarName}.category.${item.label}`]
+            ?.message ?? item.label,
+        ...(link && {link}),
+      };
+    }
+    if (item.type === 'link') {
+      return {
+        ...item,
+        label:
+          sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
+            ?.message ?? item.label,
+      };
+    }
+    return item;
+  });
 }
 
 function getSidebarsTranslations(
@@ -173,79 +188,71 @@ function translateSidebars(
   version: LoadedVersion,
   sidebarsTranslations: TranslationFileContent,
 ): Sidebars {
-  return mapValues(version.sidebars, (sidebar, sidebarName) => {
-    return translateSidebar({
+  return _.mapValues(version.sidebars, (sidebar, sidebarName) =>
+    translateSidebar({
       sidebar,
       sidebarName: getNormalizedSidebarName({
         sidebarName,
         versionName: version.versionName,
       }),
       sidebarsTranslations,
-    });
-  });
+    }),
+  );
 }
 
-function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
+function getVersionTranslationFiles(version: LoadedVersion): TranslationFile[] {
   const versionTranslations: TranslationFileContent = {
     'version.label': {
-      message: version.versionLabel,
+      message: version.label,
       description: `The label for version ${version.versionName}`,
     },
   };
 
-  const sidebarsTranslations: TranslationFileContent = getSidebarsTranslations(
-    version,
-  );
-
-  // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
+  const sidebarsTranslations: TranslationFileContent =
+    getSidebarsTranslations(version);
 
   return [
     {
       path: getVersionFileName(version.versionName),
-      content: mergeTranslations([
-        versionTranslations,
-        sidebarsTranslations,
-        // docsTranslations,
-      ]),
+      content: mergeTranslations([versionTranslations, sidebarsTranslations]),
     },
   ];
 }
 function translateVersion(
   version: LoadedVersion,
-  translationFiles: Record<string, TranslationFile>,
+  translationFiles: {[fileName: string]: TranslationFile},
 ): LoadedVersion {
   const versionTranslations =
-    translationFiles[getVersionFileName(version.versionName)].content;
+    translationFiles[getVersionFileName(version.versionName)]!.content;
   return {
     ...version,
-    versionLabel: versionTranslations['version.label']?.message,
+    label: versionTranslations['version.label']?.message ?? version.label,
     sidebars: translateSidebars(version, versionTranslations),
-    // docs: translateDocs(version.docs, versionTranslations),
   };
 }
 
 function getVersionsTranslationFiles(
   versions: LoadedVersion[],
-): TranslationFiles {
-  return flatten(versions.map(getVersionTranslationFiles));
+): TranslationFile[] {
+  return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(
   versions: LoadedVersion[],
-  translationFiles: Record<string, TranslationFile>,
+  translationFiles: {[fileName: string]: TranslationFile},
 ): LoadedVersion[] {
   return versions.map((version) => translateVersion(version, translationFiles));
 }
 
 export function getLoadedContentTranslationFiles(
   loadedContent: LoadedContent,
-): TranslationFiles {
+): TranslationFile[] {
   return getVersionsTranslationFiles(loadedContent.loadedVersions);
 }
 export function translateLoadedContent(
   loadedContent: LoadedContent,
   translationFiles: TranslationFile[],
 ): LoadedContent {
-  const translationFilesMap: Record<string, TranslationFile> = keyBy(
+  const translationFilesMap: {[fileName: string]: TranslationFile} = _.keyBy(
     translationFiles,
     (f) => f.path,
   );

package/src/types.ts

@@ -5,14 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// eslint-disable-next-line spaced-comment
 /// <reference types="@docusaurus/module-type-aliases" />
 
-import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-import {
-  BrokenMarkdownLink as IBrokenMarkdownLink,
-  ContentPaths,
-} from '@docusaurus/utils/lib/markdownLinks';
+import type {BrokenMarkdownLink, Tag} from '@docusaurus/utils';
+import type {
+  VersionMetadata,
+  LastUpdateData,
+  LoadedVersion,
+  CategoryGeneratedIndexMetadata,
+} from '@docusaurus/plugin-content-docs';
+import type {SidebarsUtils} from './sidebars/utils';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -22,259 +24,28 @@ export type DocFile = {
   lastUpdate: LastUpdateData;
 };
 
-export type VersionName = string;
-
-export type VersionMetadata = ContentPaths & {
-  versionName: VersionName; // 1.0.0
-  versionLabel: string; // Version 1.0.0
-  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
-};
-
-export type EditUrlFunction = (editUrlParams: {
-  version: string;
-  versionDocsDirPath: string;
-  docPath: string;
-  permalink: string;
-  locale: string;
-}) => string | undefined;
-
-export type MetadataOptions = {
-  routeBasePath: string;
-  homePageId?: 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 = 'none' | 'unreleased' | 'unmaintained';
-
-export type VersionOptions = {
-  path?: string;
-  label?: string;
-  banner?: VersionBanner;
-};
-
-export type VersionsOptions = {
-  lastVersion?: string;
-  versions: Record<string, VersionOptions>;
-  onlyIncludeVersions?: string[];
-};
-
-export type PluginOptions = MetadataOptions &
-  PathOptions &
-  VersionsOptions &
-  RemarkAndRehypePluginOptions & {
-    id: string;
-    include: string[];
-    docLayoutComponent: string;
-    docItemComponent: string;
-    admonitions: Record<string, unknown>;
-    disableVersioning: boolean;
-    includeCurrentVersion: boolean;
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-  };
-
-export type SidebarItemBase = {
-  customProps?: Record<string, unknown>;
-};
-
-export type SidebarItemDoc = SidebarItemBase & {
-  type: 'doc' | 'ref';
-  label?: string;
-  id: string;
-};
-
-export type SidebarItemLink = SidebarItemBase & {
-  type: 'link';
-  href: string;
-  label: string;
-};
-
-export type SidebarItemCategory = SidebarItemBase & {
-  type: 'category';
-  label: string;
-  items: SidebarItem[];
-  collapsed: boolean;
-};
-
-export type UnprocessedSidebarItemAutogenerated = {
-  type: 'autogenerated';
-  dirName: string;
-};
-
-export type UnprocessedSidebarItemCategory = SidebarItemBase & {
-  type: 'category';
-  label: string;
-  items: UnprocessedSidebarItem[];
-  collapsed: boolean;
-};
-
-export type UnprocessedSidebarItem =
-  | SidebarItemDoc
-  | SidebarItemLink
-  | UnprocessedSidebarItemCategory
-  | UnprocessedSidebarItemAutogenerated;
-
-export type UnprocessedSidebar = UnprocessedSidebarItem[];
-export type UnprocessedSidebars = Record<string, UnprocessedSidebar>;
-
-export type SidebarItem =
-  | SidebarItemDoc
-  | SidebarItemLink
-  | SidebarItemCategory;
-
-export type Sidebar = SidebarItem[];
-export type SidebarItemType = SidebarItem['type'];
-export type Sidebars = Record<string, Sidebar>;
-
-// Reduce API surface for options.sidebarItemsGenerator
-// The user-provided generator fn should receive only a subset of metadatas
-// A change to any of these metadatas can be considered as a breaking change
-export type SidebarItemsGeneratorDoc = Pick<
-  DocMetadataBase,
-  'id' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'
->;
-export type SidebarItemsGeneratorVersion = Pick<
-  VersionMetadata,
-  'versionName' | 'contentPath'
->;
-
-export type SidebarItemsGeneratorArgs = {
-  item: UnprocessedSidebarItemAutogenerated;
-  version: SidebarItemsGeneratorVersion;
-  docs: SidebarItemsGeneratorDoc[];
-  numberPrefixParser: NumberPrefixParser;
-};
-export type SidebarItemsGenerator = (
-  generatorArgs: SidebarItemsGeneratorArgs,
-) => Promise<SidebarItem[]>;
-
-// Also inject the default generator to conveniently wrap/enhance/sort the default sidebar gen logic
-// see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
-export type SidebarItemsGeneratorOptionArgs = {
-  defaultSidebarItemsGenerator: SidebarItemsGenerator;
-} & SidebarItemsGeneratorArgs;
-export type SidebarItemsGeneratorOption = (
-  generatorArgs: SidebarItemsGeneratorOptionArgs,
-) => Promise<SidebarItem[]>;
-
-export type OrderMetadata = {
-  previous?: string;
-  next?: string;
-  sidebar?: string;
-};
-
-export type LastUpdateData = {
-  lastUpdatedAt?: number;
-  formattedLastUpdatedAt?: string;
-  lastUpdatedBy?: string;
-};
-
-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 & {
-  version: VersionName;
-  unversionedId: string;
-  id: string;
-  isDocsHomePage: boolean;
-  title: string;
-  description: string;
-  source: string;
-  sourceDirName: string; // relative to the docs folder (can be ".")
-  slug: string;
-  permalink: string;
-  sidebarPosition?: number;
-  editUrl?: string | null;
-  frontMatter: DocFrontMatter & Record<string, unknown>;
-};
-
-export type DocNavLink = {
-  title: string;
-  permalink: string;
-};
-
-export type DocMetadata = DocMetadataBase & {
-  sidebar?: string;
-  previous?: DocNavLink;
-  next?: DocNavLink;
-};
-
 export type SourceToPermalink = {
   [source: string]: string;
 };
-export type LoadedVersion = VersionMetadata & {
-  versionPath: string;
-  mainDocId: string;
-  docs: DocMetadata[];
-  sidebars: Sidebars;
-  permalinkToSidebar: Record<string, string>;
-};
-
-export type LoadedContent = {
-  loadedVersions: LoadedVersion[];
-};
 
-export type GlobalDoc = {
-  id: string;
-  path: string;
-  sidebar: string | undefined;
+export type VersionTag = Tag & {
+  /** All doc ids having this tag. */
+  docIds: string[];
 };
-
-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 VersionTags = {
+  [permalink: string]: VersionTag;
 };
 
-export type GlobalPluginData = {
-  path: string;
-  versions: GlobalVersion[];
+export type FullVersion = LoadedVersion & {
+  sidebarsUtils: SidebarsUtils;
+  categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
 
-export type BrokenMarkdownLink = IBrokenMarkdownLink<VersionMetadata>;
+export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
 
 export type DocsMarkdownOption = {
   versionsMetadata: VersionMetadata[];
   siteDir: string;
   sourceToPermalink: SourceToPermalink;
-  onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void;
+  onBrokenMarkdownLink: (brokenMarkdownLink: DocBrokenMarkdownLink) => void;
 };
-
-export type NumberPrefixParser = (
-  filename: string,
-) => {filename: string; numberPrefix?: number};