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

package/src/__tests__/versions.test.ts

@@ -13,9 +13,9 @@ import {
   readVersionsMetadata,
 } from '../versions';
 import {DEFAULT_OPTIONS} from '../options';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import {PluginOptions, VersionMetadata} from '../types';
-import {I18n} from '@docusaurus/types';
+import type {I18n} from '@docusaurus/types';
 
 const DefaultI18N: I18n = {
   currentLocale: 'en',
@@ -77,10 +77,13 @@ describe('simple site', () => {
       isLast: true,
       routePriority: -1,
       sidebarFilePath: undefined,
+      tagsPath: '/docs/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/docs',
-      versionBanner: 'none',
+      versionBanner: null,
+      versionBadge: false,
+      versionClassName: 'docs-version-current',
     };
     return {simpleSiteDir, defaultOptions, defaultContext, vCurrent};
   }
@@ -111,6 +114,7 @@ describe('simple site', () => {
       {
         ...vCurrent,
         versionPath: '/myBaseUrl/docs',
+        tagsPath: '/myBaseUrl/docs/tags',
       },
     ]);
   });
@@ -141,6 +145,7 @@ describe('simple site', () => {
         versionLabel: 'current-label',
         routePriority: undefined,
         sidebarFilePath: undefined,
+        tagsPath: '/myBaseUrl/docs/current-path/tags',
         versionEditUrl: undefined,
         versionEditUrlLocalized: undefined,
       },
@@ -232,10 +237,13 @@ describe('versioned site, pluginId=default', () => {
       isLast: false,
       routePriority: undefined,
       sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
+      tagsPath: '/docs/next/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/docs/next',
       versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v101: VersionMetadata = {
@@ -250,10 +258,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-1.0.1-sidebars.json',
       ),
+      tagsPath: '/docs/tags',
       versionLabel: '1.0.1',
       versionName: '1.0.1',
       versionPath: '/docs',
-      versionBanner: 'none',
+      versionBanner: null,
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.1',
     };
 
     const v100: VersionMetadata = {
@@ -268,10 +279,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-1.0.0-sidebars.json',
       ),
+      tagsPath: '/docs/1.0.0/tags',
       versionLabel: '1.0.0',
       versionName: '1.0.0',
       versionPath: '/docs/1.0.0',
       versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     const vwithSlugs: VersionMetadata = {
@@ -289,10 +303,13 @@ describe('versioned site, pluginId=default', () => {
         versionedSiteDir,
         'versioned_sidebars/version-withSlugs-sidebars.json',
       ),
+      tagsPath: '/docs/withSlugs/tags',
       versionLabel: 'withSlugs',
       versionName: 'withSlugs',
       versionPath: '/docs/withSlugs',
       versionBanner: 'unmaintained',
+      versionBadge: true,
+      versionClassName: 'docs-version-withSlugs',
     };
 
     return {
@@ -307,14 +324,8 @@ describe('versioned site, pluginId=default', () => {
   }
 
   test('readVersionsMetadata versioned site', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: defaultOptions,
@@ -325,13 +336,8 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with includeCurrentVersion=false', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {...defaultOptions, includeCurrentVersion: false},
@@ -347,14 +353,8 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with version options', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
@@ -364,6 +364,8 @@ describe('versioned site, pluginId=default', () => {
           current: {
             path: 'current-path',
             banner: 'unmaintained',
+            badge: false,
+            className: 'custom-current-className',
           },
           '1.0.0': {
             label: '1.0.0-label',
@@ -377,13 +379,17 @@ describe('versioned site, pluginId=default', () => {
     expect(versionsMetadata).toEqual([
       {
         ...vCurrent,
+        tagsPath: '/docs/current-path/tags',
         versionPath: '/docs/current-path',
         versionBanner: 'unmaintained',
+        versionBadge: false,
+        versionClassName: 'custom-current-className',
       },
       {
         ...v101,
         isLast: false,
         routePriority: undefined,
+        tagsPath: '/docs/1.0.1/tags',
         versionPath: '/docs/1.0.1',
         versionBanner: 'unreleased',
       },
@@ -391,6 +397,7 @@ describe('versioned site, pluginId=default', () => {
         ...v100,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/docs/tags',
         versionLabel: '1.0.0-label',
         versionPath: '/docs',
         versionBanner: 'unreleased',
@@ -400,19 +407,13 @@ describe('versioned site, pluginId=default', () => {
   });
 
   test('readVersionsMetadata versioned site with editUrl', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
         ...defaultOptions,
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
       },
       context: defaultContext,
     });
@@ -421,48 +422,42 @@ describe('versioned site, pluginId=default', () => {
       {
         ...vCurrent,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v101,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-1.0.1',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.1',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.1',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.1',
       },
       {
         ...v100,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-1.0.0',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-1.0.0',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.0',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-1.0.0',
       },
       {
         ...vwithSlugs,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/versioned_docs/version-withSlugs',
+          'https://github.com/facebook/docusaurus/edit/main/website/versioned_docs/version-withSlugs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/version-withSlugs',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/version-withSlugs',
       },
     ]);
   });
 
   test('readVersionsMetadata versioned site with editUrl and editCurrentVersion=true', async () => {
-    const {
-      defaultOptions,
-      defaultContext,
-      vCurrent,
-      v101,
-      v100,
-      vwithSlugs,
-    } = await loadSite();
+    const {defaultOptions, defaultContext, vCurrent, v101, v100, vwithSlugs} =
+      await loadSite();
 
     const versionsMetadata = readVersionsMetadata({
       options: {
         ...defaultOptions,
-        editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/',
+        editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
         editCurrentVersion: true,
       },
       context: defaultContext,
@@ -472,30 +467,30 @@ describe('versioned site, pluginId=default', () => {
       {
         ...vCurrent,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v101,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...v100,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
       {
         ...vwithSlugs,
         versionEditUrl:
-          'https://github.com/facebook/docusaurus/edit/master/website/docs',
+          'https://github.com/facebook/docusaurus/edit/main/website/docs',
         versionEditUrlLocalized:
-          'https://github.com/facebook/docusaurus/edit/master/website/i18n/en/docusaurus-plugin-content-docs/current',
+          'https://github.com/facebook/docusaurus/edit/main/website/i18n/en/docusaurus-plugin-content-docs/current',
       },
     ]);
   });
@@ -528,8 +523,10 @@ describe('versioned site, pluginId=default', () => {
         ...vCurrent,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/docs/tags',
         versionPath: '/docs',
-        versionBanner: 'none',
+        versionBanner: null,
+        versionBadge: false,
       },
     ]);
   });
@@ -603,11 +600,9 @@ describe('versioned site, pluginId=default', () => {
   test('readVersionsMetadata versioned site with invalid versions.json file', async () => {
     const {defaultOptions, defaultContext} = await loadSite();
 
-    const mock = jest.spyOn(JSON, 'parse').mockImplementationOnce(() => {
-      return {
-        invalid: 'json',
-      };
-    });
+    const mock = jest.spyOn(JSON, 'parse').mockImplementationOnce(() => ({
+      invalid: 'json',
+    }));
 
     expect(() => {
       readVersionsMetadata({
@@ -648,10 +643,13 @@ describe('versioned site, pluginId=community', () => {
       isLast: false,
       routePriority: undefined,
       sidebarFilePath: path.join(versionedSiteDir, 'sidebars.json'),
+      tagsPath: '/communityBasePath/next/tags',
       versionLabel: 'Next',
       versionName: 'current',
       versionPath: '/communityBasePath/next',
       versionBanner: 'unreleased',
+      versionBadge: true,
+      versionClassName: 'docs-version-current',
     };
 
     const v100: VersionMetadata = {
@@ -669,10 +667,13 @@ describe('versioned site, pluginId=community', () => {
         versionedSiteDir,
         'community_versioned_sidebars/version-1.0.0-sidebars.json',
       ),
+      tagsPath: '/communityBasePath/tags',
       versionLabel: '1.0.0',
       versionName: '1.0.0',
       versionPath: '/communityBasePath',
-      versionBanner: 'none',
+      versionBanner: null,
+      versionBadge: true,
+      versionClassName: 'docs-version-1.0.0',
     };
 
     return {versionedSiteDir, defaultOptions, defaultContext, vCurrent, v100};
@@ -699,7 +700,7 @@ describe('versioned site, pluginId=community', () => {
 
     expect(versionsMetadata).toEqual([
       // vCurrent removed
-      v100,
+      {...v100, versionBadge: false},
     ]);
   });
 
@@ -716,8 +717,10 @@ describe('versioned site, pluginId=community', () => {
         ...vCurrent,
         isLast: true,
         routePriority: -1,
+        tagsPath: '/communityBasePath/tags',
         versionPath: '/communityBasePath',
-        versionBanner: 'none',
+        versionBanner: null,
+        versionBadge: false,
       },
     ]);
   });

package/src/categoryGeneratedIndex.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 {CategoryGeneratedIndexMetadata, DocMetadataBase} from './types';
+import {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
+import {SidebarsUtils, toNavigationLink} from './sidebars/utils';
+import {createDocsByIdIndex} from './docs';
+
+function getCategoryGeneratedIndexMetadata({
+  category,
+  sidebarsUtils,
+  docsById,
+}: {
+  category: SidebarItemCategoryWithGeneratedIndex;
+  sidebarsUtils: SidebarsUtils;
+  docsById: Record<string, DocMetadataBase>;
+}): CategoryGeneratedIndexMetadata {
+  const {sidebarName, previous, next} =
+    sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+  if (!sidebarName) {
+    throw new Error('unexpected');
+  }
+
+  return {
+    title: category.link.title ?? category.label,
+    description: category.link.description,
+    slug: category.link.slug,
+    permalink: category.link.permalink,
+    sidebar: sidebarName,
+    previous: toNavigationLink(previous, docsById),
+    next: toNavigationLink(next, docsById),
+  };
+}
+
+export function getCategoryGeneratedIndexMetadataList({
+  docs,
+  sidebarsUtils,
+}: {
+  sidebarsUtils: SidebarsUtils;
+  docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[] {
+  const docsById = createDocsByIdIndex(docs);
+
+  const categoryGeneratedIndexItems =
+    sidebarsUtils.getCategoryGeneratedIndexList();
+  return categoryGeneratedIndexItems.map((category) =>
+    getCategoryGeneratedIndexMetadata({
+      category,
+      sidebarsUtils,
+      docsById,
+    }),
+  );
+}

package/src/cli.ts

@@ -12,13 +12,9 @@ import {
 } from './versions';
 import fs from 'fs-extra';
 import path from 'path';
-import {
-  PathOptions,
-  UnprocessedSidebarItem,
-  UnprocessedSidebars,
-} from './types';
-import {loadSidebars, resolveSidebarPathOption} from './sidebars';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/core/lib/constants';
+import type {PathOptions, SidebarOptions} from './types';
+import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 
 function createVersionedSidebarFile({
   siteDir,
@@ -32,41 +28,13 @@ function createVersionedSidebarFile({
   version: string;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  const loadedSidebars = loadSidebars(sidebarPath);
+  // Note: we don't need the sidebars file to be normalized: it's ok to let plugin option changes to impact older, versioned sidebars
+  const sidebars = loadSidebarsFile(sidebarPath);
 
   // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
-  const shouldCreateVersionedSidebarFile =
-    Object.keys(loadedSidebars).length > 0;
+  const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
-    // TODO @slorber: this "version prefix" in versioned sidebars looks like a bad idea to me
-    // TODO try to get rid of it
-    // Transform id in original sidebar to versioned id.
-    const normalizeItem = (
-      item: UnprocessedSidebarItem,
-    ): UnprocessedSidebarItem => {
-      switch (item.type) {
-        case 'category':
-          return {...item, items: item.items.map(normalizeItem)};
-        case 'ref':
-        case 'doc':
-          return {
-            type: item.type,
-            id: `version-${version}/${item.id}`,
-          };
-        default:
-          return item;
-      }
-    };
-
-    const versionedSidebar: UnprocessedSidebars = Object.entries(
-      loadedSidebars,
-    ).reduce((acc: UnprocessedSidebars, [sidebarId, sidebarItems]) => {
-      const newVersionedSidebarId = `version-${version}/${sidebarId}`;
-      acc[newVersionedSidebarId] = sidebarItems.map(normalizeItem);
-      return acc;
-    }, {});
-
     const versionedSidebarsDir = getVersionedSidebarsDirPath(siteDir, pluginId);
     const newSidebarFile = path.join(
       versionedSidebarsDir,
@@ -75,19 +43,18 @@ function createVersionedSidebarFile({
     fs.ensureDirSync(path.dirname(newSidebarFile));
     fs.writeFileSync(
       newSidebarFile,
-      `${JSON.stringify(versionedSidebar, null, 2)}\n`,
+      `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
     );
   }
 }
 
 // Tests depend on non-default export for mocking.
-// eslint-disable-next-line import/prefer-default-export
 export function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,
   pluginId: string,
-  options: PathOptions,
+  options: PathOptions & SidebarOptions,
 ): void {
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]

package/src/client/docsClientUtils.ts

@@ -20,35 +20,23 @@ export type ActivePlugin = {
   pluginData: GlobalPluginData;
 };
 
-export type GetActivePluginOptions = {failfast?: boolean};
+export type GetActivePluginOptions = {failfast?: boolean}; // use fail-fast option if you know for sure one plugin instance is active
 
 // get the data of the plugin that is currently "active"
 // ie the docs of that plugin are currently browsed
 // it is useful to support multiple docs plugin instances
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options: {failfast: true}, // use fail-fast option if you know for sure one plugin instance is active
-): ActivePlugin;
-export function getActivePlugin(
-  allPluginDatas: Record<string, GlobalPluginData>,
-  pathname: string,
-  options?: GetActivePluginOptions,
-): ActivePlugin | undefined;
-
 export function getActivePlugin(
   allPluginDatas: Record<string, GlobalPluginData>,
   pathname: string,
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined {
   const activeEntry = Object.entries(allPluginDatas).find(
-    ([_id, pluginData]) => {
-      return !!matchPath(pathname, {
+    ([_id, pluginData]) =>
+      !!matchPath(pathname, {
         path: pluginData.path,
         exact: false,
         strict: false,
-      });
-    },
+      }),
   );
 
   const activePlugin: ActivePlugin | undefined = activeEntry
@@ -74,9 +62,8 @@ export type ActiveDocContext = {
   alternateDocVersions: Record<string, Doc>;
 };
 
-export const getLatestVersion = (data: GlobalPluginData): Version => {
-  return data.versions.find((version) => version.isLast)!;
-};
+export const getLatestVersion = (data: GlobalPluginData): Version =>
+  data.versions.find((version) => version.isLast)!;
 
 // Note: return undefined on doc-unrelated pages,
 // because there's no version currently considered as active
@@ -91,13 +78,14 @@ export const getActiveVersion = (
     ...data.versions.filter((version) => version !== lastVersion),
     lastVersion,
   ];
-  return orderedVersionsMetadata.find((version) => {
-    return !!matchPath(pathname, {
-      path: version.path,
-      exact: false,
-      strict: false,
-    });
-  });
+  return orderedVersionsMetadata.find(
+    (version) =>
+      !!matchPath(pathname, {
+        path: version.path,
+        exact: false,
+        strict: false,
+      }),
+  );
 };
 
 export const getActiveDocContext = (

package/src/docFrontMatter.ts

@@ -5,17 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable camelcase */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for frontmatter
   URISchema,
+  FrontMatterTagsSchema,
+  FrontMatterTOCHeadingLevels,
   validateFrontMatter,
 } from '@docusaurus/utils-validation';
-import {DocFrontMatter} from './types';
+import type {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
+// We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
 const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
@@ -29,9 +29,14 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
+  sidebar_class_name: Joi.string(),
+  tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),
   custom_edit_url: URISchema.allow('', null),
   parse_number_prefixes: Joi.boolean(),
+  pagination_next: Joi.string().allow(null),
+  pagination_prev: Joi.string().allow(null),
+  ...FrontMatterTOCHeadingLevels,
 }).unknown();
 
 export function validateDocFrontMatter(