@docusaurus/plugin-content-docs 0.0.0-4710 → 0.0.0-4713

package/lib/docs.d.ts

@@ -30,22 +30,11 @@ export declare function getMainDocId({ docs, sidebarsUtils, }: {
     sidebarsUtils: SidebarsUtils;
 }): string;
 export declare const isCategoryIndex: CategoryIndexMatcher;
-export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
 /**
  * `guides/sidebar/autogenerated.md` ->
  *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
-export declare function splitPath(str: string): {
-    /**
-     * The list of directories, from lowest level to highest.
-     * If there's no dir name, directories is ['.']
-     */
-    directories: string[];
-    /** The file name, without extension */
-    fileName: string;
-    /** The extension, with a leading dot */
-    extension: string;
-};
+export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
 export declare function getDocIds(doc: DocMetadataBase): [string, string];
 export declare function createDocsByIdIndex<Doc extends {
     id: string;

package/lib/docs.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDocsByIdIndex = exports.getDocIds = exports.splitPath = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+exports.createDocsByIdIndex = exports.getDocIds = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = 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"));
@@ -248,6 +248,10 @@ const isCategoryIndex = ({ fileName, directories, }) => {
     return eligibleDocIndexNames.includes(fileName.toLowerCase());
 };
 exports.isCategoryIndex = isCategoryIndex;
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
 function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
     // source + sourceDirName are always posix-style
     return {
@@ -257,18 +261,6 @@ function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
     };
 }
 exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
-/**
- * `guides/sidebar/autogenerated.md` ->
- *   `'autogenerated', '.md', ['sidebar', 'guides']`
- */
-function splitPath(str) {
-    return {
-        fileName: path_1.default.parse(str).name,
-        extension: path_1.default.parse(str).ext,
-        directories: path_1.default.dirname(str).split(path_1.default.sep).reverse(),
-    };
-}
-exports.splitPath = splitPath;
 // Return both doc ids
 // TODO legacy retro-compatibility due to old versioned sidebars using
 // versioned doc ids ("id" should be removed & "versionedId" should be renamed

package/lib/globalData.d.ts

@@ -4,10 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { Sidebars } from './sidebars/types';
-import type { CategoryGeneratedIndexMetadata, DocMetadata, LoadedVersion } from './types';
-import type { GlobalVersion, GlobalSidebar, GlobalDoc } from '@docusaurus/plugin-content-docs/client';
-export declare function toGlobalDataDoc(doc: DocMetadata): GlobalDoc;
-export declare function toGlobalDataGeneratedIndex(doc: CategoryGeneratedIndexMetadata): GlobalDoc;
-export declare function toGlobalSidebars(sidebars: Sidebars, version: LoadedVersion): Record<string, GlobalSidebar>;
+import type { LoadedVersion } from './types';
+import type { GlobalVersion } from '@docusaurus/plugin-content-docs/client';
 export declare function toGlobalDataVersion(version: LoadedVersion): GlobalVersion;

package/lib/globalData.js

