@docusaurus/plugin-content-docs 2.0.0-beta.15a2b59f9 → 2.0.0-beta.17

package/lib/translations.js

@@ -7,19 +7,18 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.translateLoadedContent = exports.getLoadedContentTranslationFiles = void 0;
-const lodash_1 = require("lodash");
-const sidebars_1 = require("./sidebars");
-const utils_1 = require("@docusaurus/utils");
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("./sidebars/utils");
+const utils_2 = require("@docusaurus/utils");
 const constants_1 = require("./constants");
 function getVersionFileName(versionName) {
     if (versionName === constants_1.CURRENT_VERSION_NAME) {
         return versionName;
     }
-    else {
-        // I don't like this "version-" prefix,
-        // but it's for consistency with site/versioned_docs
-        return `version-${versionName}`;
-    }
+    // I don't like this "version-" prefix,
+    // but it's for consistency with site/versioned_docs
+    return `version-${versionName}`;
 }
 // TODO legacy, the sidebar name is like "version-2.0.0-alpha.66/docs"
 // input: "version-2.0.0-alpha.66/docs"
@@ -32,8 +31,8 @@ function getNormalizedSidebarName({ versionName, sidebarName, }) {
     return rest.join('/');
 }
 /*
-// Do we need to translate doc metadatas?
-// It seems translating frontmatter labels is good enough
+// 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`]: {
@@ -44,7 +43,8 @@ function getDocTranslations(doc: DocMetadata): TranslationFileContent {
       ? {
           [`${doc.unversionedId}.sidebar_label`]: {
             message: doc.sidebar_label,
-            description: `The sidebar label for doc with id=${doc.unversionedId}`,
+            description:
+              `The sidebar label for doc with id=${doc.unversionedId}`,
           },
         }
       : undefined),
@@ -74,44 +74,88 @@ function translateDocs(
 }
  */
 function getSidebarTranslationFileContent(sidebar, sidebarName) {
-    const categories = sidebars_1.collectSidebarCategories(sidebar);
-    const categoryContent = lodash_1.chain(categories)
-        .keyBy((category) => `sidebar.${sidebarName}.category.${category.label}`)
-        .mapValues((category) => ({
-        message: category.label,
-        description: `The label for category ${category.label} in sidebar ${sidebarName}`,
-    }))
-        .value();
-    const links = sidebars_1.collectSidebarLinks(sidebar);
-    const linksContent = lodash_1.chain(links)
-        .keyBy((link) => `sidebar.${sidebarName}.link.${link.label}`)
-        .mapValues((link) => ({
-        message: link.label,
-        description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
-    }))
-        .value();
-    return utils_1.mergeTranslations([categoryContent, linksContent]);
+    const categories = (0, utils_1.collectSidebarCategories)(sidebar);
+    const categoryContent = Object.fromEntries(categories.flatMap((category) => {
+        const entries = [];
+        entries.push([
+            `sidebar.${sidebarName}.category.${category.label}`,
+            {
+                message: category.label,
+                description: `The label for category ${category.label} in sidebar ${sidebarName}`,
+            },
+        ]);
+        if (category.link) {
+            if (category.link.type === 'generated-index') {
+                if (category.link.title) {
+                    entries.push([
+                        `sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`,
+                        {
+                            message: category.link.title,
+                            description: `The generated-index page title for category ${category.label} in sidebar ${sidebarName}`,
+                        },
+                    ]);
+                }
+                if (category.link.description) {
+                    entries.push([
+                        `sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`,
+                        {
+                            message: category.link.description,
+                            description: `The generated-index page description for category ${category.label} in sidebar ${sidebarName}`,
+                        },
+                    ]);
+                }
+            }
+        }
+        return entries;
+    }));
+    const links = (0, utils_1.collectSidebarLinks)(sidebar);
+    const linksContent = Object.fromEntries(links.map((link) => [
+        `sidebar.${sidebarName}.link.${link.label}`,
+        {
+            message: link.label,
+            description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
+        },
+    ]));
+    return (0, utils_2.mergeTranslations)([categoryContent, linksContent]);
 }
 function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
