@docusaurus/plugin-content-docs 2.0.0-beta.18 → 2.0.0-beta.19

package/src/props.ts

@@ -5,13 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {LoadedVersion, VersionTag, DocMetadata} from './types';
+import type {VersionTag} from './types';
 import type {
   SidebarItemDoc,
   SidebarItem,
   SidebarItemCategory,
   SidebarItemCategoryLink,
-  PropVersionDocs,
 } from './sidebars/types';
 import type {
   PropSidebars,
@@ -21,6 +20,9 @@ import type {
   PropTagDocList,
   PropTagDocListDoc,
   PropSidebarItemLink,
+  PropVersionDocs,
+  DocMetadata,
+  LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
 import _ from 'lodash';
 import {createDocsByIdIndex} from './docs';
@@ -119,10 +121,10 @@ export function toVersionMetadataProp(
   return {
     pluginId,
     version: loadedVersion.versionName,
-    label: loadedVersion.versionLabel,
-    banner: loadedVersion.versionBanner,
-    badge: loadedVersion.versionBadge,
-    className: loadedVersion.versionClassName,
+    label: loadedVersion.label,
+    banner: loadedVersion.banner,
+    badge: loadedVersion.badge,
+    className: loadedVersion.className,
     isLast: loadedVersion.isLast,
     docsSidebars: toSidebarsProp(loadedVersion),
     docs: toVersionDocsProp(loadedVersion),
@@ -136,7 +138,7 @@ export function toTagDocListProp({
 }: {
   allTagsPath: string;
   tag: VersionTag;
-  docs: Pick<DocMetadata, 'id' | 'title' | 'description' | 'permalink'>[];
+  docs: DocMetadata[];
 }): PropTagDocList {
   function toDocListProp(): PropTagDocListDoc[] {
     const list = _.compact(
@@ -153,9 +155,10 @@ export function toTagDocListProp({
   }
 
   return {
-    name: tag.name,
+    label: tag.label,
     permalink: tag.permalink,
-    docs: toDocListProp(),
     allTagsPath,
+    count: tag.docIds.length,
+    items: toDocListProp(),
   };
 }

package/src/routes.ts

@@ -7,12 +7,11 @@
 
 import type {PluginContentLoadedActions, RouteConfig} from '@docusaurus/types';
 import {docuHash, createSlugger} from '@docusaurus/utils';
+import type {FullVersion} from './types';
 import type {
   CategoryGeneratedIndexMetadata,
   DocMetadata,
-  LoadedVersion,
-} from './types';
-import type {PropCategoryGeneratedIndex} from '@docusaurus/plugin-content-docs';
+} from '@docusaurus/plugin-content-docs';
 import {toVersionMetadataProp} from './props';
 import logger from '@docusaurus/logger';
 
@@ -22,7 +21,7 @@ export async function createCategoryGeneratedIndexRoutes({
   docCategoryGeneratedIndexComponent,
   aliasedSource,
 }: {
-  version: LoadedVersion;
+  version: FullVersion;
   actions: PluginContentLoadedActions;
   docCategoryGeneratedIndexComponent: string;
   aliasedSource: (str: string) => string;
@@ -32,42 +31,19 @@ export async function createCategoryGeneratedIndexRoutes({
   async function createCategoryGeneratedIndexRoute(
     categoryGeneratedIndex: CategoryGeneratedIndexMetadata,
   ): Promise<RouteConfig> {
-    const {
-      sidebar,
-      title,
-      description,
-      slug,
-      permalink,
-      previous,
-      next,
-      image,
-      keywords,
-    } = categoryGeneratedIndex;
+    const {sidebar, ...prop} = categoryGeneratedIndex;
 
     const propFileName = slugs.slug(
-      `${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`,
+      `${version.path}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`,
     );
 
-    const prop: PropCategoryGeneratedIndex = {
-      title,
-      description,
-      slug,
-      permalink,
-      image,
-      keywords,
-      navigation: {
-        previous,
-        next,
-      },
-    };
-
     const propData = await actions.createData(
       `${docuHash(`category/${propFileName}`)}.json`,
       JSON.stringify(prop, null, 2),
     );
 
     return {
-      path: permalink,
+      path: categoryGeneratedIndex.permalink,
       component: docCategoryGeneratedIndexComponent,
       exact: true,
       modules: {
@@ -123,7 +99,7 @@ export async function createDocRoutes({
 }
 
 export async function createVersionRoutes({
-  loadedVersion,
+  version,
   actions,
   docItemComponent,
   docLayoutComponent,
@@ -131,7 +107,7 @@ export async function createVersionRoutes({
   pluginId,
   aliasedSource,
 }: {
-  loadedVersion: LoadedVersion;
+  version: FullVersion;
   actions: PluginContentLoadedActions;
   docLayoutComponent: string;
   docItemComponent: string;
@@ -139,7 +115,7 @@ export async function createVersionRoutes({
   pluginId: string;
   aliasedSource: (str: string) => string;
 }): Promise<void> {
-  async function doCreateVersionRoutes(version: LoadedVersion): Promise<void> {
+  async function doCreateVersionRoutes(): Promise<void> {
     const versionMetadata = toVersionMetadataProp(pluginId, version);
     const versionMetadataPropPath = await actions.createData(
       `${docuHash(`version-${version.versionName}-metadata-prop`)}.json`,
@@ -162,12 +138,10 @@ export async function createVersionRoutes({
     }
 
     actions.addRoute({
-      path: version.versionPath,
-      // allow matching /docs/* as well
+      path: version.path,
+      // Allow matching /docs/* since this is the wrapping route
       exact: false,
-      // main docs component (DocPage)
       component: docLayoutComponent,
-      // sub-routes for each doc
       routes: await createVersionSubRoutes(),
       modules: {
         versionMetadata: aliasedSource(versionMetadataPropPath),
@@ -177,9 +151,9 @@ export async function createVersionRoutes({
   }
 
   try {
-    return await doCreateVersionRoutes(loadedVersion);
+    return await doCreateVersionRoutes();
   } catch (err) {
-    logger.error`Can't create version routes for version name=${loadedVersion.versionName}`;
+    logger.error`Can't create version routes for version name=${version.versionName}`;
     throw err;
   }
 }

package/src/server-export.ts

@@ -18,7 +18,5 @@ export {
   getDefaultVersionBanner,
   getVersionBadge,
   getVersionBanner,
-  getVersionsFilePath,
-  readVersionsFile,
-  readVersionNames,
 } from './versions';
+export {readVersionNames} from './versions/files';

package/src/sidebars/generator.ts

@@ -14,7 +14,7 @@ import type {
   SidebarItemCategoryLinkConfig,
 } from './types';
 import _ from 'lodash';
-import {addTrailingSlash, posixPath} from '@docusaurus/utils';
+import {addTrailingSlash} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
 import path from 'path';
 import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
@@ -76,9 +76,9 @@ Available doc IDs:
       return (
         // Doc at the root of the autogenerated sidebar dir
         doc.sourceDirName === autogenDir ||
-        // autogen dir is . and doc is in subfolder
+        // Autogen dir is . and doc is in subfolder
         autogenDir === '.' ||
-        // autogen dir is not . and doc is in subfolder
+        // Autogen dir is not . and doc is in subfolder
         // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
         doc.sourceDirName.startsWith(addTrailingSlash(autogenDir))
       );
@@ -157,7 +157,7 @@ Available doc IDs:
       folderName: string,
     ): WithPosition<NormalizedSidebarItemCategory> {
       const categoryMetadata =
-        categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
+        categoriesMetadata[path.posix.join(autogenDir, fullPath)];
       const allItems = Object.entries(dir).map(([key, content]) =>
         dirToItem(content, key, `${fullPath}/${key}`),
       );

package/src/sidebars/index.ts

@@ -32,7 +32,6 @@ export const DefaultSidebars: SidebarsConfig = {
 export const DisabledSidebars: SidebarsConfig = {};
 
 // If a path is provided, make it absolute
-// use this before loadSidebars()
 export function resolveSidebarPathOption(
   siteDir: string,
   sidebarPathOption: PluginOptions['sidebarPath'],
@@ -93,7 +92,6 @@ export async function loadSidebarsFileUnsafe(
   return importFresh(sidebarFilePath);
 }
 
-// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 export async function loadSidebars(
   sidebarFilePath: string | false | undefined,
   options: SidebarProcessorParams,

package/src/sidebars/normalization.ts

@@ -65,7 +65,7 @@ function normalizeSidebar(
     throw new Error(
       logger.interpolate`Invalid sidebar items collection code=${JSON.stringify(
         sidebar,
-      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
+      )} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`,
     );
   }
 

package/src/sidebars/postProcessor.ts

@@ -22,11 +22,11 @@ function normalizeCategoryLink(
   params: SidebarProcessorParams,
 ): SidebarItemCategoryLink | undefined {
   if (category.link?.type === 'generated-index') {
-    // default slug logic can be improved
+    // Default slug logic can be improved
     const getDefaultSlug = () =>
       `/category/${params.categoryLabelSlugger.slug(category.label)}`;
     const slug = category.link.slug ?? getDefaultSlug();
-    const permalink = normalizeUrl([params.version.versionPath, slug]);
+    const permalink = normalizeUrl([params.version.path, slug]);
     return {
       ...category.link,
       slug,

package/src/sidebars/processor.ts

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {DocMetadataBase, VersionMetadata} from '../types';
+import type {
+  DocMetadataBase,
+  VersionMetadata,
+} from '@docusaurus/plugin-content-docs';
 import type {
   NormalizedSidebarItem,
   NormalizedSidebar,
@@ -23,7 +26,7 @@ import {DefaultSidebarItemsGenerator} from './generator';
 import {validateSidebars} from './validation';
 import _ from 'lodash';
 import combinePromises from 'combine-promises';
-import {isCategoryIndex} from '../docs';
+import {getDocIds, isCategoryIndex} from '../docs';
 
 function toSidebarItemsGeneratorDoc(
   doc: DocMetadataBase,
@@ -52,7 +55,8 @@ async function processSidebar(
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
   params: SidebarProcessorParams,
 ): Promise<ProcessedSidebar> {
-  const {sidebarItemsGenerator, numberPrefixParser, docs, version} = params;
+  const {sidebarItemsGenerator, numberPrefixParser, docs, drafts, version} =
+    params;
 
   // Just a minor lazy transformation optimization
   const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
@@ -78,6 +82,19 @@ 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[]> {
@@ -85,7 +102,7 @@ async function processSidebar(
       return [
         {
           ...item,
-          items: (await Promise.all(item.items.map(processItem))).flat(),
+          items: await processItems(item.items),
         },
       ];
     }
@@ -98,7 +115,9 @@ async function processSidebar(
   async function processItems(
     items: NormalizedSidebarItem[],
   ): Promise<ProcessedSidebarItem[]> {
-    return (await Promise.all(items.map(processItem))).flat();
+    return (
+      await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))
+    ).flat();
   }
 
   const processedSidebar = await processItems(unprocessedSidebar);

package/src/sidebars/types.ts

@@ -6,11 +6,12 @@
  */
 
 import type {Optional, Required} from 'utility-types';
-import type {DocMetadataBase, VersionMetadata} from '../types';
 import type {
   NumberPrefixParser,
   SidebarOptions,
   CategoryIndexMatcher,
+  DocMetadataBase,
+  VersionMetadata,
 } from '@docusaurus/plugin-content-docs';
 import type {Slugger} from '@docusaurus/utils';
 
@@ -179,7 +180,6 @@ export type PropSidebarItemCategory = Expand<
   }
 >;
 
-// we may want to use a union type in props instead of this generic link?
 export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
@@ -199,16 +199,6 @@ export type PropSidebarBreadcrumbsItem =
   | PropSidebarItemLink
   | PropSidebarItemCategory;
 
-export type PropVersionDoc = {
-  id: string;
-  title: string;
-  description?: string;
-  sidebar?: string;
-};
-export type PropVersionDocs = {
-  [docId: string]: PropVersionDoc;
-};
-
 export type CategoryMetadataFile = {
   label?: string;
   position?: number;
@@ -243,31 +233,42 @@ export type SidebarItemsGeneratorVersion = Pick<
 >;
 
 export type SidebarItemsGeneratorArgs = {
+  /** The sidebar item with type "autogenerated" to be transformed. */
   item: SidebarItemAutogenerated;
+  /** Useful metadata for the version this sidebar belongs to. */
   version: SidebarItemsGeneratorVersion;
+  /** All the docs of that version (unfiltered). */
   docs: SidebarItemsGeneratorDoc[];
+  /** Number prefix parser configured for this plugin. */
   numberPrefixParser: NumberPrefixParser;
+  /** The default category index matcher which you can override. */
   isCategoryIndex: CategoryIndexMatcher;
+  /**
+   * Key is the path relative to the doc content directory, value is the
+   * category metadata file's content.
+   */
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile};
 };
 export type SidebarItemsGenerator = (
   generatorArgs: SidebarItemsGeneratorArgs,
 ) => Promise<NormalizedSidebar>;
 
-// 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,
+  generatorArgs: {
+    /**
+     * Useful to re-use/enhance the default sidebar generation logic from
+     * Docusaurus.
+     * @see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
+     */
+    defaultSidebarItemsGenerator: SidebarItemsGenerator;
+  } & SidebarItemsGeneratorArgs,
 ) => Promise<NormalizedSidebarItem[]>;
 
 export type SidebarProcessorParams = {
   sidebarItemsGenerator: SidebarItemsGeneratorOption;
   numberPrefixParser: NumberPrefixParser;
   docs: DocMetadataBase[];
+  drafts: DocMetadataBase[];
   version: VersionMetadata;
   categoryLabelSlugger: Slugger;
   sidebarOptions: SidebarOptions;

package/src/sidebars/utils.ts

@@ -21,7 +21,10 @@ import type {
 
 import _ from 'lodash';
 import {toMessageRelativeFilePath} from '@docusaurus/utils';
-import type {DocMetadataBase, DocNavLink} from '../types';
+import type {
+  DocMetadataBase,
+  PropNavigationLink,
+} from '@docusaurus/plugin-content-docs';
 
 export function isCategoriesShorthand(
   item: SidebarItemConfig,
@@ -346,7 +349,7 @@ Available document ids are:
   };
 }
 
-export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
+export function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink {
   const {
     title,
     permalink,
@@ -361,7 +364,7 @@ export function toDocNavigationLink(doc: DocMetadataBase): DocNavLink {
 export function toNavigationLink(
   navigationItem: SidebarNavigationItem | undefined,
   docsById: {[docId: string]: DocMetadataBase},
-): DocNavLink | undefined {
+): PropNavigationLink | undefined {
   function getDocById(docId: string) {
     const doc = docsById[docId];
     if (!doc) {

package/src/slug.ts

@@ -15,9 +15,11 @@ import {
   DefaultNumberPrefixParser,
   stripPathNumberPrefixes,
 } from './numberPrefix';
-import type {DocMetadataBase} from './types';
 import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs';
-import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
+import type {
+  NumberPrefixParser,
+  DocMetadataBase,
+} from '@docusaurus/plugin-content-docs';
 
 export default function getSlug({
   baseID,

package/src/tags.ts

@@ -6,13 +6,14 @@
  */
 
 import {groupTaggedItems} from '@docusaurus/utils';
-import type {VersionTags, DocMetadata} from './types';
+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);
   return _.mapValues(groups, (group) => ({
-    name: group.tag.label,
+    label: group.tag.label,
     docIds: group.items.map((item) => item.id),
     permalink: group.tag.permalink,
   }));

package/src/translations.ts

@@ -5,7 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {LoadedVersion, LoadedContent} from './types';
+import type {
+  LoadedVersion,
+  LoadedContent,
+} from '@docusaurus/plugin-content-docs';
 import type {
   Sidebar,
   SidebarItemCategory,
@@ -22,7 +25,6 @@ import {
 import type {
   TranslationFileContent,
   TranslationFile,
-  TranslationFiles,
   TranslationMessage,
 } from '@docusaurus/types';
 import {mergeTranslations} from '@docusaurus/utils';
@@ -54,50 +56,6 @@ function getNormalizedSidebarName({
   return rest.join('/');
 }
 
-/*
-// Do we need to translate doc metadata?
-// It seems translating front matter 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,
@@ -242,10 +200,10 @@ function translateSidebars(
   );
 }
 
-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}`,
     },
   };
@@ -253,17 +211,10 @@ function getVersionTranslationFiles(version: LoadedVersion): TranslationFiles {
   const sidebarsTranslations: TranslationFileContent =
     getSidebarsTranslations(version);
 
-  // const docsTranslations: TranslationFileContent =
-  //   getDocsTranslations(version);
-
   return [
     {
       path: getVersionFileName(version.versionName),
-      content: mergeTranslations([
-        versionTranslations,
-        sidebarsTranslations,
-        // docsTranslations,
-      ]),
+      content: mergeTranslations([versionTranslations, sidebarsTranslations]),
     },
   ];
 }
@@ -275,16 +226,14 @@ function translateVersion(
     translationFiles[getVersionFileName(version.versionName)]!.content;
   return {
     ...version,
-    versionLabel:
-      versionTranslations['version.label']?.message ?? version.versionLabel,
+    label: versionTranslations['version.label']?.message ?? version.label,
     sidebars: translateSidebars(version, versionTranslations),
-    // docs: translateDocs(version.docs, versionTranslations),
   };
 }
 
 function getVersionsTranslationFiles(
   versions: LoadedVersion[],
-): TranslationFiles {
+): TranslationFile[] {
   return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(
@@ -296,7 +245,7 @@ function translateVersions(
 
 export function getLoadedContentTranslationFiles(
   loadedContent: LoadedContent,
-): TranslationFiles {
+): TranslationFile[] {
   return getVersionsTranslationFiles(loadedContent.loadedVersions);
 }
 export function translateLoadedContent(