@docusaurus/plugin-content-docs 0.0.0-5043 → 0.0.0-5048

package/lib/cli.js

@@ -41,12 +41,7 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
         logger_1.default.info `${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
         throw err;
     }
-    // Load existing versions.
-    let versions = [];
-    const versionsJSONFile = (0, files_1.getVersionsFilePath)(siteDir, pluginId);
-    if (await fs_extra_1.default.pathExists(versionsJSONFile)) {
-        versions = await fs_extra_1.default.readJSON(versionsJSONFile);
-    }
+    const versions = (await (0, files_1.readVersionsFile)(siteDir, pluginId)) ?? [];
     // Check if version already exists.
     if (versions.includes(version)) {
         throw new Error(`${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`);
@@ -92,7 +87,7 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
     });
     // Update versions.json file.
     versions.unshift(version);
-    await fs_extra_1.default.outputFile(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+    await fs_extra_1.default.outputFile((0, files_1.getVersionsFilePath)(siteDir, pluginId), `${JSON.stringify(versions, null, 2)}\n`);
     logger_1.default.success `name=${pluginIdLogPrefix}: version name=${version} created!`;
 }
 exports.cliDocsVersionCommand = cliDocsVersionCommand;

package/lib/client/docsClientUtils.js

@@ -73,6 +73,6 @@ export function getActiveDocContext(data, pathname) {
 export function getDocVersionSuggestions(data, pathname) {
     const latestVersion = getLatestVersion(data);
     const activeDocContext = getActiveDocContext(data, pathname);
-    const latestDocSuggestion = activeDocContext?.alternateDocVersions[latestVersion.name];
+    const latestDocSuggestion = activeDocContext.alternateDocVersions[latestVersion.name];
     return { latestDocSuggestion, latestVersionSuggestion: latestVersion };
 }

package/lib/index.js

@@ -76,7 +76,7 @@ async function pluginContentDocs(context, options) {
                 if (docFiles.length === 0) {
                     throw new Error(`Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${path_1.default.relative(siteDir, versionMetadata.contentPath)}".`);
                 }
