@docusaurus/plugin-content-docs 2.0.0-beta.12faed89d → 2.0.0-beta.14

package/src/slug.ts

@@ -15,39 +15,52 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import {NumberPrefixParser} from './types';
+import type {DocMetadataBase, NumberPrefixParser} from './types';
+import {isConventionalDocIndex} from './docs';
 
 export default function getSlug({
   baseID,
   frontmatterSlug,
-  dirName,
+  source,
+  sourceDirName,
   stripDirNumberPrefixes = true,
   numberPrefixParser = DefaultNumberPrefixParser,
 }: {
   baseID: string;
   frontmatterSlug?: string;
-  dirName: string;
+  source: DocMetadataBase['slug'];
+  sourceDirName: DocMetadataBase['sourceDirName'];
   stripDirNumberPrefixes?: boolean;
   numberPrefixParser?: NumberPrefixParser;
 }): string {
-  const baseSlug = frontmatterSlug || baseID;
-  let slug: string;
-  if (baseSlug.startsWith('/')) {
-    slug = baseSlug;
-  } else {
+  function getDirNameSlug(): string {
     const dirNameStripped = stripDirNumberPrefixes
-      ? stripPathNumberPrefixes(dirName, numberPrefixParser)
-      : dirName;
+      ? stripPathNumberPrefixes(sourceDirName, numberPrefixParser)
+      : sourceDirName;
     const resolveDirname =
-      dirName === '.'
+      sourceDirName === '.'
         ? '/'
         : addLeadingSlash(addTrailingSlash(dirNameStripped));
-    slug = resolvePathname(baseSlug, resolveDirname);
+    return resolveDirname;
   }
 
-  if (!isValidPathname(slug)) {
-    throw new Error(
-      `We couldn't compute a valid slug for document with id "${baseID}" in "${dirName}" directory.
+  function computeSlug(): string {
+    if (frontmatterSlug?.startsWith('/')) {
+      return frontmatterSlug;
+    } else {
+      const dirNameSlug = getDirNameSlug();
+      if (!frontmatterSlug && isConventionalDocIndex({source, sourceDirName})) {
+        return dirNameSlug;
+      }
+      const baseSlug = frontmatterSlug || baseID;
+      return resolvePathname(baseSlug, getDirNameSlug());
+    }
+  }
+
+  function ensureValidSlug(slug: string): string {
+    if (!isValidPathname(slug)) {
+      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:
@@ -57,8 +70,10 @@ Example =>
 slug: /my/customDocPath
 ---
 `,
-    );
+      );
+    }
+    return slug;
   }
 
-  return slug;
+  return ensureValidSlug(computeSlug());
 }

package/src/tags.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {groupTaggedItems} from '@docusaurus/utils';
+import type {VersionTags, DocMetadata} from './types';
+import {mapValues} from 'lodash';
+
+export function getVersionTags(docs: DocMetadata[]): VersionTags {
+  const groups = groupTaggedItems(docs, (doc) => doc.tags);
+  return mapValues(groups, (group) => ({
+    name: group.tag.label,
+    docIds: group.items.map((item) => item.id),
+    permalink: group.tag.permalink,
+  }));
+}

package/src/translations.ts

@@ -5,27 +5,28 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {
-  LoadedVersion,
+import type {LoadedVersion, LoadedContent} from './types';
+import type {
   Sidebar,
-  LoadedContent,
+  SidebarItemCategory,
+  SidebarItemCategoryLink,
   Sidebars,
-  SidebarItem,
-} from './types';
+} from './sidebars/types';
 
