@azerion/bunosaurus-plugin-content-pages 0.0.0-stage → 4.0.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# `@docusaurus/plugin-content-pages`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pages plugin for Docusaurus.
+
+## Usage
+
+See [plugin-content-pages documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-pages).

package/lib/content.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type ContentPaths } from '@docusaurus/utils';
+import type { LoadContext } from '@docusaurus/types';
+import type { PluginOptions, LoadedContent } from '@docusaurus/plugin-content-pages';
+export declare function createPagesContentPaths({ context, options, }: {
+    context: LoadContext;
+    options: PluginOptions;
+}): ContentPaths;
+type LoadContentParams = {
+    context: LoadContext;
+    options: PluginOptions;
+    contentPaths: ContentPaths;
+};
+export declare function loadPagesContent(params: LoadContentParams): Promise<LoadedContent>;
+export {};

package/lib/content.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPagesContentPaths = createPagesContentPaths;
+exports.loadPagesContent = loadPagesContent;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+const fs_1 = require("@docusaurus/fs");
+const frontMatter_1 = require("./frontMatter");
+function createPagesContentPaths({ context, options, }) {
+    const { siteDir, localizationDir } = context;
+    const shouldTranslate = (0, utils_1.getLocaleConfig)(context.i18n).translate;
+    return {
+        contentPath: node_path_1.default.resolve(siteDir, options.path),
+        contentPathLocalized: shouldTranslate
+            ? (0, utils_1.getPluginI18nPath)({
+                localizationDir,
+                pluginName: 'docusaurus-plugin-content-pages',
+                pluginId: options.id,
+            })
+            : undefined,
+    };
+}
+const isMarkdownSource = (source) => source.endsWith('.md') || source.endsWith('.mdx');
+async function loadPagesContent(params) {
+    const { options } = params;
+    const pagesFiles = await (0, glob_1.glob)(params.options.include, {
+        cwd: params.contentPaths.contentPath,
+        ignore: options.exclude,
+    });
+    async function doProcessPageSourceFile(relativeSource) {
+        try {
+            return await processPageSourceFile(relativeSource, params);
+        }
+        catch (err) {
+            throw new Error(`Processing of page source file path=${relativeSource} failed.`, { cause: err });
+        }
+    }
+    return (await Promise.all(pagesFiles.map(doProcessPageSourceFile))).filter((res) => {
+        return res !== undefined;
+    });
+}
+async function processPageSourceFile(relativeSource, params) {
+    const { context, options, contentPaths } = params;
+    const { siteConfig, baseUrl, siteDir, i18n } = context;
+    const { vcs } = siteConfig;
+    const { editUrl } = options;
+    // Lookup in localized folder in priority
+    const contentPath = await (0, utils_1.getFolderContainingFile)((0, utils_1.getContentPathList)(contentPaths), relativeSource);
+    const source = node_path_1.default.join(contentPath, relativeSource);
+    const aliasedSourcePath = (0, utils_1.aliasedSitePath)(source, siteDir);
+    const filenameSlug = (0, utils_1.encodePath)((0, utils_1.fileToPath)(relativeSource));
+    if (!isMarkdownSource(relativeSource)) {
+        // For now, slug can't be customized for JSX pages
+        const slug = filenameSlug;
+        const permalink = (0, utils_1.normalizeUrl)([baseUrl, options.routeBasePath, slug]);
+        return {
+            type: 'jsx',
+            permalink,
+            source: aliasedSourcePath,
+        };
+    }
+    const content = await fs_1.fs.readFile(source, 'utf-8');
+    const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = await (0, utils_1.parseMarkdownFile)({
+        filePath: source,
+        fileContent: content,
+        parseFrontMatter: siteConfig.markdown.parseFrontMatter,
+    });
+    const frontMatter = (0, frontMatter_1.validatePageFrontMatter)(unsafeFrontMatter);
+    const slug = frontMatter.slug ?? filenameSlug;
+    const permalink = (0, utils_1.normalizeUrl)([baseUrl, options.routeBasePath, slug]);
+    const pagesDirPath = await (0, utils_1.getFolderContainingFile)((0, utils_1.getContentPathList)(contentPaths), relativeSource);
+    const pagesSourceAbsolute = node_path_1.default.join(pagesDirPath, relativeSource);
+    function getPagesEditUrl() {
+        const pagesPathRelative = node_path_1.default.relative(pagesDirPath, node_path_1.default.resolve(pagesSourceAbsolute));
+        if (typeof editUrl === 'function') {
+            return editUrl({
+                pagesDirPath: (0, utils_1.posixPath)(node_path_1.default.relative(siteDir, pagesDirPath)),
+                pagesPath: (0, utils_1.posixPath)(pagesPathRelative),
+                permalink,
+                locale: i18n.currentLocale,
+            });
+        }
+        else if (typeof editUrl === 'string') {
+            const isLocalized = pagesDirPath === contentPaths.contentPathLocalized;
+            const fileContentPath = isLocalized &&
+                options.editLocalizedFiles &&
+                contentPaths.contentPathLocalized
+                ? contentPaths.contentPathLocalized
+                : contentPaths.contentPath;
+            const contentPathEditUrl = (0, utils_1.normalizeUrl)([
+                editUrl,
+                (0, utils_1.posixPath)(node_path_1.default.relative(siteDir, fileContentPath)),
+            ]);
+            return (0, utils_1.getEditUrl)(pagesPathRelative, contentPathEditUrl);
+        }
+        return undefined;
+    }
+    const lastUpdatedData = await (0, utils_1.readLastUpdateData)(source, options, frontMatter.last_update, vcs);
+    if ((0, utils_1.isDraft)({ frontMatter })) {
+        return undefined;
+    }
+    const unlisted = (0, utils_1.isUnlisted)({ frontMatter });
+    return {
+        type: 'mdx',
+        permalink,
+        source: aliasedSourcePath,
+        title: frontMatter.title ?? contentTitle,
+        description: frontMatter.description ?? excerpt,
+        frontMatter,
+        lastUpdatedBy: lastUpdatedData.lastUpdatedBy,
+        lastUpdatedAt: lastUpdatedData.lastUpdatedAt,
+        editUrl: getPagesEditUrl(),
+        unlisted,
+    };
+}