-                async function processVersionDoc(docFile) {
+                function processVersionDoc(docFile) {
                     return (0, docs_1.processDocMetadata)({
                         docFile,
                         versionMetadata,

package/lib/markdown/index.js

@@ -11,6 +11,6 @@ function markdownLoader(source) {
     const fileString = source;
     const callback = this.async();
     const options = this.getOptions();
-    return callback?.(null, (0, linkify_1.linkify)(fileString, this.resourcePath, options));
+    return callback(null, (0, linkify_1.linkify)(fileString, this.resourcePath, options));
 }
 exports.default = markdownLoader;

package/lib/props.js

@@ -26,7 +26,7 @@ Available document ids are:
         const { title, permalink, frontMatter: { sidebar_label: sidebarLabel }, } = docMetadata;
         return {
             type: 'link',
-            label: sidebarLabel || item.label || title,
+            label: sidebarLabel ?? item.label ?? title,
             href: permalink,
             className: item.className,
             customProps: item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,

package/lib/sidebars/generator.js

@@ -21,7 +21,7 @@ function getLocalDocId(docId) {
 exports.CategoryMetadataFilenameBase = '_category_';
 exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryIndex, docs: allDocs, item: { dirName: autogenDir }, categoriesMetadata, }) => {
+const DefaultSidebarItemsGenerator = ({ numberPrefixParser, isCategoryIndex, docs: allDocs, item: { dirName: autogenDir }, categoriesMetadata, }) => {
     const docsById = (0, docs_1.createDocsByIdIndex)(allDocs);
     const findDoc = (docId) => docsById[docId];
     const getDoc = (docId) => {

package/lib/sidebars/postProcessor.js

@@ -61,7 +61,7 @@ function postProcessSidebarItem(item, params) {
             };
         }
         // A non-collapsible category can't be collapsed!
-        if (category.collapsible === false) {
+        if (!category.collapsible) {
             category.collapsed = false;
         }
         return category;

package/lib/sidebars/types.d.ts

@@ -157,7 +157,7 @@ export declare type SidebarItemsGeneratorArgs = {
         [filePath: string]: CategoryMetadataFile;
     };
 };
-export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<NormalizedSidebar>;
+export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => NormalizedSidebar | Promise<NormalizedSidebar>;
 export declare type SidebarItemsGeneratorOption = (generatorArgs: {
     /**
      * Useful to re-use/enhance the default sidebar generation logic from
@@ -165,7 +165,7 @@ export declare type SidebarItemsGeneratorOption = (generatorArgs: {
      * @see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
      */
     defaultSidebarItemsGenerator: SidebarItemsGenerator;
-} & SidebarItemsGeneratorArgs) => Promise<NormalizedSidebarItem[]>;
+} & SidebarItemsGeneratorArgs) => NormalizedSidebar | Promise<NormalizedSidebar>;
 export declare type SidebarProcessorParams = {
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
     numberPrefixParser: NumberPrefixParser;

package/lib/sidebars/utils.js

@@ -158,7 +158,7 @@ function createSidebarsUtils(sidebars) {
     function getCategoryGeneratedIndexNavigation(categoryGeneratedIndexPermalink) {
         function isCurrentCategoryGeneratedIndexItem(item) {
             return (item.type === 'category' &&
-                item.link?.type === 'generated-index' &&
+                item.link.type === 'generated-index' &&
                 item.link.permalink === categoryGeneratedIndexPermalink);
         }
         const sidebarName = Object.entries(sidebarNameToNavigationItems).find(([, navigationItems]) => navigationItems.find(isCurrentCategoryGeneratedIndexItem))[0];

package/lib/sidebars/validation.js

@@ -133,6 +133,10 @@ const categoryMetadataFileSchema = utils_validation_1.Joi.object({
     customProps: utils_validation_1.Joi.object().unknown(),
 });
 function validateCategoryMetadataFile(unsafeContent) {
-    return utils_validation_1.Joi.attempt(unsafeContent, categoryMetadataFileSchema);
+    const { error, value } = categoryMetadataFileSchema.validate(unsafeContent);
+    if (error) {
+        throw error;
+    }
+    return value;
 }
 exports.validateCategoryMetadataFile = validateCategoryMetadataFile;

package/lib/slug.js

@@ -28,7 +28,7 @@ function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumbe
             (0, docs_1.isCategoryIndex)((0, docs_1.toCategoryIndexMatcherParam)({ source, sourceDirName }))) {
             return dirNameSlug;
         }
-        const baseSlug = frontMatterSlug || baseID;
+        const baseSlug = frontMatterSlug ?? baseID;
         return (0, utils_1.resolvePathname)(baseSlug, getDirNameSlug());
     }
     function ensureValidSlug(slug) {

package/lib/versions/files.d.ts

@@ -18,6 +18,13 @@ export declare function getDocsDirPathLocalized({ siteDir, locale, pluginId, ver
 }): string;
 /** `community` => `[siteDir]/community_versions.json` */
 export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
+/**
+ * Reads the plugin's respective `versions.json` file, and returns its content.
+ *
+ * @throws Throws if validation fails, i.e. `versions.json` doesn't contain an
+ * array of valid version names.
+ */
+export declare function readVersionsFile(siteDir: string, pluginId: string): Promise<string[] | null>;
 /**
  * Reads the `versions.json` file, and returns an ordered list of version names.
  *

package/lib/versions/files.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVersionMetadataPaths = exports.readVersionNames = exports.getVersionsFilePath = exports.getDocsDirPathLocalized = exports.getVersionSidebarsPath = exports.getVersionDocsDirPath = void 0;
+exports.getVersionMetadataPaths = exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getDocsDirPathLocalized = exports.getVersionSidebarsPath = exports.getVersionDocsDirPath = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
@@ -63,6 +63,7 @@ async function readVersionsFile(siteDir, pluginId) {
     }
     return null;
 }
+exports.readVersionsFile = readVersionsFile;
 /**
  * Reads the `versions.json` file, and returns an ordered list of version names.
  *

package/lib/versions/validation.js

@@ -11,7 +11,7 @@ const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 function validateVersionName(name) {
     if (typeof name !== 'string') {
-        throw new Error(`Versions should be strings. Found type "${typeof name}" for version "${name}".`);
+        throw new Error(`Versions should be strings. Found type "${typeof name}" for version ${JSON.stringify(name)}.`);
     }
     if (!name.trim()) {
         throw new Error(`Invalid version name "${name}": version name must contain at least one non-whitespace character.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-5043",
+  "version": "0.0.0-5048",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -25,11 +25,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5043",
-    "@docusaurus/logger": "0.0.0-5043",
-    "@docusaurus/mdx-loader": "0.0.0-5043",
-    "@docusaurus/utils": "0.0.0-5043",
-    "@docusaurus/utils-validation": "0.0.0-5043",
+    "@docusaurus/core": "0.0.0-5048",
+    "@docusaurus/logger": "0.0.0-5048",
+    "@docusaurus/mdx-loader": "0.0.0-5048",
+    "@docusaurus/utils": "0.0.0-5048",
+    "@docusaurus/utils-validation": "0.0.0-5048",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.1.0",
     "import-fresh": "^3.3.0",
@@ -41,8 +41,8 @@
     "webpack": "^5.72.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-5043",
-    "@docusaurus/types": "0.0.0-5043",
+    "@docusaurus/module-type-aliases": "0.0.0-5048",
+    "@docusaurus/types": "0.0.0-5048",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -58,5 +58,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "28ad11cdb6c55b7a8355e327913f617d4fe359bd"
+  "gitHead": "f5680d2f2633fbd6594972ae1f4c1ddb1467f9ac"
 }

package/src/cli.ts

@@ -14,6 +14,7 @@ import {
   getVersionDocsDirPath,
   getVersionSidebarsPath,
   getDocsDirPathLocalized,
+  readVersionsFile,
 } from './versions/files';
 import {validateVersionName} from './versions/validation';
 import {loadSidebarsFileUnsafe} from './sidebars';
@@ -69,12 +70,7 @@ export async function cliDocsVersionCommand(
     throw err;
   }
 
-  // Load existing versions.
-  let versions: string[] = [];
-  const versionsJSONFile = getVersionsFilePath(siteDir, pluginId);
-  if (await fs.pathExists(versionsJSONFile)) {
-    versions = await fs.readJSON(versionsJSONFile);
-  }
+  const versions = (await readVersionsFile(siteDir, pluginId)) ?? [];
 
   // Check if version already exists.
   if (versions.includes(version)) {
@@ -137,7 +133,7 @@ export async function cliDocsVersionCommand(
   // Update versions.json file.
   versions.unshift(version);
   await fs.outputFile(
-    versionsJSONFile,
+    getVersionsFilePath(siteDir, pluginId),
     `${JSON.stringify(versions, null, 2)}\n`,
   );
 

package/src/client/docsClientUtils.ts

@@ -126,6 +126,6 @@ export function getDocVersionSuggestions(
   const latestVersion = getLatestVersion(data);
   const activeDocContext = getActiveDocContext(data, pathname);
   const latestDocSuggestion: GlobalDoc | undefined =
-    activeDocContext?.alternateDocVersions[latestVersion.name];
+    activeDocContext.alternateDocVersions[latestVersion.name];
   return {latestDocSuggestion, latestVersionSuggestion: latestVersion};
 }

package/src/client/index.ts

@@ -34,9 +34,11 @@ const StableEmptyObject = {};
 // In blog-only mode, docs hooks are still used by the theme. We need a fail-
 // safe fallback when the docs plugin is not in use
 export const useAllDocsData = (): {[pluginId: string]: GlobalPluginData} =>
-  (useAllPluginInstancesData('docusaurus-plugin-content-docs') as {
-    [pluginId: string]: GlobalPluginData;
-  }) ?? StableEmptyObject;
+  (useAllPluginInstancesData('docusaurus-plugin-content-docs') as
+    | {
+        [pluginId: string]: GlobalPluginData;
+      }
+    | undefined) ?? StableEmptyObject;
 
 export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
   usePluginData('docusaurus-plugin-content-docs', pluginId, {

package/src/index.ts

@@ -143,7 +143,7 @@ export default async function pluginContentDocs(
             )}".`,
           );
         }
-        async function processVersionDoc(docFile: DocFile) {
+        function processVersionDoc(docFile: DocFile) {
           return processDocMetadata({
             docFile,
             versionMetadata,

package/src/markdown/index.ts

@@ -16,5 +16,5 @@ export default function markdownLoader(
   const fileString = source;
   const callback = this.async();
   const options = this.getOptions();
-  return callback?.(null, linkify(fileString, this.resourcePath, options));
+  return callback(null, linkify(fileString, this.resourcePath, options));
 }

package/src/options.ts

@@ -165,7 +165,7 @@ export function validateOptions({
     }
   }
 
-  const normalizedOptions = validate(OptionsSchema, options) as PluginOptions;
+  const normalizedOptions = validate(OptionsSchema, options);
 
   if (normalizedOptions.admonitions) {
     normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([

package/src/props.ts

@@ -51,7 +51,7 @@ Available document ids are:
     } = docMetadata;
     return {
       type: 'link',
-      label: sidebarLabel || item.label || title,
+      label: sidebarLabel ?? item.label ?? title,
       href: permalink,
       className: item.className,
       customProps:

package/src/sidebars/generator.ts

@@ -46,7 +46,7 @@ type Dir = {
 };
 
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
+export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = ({
   numberPrefixParser,
   isCategoryIndex,
   docs: allDocs,

package/src/sidebars/postProcessor.ts

@@ -84,7 +84,7 @@ function postProcessSidebarItem(
       };
     }
     // A non-collapsible category can't be collapsed!
-    if (category.collapsible === false) {
+    if (!category.collapsible) {
       category.collapsed = false;
     }
     return category;

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

@@ -257,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/versions/files.ts

@@ -89,7 +89,7 @@ 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> {

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()) {