feat(docs,blog,pages): add support for "unlisted" front matter - hide md content in production (#8004)

Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/utils.test.ts

@@ -153,7 +153,14 @@ describe('createSidebarsUtils', () => {
   });
 
   it('getDocNavigation', () => {
-    expect(getDocNavigation('doc1', 'doc1', undefined)).toEqual({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc1',
+        versionedId: 'doc1',
+        displayedSidebar: undefined,
+        unlistedIds: new Set(),
+      }),
+    ).toEqual({
       sidebarName: 'sidebar1',
       previous: undefined,
       next: {
@@ -161,7 +168,14 @@ describe('createSidebarsUtils', () => {
         id: 'doc2',
       },
     });
-    expect(getDocNavigation('doc2', 'doc2', undefined)).toEqual({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc2',
+        versionedId: 'doc2',
+        displayedSidebar: undefined,
+        unlistedIds: new Set(),
+      }),
+    ).toEqual({
       sidebarName: 'sidebar1',
       previous: {
         type: 'doc',
@@ -170,7 +184,14 @@ describe('createSidebarsUtils', () => {
       next: undefined,
     });
 
-    expect(getDocNavigation('doc3', 'doc3', undefined)).toEqual({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc3',
+        versionedId: 'doc3',
+        displayedSidebar: undefined,
+        unlistedIds: new Set(),
+      }),
+    ).toEqual({
       sidebarName: 'sidebar2',
       previous: undefined,
       next: {
@@ -178,7 +199,14 @@ describe('createSidebarsUtils', () => {
         id: 'doc4',
       },
     });
-    expect(getDocNavigation('doc4', 'doc4', undefined)).toEqual({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc4',
+        versionedId: 'doc4',
+        displayedSidebar: undefined,
+        unlistedIds: new Set(),
+      }),
+    ).toEqual({
       sidebarName: 'sidebar2',
       previous: {
         type: 'doc',
@@ -188,7 +216,14 @@ describe('createSidebarsUtils', () => {
       next: undefined,
     });
 
-    expect(getDocNavigation('doc5', 'doc5', undefined)).toMatchObject({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc5',
+        versionedId: 'doc5',
+        displayedSidebar: undefined,
+        unlistedIds: new Set(),
+      }),
+    ).toMatchObject({
       sidebarName: 'sidebar3',
       previous: undefined,
       next: {
@@ -196,7 +231,14 @@ describe('createSidebarsUtils', () => {
         label: 'S3 SubCategory',
       },
     });
-    expect(getDocNavigation('doc6', 'doc6', undefined)).toMatchObject({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc6',
+        versionedId: 'doc6',
+        displayedSidebar: undefined,
+        unlistedIds: new Set(),
+      }),
+    ).toMatchObject({
       sidebarName: 'sidebar3',
       previous: {
         type: 'category',
@@ -207,7 +249,14 @@ describe('createSidebarsUtils', () => {
         id: 'doc7',
       },
     });
-    expect(getDocNavigation('doc7', 'doc7', undefined)).toEqual({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc7',
+        versionedId: 'doc7',
+        displayedSidebar: undefined,
+        unlistedIds: new Set(),
+      }),
+    ).toEqual({
       sidebarName: 'sidebar3',
       previous: {
         type: 'doc',
@@ -215,17 +264,36 @@ describe('createSidebarsUtils', () => {
       },
       next: undefined,
     });
-    expect(getDocNavigation('doc3', 'doc3', null)).toEqual({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc3',
+        versionedId: 'doc3',
+        displayedSidebar: null,
+        unlistedIds: new Set(),
+      }),
+    ).toEqual({
       sidebarName: undefined,
       previous: undefined,
       next: undefined,
     });
     expect(() =>
-      getDocNavigation('doc3', 'doc3', 'foo'),
+      getDocNavigation({
+        unversionedId: 'doc3',
+        versionedId: 'doc3',
+        displayedSidebar: 'foo',
+        unlistedIds: new Set(),
+      }),
     ).toThrowErrorMatchingInlineSnapshot(
       `"Doc with ID doc3 wants to display sidebar foo but a sidebar with this name doesn't exist"`,
     );
-    expect(getDocNavigation('doc3', 'doc3', 'sidebar1')).toEqual({
+    expect(
+      getDocNavigation({
+        unversionedId: 'doc3',
+        versionedId: 'doc3',
+        displayedSidebar: 'sidebar1',
+        unlistedIds: new Set(),
+      }),
+    ).toEqual({
       sidebarName: 'sidebar1',
       previous: undefined,
       next: undefined,

packages/docusaurus-plugin-content-docs/src/sidebars/types.ts

@@ -183,11 +183,18 @@ export type PropSidebarItemCategory = Expand<
   SidebarItemCategoryBase & {
     items: PropSidebarItem[];
     href?: string;
+
+    // Weird name => it would have been more convenient to have link.unlisted
+    // Note it is the category link that is unlisted, not the category itself
+    // We want to prevent users from clicking on an unlisted category link
+    // We can't use "href: undefined" otherwise sidebar item is not highlighted
+    linkUnlisted?: boolean;
   }
 >;
 
 export type PropSidebarItemLink = SidebarItemLink & {
   docId?: string;
+  unlisted?: boolean;
 };
 
 export type PropSidebarItemHtml = SidebarItemHtml;

packages/docusaurus-plugin-content-docs/src/sidebars/utils.ts

@@ -135,11 +135,12 @@ 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: {
+    unversionedId: string;
+    versionedId: string;
+    displayedSidebar: string | null | undefined;
+    unlistedIds: Set<string>;
+  }) => SidebarNavigation;
   getCategoryGeneratedIndexList: () => SidebarItemCategoryWithGeneratedIndex[];
   getCategoryGeneratedIndexNavigation: (
     categoryGeneratedIndexPermalink: string,
@@ -192,11 +193,17 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     };
   }
 
-  function getDocNavigation(
-    unversionedId: string,
-    versionedId: string,
-    displayedSidebar: string | null | undefined,
-  ): SidebarNavigation {
+  function getDocNavigation({
+    unversionedId,
+    versionedId,
+    displayedSidebar,
+    unlistedIds,
+  }: {
+    unversionedId: string;
+    versionedId: string;
+    displayedSidebar: string | null | undefined;
+    unlistedIds: Set<string>;
+  }): SidebarNavigation {
     // TODO legacy id retro-compatibility!
     let docId = unversionedId;
     let sidebarName =
@@ -211,12 +218,28 @@ export function createSidebarsUtils(sidebars: Sidebars): SidebarsUtils {
     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;