@docusaurus/plugin-content-docs 0.0.0-4536 → 0.0.0-4542

package/lib/lastUpdate.js

@@ -10,6 +10,7 @@ exports.getFileLastUpdate = void 0;
 const tslib_1 = require("tslib");
 const shelljs_1 = (0, tslib_1.__importDefault)(require("shelljs"));
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(?<timestamp>\d+),(?<author>.+)$/;
 let showedGitRequirementError = false;
 async function getFileLastUpdate(filePath) {
@@ -36,7 +37,13 @@ async function getFileLastUpdate(filePath) {
             }
             return null;
         }
-        const result = shelljs_1.default.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
+        if (!shelljs_1.default.test('-f', filePath)) {
+            throw new Error(`Retrieval of git history failed at "${filePath}" because the file does not exist.`);
+        }
+        const fileBasename = path_1.default.basename(filePath);
+        const fileDirname = path_1.default.dirname(filePath);
+        const result = shelljs_1.default.exec(`git log --max-count=1 --format=%ct,%an -- "${fileBasename}"`, {
+            cwd: fileDirname,
             silent: true,
         });
         if (result.code !== 0) {

package/lib/server/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export * from '../constants';
+export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, getVersionsFilePath, readVersionsFile, readVersionNames, } from '../versions';

package/lib/server/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionBanner = exports.getVersionBadge = exports.getDefaultVersionBanner = exports.filterVersions = void 0;
+const tslib_1 = require("tslib");
+// APIs available to Node.js
+(0, tslib_1.__exportStar)(require("../constants"), exports);
+var versions_1 = require("../versions");
+Object.defineProperty(exports, "filterVersions", { enumerable: true, get: function () { return versions_1.filterVersions; } });
+Object.defineProperty(exports, "getDefaultVersionBanner", { enumerable: true, get: function () { return versions_1.getDefaultVersionBanner; } });
+Object.defineProperty(exports, "getVersionBadge", { enumerable: true, get: function () { return versions_1.getVersionBadge; } });
+Object.defineProperty(exports, "getVersionBanner", { enumerable: true, get: function () { return versions_1.getVersionBanner; } });
+Object.defineProperty(exports, "getVersionsFilePath", { enumerable: true, get: function () { return versions_1.getVersionsFilePath; } });
+Object.defineProperty(exports, "readVersionsFile", { enumerable: true, get: function () { return versions_1.readVersionsFile; } });
+Object.defineProperty(exports, "readVersionNames", { enumerable: true, get: function () { return versions_1.readVersionNames; } });

package/lib/sidebars/processor.js

