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

package/src/sidebars/normalization.ts

@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {isCategoriesShorthand} from './utils';
 import type {
   NormalizedSidebarItem,
   NormalizedSidebar,
@@ -16,9 +19,6 @@ import type {
   SidebarsConfig,
   NormalizedSidebarItemCategory,
 } from './types';
-import {isCategoriesShorthand} from './utils';
-import _ from 'lodash';
-import logger from '@docusaurus/logger';
 
 function normalizeCategoriesShorthand(
   sidebar: SidebarCategoriesShorthand,

package/src/sidebars/postProcessor.ts

@@ -5,7 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
 import {normalizeUrl} from '@docusaurus/utils';
+import {getDocIds} from '../docs';
 import type {
   SidebarItem,
   Sidebars,
@@ -15,12 +17,18 @@ import type {
   ProcessedSidebars,
   SidebarItemCategoryLink,
 } from './types';
-import _ from 'lodash';
+
+export type SidebarPostProcessorParams = SidebarProcessorParams & {
+  draftIds: Set<string>;
+};
 
 function normalizeCategoryLink(
   category: ProcessedSidebarItemCategory,
-  params: SidebarProcessorParams,
+  params: SidebarPostProcessorParams,
 ): SidebarItemCategoryLink | undefined {
+  if (category.link?.type === 'doc' && params.draftIds.has(category.link.id)) {
+    return undefined;
+  }
   if (category.link?.type === 'generated-index') {
     // Default slug logic can be improved
     const getDefaultSlug = () =>
@@ -38,44 +46,55 @@ function normalizeCategoryLink(
 
 function postProcessSidebarItem(
   item: ProcessedSidebarItem,
-  params: SidebarProcessorParams,
-): SidebarItem {
+  params: SidebarPostProcessorParams,
+): SidebarItem | null {
   if (item.type === 'category') {
+    // Fail-fast if there's actually no subitems, no because all subitems are
+    // drafts. This is likely a configuration mistake.
+    if (item.items.length === 0 && !item.link) {
+      throw new Error(
+        `Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`,
+      );
+    }
     const category = {
       ...item,
       collapsed: item.collapsed ?? params.sidebarOptions.sidebarCollapsed,
       collapsible: item.collapsible ?? params.sidebarOptions.sidebarCollapsible,
       link: normalizeCategoryLink(item, params),
-      items: item.items.map((subItem) =>
-        postProcessSidebarItem(subItem, params),
-      ),
+      items: item.items
+        .map((subItem) => postProcessSidebarItem(subItem, params))
+        .filter((v): v is SidebarItem => Boolean(v)),
     };
     // If the current category doesn't have subitems, we render a normal link
     // instead.
     if (category.items.length === 0) {
-      if (!category.link) {
-        throw new Error(
-          `Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`,
-        );
+      // Doesn't make sense to render an empty generated index page, so we
+      // filter the entire category out as well.
+      if (
+        !category.link ||
+        category.link.type === 'generated-index' ||
+        params.draftIds.has(category.link.id)
+      ) {
+        return null;
       }
-      return category.link.type === 'doc'
-        ? {
-            type: 'doc',
-            label: category.label,
-            id: category.link.id,
-          }
-        : {
-            type: 'link',
-            label: category.label,
-            href: category.link.permalink,
-          };
+      return {
+        type: 'doc',
+        label: category.label,
+        id: category.link.id,
+      };
     }
     // A non-collapsible category can't be collapsed!
-    if (category.collapsible === false) {
+    if (!category.collapsible) {
       category.collapsed = false;
     }
     return category;
   }
+  if (
+    (item.type === 'doc' || item.type === 'ref') &&
+    params.draftIds.has(item.id)
+  ) {
+    return null;
+  }
   return item;
 }
 
@@ -83,7 +102,11 @@ export function postProcessSidebars(
   sidebars: ProcessedSidebars,
   params: SidebarProcessorParams,
 ): Sidebars {
+  const draftIds = new Set(params.drafts.flatMap(getDocIds));
+
   return _.mapValues(sidebars, (sidebar) =>
-    sidebar.map((item) => postProcessSidebarItem(item, params)),
+    sidebar
+      .map((item) => postProcessSidebarItem(item, {...params, draftIds}))
+      .filter((v): v is SidebarItem => Boolean(v)),
   );
 }

package/src/sidebars/processor.ts

@@ -5,6 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
+import combinePromises from 'combine-promises';
+import {DefaultSidebarItemsGenerator} from './generator';
+import {validateSidebars} from './validation';
+import {isCategoryIndex} from '../docs';
 import type {
   DocMetadataBase,
   VersionMetadata,
@@ -22,11 +27,6 @@ import type {
   SidebarProcessorParams,
   CategoryMetadataFile,
 } from './types';
-import {DefaultSidebarItemsGenerator} from './generator';
-import {validateSidebars} from './validation';
-import _ from 'lodash';
-import combinePromises from 'combine-promises';
-import {getDocIds, isCategoryIndex} from '../docs';
 
 function toSidebarItemsGeneratorDoc(
   doc: DocMetadataBase,
@@ -55,8 +55,7 @@ async function processSidebar(
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
   params: SidebarProcessorParams,
 ): Promise<ProcessedSidebar> {
-  const {sidebarItemsGenerator, numberPrefixParser, docs, drafts, version} =
-    params;
+  const {sidebarItemsGenerator, numberPrefixParser, docs, version} = params;
 
   // Just a minor lazy transformation optimization
   const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
@@ -82,19 +81,6 @@ async function processSidebar(
     return processItems(generatedItems);
   }
 
-  const draftIds = new Set(drafts.flatMap(getDocIds));
-
-  const isDraftItem = (item: NormalizedSidebarItem): boolean => {
-    if (item.type === 'doc' || item.type === 'ref') {
-      return draftIds.has(item.id);
-    }
-    // If a category only contains draft items, it should be filtered entirely.
-    if (item.type === 'category') {
-      return item.items.every(isDraftItem);
-    }
-    return false;
-  };
-
   async function processItem(
     item: NormalizedSidebarItem,
   ): Promise<ProcessedSidebarItem[]> {
@@ -102,7 +88,7 @@ async function processSidebar(
       return [
         {
           ...item,
-          items: await processItems(item.items),
+          items: (await Promise.all(item.items.map(processItem))).flat(),
         },
       ];
     }
@@ -115,9 +101,7 @@ async function processSidebar(
   async function processItems(
     items: NormalizedSidebarItem[],
   ): Promise<ProcessedSidebarItem[]> {
-    return (
-      await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))
-    ).flat();
+    return (await Promise.all(items.map(processItem))).flat();
   }
 
   const processedSidebar = await processItems(unprocessedSidebar);

package/src/sidebars/types.ts

@@ -251,7 +251,7 @@ export type SidebarItemsGeneratorArgs = {
 };
 export type SidebarItemsGenerator = (
   generatorArgs: SidebarItemsGeneratorArgs,
-) => Promise<NormalizedSidebar>;
+) => NormalizedSidebar | Promise<NormalizedSidebar>;
 
 export type SidebarItemsGeneratorOption = (
   generatorArgs: {
@@ -262,7 +262,7 @@ export type SidebarItemsGeneratorOption = (
      */
     defaultSidebarItemsGenerator: SidebarItemsGenerator;
   } & SidebarItemsGeneratorArgs,
-) => Promise<NormalizedSidebarItem[]>;
+) => NormalizedSidebar | Promise<NormalizedSidebar>;
 
 export type SidebarProcessorParams = {
   sidebarItemsGenerator: SidebarItemsGeneratorOption;

package/src/sidebars/utils.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
+import {toMessageRelativeFilePath} from '@docusaurus/utils';
 import type {
   Sidebars,
   Sidebar,
@@ -18,9 +20,6 @@ import type {
   SidebarItemCategoryWithGeneratedIndex,
   SidebarNavigationItem,
 } from './types';
-
-import _ from 'lodash';
-import {toMessageRelativeFilePath} from '@docusaurus/utils';
 import type {
   DocMetadataBase,
   PropNavigationLink,
@@ -258,7 +257,7 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     ): boolean {
       return (
         item.type === 'category' &&
-        item.link?.type === 'generated-index' &&
+        item.link.type === 'generated-index' &&
         item.link.permalink === categoryGeneratedIndexPermalink
       );
     }

package/src/sidebars/validation.ts

@@ -144,7 +144,7 @@ function validateSidebarItem(
   // manually
   Joi.assert(item, sidebarItemSchema);
 
-  if ((item as NormalizedSidebarItemCategory).type === 'category') {
+  if ((item as NormalizedSidebarItem).type === 'category') {
     (item as NormalizedSidebarItemCategory).items.forEach(validateSidebarItem);
   }
 }
@@ -170,5 +170,9 @@ const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
 export function validateCategoryMetadataFile(
   unsafeContent: unknown,
 ): CategoryMetadataFile {
-  return Joi.attempt(unsafeContent, categoryMetadataFileSchema);
+  const {error, value} = categoryMetadataFileSchema.validate(unsafeContent);
+  if (error) {
+    throw error;
+  }
+  return value;
 }

package/src/slug.ts

@@ -58,7 +58,7 @@ export default function getSlug({
     ) {
       return dirNameSlug;
     }
-    const baseSlug = frontMatterSlug || baseID;
+    const baseSlug = frontMatterSlug ?? baseID;
     return resolvePathname(baseSlug, getDirNameSlug());
   }
 

package/src/tags.ts

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
 import {groupTaggedItems} from '@docusaurus/utils';
 import type {VersionTags} from './types';
 import type {DocMetadata} from '@docusaurus/plugin-content-docs';
-import _ from 'lodash';
 
 export function getVersionTags(docs: DocMetadata[]): VersionTags {
   const groups = groupTaggedItems(docs, (doc) => doc.tags);

package/src/translations.ts

@@ -5,6 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
+import {mergeTranslations} from '@docusaurus/utils';
+import {CURRENT_VERSION_NAME} from './constants';
+import {
+  collectSidebarCategories,
+  transformSidebarItems,
+  collectSidebarLinks,
+} from './sidebars/utils';
 import type {
   LoadedVersion,
   LoadedContent,
@@ -15,20 +23,11 @@ import type {
   SidebarItemCategoryLink,
   Sidebars,
 } from './sidebars/types';
-
-import _ from 'lodash';
-import {
-  collectSidebarCategories,
-  transformSidebarItems,
-  collectSidebarLinks,
-} from './sidebars/utils';
 import type {
   TranslationFileContent,
   TranslationFile,
   TranslationMessage,
 } from '@docusaurus/types';
-import {mergeTranslations} from '@docusaurus/utils';
-import {CURRENT_VERSION_NAME} from './constants';
 
 function getVersionFileName(versionName: string): string {
   if (versionName === CURRENT_VERSION_NAME) {

package/src/types.ts

@@ -5,8 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/// <reference types="@docusaurus/module-type-aliases" />
-
 import type {BrokenMarkdownLink, Tag} from '@docusaurus/utils';
 import type {
   VersionMetadata,

package/src/versions/files.ts

@@ -7,6 +7,7 @@
 
 import path from 'path';
 import fs from 'fs-extra';
+import {getPluginI18nPath, DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import {
   VERSIONS_JSON_FILE,
   VERSIONED_DOCS_DIR,
@@ -14,7 +15,6 @@ import {
   CURRENT_VERSION_NAME,
 } from '../constants';
 import {validateVersionNames} from './validation';
-import {getPluginI18nPath, DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import type {
   PluginOptions,
   VersionMetadata,
@@ -89,13 +89,13 @@ export function getVersionsFilePath(siteDir: string, pluginId: string): string {
  * @throws Throws if validation fails, i.e. `versions.json` doesn't contain an
  * array of valid version names.
  */
-async function readVersionsFile(
+export async function readVersionsFile(
   siteDir: string,
   pluginId: string,
 ): Promise<string[] | null> {
   const versionsFilePath = getVersionsFilePath(siteDir, pluginId);
   if (await fs.pathExists(versionsFilePath)) {
-    const content = await fs.readJSON(versionsFilePath);
+    const content: unknown = await fs.readJSON(versionsFilePath);
     validateVersionNames(content);
     return content;
   }

package/src/versions/index.ts

@@ -6,8 +6,8 @@
  */
 
 import path from 'path';
-import {CURRENT_VERSION_NAME} from '../constants';
 import {normalizeUrl, posixPath} from '@docusaurus/utils';
+import {CURRENT_VERSION_NAME} from '../constants';
 import {validateVersionsOptions} from './validation';
 import {
   getDocsDirPathLocalized,

package/src/versions/validation.ts

@@ -11,7 +11,9 @@ import type {VersionsOptions} from '@docusaurus/plugin-content-docs';
 export function validateVersionName(name: unknown): asserts name is string {
   if (typeof name !== 'string') {
     throw new Error(
-      `Versions should be strings. Found type "${typeof name}" for version "${name}".`,
+      `Versions should be strings. Found type "${typeof name}" for version ${JSON.stringify(
+        name,
+      )}.`,
     );
   }
   if (!name.trim()) {