-import {chain, mapValues, flatten, keyBy} from 'lodash';
+import {chain, mapValues, keyBy} from 'lodash';
 import {
   collectSidebarCategories,
   transformSidebarItems,
   collectSidebarLinks,
-} from './sidebars';
-import {
+} from './sidebars/utils';
+import type {
   TranslationFileContent,
   TranslationFile,
   TranslationFiles,
 } 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) {
@@ -55,7 +56,7 @@ function getNormalizedSidebarName({
 }
 
 /*
-// Do we need to translate doc metadatas?
+// Do we need to translate doc metadata?
 // It seems translating frontmatter labels is good enough
 function getDocTranslations(doc: DocMetadata): TranslationFileContent {
   return {
@@ -101,14 +102,48 @@ 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) {
+        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)
@@ -131,29 +166,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,16 +230,16 @@ 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 {
@@ -193,9 +250,8 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
     },
   };
 
-  const sidebarsTranslations: TranslationFileContent = getSidebarsTranslations(
-    version,
-  );
+  const sidebarsTranslations: TranslationFileContent =
+    getSidebarsTranslations(version);
 
   // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
 
@@ -227,7 +283,7 @@ function translateVersion(
 function getVersionsTranslationFiles(
   versions: LoadedVersion[],
 ): TranslationFiles {
-  return flatten(versions.map(getVersionTranslationFiles));
+  return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(
   versions: LoadedVersion[],

package/src/types.ts

@@ -5,14 +5,15 @@
  * 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 {
+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';
 
 export type DocFile = {
   contentPath: string; // /!\ may be localized
@@ -28,9 +29,12 @@ export type VersionMetadata = ContentPaths & {
   versionName: VersionName; // 1.0.0
   versionLabel: string; // Version 1.0.0
   versionPath: string; // /baseUrl/docs/1.0.0
+  tagsPath: string;
   versionEditUrl?: string | undefined;
   versionEditUrlLocalized?: string | undefined;
-  versionBanner: VersionBanner;
+  versionBanner: VersionBanner | null;
+  versionBadge: boolean;
+  versionClassName: string;
   isLast: boolean;
   sidebarFilePath: string | false | undefined; // versioned_sidebars/1.0.0.json
   routePriority: number | undefined; // -1 for the latest docs
@@ -46,7 +50,6 @@ export type EditUrlFunction = (editUrlParams: {
 
 export type MetadataOptions = {
   routeBasePath: string;
-  homePageId?: string;
   editUrl?: string | EditUrlFunction;
   editCurrentVersion: boolean;
   editLocalizedFiles: boolean;
@@ -61,12 +64,14 @@ export type PathOptions = {
 };
 
 // TODO support custom version banner? {type: "error", content: "html content"}
-export type VersionBanner = 'none' | 'unreleased' | 'unmaintained';
+export type VersionBanner = 'unreleased' | 'unmaintained';
 
 export type VersionOptions = {
   path?: string;
   label?: string;
-  banner?: VersionBanner;
+  banner?: 'none' | VersionBanner;
+  badge?: boolean;
+  className?: string;
 };
 
 export type VersionsOptions = {
@@ -75,110 +80,36 @@ export type VersionsOptions = {
   onlyIncludeVersions?: string[];
 };
 
+export type SidebarOptions = {
+  sidebarCollapsible: boolean;
+  sidebarCollapsed: boolean;
+};
+
+export type NormalizeSidebarsParams = SidebarOptions & {
+  version: VersionMetadata;
+  categoryLabelSlugger: Slugger;
+};
+
 export type PluginOptions = MetadataOptions &
   PathOptions &
   VersionsOptions &
-  RemarkAndRehypePluginOptions & {
+  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 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;
@@ -187,9 +118,9 @@ export type LastUpdateData = {
 
 export type DocFrontMatter = {
   // Front matter uses snake case
-  /* eslint-disable camelcase */
   id?: string;
   title?: string;
+  tags?: FrontMatterTag[];
   hide_title?: boolean;
   hide_table_of_contents?: boolean;
   keywords?: string[];
@@ -198,25 +129,29 @@ export type DocFrontMatter = {
   slug?: string;
   sidebar_label?: string;
   sidebar_position?: number;
+  sidebar_class_name?: string;
   pagination_label?: string;
   custom_edit_url?: string | null;
   parse_number_prefixes?: boolean;
-  /* eslint-enable camelcase */
+  toc_min_heading_level?: number;
+  toc_max_heading_level?: number;
+  pagination_next?: string | null;
+  pagination_prev?: string | null;
 };
 
 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;
-  unversionedId: string;
-  id: string;
-  isDocsHomePage: boolean;
   title: string;
   description: string;
-  source: string;
-  sourceDirName: string; // relative to the docs folder (can be ".")
+  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"
   slug: string;
   permalink: string;
   sidebarPosition?: number;
   editUrl?: string | null;
+  tags: Tag[];
   frontMatter: DocFrontMatter & Record<string, unknown>;
 };
 
@@ -231,14 +166,35 @@ export type DocMetadata = DocMetadataBase & {
   next?: DocNavLink;
 };
 
+export type CategoryGeneratedIndexMetadata = {
+  title: string;
+  description?: string;
+  slug: string;
+  permalink: string;
+  sidebar: string;
+  previous?: DocNavLink;
+  next?: DocNavLink;
+};
+
 export type SourceToPermalink = {
   [source: string]: string;
 };
+
+export type VersionTag = {
+  name: string; // normalized name/label of the tag
+  docIds: string[]; // all doc ids having this tag
+  permalink: string; // pathname of the tag
+};
+export type VersionTags = {
+  [key: string]: VersionTag;
+};
+
 export type LoadedVersion = VersionMetadata & {
   versionPath: string;
   mainDocId: string;
   docs: DocMetadata[];
   sidebars: Sidebars;
+  categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
 
 export type LoadedContent = {
@@ -274,6 +230,7 @@ export type DocsMarkdownOption = {
   onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void;
 };
 
-export type NumberPrefixParser = (
-  filename: string,
-) => {filename: string; numberPrefix?: number};
+export type NumberPrefixParser = (filename: string) => {
+  filename: string;
+  numberPrefix?: number;
+};