@docusaurus/plugin-content-docs 0.0.0-5362 → 0.0.0-5363

package/lib/client/index.d.ts

@@ -24,7 +24,8 @@ export declare type GlobalDoc = {
      */
     id: string;
     path: string;
-    sidebar: string | undefined;
+    sidebar?: string;
+    unlisted?: boolean;
 };
 export declare type GlobalVersion = {
     name: string;

package/lib/docs.d.ts

@@ -18,7 +18,11 @@ export declare function processDocMetadata(args: {
     options: MetadataOptions;
     env: DocEnv;
 }): Promise<DocMetadataBase>;
-export declare function addDocNavigation(docsBase: DocMetadataBase[], sidebarsUtils: SidebarsUtils, sidebarFilePath: string): LoadedVersion['docs'];
+export declare function addDocNavigation({ docs, sidebarsUtils, sidebarFilePath, }: {
+    docs: DocMetadataBase[];
+    sidebarsUtils: SidebarsUtils;
+    sidebarFilePath: string;
+}): LoadedVersion['docs'];
 /**
  * The "main doc" is the "version entry point"
  * We browse this doc by clicking on a version:

package/lib/docs.js

@@ -64,10 +64,6 @@ async function readVersionDocs(versionMetadata, 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;
-}
 async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
     const { source, content, contentPath, filePath } = docFile;
     const { siteDir, i18n } = context;
@@ -150,7 +146,8 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
         }
         return undefined;
     }
-    const draft = isDraftForEnvironment({ env, frontMatter });
+    const draft = (0, utils_1.isDraft)({ env, frontMatter });
+    const unlisted = (0, utils_1.isUnlisted)({ env, frontMatter });
     const formatDate = (locale, date, calendar) => {
         try {
             return new Intl.DateTimeFormat(locale, {
@@ -180,6 +177,7 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
         slug: docSlug,
         permalink,
         draft,
+        unlisted,
         editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
         tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
         version: versionMetadata.versionName,
@@ -201,12 +199,21 @@ async function processDocMetadata(args) {
     }
 }
 exports.processDocMetadata = processDocMetadata;
-function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
-    const docsById = createDocsByIdIndex(docsBase);
-    sidebarsUtils.checkSidebarsDocIds(docsBase.flatMap(getDocIds), sidebarFilePath);
+function getUnlistedIds(docs) {
+    return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
+}
+function addDocNavigation({ docs, sidebarsUtils, sidebarFilePath, }) {
+    const docsById = createDocsByIdIndex(docs);
+    const unlistedIds = getUnlistedIds(docs);
+    sidebarsUtils.checkSidebarsDocIds(docs.flatMap(getDocIds), sidebarFilePath);
     // Add sidebar/next/previous to the docs
     function addNavData(doc) {
-        const navigation = sidebarsUtils.getDocNavigation(doc.unversionedId, doc.id, doc.frontMatter.displayed_sidebar);
+        const navigation = sidebarsUtils.getDocNavigation({
+            unversionedId: doc.unversionedId,
+            versionedId: doc.id,
+            displayedSidebar: doc.frontMatter.displayed_sidebar,
+            unlistedIds,
+        });
         const toNavigationLinkByDocId = (docId, type) => {
             if (!docId) {
                 return undefined;
@@ -216,6 +223,10 @@ function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
                 // This could only happen if user provided the ID through front matter
                 throw new Error(`Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`);
             }
+            // Gracefully handle explicitly providing an unlisted doc ID in production
+            if (navDoc.unlisted) {
+                return undefined;
+            }
             return (0, utils_2.toDocNavigationLink)(navDoc);
         };
         const previous = doc.frontMatter.pagination_prev !== undefined
@@ -226,7 +237,7 @@ function addDocNavigation(docsBase, sidebarsUtils, sidebarFilePath) {
             : (0, utils_2.toNavigationLink)(navigation.next, docsById);
         return { ...doc, sidebar: navigation.sidebarName, previous, next };
     }
-    const docsWithNavigation = docsBase.map(addNavData);
+    const docsWithNavigation = docs.map(addNavData);
     // Sort to ensure consistent output for tests
     docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
     return docsWithNavigation;

package/lib/frontMatter.js

@@ -35,7 +35,6 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     parse_number_prefixes: utils_validation_1.JoiFrontMatter.boolean(),
     pagination_next: utils_validation_1.JoiFrontMatter.string().allow(null),
     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(),
@@ -46,7 +45,9 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
         'object.missing': FrontMatterLastUpdateErrorMessage,
         'object.base': FrontMatterLastUpdateErrorMessage,
     }),
-}).unknown();
+})
+    .unknown()
+    .concat(utils_validation_1.ContentVisibilitySchema);
 function validateDocFrontMatter(frontMatter) {
     return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);
 }

package/lib/globalData.js

@@ -14,6 +14,9 @@ function toGlobalDataDoc(doc) {
     return {
         id: doc.unversionedId,
         path: doc.permalink,
+        // optimize global data size: do not add unlisted: false/undefined
+        ...(doc.unlisted && { unlisted: doc.unlisted }),
+        // TODO optimize size? remove attribute when no sidebar (breaking change?)
         sidebar: doc.sidebar,
     };
 }

package/lib/index.js

@@ -31,6 +31,8 @@ async function pluginContentDocs(context, options) {
     const pluginDataDirRoot = path_1.default.join(generatedFilesDir, 'docusaurus-plugin-content-docs');
     const dataDir = path_1.default.join(pluginDataDirRoot, pluginId);
     const aliasedSource = (source) => `~docs/${(0, utils_1.posixPath)(path_1.default.relative(pluginDataDirRoot, source))}`;
+    // TODO env should be injected into all plugins
+    const env = process.env.NODE_ENV;
     return {
         name: 'docusaurus-plugin-content-docs',
         extendCli(cli) {
@@ -77,13 +79,16 @@ async function pluginContentDocs(context, options) {
                         versionMetadata,
                         context,
                         options,
-                        env: process.env.NODE_ENV,
+                        env,
                     });
                 }
                 return Promise.all(docFiles.map(processVersionDoc));
             }
             async function doLoadVersion(versionMetadata) {
                 const docsBase = await loadVersionDocsBase(versionMetadata);
+                // TODO we only ever need draftIds in further code, not full draft items
+                // To simplify and prevent mistakes, avoid exposing draft
+                // replace draft=>draftIds in content loaded
                 const [drafts, docs] = lodash_1.default.partition(docsBase, (doc) => doc.draft);
                 const sidebars = await (0, sidebars_1.loadSidebars)(versionMetadata.sidebarFilePath, {
                     sidebarItemsGenerator: options.sidebarItemsGenerator,
@@ -100,7 +105,11 @@ async function pluginContentDocs(context, options) {
                 const sidebarsUtils = (0, utils_2.createSidebarsUtils)(sidebars);
                 return {
                     ...versionMetadata,
-                    docs: (0, docs_1.addDocNavigation)(docs, sidebarsUtils, versionMetadata.sidebarFilePath),
+                    docs: (0, docs_1.addDocNavigation)({
+                        docs,
+                        sidebarsUtils,
+                        sidebarFilePath: versionMetadata.sidebarFilePath,
+                    }),
                     drafts,
                     sidebars,
                 };

package/lib/props.d.ts

@@ -5,7 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { VersionTag, VersionTags } from './types';
-import type { PropSidebars, PropVersionMetadata, PropTagDocList, PropTagsListPage, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
+import type { SidebarItemDoc } from './sidebars/types';
+import type { PropSidebars, PropVersionMetadata, PropTagDocList, PropTagsListPage, PropSidebarItemLink, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
+export declare function toSidebarDocItemLinkProp({ item, doc, }: {
+    item: SidebarItemDoc;
+    doc: Pick<DocMetadata, 'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter' | 'unversionedId'>;
+}): PropSidebarItemLink;
 export declare function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars;
 export declare function toVersionMetadataProp(pluginId: string, loadedVersion: LoadedVersion): PropVersionMetadata;
 export declare function toTagDocListProp({ allTagsPath, tag, docs, }: {

package/lib/props.js

@@ -6,10 +6,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toTagsListTagsProp = exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
+exports.toTagsListTagsProp = exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = exports.toSidebarDocItemLinkProp = void 0;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const docs_1 = require("./docs");
+function toSidebarDocItemLinkProp({ item, doc, }) {
+    const { title, permalink, frontMatter: { sidebar_label: sidebarLabel, sidebar_custom_props: customProps, }, unlisted, unversionedId, } = doc;
+    return {
+        type: 'link',
+        label: sidebarLabel ?? item.label ?? title,
+        href: permalink,
+        className: item.className,
+        customProps: item.customProps ?? customProps,
+        docId: unversionedId,
+        unlisted,
+    };
+}
+exports.toSidebarDocItemLinkProp = toSidebarDocItemLinkProp;
 function toSidebarsProp(loadedVersion) {
     const docsById = (0, docs_1.createDocsByIdIndex)(loadedVersion.docs);
     function getDocById(docId) {
@@ -22,16 +35,8 @@ Available document ids are:
         return docMetadata;
     }
     const convertDocLink = (item) => {
-        const docMetadata = getDocById(item.id);
-        const { title, permalink, frontMatter: { sidebar_label: sidebarLabel }, } = docMetadata;
-        return {
-            type: 'link',
-            label: sidebarLabel ?? item.label ?? title,
-            href: permalink,
-            className: item.className,
-            customProps: item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
-            docId: docMetadata.unversionedId,
-        };
+        const doc = getDocById(item.id);
+        return toSidebarDocItemLinkProp({ item, doc });
     };
     function getCategoryLinkHref(link) {
         switch (link?.type) {
@@ -43,6 +48,12 @@ Available document ids are:
                 return undefined;
         }
     }
+    function getCategoryLinkUnlisted(link) {
+        if (link?.type === 'doc') {
+            return getDocById(link.id).unlisted;
+        }
+        return false;
+    }
     function getCategoryLinkCustomProps(link) {
         switch (link?.type) {
             case 'doc':
@@ -54,11 +65,13 @@ Available document ids are:
     function convertCategory(item) {
         const { link, ...rest } = item;
         const href = getCategoryLinkHref(link);
+        const linkUnlisted = getCategoryLinkUnlisted(link);
         const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
         return {
             ...rest,
             items: item.items.map(normalizeItem),
             ...(href && { href }),
+            ...(linkUnlisted && { linkUnlisted }),
             ...(customProps && { customProps }),
         };
     }
@@ -124,11 +137,14 @@ function toTagDocListProp({ allTagsPath, tag, docs, }) {
         allTagsPath,
         count: tag.docIds.length,
         items: toDocListProp(),
+        unlisted: tag.unlisted,
     };
 }
 exports.toTagDocListProp = toTagDocListProp;
 function toTagsListTagsProp(versionTags) {
-    return Object.values(versionTags).map((tagValue) => ({
+    return Object.values(versionTags)
+        .filter((tagValue) => !tagValue.unlisted)
+        .map((tagValue) => ({
         label: tagValue.label,
         permalink: tagValue.permalink,
         count: tagValue.docIds.length,

package/lib/sidebars/types.d.ts

@@ -120,9 +120,11 @@ export declare type Sidebars = {
 export declare type PropSidebarItemCategory = Expand<SidebarItemCategoryBase & {
     items: PropSidebarItem[];
     href?: string;
+    linkUnlisted?: boolean;
 }>;
 export declare type PropSidebarItemLink = SidebarItemLink & {
     docId?: string;
+    unlisted?: boolean;
 };
 export declare type PropSidebarItemHtml = SidebarItemHtml;
 export declare type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;

package/lib/sidebars/utils.d.ts

@@ -29,7 +29,12 @@ export declare 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) => SidebarNavigation;
     /**

package/lib/sidebars/utils.js

@@ -110,7 +110,7 @@ function createSidebarsUtils(sidebars) {
             next: undefined,
         };
     }
-    function getDocNavigation(unversionedId, versionedId, displayedSidebar) {
+    function getDocNavigation({ unversionedId, versionedId, displayedSidebar, unlistedIds, }) {
         // TODO legacy id retro-compatibility!
         let docId = unversionedId;
         let sidebarName = displayedSidebar === undefined
@@ -123,10 +123,22 @@ function createSidebarsUtils(sidebars) {
         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;

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;

package/lib/types.d.ts

@@ -19,6 +19,7 @@ export declare type SourceToPermalink = {
 export declare type VersionTag = Tag & {
     /** All doc ids having this tag. */
     docIds: string[];
+    unlisted: boolean;
 };
 export declare type VersionTags = {
     [permalink: string]: VersionTag;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-5362",
+  "version": "0.0.0-5363",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,13 +35,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5362",
-    "@docusaurus/logger": "0.0.0-5362",
-    "@docusaurus/mdx-loader": "0.0.0-5362",
-    "@docusaurus/module-type-aliases": "0.0.0-5362",
-    "@docusaurus/types": "0.0.0-5362",
-    "@docusaurus/utils": "0.0.0-5362",
-    "@docusaurus/utils-validation": "0.0.0-5362",
+    "@docusaurus/core": "0.0.0-5363",
+    "@docusaurus/logger": "0.0.0-5363",
+    "@docusaurus/mdx-loader": "0.0.0-5363",
+    "@docusaurus/module-type-aliases": "0.0.0-5363",
+    "@docusaurus/types": "0.0.0-5363",
+    "@docusaurus/utils": "0.0.0-5363",
+    "@docusaurus/utils-validation": "0.0.0-5363",
     "@types/react-router-config": "^5.0.6",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.1.0",
@@ -67,5 +67,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "c3bef651473ab5aabf0b28f56c2e3d680a3d5615"
+  "gitHead": "dbe94ffd19b3e3eb1dcb64e85b61350045faa250"
 }

