@docusaurus/plugin-content-docs 0.0.0-4859 → 0.0.0-4864

package/lib/docs.d.ts

@@ -11,11 +11,13 @@ import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, DocMetadataB
 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 readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
+export declare type DocEnv = 'production' | 'development';
 export declare function processDocMetadata(args: {
     docFile: DocFile;
     versionMetadata: VersionMetadata;
     context: LoadContext;
     options: MetadataOptions;
+    env: DocEnv;
 }): DocMetadataBase;
 export declare function addDocNavigation(docsBase: DocMetadataBase[], sidebarsUtils: SidebarsUtils, sidebarFilePath: string): LoadedVersion['docs'];
 /**

package/lib/docs.js

@@ -56,7 +56,11 @@ async function readVersionDocs(versionMetadata, options) {
     return Promise.all(sources.map((source) => readDocFile(versionMetadata, source, options)));
 }
 exports.readVersionDocs = readVersionDocs;
-function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
+/** 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;
     const { siteDir, i18n } = context;
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
@@ -139,6 +143,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         }
         return undefined;
     }
+    const draft = isDraftForEnvironment({ env, frontMatter });
     // Assign all of object properties during instantiation (if possible) for
     // NodeJS optimization.
     // Adding properties to object after instantiation will cause hidden
@@ -152,6 +157,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         sourceDirName,
         slug: docSlug,
         permalink,
+        draft,
         editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
         tags: (0, utils_1.normalizeFrontMatterTags)(versionMetadata.tagsPath, frontMatter.tags),
         version: versionMetadata.versionName,

package/lib/frontMatter.js

@@ -32,6 +32,7 @@ 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,
 }).unknown();
 function validateDocFrontMatter(frontMatter) {

package/lib/globalData.js

@@ -51,6 +51,7 @@ function toGlobalDataVersion(version) {
         docs: version.docs
             .map(toGlobalDataDoc)
             .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+        draftIds: version.drafts.map((doc) => doc.unversionedId),
         sidebars: toGlobalSidebars(version.sidebars, version),
     };
 }

package/lib/index.js

@@ -24,6 +24,7 @@ const tags_1 = require("./tags");
 const routes_1 = require("./routes");
 const utils_2 = require("./sidebars/utils");
 const categoryGeneratedIndex_1 = require("./categoryGeneratedIndex");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 async function pluginContentDocs(context, options) {
     const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
     // Mutate options to resolve sidebar path according to siteDir
@@ -81,16 +82,19 @@ async function pluginContentDocs(context, options) {
                         versionMetadata,
                         context,
                         options,
+                        env: process.env.NODE_ENV,
                     });
                 }
                 return Promise.all(docFiles.map(processVersionDoc));
             }
             async function doLoadVersion(versionMetadata) {
-                const docs = await loadVersionDocsBase(versionMetadata);
+                const docsBase = await loadVersionDocsBase(versionMetadata);
+                const [drafts, docs] = lodash_1.default.partition(docsBase, (doc) => doc.draft);
                 const sidebars = await (0, sidebars_1.loadSidebars)(versionMetadata.sidebarFilePath, {
                     sidebarItemsGenerator: options.sidebarItemsGenerator,
                     numberPrefixParser: options.numberPrefixParser,
                     docs,
+                    drafts,
                     version: versionMetadata,
                     sidebarOptions: {
                         sidebarCollapsed: options.sidebarCollapsed,
@@ -102,6 +106,7 @@ async function pluginContentDocs(context, options) {
                 return {
                     ...versionMetadata,
                     docs: (0, docs_1.addDocNavigation)(docs, sidebarsUtils, versionMetadata.sidebarFilePath),
+                    drafts,
                     sidebars,
                     mainDocId: (0, docs_1.getMainDocId)({ docs, sidebarsUtils }),
                     categoryGeneratedIndices: (0, categoryGeneratedIndex_1.getCategoryGeneratedIndexMetadataList)({

package/lib/sidebars/processor.js

@@ -30,7 +30,7 @@ function toSidebarItemsGeneratorVersion(version) {
 // Handle the generation of autogenerated sidebar items and other
 // post-processing checks
 async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
-    const { sidebarItemsGenerator, numberPrefixParser, docs, version } = params;
+    const { sidebarItemsGenerator, numberPrefixParser, docs, drafts, version } = params;
     // Just a minor lazy transformation optimization
     const getSidebarItemsGeneratorDocsAndVersion = lodash_1.default.memoize(() => ({
         docs: docs.map(toSidebarItemsGeneratorDoc),
@@ -51,12 +51,23 @@ async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
         // more autogenerated items, or when loop count (e.g. 10) is reached
         return processItems(generatedItems);
     }
+    const draftIds = new Set(drafts.flatMap(docs_1.getDocIds));
+    const isDraftItem = (item) => {
+        if (item.type === 'doc' || item.type === 'ref') {
+            return draftIds.has(item.id);
+        }
+        // If a category only contains draft items, it should be filtered entirely.
+        if (item.type === 'category') {
+            return item.items.every(isDraftItem);
+        }
+        return false;
+    };
     async function processItem(item) {
         if (item.type === 'category') {
             return [
                 {
                     ...item,
-                    items: (await Promise.all(item.items.map(processItem))).flat(),
+                    items: await processItems(item.items),
                 },
             ];
         }
@@ -66,7 +77,7 @@ async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
         return [item];
     }
     async function processItems(items) {
-        return (await Promise.all(items.map(processItem))).flat();
+        return (await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))).flat();
     }
     const processedSidebar = await processItems(unprocessedSidebar);
     return processedSidebar;

package/lib/sidebars/types.d.ts

@@ -170,6 +170,7 @@ export declare type SidebarProcessorParams = {
     sidebarItemsGenerator: SidebarItemsGeneratorOption;
     numberPrefixParser: NumberPrefixParser;
     docs: DocMetadataBase[];
+    drafts: DocMetadataBase[];
     version: VersionMetadata;
     categoryLabelSlugger: Slugger;
     sidebarOptions: SidebarOptions;

package/lib/types.d.ts

@@ -28,6 +28,7 @@ export declare type VersionTags = {
 export declare type LoadedVersion = VersionMetadata & {
     mainDocId: string;
     docs: DocMetadata[];
+    drafts: DocMetadata[];
     sidebars: Sidebars;
     categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4859",
+  "version": "0.0.0-4864",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -24,11 +24,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4859",
-    "@docusaurus/logger": "0.0.0-4859",
-    "@docusaurus/mdx-loader": "0.0.0-4859",
-    "@docusaurus/utils": "0.0.0-4859",
-    "@docusaurus/utils-validation": "0.0.0-4859",
+    "@docusaurus/core": "0.0.0-4864",
+    "@docusaurus/logger": "0.0.0-4864",
+    "@docusaurus/mdx-loader": "0.0.0-4864",
+    "@docusaurus/utils": "0.0.0-4864",
+    "@docusaurus/utils-validation": "0.0.0-4864",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.1",
     "import-fresh": "^3.3.0",
@@ -40,8 +40,8 @@
     "webpack": "^5.72.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4859",
-    "@docusaurus/types": "0.0.0-4859",
+    "@docusaurus/module-type-aliases": "0.0.0-4864",
+    "@docusaurus/types": "0.0.0-4864",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -57,5 +57,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "2c2a2a24c95862a8d08be5ca1a1f7ff57d41c166"
+  "gitHead": "ae6d7c8caecd661cd85ab05c9d7e9ecd935725a1"
 }

package/src/docs.ts

@@ -38,6 +38,7 @@ import type {
   PropNavigationLink,
   LastUpdateData,
   VersionMetadata,
+  DocFrontMatter,
 } from '@docusaurus/plugin-content-docs';
 
 type LastUpdateOptions = Pick<
@@ -110,16 +111,31 @@ 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;
+}
+
 function doProcessDocMetadata({
   docFile,
   versionMetadata,
   context,
   options,
+  env,
 }: {
   docFile: DocFile;
   versionMetadata: VersionMetadata;
   context: LoadContext;
   options: MetadataOptions;
+  env: DocEnv;
 }): DocMetadataBase {
   const {source, content, lastUpdate, contentPath, filePath} = docFile;
   const {siteDir, i18n} = context;
@@ -235,6 +251,8 @@ function doProcessDocMetadata({
     return undefined;
   }
 
+  const draft = isDraftForEnvironment({env, frontMatter});
+
   // Assign all of object properties during instantiation (if possible) for
   // NodeJS optimization.
   // Adding properties to object after instantiation will cause hidden
@@ -248,6 +266,7 @@ function doProcessDocMetadata({
     sourceDirName,
     slug: docSlug,
     permalink,
+    draft,
     editUrl: customEditURL !== undefined ? customEditURL : getDocEditUrl(),
     tags: normalizeFrontMatterTags(versionMetadata.tagsPath, frontMatter.tags),
     version: versionMetadata.versionName,
@@ -268,6 +287,7 @@ export function processDocMetadata(args: {
   versionMetadata: VersionMetadata;
   context: LoadContext;
   options: MetadataOptions;
+  env: DocEnv;
 }): DocMetadataBase {
   try {
     return doProcessDocMetadata(args);

package/src/frontMatter.ts

@@ -38,6 +38,7 @@ 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,
 }).unknown();
 

package/src/globalData.ts

@@ -72,6 +72,7 @@ export function toGlobalDataVersion(version: LoadedVersion): GlobalVersion {
     docs: version.docs
       .map(toGlobalDataDoc)
       .concat(version.categoryGeneratedIndices.map(toGlobalDataGeneratedIndex)),
+    draftIds: version.drafts.map((doc) => doc.unversionedId),
     sidebars: toGlobalSidebars(version.sidebars, version),
   };
 }

package/src/index.ts

@@ -22,6 +22,7 @@ import {
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import {loadSidebars, resolveSidebarPathOption} from './sidebars';
 import {CategoryMetadataFilenamePattern} from './sidebars/generator';
+import type {DocEnv} from './docs';
 import {
   readVersionDocs,
   processDocMetadata,
@@ -58,6 +59,7 @@ import type {
 } from '@docusaurus/plugin-content-docs';
 import {createSidebarsUtils} from './sidebars/utils';
 import {getCategoryGeneratedIndexMetadataList} from './categoryGeneratedIndex';
+import _ from 'lodash';
 
 export default async function pluginContentDocs(
   context: LoadContext,
@@ -147,6 +149,7 @@ export default async function pluginContentDocs(
             versionMetadata,
             context,
             options,
+            env: process.env.NODE_ENV as DocEnv,
           });
         }
         return Promise.all(docFiles.map(processVersionDoc));
@@ -155,14 +158,17 @@ export default async function pluginContentDocs(
       async function doLoadVersion(
         versionMetadata: VersionMetadata,
       ): Promise<LoadedVersion> {
-        const docs: DocMetadataBase[] = await loadVersionDocsBase(
+        const docsBase: DocMetadataBase[] = await loadVersionDocsBase(
           versionMetadata,
         );
 
+        const [drafts, docs] = _.partition(docsBase, (doc) => doc.draft);
+
         const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
           sidebarItemsGenerator: options.sidebarItemsGenerator,
           numberPrefixParser: options.numberPrefixParser,
           docs,
+          drafts,
           version: versionMetadata,
           sidebarOptions: {
             sidebarCollapsed: options.sidebarCollapsed,
@@ -180,6 +186,7 @@ export default async function pluginContentDocs(
             sidebarsUtils,
             versionMetadata.sidebarFilePath as string,
           ),
+          drafts,
           sidebars,
           mainDocId: getMainDocId({docs, sidebarsUtils}),
           categoryGeneratedIndices: getCategoryGeneratedIndexMetadataList({

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

@@ -346,6 +346,8 @@ declare module '@docusaurus/plugin-content-docs' {
      * @see {@link DocMetadata.prev}
      */
     pagination_prev?: string | null;