-    return sidebars_1.transformSidebarItems(sidebar, (item) => {
-        var _a, _b, _c, _d;
+    function transformSidebarCategoryLink(category) {
+        if (!category.link) {
+            return undefined;
+        }
+        if (category.link.type === 'generated-index') {
+            const title = sidebarsTranslations[`sidebar.${sidebarName}.category.${category.label}.link.generated-index.title`]?.message ?? category.link.title;
+            const description = sidebarsTranslations[`sidebar.${sidebarName}.category.${category.label}.link.generated-index.description`]?.message ?? category.link.description;
+            return {
+                ...category.link,
+                title,
+                description,
+            };
+        }
+        return category.link;
+    }
+    return (0, utils_1.transformSidebarItems)(sidebar, (item) => {
         if (item.type === 'category') {
+            const link = transformSidebarCategoryLink(item);
             return {
                 ...item,
-                label: (_b = (_a = sidebarsTranslations[`sidebar.${sidebarName}.category.${item.label}`]) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : item.label,
+                label: sidebarsTranslations[`sidebar.${sidebarName}.category.${item.label}`]
+                    ?.message ?? item.label,
+                ...(link && { link }),
             };
         }
         if (item.type === 'link') {
             return {
                 ...item,
-                label: (_d = (_c = sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]) === null || _c === void 0 ? void 0 : _c.message) !== null && _d !== void 0 ? _d : item.label,
+                label: sidebarsTranslations[`sidebar.${sidebarName}.link.${item.label}`]
+                    ?.message ?? item.label,
             };
         }
         return item;
     });
 }
 function getSidebarsTranslations(version) {
-    return utils_1.mergeTranslations(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
+    return (0, utils_2.mergeTranslations)(Object.entries(version.sidebars).map(([sidebarName, sidebar]) => {
         const normalizedSidebarName = getNormalizedSidebarName({
             sidebarName,
             versionName: version.versionName,
@@ -120,16 +164,14 @@ function getSidebarsTranslations(version) {
     }));
 }
 function translateSidebars(version, sidebarsTranslations) {
-    return lodash_1.mapValues(version.sidebars, (sidebar, sidebarName) => {
-        return translateSidebar({
-            sidebar,
-            sidebarName: getNormalizedSidebarName({
-                sidebarName,
-                versionName: version.versionName,
-            }),
-            sidebarsTranslations,
-        });
-    });
+    return lodash_1.default.mapValues(version.sidebars, (sidebar, sidebarName) => translateSidebar({
+        sidebar,
+        sidebarName: getNormalizedSidebarName({
+            sidebarName,
+            versionName: version.versionName,
+        }),
+        sidebarsTranslations,
+    }));
 }
 function getVersionTranslationFiles(version) {
     const versionTranslations = {
@@ -139,11 +181,12 @@ function getVersionTranslationFiles(version) {
         },
     };
     const sidebarsTranslations = getSidebarsTranslations(version);
-    // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
+    // const docsTranslations: TranslationFileContent =
+    //   getDocsTranslations(version);
     return [
         {
             path: getVersionFileName(version.versionName),
-            content: utils_1.mergeTranslations([
+            content: (0, utils_2.mergeTranslations)([
                 versionTranslations,
                 sidebarsTranslations,
                 // docsTranslations,
@@ -152,17 +195,16 @@ function getVersionTranslationFiles(version) {
     ];
 }
 function translateVersion(version, translationFiles) {
-    var _a;
     const versionTranslations = translationFiles[getVersionFileName(version.versionName)].content;
     return {
         ...version,
-        versionLabel: (_a = versionTranslations['version.label']) === null || _a === void 0 ? void 0 : _a.message,
+        versionLabel: versionTranslations['version.label']?.message,
         sidebars: translateSidebars(version, versionTranslations),
         // docs: translateDocs(version.docs, versionTranslations),
     };
 }
 function getVersionsTranslationFiles(versions) {
-    return lodash_1.flatten(versions.map(getVersionTranslationFiles));
+    return versions.flatMap(getVersionTranslationFiles);
 }
 function translateVersions(versions, translationFiles) {
     return versions.map((version) => translateVersion(version, translationFiles));
@@ -172,7 +214,7 @@ function getLoadedContentTranslationFiles(loadedContent) {
 }
 exports.getLoadedContentTranslationFiles = getLoadedContentTranslationFiles;
 function translateLoadedContent(loadedContent, translationFiles) {
-    const translationFilesMap = lodash_1.keyBy(translationFiles, (f) => f.path);
+    const translationFilesMap = lodash_1.default.keyBy(translationFiles, (f) => f.path);
     return {
         loadedVersions: translateVersions(loadedContent.loadedVersions, translationFilesMap),
     };

package/lib/types.d.ts

@@ -4,8 +4,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { RemarkAndRehypePluginOptions } from '@docusaurus/mdx-loader';
-import { BrokenMarkdownLink as IBrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
+import type { Sidebars } from './sidebars/types';
+import type { Tag, FrontMatterTag } from '@docusaurus/utils';
+import type { BrokenMarkdownLink as IBrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
+import type { VersionBanner } from '@docusaurus/plugin-content-docs';
 export declare type DocFile = {
     contentPath: string;
     filePath: string;
@@ -13,114 +15,20 @@ export declare type DocFile = {
     content: string;
     lastUpdate: LastUpdateData;
 };
-export declare type VersionName = string;
 export declare type VersionMetadata = ContentPaths & {
-    versionName: VersionName;
+    versionName: string;
     versionLabel: string;
     versionPath: string;
+    tagsPath: string;
     versionEditUrl?: string | undefined;
     versionEditUrlLocalized?: string | undefined;
-    versionBanner: VersionBanner;
+    versionBanner: VersionBanner | null;
+    versionBadge: boolean;
+    versionClassName: string;
     isLast: boolean;
     sidebarFilePath: string | false | undefined;
     routePriority: number | undefined;
 };
-export declare type EditUrlFunction = (editUrlParams: {
-    version: string;
-    versionDocsDirPath: string;
-    docPath: string;
-    permalink: string;
-    locale: string;
-}) => string | undefined;
-export declare type MetadataOptions = {
-    routeBasePath: string;
-    homePageId?: string;
-    editUrl?: string | EditUrlFunction;
-    editCurrentVersion: boolean;
-    editLocalizedFiles: boolean;
-    showLastUpdateTime?: boolean;
-    showLastUpdateAuthor?: boolean;
-    numberPrefixParser: NumberPrefixParser;
-};
-export declare type PathOptions = {
-    path: string;
-    sidebarPath?: string | false | undefined;
-};
-export declare type VersionBanner = 'none' | 'unreleased' | 'unmaintained';
-export declare type VersionOptions = {
-    path?: string;
-    label?: string;
-    banner?: VersionBanner;
-};
-export declare type VersionsOptions = {
-    lastVersion?: string;
-    versions: Record<string, VersionOptions>;
-    onlyIncludeVersions?: string[];
-};
-export declare type PluginOptions = MetadataOptions & PathOptions & VersionsOptions & RemarkAndRehypePluginOptions & {
-    id: string;
-    include: string[];
-    docLayoutComponent: string;
-    docItemComponent: string;
-    admonitions: Record<string, unknown>;
-    disableVersioning: boolean;
-    includeCurrentVersion: boolean;
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-};
-export declare type SidebarItemBase = {
-    customProps?: Record<string, unknown>;
-};
-export declare type SidebarItemDoc = SidebarItemBase & {
-    type: 'doc' | 'ref';
-    label?: string;
-    id: string;
-};
-export declare type SidebarItemLink = SidebarItemBase & {
-    type: 'link';
-    href: string;
-    label: string;
-};
-export declare type SidebarItemCategory = SidebarItemBase & {
-    type: 'category';
-    label: string;
-    items: SidebarItem[];
-    collapsed: boolean;
-};
-export declare type UnprocessedSidebarItemAutogenerated = {
-    type: 'autogenerated';
-    dirName: string;
-};
-export declare type UnprocessedSidebarItemCategory = SidebarItemBase & {
-    type: 'category';
-    label: string;
-    items: UnprocessedSidebarItem[];
-    collapsed: boolean;
-};
-export declare type UnprocessedSidebarItem = SidebarItemDoc | SidebarItemLink | UnprocessedSidebarItemCategory | UnprocessedSidebarItemAutogenerated;
-export declare type UnprocessedSidebar = UnprocessedSidebarItem[];
-export declare type UnprocessedSidebars = Record<string, UnprocessedSidebar>;
-export declare type SidebarItem = SidebarItemDoc | SidebarItemLink | SidebarItemCategory;
-export declare type Sidebar = SidebarItem[];
-export declare type SidebarItemType = SidebarItem['type'];
-export declare type Sidebars = Record<string, Sidebar>;
-export declare type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
-export declare type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
-export declare type SidebarItemsGeneratorArgs = {
-    item: UnprocessedSidebarItemAutogenerated;
-    version: SidebarItemsGeneratorVersion;
-    docs: SidebarItemsGeneratorDoc[];
-    numberPrefixParser: NumberPrefixParser;
-};
-export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<SidebarItem[]>;
-export declare type SidebarItemsGeneratorOptionArgs = {
-    defaultSidebarItemsGenerator: SidebarItemsGenerator;
-} & SidebarItemsGeneratorArgs;
-export declare type SidebarItemsGeneratorOption = (generatorArgs: SidebarItemsGeneratorOptionArgs) => Promise<SidebarItem[]>;
-export declare type OrderMetadata = {
-    previous?: string;
-    next?: string;
-    sidebar?: string;
-};
 export declare type LastUpdateData = {
     lastUpdatedAt?: number;
     formattedLastUpdatedAt?: string;
@@ -129,6 +37,7 @@ export declare type LastUpdateData = {
 export declare type DocFrontMatter = {
     id?: string;
     title?: string;
+    tags?: FrontMatterTag[];
     hide_title?: boolean;
     hide_table_of_contents?: boolean;
     keywords?: string[];
@@ -137,15 +46,21 @@ export declare type DocFrontMatter = {
     slug?: string;
     sidebar_label?: string;
     sidebar_position?: number;
+    sidebar_class_name?: string;
+    sidebar_custom_props?: Record<string, unknown>;
+    displayed_sidebar?: string | null;
     pagination_label?: string;
     custom_edit_url?: string | null;
     parse_number_prefixes?: boolean;
+    toc_min_heading_level?: number;
+    toc_max_heading_level?: number;
+    pagination_next?: string | null;
+    pagination_prev?: string | null;
 };
 export declare type DocMetadataBase = LastUpdateData & {
-    version: VersionName;
-    unversionedId: string;
     id: string;
-    isDocsHomePage: boolean;
+    unversionedId: string;
+    version: string;
     title: string;
     description: string;
     source: string;
@@ -154,6 +69,7 @@ export declare type DocMetadataBase = LastUpdateData & {
     permalink: string;
     sidebarPosition?: number;
     editUrl?: string | null;
+    tags: Tag[];
     frontMatter: DocFrontMatter & Record<string, unknown>;
 };
 export declare type DocNavLink = {
@@ -165,36 +81,38 @@ export declare type DocMetadata = DocMetadataBase & {
     previous?: DocNavLink;
     next?: DocNavLink;
 };
+export declare type CategoryGeneratedIndexMetadata = {
+    title: string;
+    description?: string;
+    slug: string;
+    permalink: string;
+    sidebar: string;
+    previous?: DocNavLink;
+    next?: DocNavLink;
+    image?: string;
+    keywords?: string | readonly string[];
+};
 export declare type SourceToPermalink = {
     [source: string]: string;
 };
+export declare type VersionTag = {
+    name: string;
+    docIds: string[];
+    permalink: string;
+};
+export declare type VersionTags = {
+    [key: string]: VersionTag;
+};
 export declare type LoadedVersion = VersionMetadata & {
     versionPath: string;
     mainDocId: string;
     docs: DocMetadata[];
     sidebars: Sidebars;
-    permalinkToSidebar: Record<string, string>;
+    categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
 export declare type LoadedContent = {
     loadedVersions: LoadedVersion[];
 };
-export declare type GlobalDoc = {
-    id: string;
-    path: string;
-    sidebar: string | undefined;
-};
-export declare type GlobalVersion = {
-    name: VersionName;
-    label: string;
-    isLast: boolean;
-    path: string;
-    mainDocId: string;
-    docs: GlobalDoc[];
-};
-export declare type GlobalPluginData = {
-    path: string;
-    versions: GlobalVersion[];
-};
 export declare type BrokenMarkdownLink = IBrokenMarkdownLink<VersionMetadata>;
 export declare type DocsMarkdownOption = {
     versionsMetadata: VersionMetadata[];
@@ -202,7 +120,3 @@ export declare type DocsMarkdownOption = {
     sourceToPermalink: SourceToPermalink;
     onBrokenMarkdownLink: (brokenMarkdownLink: BrokenMarkdownLink) => void;
 };
-export declare type NumberPrefixParser = (filename: string) => {
-    filename: string;
-    numberPrefix?: number;
-};

package/lib/versions.d.ts

@@ -4,13 +4,38 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { PluginOptions, VersionMetadata } from './types';
-import { LoadContext } from '@docusaurus/types';
+import type { VersionMetadata } from './types';
+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' | 'includeCurrentVersion' | 'disableVersioning' | 'lastVersion' | 'versions' | 'onlyIncludeVersions' | 'editUrl' | 'editCurrentVersion'>;
-}): VersionMetadata[];
+    options: Pick<PluginOptions, 'id' | 'path' | 'sidebarPath' | 'routeBasePath' | 'tagsBasePath' | 'includeCurrentVersion' | 'disableVersioning' | 'lastVersion' | 'versions' | 'onlyIncludeVersions' | 'editUrl' | 'editCurrentVersion'>;
+}): Promise<VersionMetadata[]>;
 export declare function getDocsDirPaths(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>): [string, string];