package/lib/contentHelpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { LoadedContent, Metadata } from '@docusaurus/plugin-content-pages';
+export declare function createContentHelpers(): {
+    updateContent: (content: LoadedContent) => void;
+    sourceToPage: Map<string, Metadata>;
+    sourceToPermalink: Map<string, string>;
+};

package/lib/contentHelpers.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContentHelpers = createContentHelpers;
+function indexPagesBySource(content) {
+    return new Map(content.map((page) => [page.source, page]));
+}
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to page/permalink is a mutable map passed to the mdx loader
+//  See https://github.com/facebook/docusaurus/pull/10457
+//  See https://github.com/facebook/docusaurus/pull/10185
+function createContentHelpers() {
+    const sourceToPage = new Map();
+    const sourceToPermalink = new Map();
+    // Mutable map update :/
+    function updateContent(content) {
+        sourceToPage.clear();
+        sourceToPermalink.clear();
+        indexPagesBySource(content).forEach((value, key) => {
+            sourceToPage.set(key, value);
+            sourceToPermalink.set(key, value.permalink);
+        });
+    }
+    return { updateContent, sourceToPage, sourceToPermalink };
+}

package/lib/frontMatter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { PageFrontMatter } from '@docusaurus/plugin-content-pages';
+export declare function validatePageFrontMatter(frontMatter: {
+    [key: string]: unknown;
+}): PageFrontMatter;

package/lib/frontMatter.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePageFrontMatter = validatePageFrontMatter;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+/* eslint-disable camelcase */
+const PageFrontMatterSchema = utils_validation_1.Joi.object({
+    // 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,
+    slug: utils_validation_1.Joi.string(),
+    wrapperClassName: utils_validation_1.Joi.string(),
+    hide_table_of_contents: utils_validation_1.Joi.boolean(),
+    ...utils_validation_1.FrontMatterTOCHeadingLevels,
+    last_update: utils_validation_1.FrontMatterLastUpdateSchema,
+}).concat(utils_validation_1.ContentVisibilitySchema);
+function validatePageFrontMatter(frontMatter) {
+    return (0, utils_validation_1.validateFrontMatter)(frontMatter, PageFrontMatterSchema);
+}

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { LoadContext, Plugin } from '@docusaurus/types';
+import type { PluginOptions, LoadedContent } from '@docusaurus/plugin-content-pages';
+export default function pluginContentPages(context: LoadContext, options: PluginOptions): Plugin<LoadedContent | null>;
+export { validateOptions } from './options';