@@ -61,6 +61,32 @@ async function processSidebar(unprocessedSidebar, params) {
     }
     async function processItem(item) {
         if (item.type === 'category') {
+            // If the current category doesn't have subitems, we render a normal doc link instead.
+            if (item.items.length === 0) {
+                if (!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.`);
+                }
+                switch (item.link.type) {
+                    case 'doc':
+                        return [
+                            {
+                                type: 'doc',
+                                label: item.label,
+                                id: item.link.id,
+                            },
+                        ];
+                    case 'generated-index':
+                        return [
+                            {
+                                type: 'link',
+                                label: item.label,
+                                href: item.link.permalink,
+                            },
+                        ];
+                    default:
+                        throw new Error('Unexpected sidebar category link type');
+                }
+            }
             return [await processCategoryItem(item)];
         }
         if (item.type === 'autogenerated') {

package/lib/sidebars/types.d.ts

@@ -19,6 +19,11 @@ export declare type SidebarItemDoc = SidebarItemBase & {
     label?: string;
     id: string;
 };
+export declare type SidebarItemHtml = SidebarItemBase & {
+    type: 'html';
+    value: string;
+    defaultStyle?: boolean;
+};
 export declare type SidebarItemLink = SidebarItemBase & {
     type: 'link';
     href: string;
@@ -64,7 +69,7 @@ export declare type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCateg
 export declare type SidebarCategoriesShorthand = {
     [sidebarCategory: string]: SidebarItemConfig[];
 };
-export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
+export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
 export declare type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
 export declare type SidebarsConfig = {
     [sidebarId: string]: SidebarConfig;
@@ -73,7 +78,7 @@ export declare type NormalizedSidebarItemCategory = Expand<SidebarItemCategoryBa
     items: NormalizedSidebarItem[];
     link?: SidebarItemCategoryLink;
 }>;
-export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
+export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
 export declare type NormalizedSidebar = NormalizedSidebarItem[];
 export declare type NormalizedSidebars = {
     [sidebarId: string]: NormalizedSidebar;
@@ -86,7 +91,7 @@ export declare type SidebarItemCategoryWithLink = Required<SidebarItemCategory,
 export declare type SidebarItemCategoryWithGeneratedIndex = SidebarItemCategoryWithLink & {
     link: SidebarItemCategoryLinkGeneratedIndex;
 };
-export declare type SidebarItem = SidebarItemDoc | SidebarItemLink | SidebarItemCategory;
+export declare type SidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemCategory;
 export declare type SidebarNavigationItem = SidebarItemDoc | SidebarItemCategoryWithLink;
 export declare type Sidebar = SidebarItem[];
 export declare type SidebarItemType = SidebarItem['type'];
@@ -100,7 +105,8 @@ export declare type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
 export declare type PropSidebarItemLink = SidebarItemLink & {
     docId?: string;
 };
-export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
+export declare type PropSidebarItemHtml = SidebarItemHtml;
+export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;
 export declare type PropSidebar = PropSidebarItem[];
 export declare type PropSidebars = {
     [sidebarId: string]: PropSidebar;

package/lib/sidebars/validation.js

@@ -28,6 +28,11 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append({
     id: utils_validation_1.Joi.string().required(),
     label: utils_validation_1.Joi.string(),
 });
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append({
+    type: 'html',
+    value: utils_validation_1.Joi.string().required(),
+    defaultStyle: utils_validation_1.Joi.boolean().default(false),
+});
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append({
     type: 'link',
     href: utils_validation_1.URISchema.required(),
@@ -93,6 +98,7 @@ const sidebarItemSchema = utils_validation_1.Joi.object()
             is: utils_validation_1.Joi.string().valid('doc', 'ref').required(),
             then: sidebarItemDocSchema,
         },
+        { is: 'html', then: sidebarItemHtmlSchema },
         { is: 'autogenerated', then: sidebarItemAutogeneratedSchema },
         { is: 'category', then: sidebarItemCategorySchema },
         {

package/lib/versions.d.ts

@@ -5,11 +5,35 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { VersionMetadata } from './types';
-import type { PluginOptions } from '@docusaurus/plugin-content-docs';
+import type { PluginOptions, VersionBanner } from '@docusaurus/plugin-content-docs';
 import type { LoadContext } from '@docusaurus/types';
 export declare function getVersionedDocsDirPath(siteDir: string, pluginId: string): string;
 export declare function getVersionedSidebarsDirPath(siteDir: string, pluginId: string): string;
 export declare function getVersionsFilePath(siteDir: string, pluginId: string): string;
+export declare function readVersionsFile(siteDir: string, pluginId: string): Promise<string[] | null>;
+export declare function readVersionNames(siteDir: string, options: Pick<PluginOptions, 'id' | 'disableVersioning' | 'includeCurrentVersion'>): Promise<string[]>;
+export declare function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }: {
+    versionName: string;
+    versionNames: string[];
+    lastVersionName: string;
+}): VersionBanner | null;
+export declare function getVersionBanner({ versionName, versionNames, lastVersionName, options, }: {
+    versionName: string;
+    versionNames: string[];
+    lastVersionName: string;
+    options: Pick<PluginOptions, 'versions'>;
+}): VersionBanner | null;
+export declare function getVersionBadge({ versionName, versionNames, options, }: {
+    versionName: string;
+    versionNames: string[];
+    options: Pick<PluginOptions, 'versions'>;
+}): boolean;
+/**
+ * Filter versions according to provided options.
+ * Note: we preserve the order in which versions are provided;
+ * the order of the onlyIncludeVersions array does not matter
+ */
+export declare function filterVersions(versionNamesUnfiltered: string[], options: Pick<PluginOptions, 'onlyIncludeVersions'>): string[];
 export declare function readVersionsMetadata({ context, options, }: {
     context: Pick<LoadContext, 'siteDir' | 'baseUrl' | 'i18n'>;
     options: Pick<PluginOptions, 'id' | 'path' | 'sidebarPath' | 'routeBasePath' | 'tagsBasePath' | 'includeCurrentVersion' | 'disableVersioning' | 'lastVersion' | 'versions' | 'onlyIncludeVersions' | 'editUrl' | 'editCurrentVersion'>;

package/lib/versions.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDocsDirPaths = exports.readVersionsMetadata = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = void 0;
+exports.getDocsDirPaths = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = void 0;
 const tslib_1 = require("tslib");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
@@ -56,6 +56,7 @@ async function readVersionsFile(siteDir, pluginId) {
     }
     return null;
 }
+exports.readVersionsFile = readVersionsFile;
 async function readVersionNames(siteDir, options) {
     const versionFileContent = await readVersionsFile(siteDir, options.id);
     if (!versionFileContent && options.disableVersioning) {
@@ -74,6 +75,7 @@ async function readVersionNames(siteDir, options) {
     }
     return versions;
 }
+exports.readVersionNames = readVersionNames;
 function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
     return (0, utils_1.getPluginI18nPath)({
         siteDir,
@@ -150,6 +152,7 @@ function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }
     // Older versions: display unmaintained banner
     return 'unmaintained';
 }
+exports.getDefaultVersionBanner = getDefaultVersionBanner;
 function getVersionBanner({ versionName, versionNames, lastVersionName, options, }) {
     var _a;
     const versionBannerOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.banner;
@@ -162,6 +165,7 @@ function getVersionBanner({ versionName, versionNames, lastVersionName, options,
         lastVersionName,
     });
 }
+exports.getVersionBanner = getVersionBanner;
 function getVersionBadge({ versionName, versionNames, options, }) {
     var _a;
     const versionBadgeOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.badge;
@@ -171,6 +175,7 @@ function getVersionBadge({ versionName, versionNames, options, }) {
     const versionBadgeDefault = versionNames.length !== 1;
     return versionBadgeOption !== null && versionBadgeOption !== void 0 ? versionBadgeOption : versionBadgeDefault;
 }
+exports.getVersionBadge = getVersionBadge;
 function getVersionClassName({ versionName, options, }) {
     var _a;
     const versionClassNameOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.className;
@@ -297,6 +302,7 @@ function filterVersions(versionNamesUnfiltered, options) {
     }
     return versionNamesUnfiltered;
 }
+exports.filterVersions = filterVersions;
 async function readVersionsMetadata({ context, options, }) {
     var _a;
     const versionNamesUnfiltered = await readVersionNames(context.siteDir, options);

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4536",
+  "version": "0.0.0-4542",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
     "./client": "./lib/client/index.js",
+    "./server": "./lib/server/index.js",
     ".": "./lib/index.js"
   },
   "types": "src/plugin-content-docs.d.ts",
@@ -22,11 +23,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4536",
-    "@docusaurus/logger": "0.0.0-4536",
-    "@docusaurus/mdx-loader": "0.0.0-4536",
-    "@docusaurus/utils": "0.0.0-4536",
-    "@docusaurus/utils-validation": "0.0.0-4536",
+    "@docusaurus/core": "0.0.0-4542",
+    "@docusaurus/logger": "0.0.0-4542",
+    "@docusaurus/mdx-loader": "0.0.0-4542",
+    "@docusaurus/utils": "0.0.0-4542",
+    "@docusaurus/utils-validation": "0.0.0-4542",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.0",
     "import-fresh": "^3.2.2",
@@ -39,8 +40,8 @@
     "webpack": "^5.68.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4536",
-    "@docusaurus/types": "0.0.0-4536",
+    "@docusaurus/module-type-aliases": "0.0.0-4542",
+    "@docusaurus/types": "0.0.0-4542",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -56,5 +57,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "a9d652056b10bf55db1bc1392672752a8b6250a7"
+  "gitHead": "681dde74d0f947b69f54858c12e7e8199b856714"
 }

package/src/lastUpdate.ts

@@ -7,6 +7,7 @@
 
 import shell from 'shelljs';
 import logger from '@docusaurus/logger';
+import path from 'path';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
@@ -43,9 +44,21 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const result = shell.exec(`git log -1 --format=%ct,%an "${filePath}"`, {
-      silent: true,
-    });
+    if (!shell.test('-f', filePath)) {
+      throw new Error(
+        `Retrieval of git history failed at "${filePath}" because the file does not exist.`,
+      );
+    }
+
+    const fileBasename = path.basename(filePath);
+    const fileDirname = path.dirname(filePath);
+    const result = shell.exec(
+      `git log --max-count=1 --format=%ct,%an -- "${fileBasename}"`,
+      {
+        cwd: fileDirname, // this is needed: https://github.com/facebook/docusaurus/pull/5048
+        silent: true,
+      },
+    );
     if (result.code !== 0) {
       throw new Error(
         `Retrieval of git history failed at "${filePath}" with exit code ${result.code}: ${result.stderr}`,

package/src/server/index.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+
+// APIs available to Node.js
+export * from '../constants';
+
+export {
+  filterVersions,
+  getDefaultVersionBanner,
+  getVersionBadge,
+  getVersionBanner,
+  getVersionsFilePath,
+  readVersionsFile,
+  readVersionNames,
+} from '../versions';

package/src/sidebars/processor.ts

@@ -117,6 +117,34 @@ async function processSidebar(
     item: NormalizedSidebarItem,
   ): Promise<SidebarItem[]> {
     if (item.type === 'category') {
+      // If the current category doesn't have subitems, we render a normal doc link instead.
+      if (item.items.length === 0) {
+        if (!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.`,
+          );
+        }
+        switch (item.link.type) {
+          case 'doc':
+            return [
+              {
+                type: 'doc',
+                label: item.label,
+                id: item.link.id,
+              },
+            ];
+          case 'generated-index':
+            return [
+              {
+                type: 'link',
+                label: item.label,
+                href: item.link.permalink,
+              },
+            ];
+          default:
+            throw new Error('Unexpected sidebar category link type');
+        }
+      }
       return [await processCategoryItem(item)];
     }
     if (item.type === 'autogenerated') {

package/src/sidebars/types.ts

@@ -27,6 +27,12 @@ export type SidebarItemDoc = SidebarItemBase & {
   id: string;
 };
 
+export type SidebarItemHtml = SidebarItemBase & {
+  type: 'html';
+  value: string;
+  defaultStyle?: boolean;
+};
+
 export type SidebarItemLink = SidebarItemBase & {
   type: 'link';
   href: string;
@@ -87,6 +93,7 @@ export type SidebarCategoriesShorthand = {
 
 export type SidebarItemConfig =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemAutogenerated
   | SidebarItemCategoryConfig
@@ -108,6 +115,7 @@ export type NormalizedSidebarItemCategory = Expand<
 
 export type NormalizedSidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | NormalizedSidebarItemCategory
   | SidebarItemAutogenerated;
@@ -131,6 +139,7 @@ export type SidebarItemCategoryWithGeneratedIndex =
 
 export type SidebarItem =
   | SidebarItemDoc
+  | SidebarItemHtml
   | SidebarItemLink
   | SidebarItemCategory;
 
@@ -158,7 +167,12 @@ export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
 };
 
-export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory;
+export type PropSidebarItemHtml = SidebarItemHtml;
+
+export type PropSidebarItem =
+  | PropSidebarItemLink
+  | PropSidebarItemCategory
+  | PropSidebarItemHtml;
 export type PropSidebar = PropSidebarItem[];
 export type PropSidebars = {
   [sidebarId: string]: PropSidebar;

package/src/sidebars/validation.ts

@@ -12,6 +12,7 @@ import type {
   SidebarItemBase,
   SidebarItemAutogenerated,
   SidebarItemDoc,
+  SidebarItemHtml,
   SidebarItemLink,
   SidebarItemCategoryConfig,
   SidebarItemCategoryLink,
@@ -48,6 +49,12 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append<SidebarItemDoc>({
   label: Joi.string(),
 });
 
+const sidebarItemHtmlSchema = sidebarItemBaseSchema.append<SidebarItemHtml>({
+  type: 'html',
+  value: Joi.string().required(),
+  defaultStyle: Joi.boolean().default(false),
+});
+
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
   type: 'link',
   href: URISchema.required(),
@@ -117,6 +124,7 @@ const sidebarItemSchema: Joi.Schema<SidebarItemConfig> = Joi.object()
         is: Joi.string().valid('doc', 'ref').required(),
         then: sidebarItemDocSchema,
       },
+      {is: 'html', then: sidebarItemHtmlSchema},
       {is: 'autogenerated', then: sidebarItemAutogeneratedSchema},
       {is: 'category', then: sidebarItemCategorySchema},
       {

package/src/versions.ts

@@ -85,7 +85,7 @@ function ensureValidVersionArray(
   versionArray.forEach(ensureValidVersionString);
 }
 
-async function readVersionsFile(
+export async function readVersionsFile(
   siteDir: string,
   pluginId: string,
 ): Promise<string[] | null> {
@@ -98,7 +98,7 @@ async function readVersionsFile(
   return null;
 }
 
-async function readVersionNames(
+export async function readVersionNames(
   siteDir: string,
   options: Pick<
     PluginOptions,
@@ -257,7 +257,7 @@ function getVersionEditUrls({
   };
 }
 
-function getDefaultVersionBanner({
+export function getDefaultVersionBanner({
   versionName,
   versionNames,
   lastVersionName,
@@ -280,7 +280,7 @@ function getDefaultVersionBanner({
   return 'unmaintained';
 }
 
-function getVersionBanner({
+export function getVersionBanner({
   versionName,
   versionNames,
   lastVersionName,
@@ -302,7 +302,7 @@ function getVersionBanner({
   });
 }
 
-function getVersionBadge({
+export function getVersionBadge({
   versionName,
   versionNames,
   options,
@@ -531,10 +531,10 @@ function checkVersionsOptions(
  * Note: we preserve the order in which versions are provided;
  * the order of the onlyIncludeVersions array does not matter
  */
-function filterVersions(
+export function filterVersions(
   versionNamesUnfiltered: string[],
   options: Pick<PluginOptions, 'onlyIncludeVersions'>,
-) {
+): string[] {
   if (options.onlyIncludeVersions) {
     return versionNamesUnfiltered.filter((name) =>
       (options.onlyIncludeVersions || []).includes(name),