@@ -6,11 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toGlobalDataVersion = exports.toGlobalSidebars = exports.toGlobalDataGeneratedIndex = exports.toGlobalDataDoc = void 0;
+exports.toGlobalDataVersion = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
-const utils_1 = require("@docusaurus/utils");
-const utils_2 = require("./sidebars/utils");
+const utils_1 = require("./sidebars/utils");
 function toGlobalDataDoc(doc) {
     return {
         id: doc.unversionedId,
@@ -18,7 +17,6 @@ function toGlobalDataDoc(doc) {
         sidebar: doc.sidebar,
     };
 }
-exports.toGlobalDataDoc = toGlobalDataDoc;
 function toGlobalDataGeneratedIndex(doc) {
     return {
         id: doc.slug,
@@ -26,9 +24,8 @@ function toGlobalDataGeneratedIndex(doc) {
         sidebar: doc.sidebar,
     };
 }
-exports.toGlobalDataGeneratedIndex = toGlobalDataGeneratedIndex;
 function toGlobalSidebars(sidebars, version) {
-    const { getFirstLink } = (0, utils_2.createSidebarsUtils)(sidebars);
+    const { getFirstLink } = (0, utils_1.createSidebarsUtils)(sidebars);
     return lodash_1.default.mapValues(sidebars, (sidebar, sidebarId) => {
         const firstLink = getFirstLink(sidebarId);
         if (!firstLink) {
@@ -37,14 +34,13 @@ function toGlobalSidebars(sidebars, version) {
         return {
             link: {
                 path: firstLink.type === 'generated-index'
-                    ? (0, utils_1.normalizeUrl)([version.versionPath, firstLink.slug])
+                    ? firstLink.permalink
                     : version.docs.find((doc) => doc.id === firstLink.id || doc.unversionedId === firstLink.id).permalink,
                 label: firstLink.label,
             },
         };
     });
 }
-exports.toGlobalSidebars = toGlobalSidebars;
 function toGlobalDataVersion(version) {
     return {
         name: version.versionName,

package/lib/sidebars/utils.d.ts

@@ -27,13 +27,18 @@ export declare type SidebarsUtils = {
     getDocNavigation: (unversionedId: string, versionedId: string, displayedSidebar: string | null | undefined) => SidebarNavigation;
     getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
     getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
+    /**
+     * This function may return undefined. This is usually a user mistake, because
+     * it means this sidebar will never be displayed; however, we can still use
+     * `displayed_sidebar` to make it displayed. Pretty weird but valid use-case
+     */
     getFirstLink: (sidebarId: string) => {
         type: 'doc';
         id: string;
         label: string;
     } | {
         type: 'generated-index';
-        slug: string;
+        permalink: string;
         label: string;
     } | undefined;
     checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;

package/lib/sidebars/utils.js

@@ -196,7 +196,7 @@ Available document ids are:
                 else if (item.link?.type === 'generated-index') {
                     return {
                         type: 'generated-index',
-                        slug: item.link.slug,
+                        permalink: item.link.permalink,
                         label: item.label,
                     };
                 }

package/lib/slug.js

@@ -33,12 +33,11 @@ function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumbe
     }
     function ensureValidSlug(slug) {
         if (!(0, utils_1.isValidPathname)(slug)) {
-            throw new Error(`We couldn't compute a valid slug for document with id "${baseID}" in "${sourceDirName}" directory.
+            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 front matter is incorrect or you use weird chars in the file path?
-By using the slug front matter, you should be able to fix this error, by using the slug of your choice:
+Maybe your slug front matter is incorrect or there are special characters in the file path?
+By using front matter to set a custom slug, you should be able to fix this error:
 
-Example =>
 ---
 slug: /my/customDocPath
 ---

package/lib/translations.js

@@ -195,10 +195,7 @@ function getVersionTranslationFiles(version) {
     ];
 }
 function translateVersion(version, translationFiles) {
-    const versionTranslations = translationFiles[getVersionFileName(version.versionName)]?.content;
-    if (!versionTranslations) {
-        return version;
-    }
+    const versionTranslations = translationFiles[getVersionFileName(version.versionName)].content;
     return {
         ...version,
         versionLabel: versionTranslations['version.label']?.message ?? version.versionLabel,

package/lib/versions.js

@@ -42,8 +42,8 @@ function ensureValidVersionString(version) {
     }
 }
 function ensureValidVersionArray(versionArray) {
-    if (!(versionArray instanceof Array)) {
-        throw new Error(`The versions file should contain an array of versions! Found content: ${JSON.stringify(versionArray)}`);
+    if (!Array.isArray(versionArray)) {
+        throw new Error(`The versions file should contain an array of version names! Found content: ${JSON.stringify(versionArray)}`);
     }
     versionArray.forEach(ensureValidVersionString);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4710",
+  "version": "0.0.0-4713",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4710",
-    "@docusaurus/logger": "0.0.0-4710",
-    "@docusaurus/mdx-loader": "0.0.0-4710",
-    "@docusaurus/utils": "0.0.0-4710",
-    "@docusaurus/utils-validation": "0.0.0-4710",
+    "@docusaurus/core": "0.0.0-4713",
+    "@docusaurus/logger": "0.0.0-4713",
+    "@docusaurus/mdx-loader": "0.0.0-4713",
+    "@docusaurus/utils": "0.0.0-4713",
+    "@docusaurus/utils-validation": "0.0.0-4713",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.1",
     "import-fresh": "^3.3.0",
@@ -39,8 +39,8 @@
     "webpack": "^5.70.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4710",
-    "@docusaurus/types": "0.0.0-4710",
+    "@docusaurus/module-type-aliases": "0.0.0-4713",
+    "@docusaurus/types": "0.0.0-4713",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -56,5 +56,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "b87b7d90b4b0f155d034b52406c2056ea1dced54"
+  "gitHead": "43c65e82adb2329758821232b7157fceb9830980"
 }

package/src/docFrontMatter.ts

@@ -25,7 +25,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   hide_table_of_contents: Joi.boolean(),
   keywords: Joi.array().items(Joi.string().required()),
   image: URISchema,
-  description: Joi.string().allow(''), // see  https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  description: Joi.string().allow(''), // see https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   slug: Joi.string(),
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),

package/src/docs.ts

@@ -391,6 +391,10 @@ export const isCategoryIndex: CategoryIndexMatcher = ({
   return eligibleDocIndexNames.includes(fileName.toLowerCase());
 };
 
+/**
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
+ */
 export function toCategoryIndexMatcherParam({
   source,
   sourceDirName,
@@ -406,28 +410,6 @@ export function toCategoryIndexMatcherParam({
   };
 }
 
-/**
- * `guides/sidebar/autogenerated.md` ->
- *   `'autogenerated', '.md', ['sidebar', 'guides']`
- */
-export function splitPath(str: string): {
-  /**
-   * The list of directories, from lowest level to highest.
-   * If there's no dir name, directories is ['.']
-   */
-  directories: string[];
-  /** The file name, without extension */
-  fileName: string;
-  /** The extension, with a leading dot */
-  extension: string;
-} {
-  return {
-    fileName: path.parse(str).name,
-    extension: path.parse(str).ext,
-    directories: path.dirname(str).split(path.sep).reverse(),
-  };
-}
-
 // Return both doc ids
 // TODO legacy retro-compatibility due to old versioned sidebars using
 // versioned doc ids ("id" should be removed & "versionedId" should be renamed

package/src/globalData.ts

@@ -6,7 +6,6 @@
  */
 
 import _ from 'lodash';
-import {normalizeUrl} from '@docusaurus/utils';
 import type {Sidebars} from './sidebars/types';
 import {createSidebarsUtils} from './sidebars/utils';
 import type {
@@ -20,7 +19,7 @@ import type {
   GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
 
-export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
+function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
     id: doc.unversionedId,
     path: doc.permalink,
@@ -28,7 +27,7 @@ export function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   };
 }
 
-export function toGlobalDataGeneratedIndex(
+function toGlobalDataGeneratedIndex(
   doc: CategoryGeneratedIndexMetadata,
 ): GlobalDoc {
   return {
@@ -38,7 +37,7 @@ export function toGlobalDataGeneratedIndex(
   };
 }
 
-export function toGlobalSidebars(
+function toGlobalSidebars(
   sidebars: Sidebars,
   version: LoadedVersion,
 ): Record<string, GlobalSidebar> {
@@ -52,7 +51,7 @@ export function toGlobalSidebars(
       link: {
         path:
           firstLink.type === 'generated-index'
-            ? normalizeUrl([version.versionPath, firstLink.slug])
+            ? firstLink.permalink
             : version.docs.find(
                 (doc) =>
                   doc.id === firstLink.id || doc.unversionedId === firstLink.id,

package/src/plugin-content-docs.d.ts

@@ -18,8 +18,14 @@ declare module '@docusaurus/plugin-content-docs' {
   };
 
   export type CategoryIndexMatcherParam = {
+    /** The file name, without extension */
     fileName: string;
+    /**
+     * The list of directories, from lowest level to highest.
+     * If there's no dir name, directories is ['.']
+     */
     directories: string[];
+    /** The extension, with a leading dot */
     extension: string;
   };
   export type CategoryIndexMatcher = (

package/src/sidebars/utils.ts

@@ -139,6 +139,11 @@ export type SidebarsUtils = {
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
   ) => SidebarNavigation;
+  /**
+   * This function may return undefined. This is usually a user mistake, because
+   * it means this sidebar will never be displayed; however, we can still use
+   * `displayed_sidebar` to make it displayed. Pretty weird but valid use-case
+   */
   getFirstLink: (sidebarId: string) =>
     | {
         type: 'doc';
@@ -147,7 +152,7 @@ export type SidebarsUtils = {
       }
     | {
         type: 'generated-index';
-        slug: string;
+        permalink: string;
         label: string;
       }
     | undefined;
@@ -295,7 +300,7 @@ Available document ids are:
       }
     | {
         type: 'generated-index';
-        slug: string;
+        permalink: string;
         label: string;
       }
     | undefined {
@@ -316,7 +321,7 @@ Available document ids are:
         } else if (item.link?.type === 'generated-index') {
           return {
             type: 'generated-index',
-            slug: item.link.slug,
+            permalink: item.link.permalink,
             label: item.label,
           };
         }

package/src/slug.ts

@@ -63,12 +63,11 @@ export default function getSlug({
   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.
+        `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 front matter is incorrect or you use weird chars in the file path?
-By using the slug front matter, you should be able to fix this error, by using the slug of your choice:
+Maybe your slug front matter is incorrect or there are special characters in the file path?
+By using front matter to set a custom slug, you should be able to fix this error:
 
-Example =>
 ---
 slug: /my/customDocPath
 ---

package/src/translations.ts

@@ -274,10 +274,7 @@ function translateVersion(
   translationFiles: Record<string, TranslationFile>,
 ): LoadedVersion {
   const versionTranslations =
-    translationFiles[getVersionFileName(version.versionName)]?.content;
-  if (!versionTranslations) {
-    return version;
-  }
+    translationFiles[getVersionFileName(version.versionName)]!.content;
   return {
     ...version,
     versionLabel:

package/src/versions.ts

@@ -74,9 +74,9 @@ function ensureValidVersionString(version: unknown): asserts version is string {
 function ensureValidVersionArray(
   versionArray: unknown,
 ): asserts versionArray is string[] {
-  if (!(versionArray instanceof Array)) {
+  if (!Array.isArray(versionArray)) {
     throw new Error(
-      `The versions file should contain an array of versions! Found content: ${JSON.stringify(
+      `The versions file should contain an array of version names! Found content: ${JSON.stringify(
         versionArray,
       )}`,
     );