@docusaurus/plugin-content-docs 2.4.1 → 3.0.0-beta.0

package/lib/routes.js

@@ -6,20 +6,22 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createVersionRoutes = exports.createDocRoutes = exports.createCategoryGeneratedIndexRoutes = void 0;
+exports.createAllRoutes = exports.buildAllRoutes = void 0;
 const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const props_1 = require("./props");
-async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }) {
+const tags_1 = require("./tags");
+async function buildVersionCategoryGeneratedIndexRoutes({ version, actions, options, aliasedSource, }) {
     const slugs = (0, utils_1.createSlugger)();
-    async function createCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
+    async function buildCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
         const { sidebar, ...prop } = categoryGeneratedIndex;
         const propFileName = slugs.slug(`${version.path}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`);
         const propData = await actions.createData(`${(0, utils_1.docuHash)(`category/${propFileName}`)}.json`, JSON.stringify(prop, null, 2));
         return {
             path: categoryGeneratedIndex.permalink,
-            component: docCategoryGeneratedIndexComponent,
+            component: options.docCategoryGeneratedIndexComponent,
             exact: true,
             modules: {
                 categoryGeneratedIndex: aliasedSource(propData),
@@ -29,23 +31,22 @@ async function createCategoryGeneratedIndexRoutes({ version, actions, docCategor
             ...(sidebar && { sidebar }),
         };
     }
-    return Promise.all(version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute));
+    return Promise.all(version.categoryGeneratedIndices.map(buildCategoryGeneratedIndexRoute));
 }
-exports.createCategoryGeneratedIndexRoutes = createCategoryGeneratedIndexRoutes;
-async function createDocRoutes({ docs, actions, docItemComponent, }) {
-    return Promise.all(docs.map(async (metadataItem) => {
+async function buildVersionDocRoutes({ version, actions, options, }) {
+    return Promise.all(version.docs.map(async (metadataItem) => {
         await actions.createData(
         // Note that this created data path must be in sync with
         // metadataPath provided to mdx-loader.
         `${(0, utils_1.docuHash)(metadataItem.source)}.json`, JSON.stringify(metadataItem, null, 2));
         const docRoute = {
             path: metadataItem.permalink,
-            component: docItemComponent,
+            component: options.docItemComponent,
             exact: true,
             modules: {
                 content: metadataItem.source,
             },
-            // Because the parent (DocPage) comp need to access it easily
+            // Because the parent (DocRoot) comp need to access it easily
             // This permits to render the sidebar once without unmount/remount when
             // navigating (and preserve sidebar state)
             ...(metadataItem.sidebar && {
@@ -55,42 +56,113 @@ async function createDocRoutes({ docs, actions, docItemComponent, }) {
         return docRoute;
     }));
 }
-exports.createDocRoutes = createDocRoutes;
-async function createVersionRoutes({ version, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }) {
-    async function doCreateVersionRoutes() {
-        const versionMetadata = (0, props_1.toVersionMetadataProp)(pluginId, version);
-        const versionMetadataPropPath = await actions.createData(`${(0, utils_1.docuHash)(`version-${version.versionName}-metadata-prop`)}.json`, JSON.stringify(versionMetadata, null, 2));
-        async function createVersionSubRoutes() {
-            const [docRoutes, sidebarsRoutes] = await Promise.all([
-                createDocRoutes({ docs: version.docs, actions, docItemComponent }),
-                createCategoryGeneratedIndexRoutes({
-                    version,
-                    actions,
-                    docCategoryGeneratedIndexComponent,
-                    aliasedSource,
-                }),
-            ]);
-            const routes = [...docRoutes, ...sidebarsRoutes];
-            return routes.sort((a, b) => a.path.localeCompare(b.path));
+async function buildVersionSidebarRoute(param) {
+    const [docRoutes, categoryGeneratedIndexRoutes] = await Promise.all([
+        buildVersionDocRoutes(param),
+        buildVersionCategoryGeneratedIndexRoutes(param),
+    ]);
+    const subRoutes = [...docRoutes, ...categoryGeneratedIndexRoutes];
+    return {
+        path: param.version.path,
+        exact: false,
+        component: param.options.docRootComponent,
+        routes: subRoutes,
+    };
+}
+async function buildVersionTagsRoutes(param) {
+    const { version, options, actions, aliasedSource } = param;
+    const versionTags = (0, tags_1.getVersionTags)(version.docs);
+    async function buildTagsListRoute() {
+        // Don't create a tags list page if there's no tag
+        if (Object.keys(versionTags).length === 0) {
+            return null;
         }
-        actions.addRoute({
+        const tagsProp = (0, props_1.toTagsListTagsProp)(versionTags);
+        const tagsPropPath = await actions.createData(`${(0, utils_1.docuHash)(`tags-list-${version.versionName}-prop`)}.json`, JSON.stringify(tagsProp, null, 2));
+        return {
+            path: version.tagsPath,
+            exact: true,
+            component: options.docTagsListComponent,
+            modules: {
+                tags: aliasedSource(tagsPropPath),
+            },
+        };
+    }
+    async function buildTagDocListRoute(tag) {
+        const tagProps = (0, props_1.toTagDocListProp)({
+            allTagsPath: version.tagsPath,
+            tag,
+            docs: version.docs,
+        });
+        const tagPropPath = await actions.createData(`${(0, utils_1.docuHash)(`tag-${tag.permalink}`)}.json`, JSON.stringify(tagProps, null, 2));
+        return {
+            path: tag.permalink,
+            component: options.docTagDocListComponent,
+            exact: true,
+            modules: {
+                tag: aliasedSource(tagPropPath),
+            },
+        };
+    }
+    const [tagsListRoute, allTagsDocListRoutes] = await Promise.all([
+        buildTagsListRoute(),
+        Promise.all(Object.values(versionTags).map(buildTagDocListRoute)),
+    ]);
+    return lodash_1.default.compact([tagsListRoute, ...allTagsDocListRoutes]);
+}
+async function buildVersionRoutes(param) {
+    const { version, actions, options, aliasedSource } = param;
+    async function buildVersionSubRoutes() {
+        const [sidebarRoute, tagsRoutes] = await Promise.all([
+            buildVersionSidebarRoute(param),
+            buildVersionTagsRoutes(param),
+        ]);
+        return [sidebarRoute, ...tagsRoutes];
+    }
+    async function doBuildVersionRoutes() {
+        const versionProp = (0, props_1.toVersionMetadataProp)(options.id, version);
+        const versionPropPath = await actions.createData(`${(0, utils_1.docuHash)(`version-${version.versionName}-metadata-prop`)}.json`, JSON.stringify(versionProp, null, 2));
+        const subRoutes = await buildVersionSubRoutes();
+        return {
             path: version.path,
-            // Allow matching /docs/* since this is the wrapping route
             exact: false,
-            component: docLayoutComponent,
-            routes: await createVersionSubRoutes(),
+            component: options.docVersionRootComponent,
+            routes: subRoutes,
             modules: {
-                versionMetadata: aliasedSource(versionMetadataPropPath),
+                version: aliasedSource(versionPropPath),
             },
             priority: version.routePriority,
-        });
+        };
     }
     try {
-        return await doCreateVersionRoutes();
+        return await doBuildVersionRoutes();
     }
     catch (err) {
         logger_1.default.error `Can't create version routes for version name=${version.versionName}`;
         throw err;
     }
 }
-exports.createVersionRoutes = createVersionRoutes;
+// TODO we want this buildAllRoutes function to be easily testable
+// Ideally, we should avoid side effects here (ie not injecting actions)
+async function buildAllRoutes(param) {
+    const subRoutes = await Promise.all(param.versions.map((version) => buildVersionRoutes({
+        ...param,
+        version,
+    })));
+    // all docs routes are wrapped under a single parent route, this ensures
+    // the theme layout never unmounts/remounts when navigating between versions
+    return [
+        {
+            path: (0, utils_1.normalizeUrl)([param.baseUrl, param.options.routeBasePath]),
+            exact: false,
+            component: param.options.docsRootComponent,
+            routes: subRoutes,
+        },
+    ];
+}
+exports.buildAllRoutes = buildAllRoutes;
+async function createAllRoutes(param) {
+    const routes = await buildAllRoutes(param);
+    routes.forEach(param.actions.addRoute);
+}
+exports.createAllRoutes = createAllRoutes;

package/lib/sidebars/generator.js

@@ -91,7 +91,7 @@ Available doc IDs:
      */
     function generateSidebar(fsModel) {
         function createDocItem(id, fullPath, fileName) {
-            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className }, } = getDoc(id);
+            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className, sidebar_custom_props: customProps, }, } = getDoc(id);
             return {
                 type: 'doc',
                 id,
@@ -101,6 +101,7 @@ Available doc IDs:
                 // sidebar
                 ...(label !== undefined && { label }),
                 ...(className !== undefined && { className }),
+                ...(customProps !== undefined && { customProps }),
             };
         }
         function createCategoryItem(dir, fullPath, folderName) {

package/lib/sidebars/postProcessor.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { Sidebars, SidebarProcessorParams, ProcessedSidebars } from './types';
-export declare type SidebarPostProcessorParams = SidebarProcessorParams & {
+export type SidebarPostProcessorParams = SidebarProcessorParams & {
     draftIds: Set<string>;
 };
 export declare function postProcessSidebars(sidebars: ProcessedSidebars, params: SidebarProcessorParams): Sidebars;

package/lib/sidebars/postProcessor.js

@@ -10,7 +10,6 @@ exports.postProcessSidebars = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
-const docs_1 = require("../docs");
 function normalizeCategoryLink(category, params) {
     if (category.link?.type === 'doc' && params.draftIds.has(category.link.id)) {
         return undefined;
@@ -73,7 +72,7 @@ function postProcessSidebarItem(item, params) {
     return item;
 }
 function postProcessSidebars(sidebars, params) {
-    const draftIds = new Set(params.drafts.flatMap(docs_1.getDocIds));
+    const draftIds = new Set(params.drafts.map((d) => d.id));
     return lodash_1.default.mapValues(sidebars, (sidebar) => sidebar
         .map((item) => postProcessSidebarItem(item, { ...params, draftIds }))
         .filter((v) => Boolean(v)));

package/lib/sidebars/processor.js

@@ -16,7 +16,6 @@ const docs_1 = require("../docs");
 function toSidebarItemsGeneratorDoc(doc) {
     return lodash_1.default.pick(doc, [
         'id',
-        'unversionedId',
         'title',
         'frontMatter',
         'source',

package/lib/sidebars/types.d.ts

@@ -7,18 +7,18 @@
 import type { Optional, Required } from 'utility-types';
 import type { NumberPrefixParser, SidebarOptions, CategoryIndexMatcher, DocMetadataBase, VersionMetadata } from '@docusaurus/plugin-content-docs';
 import type { Slugger } from '@docusaurus/utils';
-declare type Expand<T extends {
+type Expand<T extends {
     [x: string]: unknown;
 }> = {
     [P in keyof T]: T[P];
 };
-export declare type SidebarItemBase = {
+export type SidebarItemBase = {
     className?: string;
     customProps?: {
         [key: string]: unknown;
     };
 };
-export declare type SidebarItemDoc = SidebarItemBase & {
+export type SidebarItemDoc = SidebarItemBase & {
     type: 'doc' | 'ref';
     label?: string;
     id: string;
@@ -28,34 +28,34 @@ export declare type SidebarItemDoc = SidebarItemBase & {
      */
     translatable?: true;
 };
-export declare type SidebarItemHtml = SidebarItemBase & {
+export type SidebarItemHtml = SidebarItemBase & {
     type: 'html';
     value: string;
     defaultStyle?: boolean;
 };
-export declare type SidebarItemLink = SidebarItemBase & {
+export type SidebarItemLink = SidebarItemBase & {
     type: 'link';
     href: string;
     label: string;
     autoAddBaseUrl?: boolean;
     description?: string;
 };
-export declare type SidebarItemAutogenerated = SidebarItemBase & {
+export type SidebarItemAutogenerated = SidebarItemBase & {
     type: 'autogenerated';
     dirName: string;
 };
-declare type SidebarItemCategoryBase = SidebarItemBase & {
+type SidebarItemCategoryBase = SidebarItemBase & {
     type: 'category';
     label: string;
     collapsed: boolean;
     collapsible: boolean;
     description?: string;
 };
-export declare type SidebarItemCategoryLinkDoc = {
+export type SidebarItemCategoryLinkDoc = {
     type: 'doc';
     id: string;
 };
-export declare type SidebarItemCategoryLinkGeneratedIndexConfig = {
+export type SidebarItemCategoryLinkGeneratedIndexConfig = {
     type: 'generated-index';
     slug?: string;
     title?: string;
@@ -63,7 +63,7 @@ export declare type SidebarItemCategoryLinkGeneratedIndexConfig = {
     image?: string;
     keywords?: string | readonly string[];
 };
-export declare type SidebarItemCategoryLinkGeneratedIndex = {
+export type SidebarItemCategoryLinkGeneratedIndex = {
     type: 'generated-index';
     slug: string;
     permalink: string;
@@ -72,68 +72,70 @@ export declare type SidebarItemCategoryLinkGeneratedIndex = {
     image?: string;
     keywords?: string | readonly string[];
 };
-export declare type SidebarItemCategoryLinkConfig = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndexConfig;
-export declare type SidebarItemCategoryLink = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
-export declare type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+export type SidebarItemCategoryLinkConfig = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndexConfig;
+export type SidebarItemCategoryLink = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
+export type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: SidebarCategoriesShorthand | SidebarItemConfig[];
     link?: SidebarItemCategoryLinkConfig;
 }>;
-export declare type SidebarCategoriesShorthand = {
+export type SidebarCategoriesShorthand = {
     [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
 };
-export declare type SidebarItemConfig = Omit<SidebarItemDoc, 'translatable'> | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
-export declare type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
-export declare type SidebarsConfig = {
+export type SidebarItemConfig = Omit<SidebarItemDoc, 'translatable'> | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
+export type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
+export type SidebarsConfig = {
     [sidebarId: string]: SidebarConfig;
 };
-export declare type NormalizedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+export type NormalizedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: NormalizedSidebarItem[];
     link?: SidebarItemCategoryLinkConfig;
 }>;
-export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
-export declare type NormalizedSidebar = NormalizedSidebarItem[];
-export declare type NormalizedSidebars = {
+export type NormalizedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
+export type NormalizedSidebar = NormalizedSidebarItem[];
+export type NormalizedSidebars = {
     [sidebarId: string]: NormalizedSidebar;
 };
-export declare type ProcessedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+export type ProcessedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: ProcessedSidebarItem[];
     link?: SidebarItemCategoryLinkConfig;
 }>;
-export declare type ProcessedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | ProcessedSidebarItemCategory;
-export declare type ProcessedSidebar = ProcessedSidebarItem[];
-export declare type ProcessedSidebars = {
+export type ProcessedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | ProcessedSidebarItemCategory;
+export type ProcessedSidebar = ProcessedSidebarItem[];
+export type ProcessedSidebars = {
     [sidebarId: string]: ProcessedSidebar;
 };
-export declare type SidebarItemCategory = Expand<SidebarItemCategoryBase & {
+export type SidebarItemCategory = Expand<SidebarItemCategoryBase & {
     items: SidebarItem[];
     link?: SidebarItemCategoryLink;
 }>;
-export declare type SidebarItemCategoryWithLink = Required<SidebarItemCategory, 'link'>;
-export declare type SidebarItemCategoryWithGeneratedIndex = SidebarItemCategoryWithLink & {
+export type SidebarItemCategoryWithLink = Required<SidebarItemCategory, 'link'>;
+export type SidebarItemCategoryWithGeneratedIndex = SidebarItemCategoryWithLink & {
     link: SidebarItemCategoryLinkGeneratedIndex;
 };
-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'];
-export declare type Sidebars = {
+export type SidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemCategory;
+export type SidebarNavigationItem = SidebarItemDoc | SidebarItemCategoryWithLink;
+export type Sidebar = SidebarItem[];
+export type SidebarItemType = SidebarItem['type'];
+export type Sidebars = {
     [sidebarId: string]: Sidebar;
 };
-export declare type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
+export type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
     items: PropSidebarItem[];
     href?: string;
+    linkUnlisted?: boolean;
 }>;
-export declare type PropSidebarItemLink = SidebarItemLink & {
+export type PropSidebarItemLink = SidebarItemLink & {
     docId?: string;
+    unlisted?: boolean;
 };
-export declare type PropSidebarItemHtml = SidebarItemHtml;
-export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;
-export declare type PropSidebar = PropSidebarItem[];
-export declare type PropSidebars = {
+export type PropSidebarItemHtml = SidebarItemHtml;
+export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;
+export type PropSidebar = PropSidebarItem[];
+export type PropSidebars = {
     [sidebarId: string]: PropSidebar;
 };
-export declare type PropSidebarBreadcrumbsItem = PropSidebarItemLink | PropSidebarItemCategory;
-export declare type CategoryMetadataFile = {
+export type PropSidebarBreadcrumbsItem = PropSidebarItemLink | PropSidebarItemCategory;
+export type CategoryMetadataFile = {
     label?: string;
     position?: number;
     collapsed?: boolean;
@@ -144,9 +146,9 @@ export declare type CategoryMetadataFile = {
         [key: string]: unknown;
     };
 };
-export declare type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'unversionedId' | 'title' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
-export declare type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
-export declare type SidebarItemsGeneratorArgs = {
+export type SidebarItemsGeneratorDoc = Pick<DocMetadataBase, 'id' | 'title' | 'frontMatter' | 'source' | 'sourceDirName' | 'sidebarPosition'>;
+export type SidebarItemsGeneratorVersion = Pick<VersionMetadata, 'versionName' | 'contentPath'>;
+export type SidebarItemsGeneratorArgs = {
     /** The sidebar item with type "autogenerated" to be transformed. */
     item: SidebarItemAutogenerated;
     /** Useful metadata for the version this sidebar belongs to. */
@@ -165,8 +167,8 @@ export declare type SidebarItemsGeneratorArgs = {
         [filePath: string]: CategoryMetadataFile;
     };
 };
-export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => NormalizedSidebar | Promise<NormalizedSidebar>;
-export declare type SidebarItemsGeneratorOption = (generatorArgs: {
+export type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => NormalizedSidebar | Promise<NormalizedSidebar>;
+export type SidebarItemsGeneratorOption = (generatorArgs: {
     /**
      * Useful to re-use/enhance the default sidebar generation logic from
      * Docusaurus.
@@ -174,7 +176,7 @@ export declare type SidebarItemsGeneratorOption = (generatorArgs: {
      */
     defaultSidebarItemsGenerator: SidebarItemsGenerator;
 } & SidebarItemsGeneratorArgs) => NormalizedSidebar | Promise<NormalizedSidebar>;
-export declare type SidebarProcessorParams = {
+export type SidebarProcessorParams = {
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
     numberPrefixParser: NumberPrefixParser;
     docs: DocMetadataBase[];

package/lib/sidebars/utils.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig, SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
-import type { DocMetadataBase, PropNavigationLink } from '@docusaurus/plugin-content-docs';
+import type { DocMetadataBase, PropNavigationLink, VersionMetadata } from '@docusaurus/plugin-content-docs';
 export declare function isCategoriesShorthand(item: SidebarItemConfig): item is SidebarCategoriesShorthand;
 export declare function transformSidebarItems(sidebar: Sidebar, updateFn: (item: SidebarItem) => SidebarItem): Sidebar;
 export declare function collectSidebarDocItems(sidebar: Sidebar): SidebarItemDoc[];
@@ -20,16 +20,20 @@ export declare function collectSidebarsDocIds(sidebars: Sidebars): {
 export declare function collectSidebarsNavigations(sidebars: Sidebars): {
     [sidebarId: string]: SidebarNavigationItem[];
 };
-export declare type SidebarNavigation = {
+export type SidebarNavigation = {
     sidebarName: string | undefined;
     previous: SidebarNavigationItem | undefined;
     next: SidebarNavigationItem | undefined;
 };
-export declare type SidebarsUtils = {
+export type SidebarsUtils = {
     sidebars: Sidebars;
     getFirstDocIdOfFirstSidebar: () => string | undefined;
     getSidebarNameByDocId: (docId: string) => string | undefined;
-    getDocNavigation: (unversionedId: string, versionedId: string, displayedSidebar: string | null | undefined) => SidebarNavigation;
+    getDocNavigation: (params: {
+        docId: string;
+        displayedSidebar: string | null | undefined;
+        unlistedIds: Set<string>;
+    }) => SidebarNavigation;
     getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
     getCategoryGeneratedIndexNavigation: (categoryGeneratedIndexPermalink: string) => SidebarNavigation;
     /**
@@ -46,7 +50,15 @@ export declare type SidebarsUtils = {
         permalink: string;
         label: string;
     } | undefined;
-    checkSidebarsDocIds: (validDocIds: string[], sidebarFilePath: string) => void;
+    checkLegacyVersionedSidebarNames: ({ versionMetadata, }: {
+        sidebarFilePath: string;
+        versionMetadata: VersionMetadata;
+    }) => void;
+    checkSidebarsDocIds: ({ allDocIds, sidebarFilePath, versionMetadata, }: {
+        allDocIds: string[];
+        sidebarFilePath: string;
+        versionMetadata: VersionMetadata;
+    }) => void;
 };
 export declare function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils;
 export declare function toDocNavigationLink(doc: DocMetadataBase): PropNavigationLink;

package/lib/sidebars/utils.js

@@ -110,23 +110,29 @@ function createSidebarsUtils(sidebars) {
             next: undefined,
         };
     }
-    function getDocNavigation(unversionedId, versionedId, displayedSidebar) {
-        // TODO legacy id retro-compatibility!
-        let docId = unversionedId;
-        let sidebarName = displayedSidebar === undefined
+    function getDocNavigation({ docId, displayedSidebar, unlistedIds, }) {
+        const sidebarName = displayedSidebar === undefined
             ? getSidebarNameByDocId(docId)
             : displayedSidebar;
-        if (sidebarName === undefined) {
-            docId = versionedId;
-            sidebarName = getSidebarNameByDocId(docId);
-        }
         if (!sidebarName) {
             return emptySidebarNavigation();
         }
-        const navigationItems = sidebarNameToNavigationItems[sidebarName];
+        let navigationItems = sidebarNameToNavigationItems[sidebarName];
         if (!navigationItems) {
             throw new Error(`Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`);
         }
+        // Filter unlisted items from navigation
+        navigationItems = navigationItems.filter((item) => {
+            if (item.type === 'doc' && unlistedIds.has(item.id)) {
+                return false;
+            }
+            if (item.type === 'category' &&
+                item.link.type === 'doc' &&
+                unlistedIds.has(item.link.id)) {
+                return false;
+            }
+            return true;
+        });
         const currentItemIndex = navigationItems.findIndex((item) => {
             if (item.type === 'doc') {
                 return item.id === docId;
@@ -174,16 +180,73 @@ function createSidebarsUtils(sidebars) {
             next: navigationItems[currentItemIndex + 1],
         };
     }
-    function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
+    // TODO remove in Docusaurus v4
+    function getLegacyVersionedPrefix(versionMetadata) {
+        return `version-${versionMetadata.versionName}/`;
+    }
+    // In early v2, sidebar names used to be versioned
+    // example: "version-2.0.0-alpha.66/my-sidebar-name"
+    // In v3 it's not the case anymore and we throw an error to explain
+    // TODO remove in Docusaurus v4
+    function checkLegacyVersionedSidebarNames({ versionMetadata, sidebarFilePath, }) {
+        const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+        const legacySidebarNames = Object.keys(sidebars).filter((sidebarName) => sidebarName.startsWith(illegalPrefix));
+        if (legacySidebarNames.length > 0) {
+            throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
+These legacy versioned sidebar names are not supported anymore in Docusaurus v3:
+- ${legacySidebarNames.sort().join('\n- ')}
+
+The sidebar names you should now use are:
+- ${legacySidebarNames
+                .sort()
+                .map((legacyName) => legacyName.split('/').splice(1).join('/'))
+                .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`);
+        }
+    }
+    // throw a better error message for Docusaurus v3 breaking change
+    // TODO this can be removed in Docusaurus v4
+    function handleLegacyVersionedDocIds({ invalidDocIds, sidebarFilePath, versionMetadata, }) {
+        const illegalPrefix = getLegacyVersionedPrefix(versionMetadata);
+        // In older v2.0 alpha/betas, versioned docs had a legacy versioned prefix
+        // Example: "version-1.4/my-doc-id"
+        //
+        const legacyVersionedDocIds = invalidDocIds.filter((docId) => docId.startsWith(illegalPrefix));
+        if (legacyVersionedDocIds.length > 0) {
+            throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
+These legacy versioned document ids are not supported anymore in Docusaurus v3:
+- ${legacyVersionedDocIds.sort().join('\n- ')}
+
+The document ids you should now use are:
+- ${legacyVersionedDocIds
+                .sort()
+                .map((legacyId) => legacyId.split('/').splice(1).join('/'))
+                .join('\n- ')}
+
+Please remove the "${illegalPrefix}" prefix from your versioned sidebar file.
+This breaking change is documented on Docusaurus v3 release notes: https://docusaurus.io/blog/releases/3.0
+`);
+        }
+    }
+    function checkSidebarsDocIds({ allDocIds, sidebarFilePath, versionMetadata, }) {
         const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
-        const invalidSidebarDocIds = lodash_1.default.difference(allSidebarDocIds, validDocIds);
-        if (invalidSidebarDocIds.length > 0) {
+        const invalidDocIds = lodash_1.default.difference(allSidebarDocIds, allDocIds);
+        if (invalidDocIds.length > 0) {
+            handleLegacyVersionedDocIds({
+                invalidDocIds,
+                sidebarFilePath,
+                versionMetadata,
+            });
             throw new Error(`Invalid sidebar file at "${(0, utils_1.toMessageRelativeFilePath)(sidebarFilePath)}".
 These sidebar document ids do not exist:
-- ${invalidSidebarDocIds.sort().join('\n- ')}
+- ${invalidDocIds.sort().join('\n- ')}
 
 Available document ids are:
-- ${lodash_1.default.uniq(validDocIds).sort().join('\n- ')}`);
+- ${lodash_1.default.uniq(allDocIds).sort().join('\n- ')}
+`);
         }
     }
     function getFirstLink(sidebar) {
@@ -225,6 +288,7 @@ Available document ids are:
         getDocNavigation,
         getCategoryGeneratedIndexList,
         getCategoryGeneratedIndexNavigation,
+        checkLegacyVersionedSidebarNames,
         checkSidebarsDocIds,
         getFirstLink: (id) => getFirstLink(sidebars[id]),
     };

package/lib/tags.js

@@ -12,10 +12,17 @@ const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 function getVersionTags(docs) {
     const groups = (0, utils_1.groupTaggedItems)(docs, (doc) => doc.tags);
-    return lodash_1.default.mapValues(groups, (group) => ({
-        label: group.tag.label,
-        docIds: group.items.map((item) => item.id),
-        permalink: group.tag.permalink,
-    }));
+    return lodash_1.default.mapValues(groups, ({ tag, items: tagDocs }) => {
+        const tagVisibility = (0, utils_1.getTagVisibility)({
+            items: tagDocs,
+            isUnlisted: (item) => item.unlisted,
+        });
+        return {
+            label: tag.label,
+            docIds: tagVisibility.listedItems.map((item) => item.id),
+            permalink: tag.permalink,
+            unlisted: tagVisibility.unlisted,
+        };
+    });
 }
 exports.getVersionTags = getVersionTags;