package/lib/index.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOptions = void 0;
+exports.default = pluginContentPages;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+const mdx_loader_1 = require("@docusaurus/mdx-loader");
+const fs_1 = require("@docusaurus/fs");
+const routes_1 = require("./routes");
+const content_1 = require("./content");
+const contentHelpers_1 = require("./contentHelpers");
+function pluginContentPages(context, options) {
+    const { siteConfig, siteDir, generatedFilesDir } = context;
+    const contentPaths = (0, content_1.createPagesContentPaths)({ context, options });
+    const contentHelpers = (0, contentHelpers_1.createContentHelpers)();
+    const pluginDataDirRoot = node_path_1.default.join(generatedFilesDir, 'docusaurus-plugin-content-pages');
+    const dataDir = node_path_1.default.join(pluginDataDirRoot, options.id);
+    function createPagesMDXLoaderRule() {
+        const { admonitions, rehypePlugins, remarkPlugins, recmaPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
+        const contentDirs = (0, utils_1.getContentPathList)(contentPaths);
+        return (0, mdx_loader_1.createMDXLoaderRule)({
+            include: contentDirs
+                // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+                .map(utils_1.addTrailingPathSeparator),
+            options: {
+                admonitions,
+                remarkPlugins,
+                rehypePlugins,
+                recmaPlugins,
+                beforeDefaultRehypePlugins,
+                beforeDefaultRemarkPlugins,
+                staticDirs: siteConfig.staticDirectories.map((dir) => node_path_1.default.resolve(siteDir, dir)),
+                siteDir,
+                isMDXPartial: (0, glob_1.createAbsoluteFilePathMatcher)(options.exclude, contentDirs),
+                metadataPath: (mdxPath) => {
+                    // Note that metadataPath must be the same/in-sync as
+                    // the path from createData for each MDX.
+                    const aliasedSource = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
+                    return node_path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedSource)}.json`);
+                },
+                // createAssets converts relative paths to require() calls
+                createAssets: ({ frontMatter }) => ({
+                    image: frontMatter.image,
+                }),
+                markdownConfig: siteConfig.markdown,
+                resolveMarkdownLink: ({ linkPathname, sourceFilePath }) => {
+                    return (0, utils_1.resolveMarkdownLinkPathname)(linkPathname, {
+                        sourceFilePath,
+                        sourceToPermalink: contentHelpers.sourceToPermalink,
+                        siteDir,
+                        contentPaths,
+                    });
+                },
+            },
+        });
+    }
+    const pagesMDXLoaderRule = createPagesMDXLoaderRule();
+    return {
+        name: 'docusaurus-plugin-content-pages',
+        getPathsToWatch() {
+            const { include } = options;
+            return (0, utils_1.getContentPathList)(contentPaths).flatMap((contentPath) => include.map((pattern) => `${contentPath}/${pattern}`));
+        },
+        async loadContent() {
+            if (!(await (0, fs_1.pathExists)(contentPaths.contentPath))) {
+                return null;
+            }
+            return (0, content_1.loadPagesContent)({ context, options, contentPaths });
+        },
+        async contentLoaded({ content, actions }) {
+            if (!content) {
+                return;
+            }
+            contentHelpers.updateContent(content);
+            await (0, routes_1.createAllRoutes)({ content, options, actions });
+        },
+        configureWebpack() {
+            return {
+                module: {
+                    rules: [pagesMDXLoaderRule],
+                },
+            };
+        },
+    };
+}
+var options_1 = require("./options");
+Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return options_1.validateOptions; } });

package/lib/options.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { OptionValidationContext } from '@docusaurus/types';
+import type { PluginOptions, Options } from '@docusaurus/plugin-content-pages';
+export declare const DEFAULT_OPTIONS: PluginOptions;
+export declare function validateOptions({ validate, options, }: OptionValidationContext<Options, PluginOptions>): PluginOptions;

package/lib/options.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = validateOptions;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+exports.DEFAULT_OPTIONS = {
+    id: utils_1.DEFAULT_PLUGIN_ID,
+    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: glob_1.GlobExcludeDefault,
+    mdxPageComponent: '@theme/MDXPage',
+    remarkPlugins: [],
+    rehypePlugins: [],
+    recmaPlugins: [],
+    beforeDefaultRehypePlugins: [],
+    beforeDefaultRemarkPlugins: [],
+    admonitions: true,
+    showLastUpdateTime: false,
+    showLastUpdateAuthor: false,
+    editLocalizedFiles: false,
+};
+const PluginOptionSchema = utils_validation_1.Joi.object({
+    path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
+    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),
+    remarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.remarkPlugins),
+    rehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.rehypePlugins),
+    recmaPlugins: utils_validation_1.RecmaPluginsSchema.default(exports.DEFAULT_OPTIONS.recmaPlugins),
+    beforeDefaultRehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRehypePlugins),
+    beforeDefaultRemarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRemarkPlugins),
+    admonitions: utils_validation_1.AdmonitionsSchema.default(exports.DEFAULT_OPTIONS.admonitions),
+    showLastUpdateTime: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateTime),
+    showLastUpdateAuthor: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateAuthor),
+    editUrl: utils_validation_1.Joi.alternatives().try(utils_validation_1.URISchema, utils_validation_1.Joi.function()),
+    editLocalizedFiles: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.editLocalizedFiles),
+});
+function validateOptions({ validate, options, }) {
+    const validatedOptions = validate(PluginOptionSchema, options);
+    return validatedOptions;
+}

package/lib/routes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { PluginContentLoadedActions } from '@docusaurus/types';
+import type { PluginOptions, LoadedContent } from '@docusaurus/plugin-content-pages';
+type CreateAllRoutesParam = {
+    content: LoadedContent;
+    options: PluginOptions;
+    actions: PluginContentLoadedActions;
+};
+export declare function createAllRoutes(param: CreateAllRoutesParam): Promise<void>;
+export {};

package/lib/routes.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAllRoutes = createAllRoutes;
+const utils_1 = require("@docusaurus/utils");
+function createPageRouteMetadata(metadata) {
+    const lastUpdatedAt = metadata.type === 'mdx' ? metadata.lastUpdatedAt : undefined;
+    return {
+        sourceFilePath: (0, utils_1.aliasedSitePathToRelativePath)(metadata.source),
+        lastUpdatedAt,
+    };
+}
+async function createAllRoutes(param) {
+    const routes = await buildAllRoutes(param);
+    routes.forEach(param.actions.addRoute);
+}
+async function buildAllRoutes({ content, actions, options, }) {
+    const { createData } = actions;
+    async function buildMDXPageRoute(metadata) {
+        await createData(
+        // Note that this created data path must be in sync with
+        // metadataPath provided to mdx-loader.
+        `${(0, utils_1.docuHash)(metadata.source)}.json`, metadata);
+        return {
+            path: metadata.permalink,
+            component: options.mdxPageComponent,
+            exact: true,
+            metadata: createPageRouteMetadata(metadata),
+            modules: {
+                content: metadata.source,
+            },
+        };
+    }
+    async function buildJSXRoute(metadata) {
+        return {
+            path: metadata.permalink,
+            component: metadata.source,
+            exact: true,
+            metadata: createPageRouteMetadata(metadata),
+            modules: {
+                config: `@generated/docusaurus.config`,
+            },
+        };
+    }
+    async function buildPageRoute(metadata) {
+        return metadata.type === 'mdx'
+            ? buildMDXPageRoute(metadata)
+            : buildJSXRoute(metadata);
+    }
+    return Promise.all(content.map(buildPageRoute));
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@azerion/bunosaurus-plugin-content-pages",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "Pages plugin for Docusaurus.",
+  "main": "lib/index.js",
+  "types": "src/plugin-content-pages.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-plugin-content-pages"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/core": "npm:@azerion/bunosaurus-core@4.0.0",
+    "@docusaurus/fs": "npm:@azerion/bunosaurus-fs@4.0.0",
+    "@docusaurus/glob": "npm:@azerion/bunosaurus-glob@4.0.0",
+    "@docusaurus/mdx-loader": "npm:@azerion/bunosaurus-mdx-loader@4.0.0",
+    "@docusaurus/types": "npm:@azerion/bunosaurus-types@4.0.0",
+    "@docusaurus/utils": "npm:@azerion/bunosaurus-utils@4.0.0",
+    "@docusaurus/utils-validation": "npm:@azerion/bunosaurus-utils-validation@4.0.0",
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  },
+  "devDependencies": {
+    "webpack": "^5.111.0"
+  }
+}

package/src/content.ts

@@ -0,0 +1,204 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import path from 'node:path';
+import {
+  encodePath,
+  fileToPath,
+  aliasedSitePath,
+  getFolderContainingFile,
+  normalizeUrl,
+  parseMarkdownFile,
+  isUnlisted,
+  isDraft,
+  readLastUpdateData,
+  getEditUrl,
+  posixPath,
+  getPluginI18nPath,
+  getContentPathList,
+  getLocaleConfig,
+  type ContentPaths,
+} from '@docusaurus/utils';
+import {glob} from '@docusaurus/glob';
+import {fs} from '@docusaurus/fs';
+import {validatePageFrontMatter} from './frontMatter';
+import type {LoadContext} from '@docusaurus/types';
+import type {
+  PluginOptions,
+  Metadata,
+  LoadedContent,
+} from '@docusaurus/plugin-content-pages';
+
+export function createPagesContentPaths({
+  context,
+  options,
+}: {
+  context: LoadContext;
+  options: PluginOptions;
+}): ContentPaths {
+  const {siteDir, localizationDir} = context;
+
+  const shouldTranslate = getLocaleConfig(context.i18n).translate;
+  return {
+    contentPath: path.resolve(siteDir, options.path),
+    contentPathLocalized: shouldTranslate
+      ? getPluginI18nPath({
+          localizationDir,
+          pluginName: 'docusaurus-plugin-content-pages',
+          pluginId: options.id,
+        })
+      : undefined,
+  };
+}
+
+const isMarkdownSource = (source: string) =>
+  source.endsWith('.md') || source.endsWith('.mdx');
+
+type LoadContentParams = {
+  context: LoadContext;
+  options: PluginOptions;
+  contentPaths: ContentPaths;
+};
+
+export async function loadPagesContent(
+  params: LoadContentParams,
+): Promise<LoadedContent> {
+  const {options} = params;
+
+  const pagesFiles = await glob(params.options.include, {
+    cwd: params.contentPaths.contentPath,
+    ignore: options.exclude,
+  });
+
+  async function doProcessPageSourceFile(relativeSource: string) {
+    try {
+      return await processPageSourceFile(relativeSource, params);
+    } catch (err) {
+      throw new Error(
+        `Processing of page source file path=${relativeSource} failed.`,
+        {cause: err},
+      );
+    }
+  }
+
+  return (await Promise.all(pagesFiles.map(doProcessPageSourceFile))).filter(
+    (res): res is Metadata => {
+      return res !== undefined;
+    },
+  );
+}
+
+async function processPageSourceFile(
+  relativeSource: string,
+  params: LoadContentParams,
+): Promise<Metadata | undefined> {
+  const {context, options, contentPaths} = params;
+  const {siteConfig, baseUrl, siteDir, i18n} = context;
+  const {vcs} = siteConfig;
+  const {editUrl} = options;
+
+  // Lookup in localized folder in priority
+  const contentPath = await getFolderContainingFile(
+    getContentPathList(contentPaths),
+    relativeSource,
+  );
+
+  const source = path.join(contentPath, relativeSource);
+  const aliasedSourcePath = aliasedSitePath(source, siteDir);
+
+  const filenameSlug = encodePath(fileToPath(relativeSource));
+
+  if (!isMarkdownSource(relativeSource)) {
+    // For now, slug can't be customized for JSX pages
+    const slug = filenameSlug;
+    const permalink = normalizeUrl([baseUrl, options.routeBasePath, slug]);
+    return {
+      type: 'jsx',
+      permalink,
+      source: aliasedSourcePath,
+    };
+  }
+
+  const content = await fs.readFile(source, 'utf-8');
+  const {
+    frontMatter: unsafeFrontMatter,
+    contentTitle,
+    excerpt,
+  } = await parseMarkdownFile({
+    filePath: source,
+    fileContent: content,
+    parseFrontMatter: siteConfig.markdown.parseFrontMatter,
+  });
+  const frontMatter = validatePageFrontMatter(unsafeFrontMatter);
+
+  const slug = frontMatter.slug ?? filenameSlug;
+  const permalink = normalizeUrl([baseUrl, options.routeBasePath, slug]);
+
+  const pagesDirPath = await getFolderContainingFile(
+    getContentPathList(contentPaths),
+    relativeSource,
+  );
+
+  const pagesSourceAbsolute = path.join(pagesDirPath, relativeSource);
+
+  function getPagesEditUrl() {
+    const pagesPathRelative = path.relative(
+      pagesDirPath,
+      path.resolve(pagesSourceAbsolute),
+    );
+
+    if (typeof editUrl === 'function') {
+      return editUrl({
+        pagesDirPath: posixPath(path.relative(siteDir, pagesDirPath)),
+        pagesPath: posixPath(pagesPathRelative),
+        permalink,
+        locale: i18n.currentLocale,
+      });
+    } else if (typeof editUrl === 'string') {
+      const isLocalized = pagesDirPath === contentPaths.contentPathLocalized;
+      const fileContentPath =
+        isLocalized &&
+        options.editLocalizedFiles &&
+        contentPaths.contentPathLocalized
+          ? contentPaths.contentPathLocalized
+          : contentPaths.contentPath;
+
+      const contentPathEditUrl = normalizeUrl([
+        editUrl,
+        posixPath(path.relative(siteDir, fileContentPath)),
+      ]);
+
+      return getEditUrl(pagesPathRelative, contentPathEditUrl);
+    }
+    return undefined;
+  }
+
+  const lastUpdatedData = await readLastUpdateData(
+    source,
+    options,
+    frontMatter.last_update,
+    vcs,
+  );
+
+  if (isDraft({frontMatter})) {
+    return undefined;
+  }
+  const unlisted = isUnlisted({frontMatter});
+
+  return {
+    type: 'mdx',
+    permalink,
+    source: aliasedSourcePath,
+    title: frontMatter.title ?? contentTitle,
+    description: frontMatter.description ?? excerpt,
+    frontMatter,
+    lastUpdatedBy: lastUpdatedData.lastUpdatedBy,
+    lastUpdatedAt: lastUpdatedData.lastUpdatedAt,
+    editUrl: getPagesEditUrl(),
+    unlisted,
+  };
+}

package/src/contentHelpers.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {LoadedContent, Metadata} from '@docusaurus/plugin-content-pages';
+
+function indexPagesBySource(content: LoadedContent): Map<string, Metadata> {
+  return new Map(content.map((page) => [page.source, page]));
+}
+
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to page/permalink is a mutable map passed to the mdx loader
+//  See https://github.com/facebook/docusaurus/pull/10457
+//  See https://github.com/facebook/docusaurus/pull/10185
+export function createContentHelpers() {
+  const sourceToPage = new Map<string, Metadata>();
+  const sourceToPermalink = new Map<string, string>();
+
+  // Mutable map update :/
+  function updateContent(content: LoadedContent): void {
+    sourceToPage.clear();
+    sourceToPermalink.clear();
+    indexPagesBySource(content).forEach((value, key) => {
+      sourceToPage.set(key, value);
+      sourceToPermalink.set(key, value.permalink);
+    });
+  }
+
+  return {updateContent, sourceToPage, sourceToPermalink};
+}

package/src/frontMatter.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  Joi,
+  validateFrontMatter,
+  FrontMatterTOCHeadingLevels,
+  ContentVisibilitySchema,
+  URISchema,
+  FrontMatterLastUpdateSchema,
+} from '@docusaurus/utils-validation';
+import type {PageFrontMatter} from '@docusaurus/plugin-content-pages';
+/* eslint-disable camelcase */
+
+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,
+  slug: Joi.string(),
+  wrapperClassName: Joi.string(),
+  hide_table_of_contents: Joi.boolean(),
+  ...FrontMatterTOCHeadingLevels,
+  last_update: FrontMatterLastUpdateSchema,
+}).concat(ContentVisibilitySchema);
+
+export function validatePageFrontMatter(frontMatter: {
+  [key: string]: unknown;
+}): PageFrontMatter {
+  return validateFrontMatter(frontMatter, PageFrontMatterSchema);
+}

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import path from 'node:path';
+import {
+  aliasedSitePath,
+  docuHash,
+  addTrailingPathSeparator,
+  getContentPathList,
+  resolveMarkdownLinkPathname,
+} from '@docusaurus/utils';
+import {createAbsoluteFilePathMatcher} from '@docusaurus/glob';
+import {createMDXLoaderRule} from '@docusaurus/mdx-loader';
+import {pathExists} from '@docusaurus/fs';
+import {createAllRoutes} from './routes';
+import {createPagesContentPaths, loadPagesContent} from './content';
+import {createContentHelpers} from './contentHelpers';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {
+  PluginOptions,
+  LoadedContent,
+  PageFrontMatter,
+} from '@docusaurus/plugin-content-pages';
+import type {RuleSetRule} from 'webpack';
+
+export default function pluginContentPages(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin<LoadedContent | null> {
+  const {siteConfig, siteDir, generatedFilesDir} = context;
+
+  const contentPaths = createPagesContentPaths({context, options});
+  const contentHelpers = createContentHelpers();
+
+  const pluginDataDirRoot = path.join(
+    generatedFilesDir,
+    'docusaurus-plugin-content-pages',
+  );
+  const dataDir = path.join(pluginDataDirRoot, options.id);
+
+  function createPagesMDXLoaderRule(): RuleSetRule {
+    const {
+      admonitions,
+      rehypePlugins,
+      remarkPlugins,
+      recmaPlugins,
+      beforeDefaultRehypePlugins,
+      beforeDefaultRemarkPlugins,
+    } = options;
+    const contentDirs = getContentPathList(contentPaths);
+
+    return createMDXLoaderRule({
+      include: contentDirs
+        // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+        .map(addTrailingPathSeparator),
+      options: {
+        admonitions,
+        remarkPlugins,
+        rehypePlugins,
+        recmaPlugins,
+        beforeDefaultRehypePlugins,
+        beforeDefaultRemarkPlugins,
+        staticDirs: siteConfig.staticDirectories.map((dir) =>
+          path.resolve(siteDir, dir),
+        ),
+        siteDir,
+        isMDXPartial: createAbsoluteFilePathMatcher(
+          options.exclude,
+          contentDirs,
+        ),
+        metadataPath: (mdxPath: string) => {
+          // 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`);
+        },
+        // createAssets converts relative paths to require() calls
+        createAssets: ({frontMatter}: {frontMatter: PageFrontMatter}) => ({
+          image: frontMatter.image,
+        }),
+        markdownConfig: siteConfig.markdown,
+        resolveMarkdownLink: ({linkPathname, sourceFilePath}) => {
+          return resolveMarkdownLinkPathname(linkPathname, {
+            sourceFilePath,
+            sourceToPermalink: contentHelpers.sourceToPermalink,
+            siteDir,
+            contentPaths,
+          });
+        },
+      },
+    });
+  }
+
+  const pagesMDXLoaderRule = createPagesMDXLoaderRule();
+
+  return {
+    name: 'docusaurus-plugin-content-pages',
+
+    getPathsToWatch() {
+      const {include} = options;
+      return getContentPathList(contentPaths).flatMap((contentPath) =>
+        include.map((pattern) => `${contentPath}/${pattern}`),
+      );
+    },
+
+    async loadContent() {
+      if (!(await pathExists(contentPaths.contentPath))) {
+        return null;
+      }
+      return loadPagesContent({context, options, contentPaths});
+    },
+
+    async contentLoaded({content, actions}) {
+      if (!content) {
+        return;
+      }
+      contentHelpers.updateContent(content);
+      await createAllRoutes({content, options, actions});
+    },
+
+    configureWebpack() {
+      return {
+        module: {
+          rules: [pagesMDXLoaderRule],
+        },
+      };
+    },
+  };
+}
+
+export {validateOptions} from './options';

package/src/options.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {
+  Joi,
+  RemarkPluginsSchema,
+  RehypePluginsSchema,
+  RecmaPluginsSchema,
+  AdmonitionsSchema,
+  RouteBasePathSchema,
+  URISchema,
+} from '@docusaurus/utils-validation';
+import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
+import {GlobExcludeDefault} from '@docusaurus/glob';
+import type {OptionValidationContext} from '@docusaurus/types';
+import type {PluginOptions, Options} from '@docusaurus/plugin-content-pages';
+
+export const DEFAULT_OPTIONS: PluginOptions = {
+  id: DEFAULT_PLUGIN_ID,
+  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: [],
+  recmaPlugins: [],
+  beforeDefaultRehypePlugins: [],
+  beforeDefaultRemarkPlugins: [],
+  admonitions: true,
+  showLastUpdateTime: false,
+  showLastUpdateAuthor: false,
+  editLocalizedFiles: false,
+};
+
+const PluginOptionSchema = Joi.object<PluginOptions>({
+  path: Joi.string().default(DEFAULT_OPTIONS.path),
+  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),
+  remarkPlugins: RemarkPluginsSchema.default(DEFAULT_OPTIONS.remarkPlugins),
+  rehypePlugins: RehypePluginsSchema.default(DEFAULT_OPTIONS.rehypePlugins),
+  recmaPlugins: RecmaPluginsSchema.default(DEFAULT_OPTIONS.recmaPlugins),
+  beforeDefaultRehypePlugins: RehypePluginsSchema.default(
+    DEFAULT_OPTIONS.beforeDefaultRehypePlugins,
+  ),
+  beforeDefaultRemarkPlugins: RemarkPluginsSchema.default(
+    DEFAULT_OPTIONS.beforeDefaultRemarkPlugins,
+  ),
+  admonitions: AdmonitionsSchema.default(DEFAULT_OPTIONS.admonitions),
+  showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime),
+  showLastUpdateAuthor: Joi.bool().default(
+    DEFAULT_OPTIONS.showLastUpdateAuthor,
+  ),
+  editUrl: Joi.alternatives().try(URISchema, Joi.function()),
+  editLocalizedFiles: Joi.boolean().default(DEFAULT_OPTIONS.editLocalizedFiles),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  const validatedOptions = validate(PluginOptionSchema, options);
+  return validatedOptions;
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare module '@docusaurus/plugin-content-pages' {
+  import type {MDXOptions} from '@docusaurus/mdx-loader';
+  import type {
+    LoadContext,
+    Plugin,
+    OptionValidationContext,
+  } from '@docusaurus/types';
+  import type {FrontMatterLastUpdate, LastUpdateData} from '@docusaurus/utils';
+
+  export type Assets = {
+    image?: string;
+  };
+
+  export type PluginOptions = MDXOptions & {
+    id: string;
+    path: string;
+    routeBasePath: string;
+    include: string[];
+    exclude: string[];
+    mdxPageComponent: string;
+    showLastUpdateTime: boolean;
+    showLastUpdateAuthor: boolean;
+    editUrl?: string | EditUrlFunction;
+    editLocalizedFiles?: boolean;
+  };
+
+  export type Options = Partial<PluginOptions>;
+
+  export type PageFrontMatter = {
+    readonly title?: string;
+    readonly description?: string;
+    readonly image?: string;
+    readonly slug?: 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;
+    readonly last_update?: FrontMatterLastUpdate;
+  };
+
+  export type JSXPageMetadata = {
+    type: 'jsx';
+    permalink: string;
+    source: string;
+  };
+
+  export type MDXPageMetadata = LastUpdateData & {
+    type: 'mdx';
+    permalink: string;
+    source: string;
+    frontMatter: PageFrontMatter & {[key: string]: unknown};
+    editUrl?: string;
+    title?: string;
+    description?: string;
+    unlisted: boolean;
+  };
+
+  export type EditUrlFunction = (editUrlParams: {
+    /**
+     * The root content directory containing this post file, relative to the
+     * site path. Usually the same as `options.path` but can be localized
+     */
+    pagesDirPath: string;
+    /** Path to this pages file, relative to `pagesDirPath`. */
+    pagesPath: string;
+    /** @see {@link PagesPostMetadata.permalink} */
+    permalink: string;
+    /** Locale name. */
+    locale: string;
+  }) => string | undefined;
+
+  export type Metadata = JSXPageMetadata | MDXPageMetadata;
+
+  export type LoadedContent = Metadata[];
+
+  export default function pluginContentPages(
+    context: LoadContext,
+    options: PluginOptions,
+  ): Plugin<LoadedContent | null>;
+
+  export function validateOptions(
+    args: OptionValidationContext<Options | undefined, PluginOptions>,
+  ): PluginOptions;
+}
+
+declare module '@theme/MDXPage' {
+  import type {ReactNode} from 'react';
+  import type {LoadedMDXContent} from '@docusaurus/mdx-loader';
+  import type {
+    MDXPageMetadata,
+    PageFrontMatter,
+    Assets,
+  } from '@docusaurus/plugin-content-pages';
+
+  export interface Props {
+    readonly content: LoadedMDXContent<
+      PageFrontMatter,
+      MDXPageMetadata,
+      Assets
+    >;
+  }
+
+  export default function MDXPage(props: Props): ReactNode;
+}