+    /** Should this doc be excluded from production builds? */
+    draft?: boolean;
   };
 
   export type LastUpdateData = {
@@ -390,6 +392,10 @@ declare module '@docusaurus/plugin-content-docs' {
     slug: string;
     /** Full URL to this doc, with base URL and version path. */
     permalink: string;
+    /**
+     * Draft docs will be excluded for production environment.
+     */
+    draft: boolean;
     /**
      * Position in an autogenerated sidebar slice, acquired through front matter
      * or number prefix.
@@ -597,6 +603,8 @@ declare module '@docusaurus/plugin-content-docs/client' {
     /** 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};
   };
 

package/src/sidebars/processor.ts

@@ -26,7 +26,7 @@ import {DefaultSidebarItemsGenerator} from './generator';
 import {validateSidebars} from './validation';
 import _ from 'lodash';
 import combinePromises from 'combine-promises';
-import {isCategoryIndex} from '../docs';
+import {getDocIds, isCategoryIndex} from '../docs';
 
 function toSidebarItemsGeneratorDoc(
   doc: DocMetadataBase,
@@ -55,7 +55,8 @@ async function processSidebar(
   categoriesMetadata: {[filePath: string]: CategoryMetadataFile},
   params: SidebarProcessorParams,
 ): Promise<ProcessedSidebar> {
-  const {sidebarItemsGenerator, numberPrefixParser, docs, version} = params;
+  const {sidebarItemsGenerator, numberPrefixParser, docs, drafts, version} =
+    params;
 
   // Just a minor lazy transformation optimization
   const getSidebarItemsGeneratorDocsAndVersion = _.memoize(() => ({
@@ -81,6 +82,19 @@ async function processSidebar(
     return processItems(generatedItems);
   }
 
+  const draftIds = new Set(drafts.flatMap(getDocIds));
+
+  const isDraftItem = (item: NormalizedSidebarItem): boolean => {
+    if (item.type === 'doc' || item.type === 'ref') {
+      return draftIds.has(item.id);
+    }
+    // If a category only contains draft items, it should be filtered entirely.
+    if (item.type === 'category') {
+      return item.items.every(isDraftItem);
+    }
+    return false;
+  };
+
   async function processItem(
     item: NormalizedSidebarItem,
   ): Promise<ProcessedSidebarItem[]> {
@@ -88,7 +102,7 @@ async function processSidebar(
       return [
         {
           ...item,
-          items: (await Promise.all(item.items.map(processItem))).flat(),
+          items: await processItems(item.items),
         },
       ];
     }
@@ -101,7 +115,9 @@ async function processSidebar(
   async function processItems(
     items: NormalizedSidebarItem[],
   ): Promise<ProcessedSidebarItem[]> {
-    return (await Promise.all(items.map(processItem))).flat();
+    return (
+      await Promise.all(items.filter((i) => !isDraftItem(i)).map(processItem))
+    ).flat();
   }
 
   const processedSidebar = await processItems(unprocessedSidebar);

package/src/sidebars/types.ts

@@ -269,6 +269,7 @@ export type SidebarProcessorParams = {
   sidebarItemsGenerator: SidebarItemsGeneratorOption;
   numberPrefixParser: NumberPrefixParser;
   docs: DocMetadataBase[];
+  drafts: DocMetadataBase[];
   version: VersionMetadata;
   categoryLabelSlugger: Slugger;
   sidebarOptions: SidebarOptions;

package/src/types.ts

@@ -40,6 +40,7 @@ export type VersionTags = {
 export type LoadedVersion = VersionMetadata & {
   mainDocId: string;
   docs: DocMetadata[];
+  drafts: DocMetadata[];
   sidebars: Sidebars;
   categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };