@docusaurus/plugin-content-pages 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/src/index.ts

@@ -5,11 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import globby from 'globby';
-import fs from 'fs';
+import fs from 'fs-extra';
 import path from 'path';
-import minimatch from 'minimatch';
-import slash from 'slash';
 import {
   encodePath,
   fileToPath,
@@ -18,29 +15,22 @@ import {
   getPluginI18nPath,
   getFolderContainingFile,
   addTrailingPathSeparator,
+  Globby,
+  createAbsoluteFilePathMatcher,
+  normalizeUrl,
+  DEFAULT_PLUGIN_ID,
+  parseMarkdownString,
 } from '@docusaurus/utils';
-import {
-  LoadContext,
-  Plugin,
-  OptionValidationContext,
-  ValidationResult,
-  ConfigureWebpackUtils,
-} from '@docusaurus/types';
-import {Configuration} from 'webpack';
+import type {LoadContext, Plugin} from '@docusaurus/types';
 import admonitions from 'remark-admonitions';
-import {PluginOptionSchema} from './pluginOptionSchema';
-import {
-  DEFAULT_PLUGIN_ID,
-  STATIC_DIR_NAME,
-} from '@docusaurus/core/lib/constants';
+import {validatePageFrontMatter} from './frontMatter';
 
-import {
+import type {PagesContentPaths} from './types';
+import type {
   PluginOptions,
-  LoadedContent,
   Metadata,
-  PagesContentPaths,
-} from './types';
-import {flatten} from 'lodash';
+  LoadedContent,
+} from '@docusaurus/plugin-content-pages';
 
 export function getContentPathList(contentPaths: PagesContentPaths): string[] {
   return [contentPaths.contentPathLocalized, contentPaths.contentPath];
@@ -49,13 +39,13 @@ export function getContentPathList(contentPaths: PagesContentPaths): string[] {
 const isMarkdownSource = (source: string) =>
   source.endsWith('.md') || source.endsWith('.mdx');
 
-export default function pluginContentPages(
+export default async function pluginContentPages(
   context: LoadContext,
   options: PluginOptions,
-): Plugin<LoadedContent | null> {
+): Promise<Plugin<LoadedContent | null>> {
   if (options.admonitions) {
     options.remarkPlugins = options.remarkPlugins.concat([
-      [admonitions, options.admonitions || {}],
+      [admonitions, options.admonitions],
     ]);
   }
   const {
@@ -81,42 +71,25 @@ export default function pluginContentPages(
   );
   const dataDir = path.join(pluginDataDirRoot, options.id ?? DEFAULT_PLUGIN_ID);
 
-  const excludeRegex = new RegExp(
-    options.exclude
-      .map((pattern) => minimatch.makeRe(pattern).source)
-      .join('|'),
-  );
   return {
     name: 'docusaurus-plugin-content-pages',
 
     getPathsToWatch() {
-      const {include = []} = options;
-      return flatten(
-        getContentPathList(contentPaths).map((contentPath) => {
-          return include.map((pattern) => `${contentPath}/${pattern}`);
-        }),
+      const {include} = options;
+      return getContentPathList(contentPaths).flatMap((contentPath) =>
+        include.map((pattern) => `${contentPath}/${pattern}`),
       );
     },
 
-    getClientModules() {
-      const modules = [];
-
-      if (options.admonitions) {
-        modules.push(require.resolve('remark-admonitions/styles/infima.css'));
-      }
-
-      return modules;
-    },
-
     async loadContent() {
       const {include} = options;
 
-      if (!fs.existsSync(contentPaths.contentPath)) {
+      if (!(await fs.pathExists(contentPaths.contentPath))) {
         return null;
       }
 
       const {baseUrl} = siteConfig;
-      const pagesFiles = await globby(include, {
+      const pagesFiles = await Globby(include, {
         cwd: contentPaths.contentPath,
         ignore: options.exclude,
       });
@@ -130,21 +103,33 @@ export default function pluginContentPages(
 
         const source = path.join(contentPath, relativeSource);
         const aliasedSourcePath = aliasedSitePath(source, siteDir);
-        const pathName = encodePath(fileToPath(relativeSource));
-        const permalink = pathName.replace(/^\//, baseUrl || '');
-        if (isMarkdownSource(relativeSource)) {
-          return {
-            type: 'mdx',
-            permalink,
-            source: aliasedSourcePath,
-          };
-        } else {
+        const permalink = normalizeUrl([
+          baseUrl,
+          options.routeBasePath,
+          encodePath(fileToPath(relativeSource)),
+        ]);
+        if (!isMarkdownSource(relativeSource)) {
           return {
             type: 'jsx',
             permalink,
             source: aliasedSourcePath,
           };
         }
+        const content = await fs.readFile(source, 'utf-8');
+        const {
+          frontMatter: unsafeFrontMatter,
+          contentTitle,
+          excerpt,
+        } = parseMarkdownString(content);
+        const frontMatter = validatePageFrontMatter(unsafeFrontMatter);
+        return {
+          type: 'mdx',
+          permalink,
+          source: aliasedSourcePath,
+          title: frontMatter.title ?? contentTitle,
+          description: frontMatter.description ?? excerpt,
+          frontMatter,
+        };
       }
 
       return Promise.all(pagesFiles.map(toMetadata));
@@ -189,17 +174,14 @@ export default function pluginContentPages(
       );
     },
 
-    configureWebpack(
-      _config: Configuration,
-      isServer: boolean,
-      {getJSLoader}: ConfigureWebpackUtils,
-    ) {
+    configureWebpack(config, isServer, {getJSLoader}) {
       const {
         rehypePlugins,
         remarkPlugins,
         beforeDefaultRehypePlugins,
         beforeDefaultRemarkPlugins,
       } = options;
+      const contentDirs = getContentPathList(contentPaths);
       return {
         resolve: {
           alias: {
@@ -209,8 +191,8 @@ export default function pluginContentPages(
         module: {
           rules: [
             {
-              test: /(\.mdx?)$/,
-              include: getContentPathList(contentPaths)
+              test: /\.mdx?$/i,
+              include: contentDirs
                 // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                 .map(addTrailingPathSeparator),
               use: [
@@ -222,22 +204,23 @@ export default function pluginContentPages(
                     rehypePlugins,
                     beforeDefaultRehypePlugins,
                     beforeDefaultRemarkPlugins,
-                    keepContentTitle: true,
-                    staticDir: path.join(siteDir, STATIC_DIR_NAME),
-                    // Note that metadataPath must be the same/in-sync as
-                    // the path from createData for each MDX.
+                    staticDirs: siteConfig.staticDirectories.map((dir) =>
+                      path.resolve(siteDir, dir),
+                    ),
+                    siteDir,
+                    isMDXPartial: createAbsoluteFilePathMatcher(
+                      options.exclude,
+                      contentDirs,
+                    ),
                     metadataPath: (mdxPath: string) => {
-                      if (excludeRegex.test(slash(mdxPath))) {
-                        return null;
-                      }
+                      // Note that metadataPath must be the same/in-sync as
+                      // the path from createData for each MDX.
                       const aliasedSource = aliasedSitePath(mdxPath, siteDir);
                       return path.join(
                         dataDir,
                         `${docuHash(aliasedSource)}.json`,
                       );
                     },
-                    forbidFrontMatter: (mdxPath: string) =>
-                      excludeRegex.test(slash(mdxPath)),
                   },
                 },
                 {
@@ -256,10 +239,4 @@ export default function pluginContentPages(
   };
 }
 
-export function validateOptions({
-  validate,
-  options,
-}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
-  const validatedOptions = validate(PluginOptionSchema, options);
-  return validatedOptions;
-}
+export {validateOptions} from './options';

package/src/markdownLoader.ts

@@ -5,21 +5,18 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// TODO temporary until Webpack5 export this type
-// see https://github.com/webpack/webpack/issues/11630
-interface Loader extends Function {
-  (this: any, source: string): string | Buffer | void | undefined;
-}
+import type {LoaderContext} from 'webpack';
 
-const markdownLoader: Loader = function (fileString) {
+export default function markdownLoader(
+  this: LoaderContext<undefined>,
+  fileString: string,
+): void {
   const callback = this.async();
 
   // const options = this.getOptions();
 
-  // TODO provide additinal md processing here? like interlinking pages?
+  // TODO provide additional md processing here? like interlinking pages?
   // fileString = linkify(fileString)
 
-  return callback && callback(null, fileString);
-};
-
-export default markdownLoader;
+  return callback?.(null, fileString);
+}

package/src/{pluginOptionSchema.ts → options.ts}

@@ -4,32 +4,31 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import {PluginOptions} from './types';
+
+import type {PluginOptions, Options} from '@docusaurus/plugin-content-pages';
 import {
   Joi,
   RemarkPluginsSchema,
   RehypePluginsSchema,
   AdmonitionsSchema,
 } from '@docusaurus/utils-validation';
+import {GlobExcludeDefault} from '@docusaurus/utils';
+import type {OptionValidationContext} from '@docusaurus/types';
 
 export const DEFAULT_OPTIONS: PluginOptions = {
   path: 'src/pages', // Path to data on filesystem, relative to site dir.
   routeBasePath: '/', // URL Route.
   include: ['**/*.{js,jsx,ts,tsx,md,mdx}'], // Extensions to include.
+  exclude: GlobExcludeDefault,
   mdxPageComponent: '@theme/MDXPage',
   remarkPlugins: [],
   rehypePlugins: [],
   beforeDefaultRehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   admonitions: {},
-  exclude: [
-    '**/_*.{js,jsx,ts,tsx,md,mdx}',
-    '**/*.test.{js,ts}',
-    '**/__tests__/**',
-  ],
 };
 
-export const PluginOptionSchema = Joi.object({
+const PluginOptionSchema = Joi.object({
   path: Joi.string().default(DEFAULT_OPTIONS.path),
   routeBasePath: Joi.string().default(DEFAULT_OPTIONS.routeBasePath),
   include: Joi.array().items(Joi.string()).default(DEFAULT_OPTIONS.include),
@@ -45,3 +44,11 @@ export const PluginOptionSchema = Joi.object({
   ),
   admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
 });
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  const validatedOptions = validate(PluginOptionSchema, options);
+  return validatedOptions;
+}

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

@@ -5,24 +5,66 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-declare module '@theme/MDXPage' {
-  import type {TOCItem} from '@docusaurus/types';
-
-  export type Props = {
-    readonly content: {
-      readonly frontMatter: {
-        readonly title: string;
-        readonly description: string;
-        readonly wrapperClassName?: string;
-        // eslint-disable-next-line camelcase
-        readonly hide_table_of_contents?: string;
-      };
-      readonly metadata: {readonly permalink: string};
-      readonly toc: readonly TOCItem[];
-      (): JSX.Element;
-    };
+declare module '@docusaurus/plugin-content-pages' {
+  import type {MDXOptions} from '@docusaurus/mdx-loader';
+  import type {LoadContext, Plugin} from '@docusaurus/types';
+
+  export type PluginOptions = MDXOptions & {
+    id?: string;
+    path: string;
+    routeBasePath: string;
+    include: string[];
+    exclude: string[];
+    mdxPageComponent: string;
+    admonitions: {[key: string]: unknown};
+  };
+
+  export type Options = Partial<PluginOptions>;
+
+  export type FrontMatter = {
+    readonly title?: string;
+    readonly description?: string;
+    readonly wrapperClassName?: string;
+    readonly hide_table_of_contents?: string;
+    readonly toc_min_heading_level?: number;
+    readonly toc_max_heading_level?: number;
+  };
+
+  export type JSXPageMetadata = {
+    type: 'jsx';
+    permalink: string;
+    source: string;
+  };
+
+  export type MDXPageMetadata = {
+    type: 'mdx';
+    permalink: string;
+    source: string;
+    frontMatter: FrontMatter & {[key: string]: unknown};
+    title?: string;
+    description?: string;
   };
 
-  const MDXPage: (props: Props) => JSX.Element;
-  export default MDXPage;
+  export type Metadata = JSXPageMetadata | MDXPageMetadata;
+
+  export type LoadedContent = Metadata[];
+
+  export default function pluginContentPages(
+    context: LoadContext,
+    options: PluginOptions,
+  ): Promise<Plugin<LoadedContent | null>>;
+}
+
+declare module '@theme/MDXPage' {
+  import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
+  import type {
+    MDXPageMetadata,
+    FrontMatter,
+  } from '@docusaurus/plugin-content-pages';
+
+  export interface Props {
+    readonly content: LoadedMDXContent<FrontMatter, MDXPageMetadata>;
+  }
+
+  export default function MDXPage(props: Props): JSX.Element;
 }

package/src/types.ts

@@ -5,34 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {RemarkAndRehypePluginOptions} from '@docusaurus/mdx-loader';
-
-export interface PluginOptions extends RemarkAndRehypePluginOptions {
-  id?: string;
-  path: string;
-  routeBasePath: string;
-  include: string[];
-  exclude: string[];
-  mdxPageComponent: string;
-  admonitions: Record<string, unknown>;
-}
-
-export type JSXPageMetadata = {
-  type: 'jsx';
-  permalink: string;
-  source: string;
-};
-
-export type MDXPageMetadata = {
-  type: 'mdx';
-  permalink: string;
-  source: string;
-};
-
-export type Metadata = JSXPageMetadata | MDXPageMetadata;
-
-export type LoadedContent = Metadata[];
-
 export type PagesContentPaths = {
   contentPath: string;
   contentPathLocalized: string;