package/src/routes.ts

@@ -0,0 +1,89 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {aliasedSitePathToRelativePath, docuHash} from '@docusaurus/utils';
+import type {
+  PluginContentLoadedActions,
+  RouteConfig,
+  RouteMetadata,
+} from '@docusaurus/types';
+import type {
+  PluginOptions,
+  Metadata,
+  LoadedContent,
+  MDXPageMetadata,
+} from '@docusaurus/plugin-content-pages';
+
+type CreateAllRoutesParam = {
+  content: LoadedContent;
+  options: PluginOptions;
+  actions: PluginContentLoadedActions;
+};
+
+function createPageRouteMetadata(metadata: Metadata): RouteMetadata {
+  const lastUpdatedAt =
+    metadata.type === 'mdx' ? metadata.lastUpdatedAt : undefined;
+  return {
+    sourceFilePath: aliasedSitePathToRelativePath(metadata.source),
+    lastUpdatedAt,
+  };
+}
+
+export async function createAllRoutes(
+  param: CreateAllRoutesParam,
+): Promise<void> {
+  const routes = await buildAllRoutes(param);
+  routes.forEach(param.actions.addRoute);
+}
+
+async function buildAllRoutes({
+  content,
+  actions,
+  options,
+}: CreateAllRoutesParam): Promise<RouteConfig[]> {
+  const {createData} = actions;
+
+  async function buildMDXPageRoute(
+    metadata: MDXPageMetadata,
+  ): Promise<RouteConfig> {
+    await createData(
+      // Note that this created data path must be in sync with
+      // metadataPath provided to mdx-loader.
+      `${docuHash(metadata.source)}.json`,
+      metadata,
+    );
+    return {
+      path: metadata.permalink,
+      component: options.mdxPageComponent,
+      exact: true,
+      metadata: createPageRouteMetadata(metadata),
+      modules: {
+        content: metadata.source,
+      },
+    };
+  }
+
+  async function buildJSXRoute(metadata: Metadata): Promise<RouteConfig> {
+    return {
+      path: metadata.permalink,
+      component: metadata.source,
+      exact: true,
+      metadata: createPageRouteMetadata(metadata),
+      modules: {
+        config: `@generated/docusaurus.config`,
+      },
+    };
+  }
+
+  async function buildPageRoute(metadata: Metadata): Promise<RouteConfig> {
+    return metadata.type === 'mdx'
+      ? buildMDXPageRoute(metadata)
+      : buildJSXRoute(metadata);
+  }
+
+  return Promise.all(content.map(buildPageRoute));
+}