@docusaurus/plugin-content-docs 2.0.0-beta.21 → 2.0.0-beta.22

package/lib/cli.js

@@ -50,12 +50,12 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
         logger_1.default.info `Versioned docs will be created for the following locales: name=${i18n.locales}`;
     }
     await Promise.all(i18n.locales.map(async (locale) => {
+        const localizationDir = path_1.default.resolve(siteDir, i18n.path, i18n.localeConfigs[locale].path);
         // Copy docs files.
         const docsDir = locale === i18n.defaultLocale
             ? path_1.default.resolve(siteDir, docsPath)
             : (0, files_1.getDocsDirPathLocalized)({
-                siteDir,
-                locale,
+                localizationDir,
                 pluginId,
                 versionName: constants_1.CURRENT_VERSION_NAME,
             });
@@ -72,8 +72,7 @@ async function cliDocsVersionCommand(version, { id: pluginId, path: docsPath, si
         const newVersionDir = locale === i18n.defaultLocale
             ? (0, files_1.getVersionDocsDirPath)(siteDir, pluginId, version)
             : (0, files_1.getDocsDirPathLocalized)({
-                siteDir,
-                locale,
+                localizationDir,
                 pluginId,
                 versionName: version,
             });

package/lib/client/index.d.ts

@@ -4,8 +4,59 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { GlobalPluginData, GlobalVersion, ActivePlugin, ActiveDocContext, DocVersionSuggestions } from '@docusaurus/plugin-content-docs/client';
 import type { UseDataOptions } from '@docusaurus/types';
+export declare type ActivePlugin = {
+    pluginId: string;
+    pluginData: GlobalPluginData;
+};
+export declare type ActiveDocContext = {
+    activeVersion?: GlobalVersion;
+    activeDoc?: GlobalDoc;
+    alternateDocVersions: {
+        [versionName: string]: GlobalDoc;
+    };
+};
+export declare type GlobalDoc = {
+    /**
+     * For generated index pages, this is the `slug`, **not** `permalink`
+     * (without base URL). Because slugs have leading slashes but IDs don't,
+     * there won't be clashes.
+     */
+    id: string;
+    path: string;
+    sidebar: string | undefined;
+};
+export declare type GlobalVersion = {
+    name: string;
+    label: string;
+    isLast: boolean;
+    path: string;
+    /** The doc with `slug: /`, or first doc in first sidebar */
+    mainDocId: string;
+    docs: GlobalDoc[];
+    /** Unversioned IDs. In development, this list is empty. */
+    draftIds: string[];
+    sidebars?: {
+        [sidebarId: string]: GlobalSidebar;
+    };
+};
+export declare type GlobalSidebar = {
+    link?: {
+        label: string;
+        path: string;
+    };
+};
+export declare type GlobalPluginData = {
+    path: string;
+    versions: GlobalVersion[];
+    breadcrumbs: boolean;
+};
+export declare type DocVersionSuggestions = {
+    /** Suggest the latest version */
+    latestVersionSuggestion: GlobalVersion;
+    /** Suggest the same doc, in latest version (if one exists) */
+    latestDocSuggestion?: GlobalDoc;
+};
 export declare const useAllDocsData: () => {
     [pluginId: string]: GlobalPluginData;
 };
@@ -15,8 +66,16 @@ export declare function useActivePluginAndVersion(options?: UseDataOptions): {
     activePlugin: ActivePlugin;
     activeVersion: GlobalVersion | undefined;
 } | undefined;
+/** Versions are returned ordered (most recent first). */
 export declare function useVersions(pluginId: string | undefined): GlobalVersion[];
 export declare function useLatestVersion(pluginId: string | undefined): GlobalVersion;
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
 export declare function useActiveVersion(pluginId: string | undefined): GlobalVersion | undefined;
 export declare function useActiveDocContext(pluginId: string | undefined): ActiveDocContext;
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
 export declare function useDocVersionSuggestions(pluginId: string | undefined): DocVersionSuggestions;

package/lib/client/index.js

@@ -34,6 +34,7 @@ export function useActivePluginAndVersion(options = {}) {
         activeVersion,
     };
 }
+/** Versions are returned ordered (most recent first). */
 export function useVersions(pluginId) {
     const data = useDocsData(pluginId);
     return data.versions;
@@ -42,6 +43,10 @@ export function useLatestVersion(pluginId) {
     const data = useDocsData(pluginId);
     return getLatestVersion(data);
 }
+/**
+ * Returns `undefined` on doc-unrelated pages, because there's no version
+ * currently considered as active.
+ */
 export function useActiveVersion(pluginId) {
     const data = useDocsData(pluginId);
     const { pathname } = useLocation();
@@ -52,6 +57,9 @@ export function useActiveDocContext(pluginId) {
     const { pathname } = useLocation();
     return getActiveDocContext(data, pathname);
 }
+/**
+ * Useful to say "hey, you are not on the latest docs version, please switch"
+ */
 export function useDocVersionSuggestions(pluginId) {
     const data = useDocsData(pluginId);
     const { pathname } = useLocation();

package/lib/docs.d.ts

@@ -8,8 +8,7 @@ import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, DocMetadataB
 import type { LoadContext } from '@docusaurus/types';
 import type { SidebarsUtils } from './sidebars/utils';
 import type { DocFile } from './types';
-declare type LastUpdateOptions = Pick<PluginOptions, 'showLastUpdateAuthor' | 'showLastUpdateTime'>;
-export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string, options: LastUpdateOptions): Promise<DocFile>;
+export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string): Promise<DocFile>;
 export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
 export declare type DocEnv = 'production' | 'development';
 export declare function processDocMetadata(args: {
@@ -18,7 +17,7 @@ export declare function processDocMetadata(args: {
     context: LoadContext;
     options: MetadataOptions;
     env: DocEnv;
-}): DocMetadataBase;
+}): Promise<DocMetadataBase>;
 export declare function addDocNavigation(docsBase: DocMetadataBase[], sidebarsUtils: SidebarsUtils, sidebarFilePath: string): LoadedVersion['docs'];
 /**
  * The "main doc" is the "version entry point"
@@ -44,4 +43,3 @@ export declare function createDocsByIdIndex<Doc extends {
 }>(docs: Doc[]): {
     [docId: string]: Doc;
 };
-export {};

package/lib/docs.js

@@ -18,9 +18,18 @@ const constants_1 = require("./constants");
 const numberPrefix_1 = require("./numberPrefix");
 const frontMatter_1 = require("./frontMatter");
 const utils_2 = require("./sidebars/utils");
-async function readLastUpdateData(filePath, options) {
+async function readLastUpdateData(filePath, options, lastUpdateFrontMatter) {
     const { showLastUpdateAuthor, showLastUpdateTime } = options;
     if (showLastUpdateAuthor || showLastUpdateTime) {
+        const frontMatterTimestamp = lastUpdateFrontMatter?.date
+            ? new Date(lastUpdateFrontMatter.date).getTime() / 1000
+            : undefined;
+        if (lastUpdateFrontMatter?.author && lastUpdateFrontMatter.date) {
+            return {
+                lastUpdatedAt: frontMatterTimestamp,
+                lastUpdatedBy: lastUpdateFrontMatter.author,
+            };
+        }
         // Use fake data in dev for faster development.
         const fileLastUpdateData = process.env.NODE_ENV === 'production'
             ? await (0, lastUpdate_1.getFileLastUpdate)(filePath)
@@ -28,24 +37,23 @@ async function readLastUpdateData(filePath, options) {
                 author: 'Author',
                 timestamp: 1539502055,
             };
-        if (fileLastUpdateData) {
-            const { author, timestamp } = fileLastUpdateData;
-            return {
-                lastUpdatedAt: showLastUpdateTime ? timestamp : undefined,
-                lastUpdatedBy: showLastUpdateAuthor ? author : undefined,
-            };
-        }
+        const { author, timestamp } = fileLastUpdateData ?? {};
+        return {
+            lastUpdatedBy: showLastUpdateAuthor
+                ? lastUpdateFrontMatter?.author ?? author
+                : undefined,
+            lastUpdatedAt: showLastUpdateTime
+                ? frontMatterTimestamp ?? timestamp
+                : undefined,
+        };
     }
     return {};
 }
-async function readDocFile(versionMetadata, source, options) {
+async function readDocFile(versionMetadata, source) {
     const contentPath = await (0, utils_1.getFolderContainingFile)((0, utils_1.getContentPathList)(versionMetadata), source);
     const filePath = path_1.default.join(contentPath, source);
-    const [content, lastUpdate] = await Promise.all([
-        fs_extra_1.default.readFile(filePath, 'utf-8'),
-        readLastUpdateData(filePath, options),
-    ]);
-    return { source, content, lastUpdate, contentPath, filePath };
+    const content = await fs_extra_1.default.readFile(filePath, 'utf-8');
+    return { source, content, contentPath, filePath };
 }
 exports.readDocFile = readDocFile;
 async function readVersionDocs(versionMetadata, options) {
@@ -53,15 +61,15 @@ async function readVersionDocs(versionMetadata, options) {
         cwd: versionMetadata.contentPath,
         ignore: options.exclude,
     });
-    return Promise.all(sources.map((source) => readDocFile(versionMetadata, source, options)));
+    return Promise.all(sources.map((source) => readDocFile(versionMetadata, source)));
 }
 exports.readVersionDocs = readVersionDocs;
 /** Docs with draft front matter are only considered draft in production. */
 function isDraftForEnvironment({ env, frontMatter, }) {
     return (env === 'production' && frontMatter.draft) ?? false;
 }
-function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
-    const { source, content, lastUpdate, contentPath, filePath } = docFile;
+async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
+    const { source, content, contentPath, filePath } = docFile;
     const { siteDir, i18n } = context;
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
     const frontMatter = (0, frontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
@@ -69,7 +77,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, env,
     // Strip number prefixes by default
     // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
-    parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
+    parse_number_prefixes: parseNumberPrefixes = true, last_update: lastUpdateFrontMatter, } = frontMatter;
+    const lastUpdate = await readLastUpdateData(filePath, options, lastUpdateFrontMatter);
     // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
     const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
     // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .
@@ -142,6 +151,21 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, env,
         return undefined;
     }
     const draft = isDraftForEnvironment({ env, frontMatter });
+    const formatDate = (locale, date, calendar) => {
+        try {
+            return new Intl.DateTimeFormat(locale, {
+                day: 'numeric',
+                month: 'short',
+                year: 'numeric',
+                timeZone: 'UTC',
+                calendar,
+            }).format(date);
+        }
+        catch (err) {
+            logger_1.default.error `Can't format docs lastUpdatedAt date "${String(date)}"`;
+            throw err;
+        }
+    };
     // Assign all of object properties during instantiation (if possible) for
     // NodeJS optimization.
     // Adding properties to object after instantiation will cause hidden
@@ -162,9 +186,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, env,
         lastUpdatedBy: lastUpdate.lastUpdatedBy,
         lastUpdatedAt: lastUpdate.lastUpdatedAt,
         formattedLastUpdatedAt: lastUpdate.lastUpdatedAt
-            ? new Intl.DateTimeFormat(i18n.currentLocale, {
-                calendar: i18n.localeConfigs[i18n.currentLocale].calendar,
-            }).format(lastUpdate.lastUpdatedAt * 1000)
+            ? formatDate(i18n.currentLocale, new Date(lastUpdate.lastUpdatedAt * 1000), i18n.localeConfigs[i18n.currentLocale].calendar)
             : undefined,
         sidebarPosition,
         frontMatter,

package/lib/frontMatter.js

@@ -8,6 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateDocFrontMatter = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const FrontMatterLastUpdateErrorMessage = '{{#label}} does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).';
 // NOTE: we don't add any default value on purpose here
 // We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
@@ -36,6 +37,15 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
     draft: utils_validation_1.JoiFrontMatter.boolean(),
     ...utils_validation_1.FrontMatterTOCHeadingLevels,
+    last_update: utils_validation_1.JoiFrontMatter.object({
+        author: utils_validation_1.JoiFrontMatter.string(),
+        date: utils_validation_1.JoiFrontMatter.date().raw(),
+    })
+        .or('author', 'date')
+        .messages({
+        'object.missing': FrontMatterLastUpdateErrorMessage,
+        'object.base': FrontMatterLastUpdateErrorMessage,
+    }),
 }).unknown();
 function validateDocFrontMatter(frontMatter) {
     return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);

package/lib/index.js

@@ -50,9 +50,7 @@ async function pluginContentDocs(context, options) {
                 .command(command)
                 .arguments('<version>')
                 .description(commandDescription)
-                .action((version) => {
-                (0, cli_1.cliDocsVersionCommand)(version, options, context);
-            });
+                .action((version) => (0, cli_1.cliDocsVersionCommand)(version, options, context));
         },
         getTranslationFiles({ content }) {
             return (0, translations_1.getLoadedContentTranslationFiles)(content);
@@ -212,10 +210,7 @@ async function pluginContentDocs(context, options) {
                 sourceToPermalink: getSourceToPermalink(),
                 versionsMetadata,
                 onBrokenMarkdownLink: (brokenMarkdownLink) => {
-                    if (siteConfig.onBrokenMarkdownLinks === 'ignore') {
-                        return;
-                    }
-                    (0, utils_1.reportMessage)(`Docs markdown link couldn't be resolved: (${brokenMarkdownLink.link}) in ${brokenMarkdownLink.filePath} for version ${brokenMarkdownLink.contentPaths.versionName}`, siteConfig.onBrokenMarkdownLinks);
+                    logger_1.default.report(siteConfig.onBrokenMarkdownLinks) `Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
                 },
             };
             function createMDXLoaderRule() {
@@ -230,6 +225,7 @@ async function pluginContentDocs(context, options) {
                         {
                             loader: require.resolve('@docusaurus/mdx-loader'),
                             options: {
+                                admonitions: options.admonitions,
                                 remarkPlugins,
                                 rehypePlugins,
                                 beforeDefaultRehypePlugins,

package/lib/lastUpdate.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export declare function getFileLastUpdate(filePath?: string): Promise<{
+export declare function getFileLastUpdate(filePath: string): Promise<{
     timestamp: number;
     author: string;
 } | null>;

package/lib/options.js

@@ -11,7 +11,6 @@ const tslib_1 = require("tslib");
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const utils_1 = require("@docusaurus/utils");
-const remark_admonitions_1 = tslib_1.__importDefault(require("remark-admonitions"));
 const generator_1 = require("./sidebars/generator");
 const numberPrefix_1 = require("./numberPrefix");
 exports.DEFAULT_OPTIONS = {
@@ -33,7 +32,7 @@ exports.DEFAULT_OPTIONS = {
     beforeDefaultRehypePlugins: [],
     showLastUpdateTime: false,
     showLastUpdateAuthor: false,
-    admonitions: {},
+    admonitions: true,
     includeCurrentVersion: true,
     disableVersioning: false,
     lastVersion: undefined,
@@ -90,9 +89,7 @@ const OptionsSchema = utils_validation_1.Joi.object({
     rehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.rehypePlugins),
     beforeDefaultRemarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRemarkPlugins),
     beforeDefaultRehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRehypePlugins),
-    admonitions: utils_validation_1.Joi.alternatives()
-        .try(utils_validation_1.AdmonitionsSchema, utils_validation_1.Joi.boolean().invalid(true))
-        .default(exports.DEFAULT_OPTIONS.admonitions),
+    admonitions: utils_validation_1.AdmonitionsSchema.default(exports.DEFAULT_OPTIONS.admonitions),
     showLastUpdateTime: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateTime),
     showLastUpdateAuthor: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateAuthor),
     includeCurrentVersion: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.includeCurrentVersion),
@@ -123,11 +120,6 @@ function validateOptions({ validate, options: userOptions, }) {
         }
     }
     const normalizedOptions = validate(OptionsSchema, options);
-    if (normalizedOptions.admonitions) {
-        normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
-            [remark_admonitions_1.default, normalizedOptions.admonitions],
-        ]);
-    }
     return normalizedOptions;
 }
 exports.validateOptions = validateOptions;

package/lib/props.js

@@ -43,10 +43,24 @@ Available document ids are:
                 return undefined;
         }
     }
+    function getCategoryLinkCustomProps(link) {
+        switch (link?.type) {
+            case 'doc':
+                return getDocById(link.id).frontMatter.sidebar_custom_props;
+            default:
+                return undefined;
+        }
+    }
     function convertCategory(item) {
         const { link, ...rest } = item;
         const href = getCategoryLinkHref(link);
-        return { ...rest, items: item.items.map(normalizeItem), ...(href && { href }) };
+        const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
+        return {
+            ...rest,
+            items: item.items.map(normalizeItem),
+            ...(href && { href }),
+            ...(customProps && { customProps }),
+        };
     }
     function normalizeItem(item) {
         switch (item.type) {

package/lib/sidebars/normalization.js

@@ -30,6 +30,10 @@ function normalizeItem(item) {
         // This will never throw anyways
         return normalizeSidebar(item, 'sidebar items slice');
     }
+    if ((item.type === 'doc' || item.type === 'ref') &&
+        typeof item.label === 'string') {
+        return [{ ...item, translatable: true }];
+    }
     if (item.type === 'category') {
         const normalizedCategory = {
             ...item,

package/lib/sidebars/types.d.ts

@@ -22,6 +22,11 @@ export declare type SidebarItemDoc = SidebarItemBase & {
     type: 'doc' | 'ref';
     label?: string;
     id: string;
+    /**
+     * This is an internal marker. Items with labels defined in the config needs
+     * to be translated with JSON
+     */
+    translatable?: true;
 };
 export declare type SidebarItemHtml = SidebarItemBase & {
     type: 'html';
@@ -73,7 +78,7 @@ export declare type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCateg
 export declare type SidebarCategoriesShorthand = {
     [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
 };
-export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
+export declare type SidebarItemConfig = Omit<SidebarItemDoc, 'translatable'> | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
 export declare type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
 export declare type SidebarsConfig = {
     [sidebarId: string]: SidebarConfig;

package/lib/sidebars/utils.d.ts

@@ -11,6 +11,7 @@ export declare function transformSidebarItems(sidebar: Sidebar, updateFn: (item:
 export declare function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[];
 export declare function collectSidebarCategories(sidebar: Sidebar): SidebarItemCategory[];
 export declare function collectSidebarLinks(sidebar: Sidebar): SidebarItemLink[];
+export declare function collectSidebarRefs(sidebar: Sidebar): SidebarItemDoc[];
 export declare function collectSidebarDocIds(sidebar: Sidebar): string[];
 export declare function collectSidebarNavigation(sidebar: Sidebar): SidebarNavigationItem[];
 export declare function collectSidebarsDocIds(sidebars: Sidebars): {

package/lib/sidebars/utils.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toNavigationLink = exports.toDocNavigationLink = exports.createSidebarsUtils = exports.collectSidebarsNavigations = exports.collectSidebarsDocIds = exports.collectSidebarNavigation = exports.collectSidebarDocIds = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.transformSidebarItems = exports.isCategoriesShorthand = void 0;
+exports.toNavigationLink = exports.toDocNavigationLink = exports.createSidebarsUtils = exports.collectSidebarsNavigations = exports.collectSidebarsDocIds = exports.collectSidebarNavigation = exports.collectSidebarDocIds = exports.collectSidebarRefs = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.transformSidebarItems = exports.isCategoriesShorthand = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
@@ -55,6 +55,10 @@ function collectSidebarLinks(sidebar) {
     return collectSidebarItemsOfType('link', sidebar);
 }
 exports.collectSidebarLinks = collectSidebarLinks;
+function collectSidebarRefs(sidebar) {
+    return collectSidebarItemsOfType('ref', sidebar);
+}
+exports.collectSidebarRefs = collectSidebarRefs;
 // /!\ docId order matters for navigation!
 function collectSidebarDocIds(sidebar) {
     return flattenSidebarItems(sidebar).flatMap((item) => {

package/lib/sidebars/validation.js

@@ -26,6 +26,7 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append({
     type: utils_validation_1.Joi.string().valid('doc', 'ref').required(),
     id: utils_validation_1.Joi.string().required(),
     label: utils_validation_1.Joi.string(),
+    translatable: utils_validation_1.Joi.boolean(),
 });
 const sidebarItemHtmlSchema = sidebarItemBaseSchema.append({
     type: 'html',

package/lib/translations.js

@@ -71,7 +71,17 @@ function getSidebarTranslationFileContent(sidebar, sidebarName) {
             description: `The label for link ${link.label} in sidebar ${sidebarName}, linking to ${link.href}`,
         },
     ]));
-    return (0, utils_1.mergeTranslations)([categoryContent, linksContent]);
+    const docs = (0, utils_2.collectSidebarDocItems)(sidebar)
+        .concat((0, utils_2.collectSidebarRefs)(sidebar))
+        .filter((item) => item.translatable);
+    const docLinksContent = Object.fromEntries(docs.map((doc) => [
+        `sidebar.${sidebarName}.doc.${doc.label}`,
+        {
+            message: doc.label,
+            description: `The label for the doc item ${doc.label} in sidebar ${sidebarName}, linking to the doc ${doc.id}`,
+        },
+    ]));
+    return (0, utils_1.mergeTranslations)([categoryContent, linksContent, docLinksContent]);
 }
 function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
     function transformSidebarCategoryLink(category) {
@@ -106,6 +116,13 @@ function translateSidebar({ sidebar, sidebarName, sidebarsTranslations, }) {
                     ?.message ?? item.label,
             };
         }
+        if ((item.type === 'doc' || item.type === 'ref') && item.translatable) {
+            return {
+                ...item,
+                label: sidebarsTranslations[`sidebar.${sidebarName}.doc.${item.label}`]
+                    ?.message ?? item.label,
+            };
+        }
         return item;
     });
 }

package/lib/types.d.ts

@@ -5,14 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { BrokenMarkdownLink, Tag } from '@docusaurus/utils';
-import type { VersionMetadata, LastUpdateData, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
+import type { VersionMetadata, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';
 export declare type DocFile = {
     contentPath: string;
     filePath: string;
     source: string;
     content: string;
-    lastUpdate: LastUpdateData;
 };
 export declare type SourceToPermalink = {
     [source: string]: string;

package/lib/versions/files.d.ts

@@ -10,9 +10,8 @@ import type { VersionContext } from './index';
 export declare function getVersionDocsDirPath(siteDir: string, pluginId: string, versionName: string): string;
 /** `[siteDir]/community_versioned_sidebars/version-1.0.0-sidebars.json` */
 export declare function getVersionSidebarsPath(siteDir: string, pluginId: string, versionName: string): string;
-export declare function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }: {
-    siteDir: string;
-    locale: string;
+export declare function getDocsDirPathLocalized({ localizationDir, pluginId, versionName, }: {
+    localizationDir: string;
     pluginId: string;
     versionName: string;
 }): string;

package/lib/versions/files.js

@@ -29,10 +29,9 @@ function getVersionSidebarsPath(siteDir, pluginId, versionName) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_SIDEBARS_DIR, pluginId), `version-${versionName}-sidebars.json`);
 }
 exports.getVersionSidebarsPath = getVersionSidebarsPath;
-function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
+function getDocsDirPathLocalized({ localizationDir, pluginId, versionName, }) {
     return (0, utils_1.getPluginI18nPath)({
-        siteDir,
-        locale,
+        localizationDir,
         pluginName: 'docusaurus-plugin-content-docs',
         pluginId,
         subPaths: [
@@ -110,8 +109,7 @@ exports.readVersionNames = readVersionNames;
 async function getVersionMetadataPaths({ versionName, context, options, }) {
     const isCurrent = versionName === constants_1.CURRENT_VERSION_NAME;
     const contentPathLocalized = getDocsDirPathLocalized({
-        siteDir: context.siteDir,
-        locale: context.i18n.currentLocale,
+        localizationDir: context.localizationDir,
         pluginId: options.id,
         versionName,
     });

package/lib/versions/index.js

@@ -22,8 +22,7 @@ function getVersionEditUrls({ contentPath, contentPathLocalized, context, option
     const editDirPath = options.editCurrentVersion ? options.path : contentPath;
     const editDirPathLocalized = options.editCurrentVersion
         ? (0, files_1.getDocsDirPathLocalized)({
-            siteDir: context.siteDir,
-            locale: context.i18n.currentLocale,
+            localizationDir: context.localizationDir,
             versionName: constants_1.CURRENT_VERSION_NAME,
             pluginId: options.id,
         })