package/src/client/index.ts

@@ -37,7 +37,8 @@ export type GlobalDoc = {
    */
   id: string;
   path: string;
-  sidebar: string | undefined;
+  sidebar?: string;
+  unlisted?: boolean;
 };
 
 export type GlobalVersion = {

package/src/docs.ts

@@ -18,6 +18,8 @@ import {
   posixPath,
   Globby,
   normalizeFrontMatterTags,
+  isUnlisted,
+  isDraft,
 } from '@docusaurus/utils';
 
 import {getFileLastUpdate} from './lastUpdate';
@@ -35,7 +37,6 @@ import type {
   PropNavigationLink,
   LastUpdateData,
   VersionMetadata,
-  DocFrontMatter,
   LoadedVersion,
   FileChange,
 } from '@docusaurus/plugin-content-docs';
@@ -125,17 +126,6 @@ export async function readVersionDocs(
 
 export type DocEnv = 'production' | 'development';
 
-/** Docs with draft front matter are only considered draft in production. */
-function isDraftForEnvironment({
-  env,
-  frontMatter,
-}: {
-  frontMatter: DocFrontMatter;
-  env: DocEnv;
-}): boolean {
-  return (env === 'production' && frontMatter.draft) ?? false;
-}
-
 async function doProcessDocMetadata({
   docFile,
   versionMetadata,
@@ -268,7 +258,8 @@ async function doProcessDocMetadata({
     return undefined;
   }
 
-  const draft = isDraftForEnvironment({env, frontMatter});
+  const draft = isDraft({env, frontMatter});
+  const unlisted = isUnlisted({env, frontMatter});
 
   const formatDate = (locale: string, date: Date, calendar: string): string => {
     try {
@@ -299,6 +290,7 @@ async function doProcessDocMetadata({
     slug: docSlug,
     permalink,
     draft,
+    unlisted,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
     tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
@@ -333,25 +325,32 @@ export async function processDocMetadata(args: {
   }
 }
 
-export function addDocNavigation(
-  docsBase: DocMetadataBase[],
-  sidebarsUtils: SidebarsUtils,
-  sidebarFilePath: string,
-): LoadedVersion['docs'] {
-  const docsById = createDocsByIdIndex(docsBase);
+function getUnlistedIds(docs: DocMetadataBase[]): Set<string> {
+  return new Set(docs.filter((doc) => doc.unlisted).map((doc) => doc.id));
+}
 
-  sidebarsUtils.checkSidebarsDocIds(
-    docsBase.flatMap(getDocIds),
-    sidebarFilePath,
-  );
+export function addDocNavigation({
+  docs,
+  sidebarsUtils,
+  sidebarFilePath,
+}: {
+  docs: DocMetadataBase[];
+  sidebarsUtils: SidebarsUtils;
+  sidebarFilePath: string;
+}): LoadedVersion['docs'] {
+  const docsById = createDocsByIdIndex(docs);
+  const unlistedIds = getUnlistedIds(docs);
+
+  sidebarsUtils.checkSidebarsDocIds(docs.flatMap(getDocIds), sidebarFilePath);
 
   // Add sidebar/next/previous to the docs
   function addNavData(doc: DocMetadataBase): DocMetadata {
-    const navigation = sidebarsUtils.getDocNavigation(
-      doc.unversionedId,
-      doc.id,
-      doc.frontMatter.displayed_sidebar,
-    );
+    const navigation = sidebarsUtils.getDocNavigation({
+      unversionedId: doc.unversionedId,
+      versionedId: doc.id,
+      displayedSidebar: doc.frontMatter.displayed_sidebar,
+      unlistedIds,
+    });
 
     const toNavigationLinkByDocId = (
       docId: string | null | undefined,
@@ -367,6 +366,10 @@ export function addDocNavigation(
           `Error when loading ${doc.id} in ${doc.sourceDirName}: the pagination_${type} front matter points to a non-existent ID ${docId}.`,
         );
       }
+      // Gracefully handle explicitly providing an unlisted doc ID in production
+      if (navDoc.unlisted) {
+        return undefined;
+      }
       return toDocNavigationLink(navDoc);
     };
 
@@ -382,7 +385,7 @@ export function addDocNavigation(
     return {...doc, sidebar: navigation.sidebarName, previous, next};
   }
 
-  const docsWithNavigation = docsBase.map(addNavData);
+  const docsWithNavigation = docs.map(addNavData);
   // Sort to ensure consistent output for tests
   docsWithNavigation.sort((a, b) => a.id.localeCompare(b.id));
   return docsWithNavigation;

package/src/frontMatter.ts

@@ -11,6 +11,7 @@ import {
   FrontMatterTagsSchema,
   FrontMatterTOCHeadingLevels,
   validateFrontMatter,
+  ContentVisibilitySchema,
 } from '@docusaurus/utils-validation';
 import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 
@@ -43,7 +44,6 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   parse_number_prefixes: Joi.boolean(),
   pagination_next: Joi.string().allow(null),
   pagination_prev: Joi.string().allow(null),
-  draft: Joi.boolean(),
   ...FrontMatterTOCHeadingLevels,
   last_update: Joi.object({
     author: Joi.string(),
@@ -54,7 +54,9 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
       'object.missing': FrontMatterLastUpdateErrorMessage,
       'object.base': FrontMatterLastUpdateErrorMessage,
     }),
-}).unknown();
+})
+  .unknown()
+  .concat(ContentVisibilitySchema);
 
 export function validateDocFrontMatter(frontMatter: {
   [key: string]: unknown;

package/src/globalData.ts

@@ -23,6 +23,11 @@ function toGlobalDataDoc(doc: DocMetadata): GlobalDoc {
   return {
     id: doc.unversionedId,
     path: doc.permalink,
+
+    // optimize global data size: do not add unlisted: false/undefined
+    ...(doc.unlisted && {unlisted: doc.unlisted}),
+
+    // TODO optimize size? remove attribute when no sidebar (breaking change?)
     sidebar: doc.sidebar,
   };
 }

package/src/index.ts

@@ -75,6 +75,9 @@ export default async function pluginContentDocs(
   const aliasedSource = (source: string) =>
     `~docs/${posixPath(path.relative(pluginDataDirRoot, source))}`;
 
+  // TODO env should be injected into all plugins
+  const env = process.env.NODE_ENV as DocEnv;
+
   return {
     name: 'docusaurus-plugin-content-docs',
 
@@ -143,7 +146,7 @@ export default async function pluginContentDocs(
             versionMetadata,
             context,
             options,
-            env: process.env.NODE_ENV as DocEnv,
+            env,
           });
         }
         return Promise.all(docFiles.map(processVersionDoc));
@@ -156,6 +159,9 @@ export default async function pluginContentDocs(
           versionMetadata,
         );
 
+        // TODO we only ever need draftIds in further code, not full draft items
+        // To simplify and prevent mistakes, avoid exposing draft
+        // replace draft=>draftIds in content loaded
         const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
 
         const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
@@ -175,11 +181,11 @@ export default async function pluginContentDocs(
 
         return {
           ...versionMetadata,
-          docs: addDocNavigation(
+          docs: addDocNavigation({
             docs,
             sidebarsUtils,
-            versionMetadata.sidebarFilePath as string,
-          ),
+            sidebarFilePath: versionMetadata.sidebarFilePath as string,
+          }),
           drafts,
           sidebars,
         };

package/src/plugin-content-docs.d.ts

@@ -398,6 +398,8 @@ declare module '@docusaurus/plugin-content-docs' {
     pagination_prev?: string | null;
     /** Should this doc be excluded from production builds? */
     draft?: boolean;
+    /** Should this doc be accessible but hidden in production builds? */
+    unlisted?: boolean;
     /** Allows overriding the last updated author and/or date. */
     last_update?: FileChange;
   };
@@ -448,6 +450,11 @@ declare module '@docusaurus/plugin-content-docs' {
      * Draft docs will be excluded for production environment.
      */
     draft: boolean;
+    /**
+     * Unlisted docs are accessible when directly visible, but will be hidden
+     * from the sidebar and pagination in production.
+     */
+    unlisted: boolean;
     /**
      * Position in an autogenerated sidebar slice, acquired through front matter
      * or number prefix.

package/src/props.ts

@@ -28,6 +28,37 @@ import type {
   LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
 
+export function toSidebarDocItemLinkProp({
+  item,
+  doc,
+}: {
+  item: SidebarItemDoc;
+  doc: Pick<
+    DocMetadata,
+    'id' | 'title' | 'permalink' | 'unlisted' | 'frontMatter' | 'unversionedId'
+  >;
+}): PropSidebarItemLink {
+  const {
+    title,
+    permalink,
+    frontMatter: {
+      sidebar_label: sidebarLabel,
+      sidebar_custom_props: customProps,
+    },
+    unlisted,
+    unversionedId,
+  } = doc;
+  return {
+    type: 'link',
+    label: sidebarLabel ?? item.label ?? title,
+    href: permalink,
+    className: item.className,
+    customProps: item.customProps ?? customProps,
+    docId: unversionedId,
+    unlisted,
+  };
+}
+
 export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
   const docsById = createDocsByIdIndex(loadedVersion.docs);
 
@@ -44,21 +75,8 @@ Available document ids are:
   }
 
   const convertDocLink = (item: SidebarItemDoc): PropSidebarItemLink => {
-    const docMetadata = getDocById(item.id);
-    const {
-      title,
-      permalink,
-      frontMatter: {sidebar_label: sidebarLabel},
-    } = docMetadata;
-    return {
-      type: 'link',
-      label: sidebarLabel ?? item.label ?? title,
-      href: permalink,
-      className: item.className,
-      customProps:
-        item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
-      docId: docMetadata.unversionedId,
-    };
+    const doc = getDocById(item.id);
+    return toSidebarDocItemLinkProp({item, doc});
   };
 
   function getCategoryLinkHref(
@@ -74,6 +92,15 @@ Available document ids are:
     }
   }
 
+  function getCategoryLinkUnlisted(
+    link: SidebarItemCategoryLink | undefined,
+  ): boolean {
+    if (link?.type === 'doc') {
+      return getDocById(link.id).unlisted;
+    }
+    return false;
+  }
+
   function getCategoryLinkCustomProps(
     link: SidebarItemCategoryLink | undefined,
   ) {
@@ -88,12 +115,14 @@ Available document ids are:
   function convertCategory(item: SidebarItemCategory): PropSidebarItemCategory {
     const {link, ...rest} = item;
     const href = getCategoryLinkHref(link);
+    const linkUnlisted = getCategoryLinkUnlisted(link);
     const customProps = item.customProps ?? getCategoryLinkCustomProps(link);
 
     return {
       ...rest,
       items: item.items.map(normalizeItem),
       ...(href && {href}),
+      ...(linkUnlisted && {linkUnlisted}),
       ...(customProps && {customProps}),
     };
   }
@@ -180,15 +209,18 @@ export function toTagDocListProp({
     allTagsPath,
     count: tag.docIds.length,
     items: toDocListProp(),
+    unlisted: tag.unlisted,
   };
 }
 
 export function toTagsListTagsProp(
   versionTags: VersionTags,
 ): PropTagsListPage['tags'] {
-  return Object.values(versionTags).map((tagValue) => ({
-    label: tagValue.label,
-    permalink: tagValue.permalink,
-    count: tagValue.docIds.length,
-  }));
+  return Object.values(versionTags)
+    .filter((tagValue) => !tagValue.unlisted)
+    .map((tagValue) => ({
+      label: tagValue.label,
+      permalink: tagValue.permalink,
+      count: tagValue.docIds.length,
+    }));
 }

package/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;

package/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;

package/src/tags.ts

@@ -6,15 +6,22 @@
  */
 
 import _ from 'lodash';
-import {groupTaggedItems} from '@docusaurus/utils';
+import {getTagVisibility, groupTaggedItems} from '@docusaurus/utils';
 import type {VersionTags} from './types';
 import type {DocMetadata} from '@docusaurus/plugin-content-docs';
 
 export function getVersionTags(docs: DocMetadata[]): VersionTags {
   const groups = groupTaggedItems(docs, (doc) => doc.tags);
-  return _.mapValues(groups, (group) => ({
-    label: group.tag.label,
-    docIds: group.items.map((item) => item.id),
-    permalink: group.tag.permalink,
-  }));
+  return _.mapValues(groups, ({tag, items: tagDocs}) => {
+    const tagVisibility = getTagVisibility({
+      items: tagDocs,
+      isUnlisted: (item) => item.unlisted,
+    });
+    return {
+      label: tag.label,
+      docIds: tagVisibility.listedItems.map((item) => item.id),
+      permalink: tag.permalink,
+      unlisted: tagVisibility.unlisted,
+    };
+  });
 }

package/src/types.ts

@@ -27,6 +27,7 @@ export type SourceToPermalink = {
 export type VersionTag = Tag & {
   /** All doc ids having this tag. */
   docIds: string[];
+  unlisted: boolean;
 };
 export type VersionTags = {
   [permalink: string]: VersionTag;