@docusaurus/plugin-content-pages 2.4.1 → 3.0.0-alpha.0

package/lib/frontMatter.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { FrontMatter } from '@docusaurus/plugin-content-pages';
+import type { PageFrontMatter } from '@docusaurus/plugin-content-pages';
 export declare function validatePageFrontMatter(frontMatter: {
     [key: string]: unknown;
-}): FrontMatter;
+}): PageFrontMatter;

package/lib/frontMatter.js

@@ -9,12 +9,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validatePageFrontMatter = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const PageFrontMatterSchema = utils_validation_1.Joi.object({
-    title: utils_validation_1.Joi.string(),
-    description: utils_validation_1.Joi.string(),
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+    title: utils_validation_1.Joi.string().allow(''),
+    // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+    description: utils_validation_1.Joi.string().allow(''),
+    keywords: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().required()),
+    image: utils_validation_1.URISchema,
     wrapperClassName: utils_validation_1.Joi.string(),
     hide_table_of_contents: utils_validation_1.Joi.boolean(),
     ...utils_validation_1.FrontMatterTOCHeadingLevels,
-});
+}).concat(utils_validation_1.ContentVisibilitySchema);
 function validatePageFrontMatter(frontMatter) {
     return (0, utils_validation_1.validateFrontMatter)(frontMatter, PageFrontMatterSchema);
 }

package/lib/index.js

@@ -45,7 +45,7 @@ function pluginContentPages(context, options) {
                 cwd: contentPaths.contentPath,
                 ignore: options.exclude,
             });
-            async function toMetadata(relativeSource) {
+            async function processPageSourceFile(relativeSource) {
                 // Lookup in localized folder in priority
                 const contentPath = await (0, utils_1.getFolderContainingFile)(getContentPathList(contentPaths), relativeSource);
                 const source = path_1.default.join(contentPath, relativeSource);
@@ -65,6 +65,10 @@ function pluginContentPages(context, options) {
                 const content = await fs_extra_1.default.readFile(source, 'utf-8');
                 const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
                 const frontMatter = (0, frontMatter_1.validatePageFrontMatter)(unsafeFrontMatter);
+                if ((0, utils_1.isDraft)({ frontMatter })) {
+                    return undefined;
+                }
+                const unlisted = (0, utils_1.isUnlisted)({ frontMatter });
                 return {
                     type: 'mdx',
                     permalink,
@@ -72,9 +76,18 @@ function pluginContentPages(context, options) {
                     title: frontMatter.title ?? contentTitle,
                     description: frontMatter.description ?? excerpt,
                     frontMatter,
+                    unlisted,
                 };
             }
-            return Promise.all(pagesFiles.map(toMetadata));
+            async function doProcessPageSourceFile(relativeSource) {
+                try {
+                    return await processPageSourceFile(relativeSource);
+                }
+                catch (err) {
+                    throw new Error(`Processing of page source file path=${relativeSource} failed.`, { cause: err });
+                }
+            }
+            return (await Promise.all(pagesFiles.map(doProcessPageSourceFile))).filter(Boolean);
         },
         async contentLoaded({ content, actions }) {
             if (!content) {
@@ -109,7 +122,7 @@ function pluginContentPages(context, options) {
                 }
             }));
         },
-        configureWebpack(config, isServer, { getJSLoader }) {
+        configureWebpack() {
             const { admonitions, rehypePlugins, remarkPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
             const contentDirs = getContentPathList(contentPaths);
             return {
@@ -126,7 +139,6 @@ function pluginContentPages(context, options) {
                                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                                 .map(utils_1.addTrailingPathSeparator),
                             use: [
-                                getJSLoader({ isServer }),
                                 {
                                     loader: require.resolve('@docusaurus/mdx-loader'),
                                     options: {
@@ -144,6 +156,11 @@ function pluginContentPages(context, options) {
                                             const aliasedSource = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
                                             return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedSource)}.json`);
                                         },
+                                        // Assets allow to convert some relative images paths to
+                                        // require(...) calls
+                                        createAssets: ({ frontMatter, }) => ({
+                                            image: frontMatter.image,
+                                        }),
                                         markdownConfig: siteConfig.markdown,
                                     },
                                 },

package/lib/options.js

@@ -23,7 +23,7 @@ exports.DEFAULT_OPTIONS = {
 };
 const PluginOptionSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
-    routeBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.routeBasePath),
+    routeBasePath: utils_validation_1.RouteBasePathSchema.default(exports.DEFAULT_OPTIONS.routeBasePath),
     include: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.include),
     exclude: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.exclude),
     mdxPageComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.mdxPageComponent),

package/lib/types.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export declare type PagesContentPaths = {
+export type PagesContentPaths = {
     contentPath: string;
     contentPathLocalized: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-pages",
-  "version": "2.4.1",
+  "version": "3.0.0-alpha.0",
   "description": "Pages plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-content-pages.d.ts",
@@ -18,21 +18,21 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.4.1",
-    "@docusaurus/mdx-loader": "2.4.1",
-    "@docusaurus/types": "2.4.1",
-    "@docusaurus/utils": "2.4.1",
-    "@docusaurus/utils-validation": "2.4.1",
-    "fs-extra": "^10.1.0",
-    "tslib": "^2.4.0",
-    "webpack": "^5.73.0"
+    "@docusaurus/core": "3.0.0-alpha.0",
+    "@docusaurus/mdx-loader": "3.0.0-alpha.0",
+    "@docusaurus/types": "3.0.0-alpha.0",
+    "@docusaurus/utils": "3.0.0-alpha.0",
+    "@docusaurus/utils-validation": "3.0.0-alpha.0",
+    "fs-extra": "^11.1.0",
+    "tslib": "^2.5.0",
+    "webpack": "^5.76.0"
   },
   "peerDependencies": {
-    "react": "^16.8.4 || ^17.0.0",
-    "react-dom": "^16.8.4 || ^17.0.0"
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
   },
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "60e657d8ae5a4a9ed1c2d777f9defd882cc12681"
+  "gitHead": "7327f7ff880ed97ad7855744e59c9c55d467a950"
 }

package/src/frontMatter.ts

@@ -9,19 +9,25 @@ import {
   Joi,
   validateFrontMatter,
   FrontMatterTOCHeadingLevels,
+  ContentVisibilitySchema,
+  URISchema,
 } from '@docusaurus/utils-validation';
-import type {FrontMatter} from '@docusaurus/plugin-content-pages';
+import type {PageFrontMatter} from '@docusaurus/plugin-content-pages';
 
-const PageFrontMatterSchema = Joi.object<FrontMatter>({
-  title: Joi.string(),
-  description: Joi.string(),
+const PageFrontMatterSchema = Joi.object<PageFrontMatter>({
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  title: Joi.string().allow(''),
+  // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
+  description: Joi.string().allow(''),
+  keywords: Joi.array().items(Joi.string().required()),
+  image: URISchema,
   wrapperClassName: Joi.string(),
   hide_table_of_contents: Joi.boolean(),
   ...FrontMatterTOCHeadingLevels,
-});
+}).concat(ContentVisibilitySchema);
 
 export function validatePageFrontMatter(frontMatter: {
   [key: string]: unknown;
-}): FrontMatter {
+}): PageFrontMatter {
   return validateFrontMatter(frontMatter, PageFrontMatterSchema);
 }

package/src/index.ts

@@ -20,6 +20,8 @@ import {
   normalizeUrl,
   DEFAULT_PLUGIN_ID,
   parseMarkdownString,
+  isUnlisted,
+  isDraft,
 } from '@docusaurus/utils';
 import {validatePageFrontMatter} from './frontMatter';
 
@@ -29,6 +31,7 @@ import type {
   PluginOptions,
   Metadata,
   LoadedContent,
+  PageFrontMatter,
 } from '@docusaurus/plugin-content-pages';
 
 export function getContentPathList(contentPaths: PagesContentPaths): string[] {
@@ -82,7 +85,9 @@ export default function pluginContentPages(
         ignore: options.exclude,
       });
 
-      async function toMetadata(relativeSource: string): Promise<Metadata> {
+      async function processPageSourceFile(
+        relativeSource: string,
+      ): Promise<Metadata | undefined> {
         // Lookup in localized folder in priority
         const contentPath = await getFolderContainingFile(
           getContentPathList(contentPaths),
@@ -110,6 +115,12 @@ export default function pluginContentPages(
           excerpt,
         } = parseMarkdownString(content);
         const frontMatter = validatePageFrontMatter(unsafeFrontMatter);
+
+        if (isDraft({frontMatter})) {
+          return undefined;
+        }
+        const unlisted = isUnlisted({frontMatter});
+
         return {
           type: 'mdx',
           permalink,
@@ -117,10 +128,24 @@ export default function pluginContentPages(
           title: frontMatter.title ?? contentTitle,
           description: frontMatter.description ?? excerpt,
           frontMatter,
+          unlisted,
         };
       }
 
-      return Promise.all(pagesFiles.map(toMetadata));
+      async function doProcessPageSourceFile(relativeSource: string) {
+        try {
+          return await processPageSourceFile(relativeSource);
+        } catch (err) {
+          throw new Error(
+            `Processing of page source file path=${relativeSource} failed.`,
+            {cause: err as Error},
+          );
+        }
+      }
+
+      return (
+        await Promise.all(pagesFiles.map(doProcessPageSourceFile))
+      ).filter(Boolean) as Metadata[];
     },
 
     async contentLoaded({content, actions}) {
@@ -162,7 +187,7 @@ export default function pluginContentPages(
       );
     },
 
-    configureWebpack(config, isServer, {getJSLoader}) {
+    configureWebpack() {
       const {
         admonitions,
         rehypePlugins,
@@ -185,7 +210,6 @@ export default function pluginContentPages(
                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                 .map(addTrailingPathSeparator),
               use: [
-                getJSLoader({isServer}),
                 {
                   loader: require.resolve('@docusaurus/mdx-loader'),
                   options: {
@@ -211,6 +235,15 @@ export default function pluginContentPages(
                         `${docuHash(aliasedSource)}.json`,
                       );
                     },
+                    // Assets allow to convert some relative images paths to
+                    // require(...) calls
+                    createAssets: ({
+                      frontMatter,
+                    }: {
+                      frontMatter: PageFrontMatter;
+                    }) => ({
+                      image: frontMatter.image,
+                    }),
                     markdownConfig: siteConfig.markdown,
                   },
                 },

package/src/options.ts

@@ -10,6 +10,7 @@ import {
   RemarkPluginsSchema,
   RehypePluginsSchema,
   AdmonitionsSchema,
+  RouteBasePathSchema,
 } from '@docusaurus/utils-validation';
 import {GlobExcludeDefault} from '@docusaurus/utils';
 import type {OptionValidationContext} from '@docusaurus/types';
@@ -30,7 +31,7 @@ export const DEFAULT_OPTIONS: PluginOptions = {
 
 const PluginOptionSchema = Joi.object<PluginOptions>({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
-  routeBasePath: Joi.string().default(DEFAULT_OPTIONS.routeBasePath),
+  routeBasePath: RouteBasePathSchema.default(DEFAULT_OPTIONS.routeBasePath),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
   exclude: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.exclude),
   mdxPageComponent: Joi.string().default(DEFAULT_OPTIONS.mdxPageComponent),

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

@@ -9,6 +9,10 @@ declare module '@docusaurus/plugin-content-pages' {
   import type {MDXOptions} from '@docusaurus/mdx-loader';
   import type {LoadContext, Plugin} from '@docusaurus/types';
 
+  export type Assets = {
+    image?: string;
+  };
+
   export type PluginOptions = MDXOptions & {
     id?: string;
     path: string;
@@ -20,13 +24,17 @@ declare module '@docusaurus/plugin-content-pages' {
 
   export type Options = Partial<PluginOptions>;
 
-  export type FrontMatter = {
+  export type PageFrontMatter = {
     readonly title?: string;
     readonly description?: string;
+    readonly image?: string;
+    readonly keywords?: string[];
     readonly wrapperClassName?: string;
     readonly hide_table_of_contents?: string;
     readonly toc_min_heading_level?: number;
     readonly toc_max_heading_level?: number;
+    readonly draft?: boolean;
+    readonly unlisted?: boolean;
   };
 
   export type JSXPageMetadata = {
@@ -39,9 +47,10 @@ declare module '@docusaurus/plugin-content-pages' {
     type: 'mdx';
     permalink: string;
     source: string;
-    frontMatter: FrontMatter & {[key: string]: unknown};
+    frontMatter: PageFrontMatter & {[key: string]: unknown};
     title?: string;
     description?: string;
+    unlisted: boolean;
   };
 
   export type Metadata = JSXPageMetadata | MDXPageMetadata;
@@ -58,11 +67,16 @@ declare module '@theme/MDXPage' {
   import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
   import type {
     MDXPageMetadata,
-    FrontMatter,
+    PageFrontMatter,
+    Assets,
   } from '@docusaurus/plugin-content-pages';
 
   export interface Props {
-    readonly content: LoadedMDXContent<FrontMatter, MDXPageMetadata>;
+    readonly content: LoadedMDXContent<
+      PageFrontMatter,
+      MDXPageMetadata,
+      Assets
+    >;
   }
 
   export default function MDXPage(props: Props): JSX.Element;