@docusaurus/plugin-content-docs 0.0.0-5956 → 0.0.0-5957

package/lib/index.js

@@ -160,57 +160,56 @@ async function pluginContentDocs(context, options) {
         },
         configureWebpack(_config, isServer, utils, content) {
             const { rehypePlugins, remarkPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
+            const contentDirs = versionsMetadata
+                .flatMap(utils_1.getContentPathList)
+                // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+                .map(utils_1.addTrailingPathSeparator);
+            // TODO this does not re-run when content gets updated in dev!
+            //  it's probably better to restore a mutable cache in the plugin
             function getSourceToPermalink() {
                 const allDocs = content.loadedVersions.flatMap((v) => v.docs);
                 return Object.fromEntries(allDocs.map(({ source, permalink }) => [source, permalink]));
             }
-            const docsMarkdownOptions = {
-                siteDir,
-                sourceToPermalink: getSourceToPermalink(),
-                versionsMetadata,
-                onBrokenMarkdownLink: (brokenMarkdownLink) => {
-                    logger_1.default.report(siteConfig.onBrokenMarkdownLinks) `Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
-                },
-            };
-            function createMDXLoaderRule() {
-                const contentDirs = versionsMetadata
-                    .flatMap(utils_1.getContentPathList)
-                    // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
-                    .map(utils_1.addTrailingPathSeparator);
+            const sourceToPermalink = getSourceToPermalink();
+            function createMDXLoader() {
+                const loaderOptions = {
+                    admonitions: options.admonitions,
+                    remarkPlugins,
+                    rehypePlugins,
+                    beforeDefaultRehypePlugins,
+                    beforeDefaultRemarkPlugins,
+                    staticDirs: siteConfig.staticDirectories.map((dir) => path_1.default.resolve(siteDir, dir)),
+                    siteDir,
+                    isMDXPartial: (0, utils_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 aliasedPath = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
+                        return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
+                    },
+                    // Assets allow to convert some relative images paths to
+                    // require(...) calls
+                    createAssets: ({ frontMatter }) => ({
+                        image: frontMatter.image,
+                    }),
+                    markdownConfig: siteConfig.markdown,
+                    resolveMarkdownLink: ({ linkPathname, sourceFilePath }) => {
+                        const version = (0, versions_1.getVersionFromSourceFilePath)(sourceFilePath, content.loadedVersions);
+                        const permalink = (0, utils_1.resolveMarkdownLinkPathname)(linkPathname, {
+                            sourceFilePath,
+                            sourceToPermalink,
+                            siteDir,
+                            contentPaths: version,
+                        });
+                        if (permalink === null) {
+                            logger_1.default.report(siteConfig.onBrokenMarkdownLinks) `Docs markdown link couldn't be resolved: (url=${linkPathname}) in source file path=${sourceFilePath} for version number=${version.versionName}`;
+                        }
+                        return permalink;
+                    },
+                };
                 return {
-                    test: /\.mdx?$/i,
-                    include: contentDirs,
-                    use: [
-                        {
-                            loader: require.resolve('@docusaurus/mdx-loader'),
-                            options: {
-                                admonitions: options.admonitions,
-                                remarkPlugins,
-                                rehypePlugins,
-                                beforeDefaultRehypePlugins,
-                                beforeDefaultRemarkPlugins,
-                                staticDirs: siteConfig.staticDirectories.map((dir) => path_1.default.resolve(siteDir, dir)),
-                                siteDir,
-                                isMDXPartial: (0, utils_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 aliasedPath = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
-                                    return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
-                                },
-                                // Assets allow to convert some relative images paths to
-                                // require(...) calls
-                                createAssets: ({ frontMatter, }) => ({
-                                    image: frontMatter.image,
-                                }),
-                                markdownConfig: siteConfig.markdown,
-                            },
-                        },
-                        {
-                            loader: path_1.default.resolve(__dirname, './markdown/index.js'),
-                            options: docsMarkdownOptions,
-                        },
-                    ].filter(Boolean),
+                    loader: require.resolve('@docusaurus/mdx-loader'),
+                    options: loaderOptions,
                 };
             }
             return {
@@ -225,7 +224,13 @@ async function pluginContentDocs(context, options) {
                     },
                 },
                 module: {
-                    rules: [createMDXLoaderRule()],
+                    rules: [
+                        {
+                            test: /\.mdx?$/i,
+                            include: contentDirs,
+                            use: [createMDXLoader()],
+                        },
+                    ],
                 },
             };
         },

package/lib/types.d.ts

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference path="../src/plugin-content-docs.d.ts" />
-import type { BrokenMarkdownLink, Tag } from '@docusaurus/utils';
-import type { VersionMetadata, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
+import type { Tag } from '@docusaurus/utils';
+import type { LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';
 export type DocFile = {
     contentPath: string;
@@ -29,10 +29,3 @@ export type FullVersion = LoadedVersion & {
     sidebarsUtils: SidebarsUtils;
     categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
-export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
-export type DocsMarkdownOption = {
-    versionsMetadata: VersionMetadata[];
-    siteDir: string;
-    sourceToPermalink: SourceToPermalink;
-    onBrokenMarkdownLink: (brokenMarkdownLink: DocBrokenMarkdownLink) => void;
-};

package/lib/versions/index.d.ts

@@ -38,3 +38,4 @@ export declare function readVersionsMetadata({ context, options, }: {
     options: PluginOptions;
 }): Promise<VersionMetadata[]>;
 export declare function toFullVersion(version: LoadedVersion): FullVersion;
+export declare function getVersionFromSourceFilePath(filePath: string, versionsMetadata: VersionMetadata[]): VersionMetadata;

package/lib/versions/index.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toFullVersion = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
+exports.getVersionFromSourceFilePath = exports.toFullVersion = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
@@ -171,3 +171,11 @@ function toFullVersion(version) {
     };
 }
 exports.toFullVersion = toFullVersion;
+function getVersionFromSourceFilePath(filePath, versionsMetadata) {
+    const versionFound = versionsMetadata.find((version) => (0, utils_1.getContentPathList)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
+    if (!versionFound) {
+        throw new Error(`Unexpected error: file at "${filePath}" does not belong to any docs version!`);
+    }
+    return versionFound;
+}
+exports.getVersionFromSourceFilePath = getVersionFromSourceFilePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-5956",
+  "version": "0.0.0-5957",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,14 +35,14 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5956",
-    "@docusaurus/logger": "0.0.0-5956",
-    "@docusaurus/mdx-loader": "0.0.0-5956",
-    "@docusaurus/module-type-aliases": "0.0.0-5956",
-    "@docusaurus/types": "0.0.0-5956",
-    "@docusaurus/utils": "0.0.0-5956",
-    "@docusaurus/utils-common": "0.0.0-5956",
-    "@docusaurus/utils-validation": "0.0.0-5956",
+    "@docusaurus/core": "0.0.0-5957",
+    "@docusaurus/logger": "0.0.0-5957",
+    "@docusaurus/mdx-loader": "0.0.0-5957",
+    "@docusaurus/module-type-aliases": "0.0.0-5957",
+    "@docusaurus/types": "0.0.0-5957",
+    "@docusaurus/utils": "0.0.0-5957",
+    "@docusaurus/utils-common": "0.0.0-5957",
+    "@docusaurus/utils-validation": "0.0.0-5957",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
@@ -66,5 +66,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "9d56d3ae55b9d718ecc50f61719c02872478bf52"
+  "gitHead": "edb3a453b0b3a853eadfc4e9ec44d47ea76d5002"
 }

package/src/index.ts

@@ -17,6 +17,7 @@ import {
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
   createSlugger,
+  resolveMarkdownLinkPathname,
   DEFAULT_PLUGIN_ID,
 } from '@docusaurus/utils';
 import {loadSidebars, resolveSidebarPathOption} from './sidebars';
@@ -28,7 +29,11 @@ import {
   type DocEnv,
   createDocsByIdIndex,
 } from './docs';
-import {readVersionsMetadata, toFullVersion} from './versions';
+import {
+  getVersionFromSourceFilePath,
+  readVersionsMetadata,
+  toFullVersion,
+} from './versions';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
 import {toGlobalDataVersion} from './globalData';
@@ -38,6 +43,7 @@ import {
 } from './translations';
 import {createAllRoutes} from './routes';
 import {createSidebarsUtils} from './sidebars/utils';
+import type {Options as MDXLoaderOptions} from '@docusaurus/mdx-loader';
 
 import type {
   PluginOptions,
@@ -48,13 +54,8 @@ import type {
   LoadedVersion,
 } from '@docusaurus/plugin-content-docs';
 import type {LoadContext, Plugin} from '@docusaurus/types';
-import type {
-  SourceToPermalink,
-  DocFile,
-  DocsMarkdownOption,
-  FullVersion,
-} from './types';
-import type {RuleSetRule} from 'webpack';
+import type {SourceToPermalink, DocFile, FullVersion} from './types';
+import type {RuleSetUseItem} from 'webpack';
 
 export default async function pluginContentDocs(
   context: LoadContext,
@@ -251,72 +252,71 @@ export default async function pluginContentDocs(
         beforeDefaultRemarkPlugins,
       } = options;
 
+      const contentDirs = versionsMetadata
+        .flatMap(getContentPathList)
+        // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+        .map(addTrailingPathSeparator);
+
+      // TODO this does not re-run when content gets updated in dev!
+      //  it's probably better to restore a mutable cache in the plugin
       function getSourceToPermalink(): SourceToPermalink {
         const allDocs = content.loadedVersions.flatMap((v) => v.docs);
         return Object.fromEntries(
           allDocs.map(({source, permalink}) => [source, permalink]),
         );
       }
+      const sourceToPermalink = getSourceToPermalink();
+
+      function createMDXLoader(): RuleSetUseItem {
+        const loaderOptions: MDXLoaderOptions = {
+          admonitions: options.admonitions,
+          remarkPlugins,
+          rehypePlugins,
+          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 aliasedPath = aliasedSitePath(mdxPath, siteDir);
+            return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
+          },
+          // Assets allow to convert some relative images paths to
+          // require(...) calls
+          createAssets: ({frontMatter}: {frontMatter: DocFrontMatter}) => ({
+            image: frontMatter.image,
+          }),
+          markdownConfig: siteConfig.markdown,
+          resolveMarkdownLink: ({linkPathname, sourceFilePath}) => {
+            const version = getVersionFromSourceFilePath(
+              sourceFilePath,
+              content.loadedVersions,
+            );
+            const permalink = resolveMarkdownLinkPathname(linkPathname, {
+              sourceFilePath,
+              sourceToPermalink,
+              siteDir,
+              contentPaths: version,
+            });
+            if (permalink === null) {
+              logger.report(
+                siteConfig.onBrokenMarkdownLinks,
+              )`Docs markdown link couldn't be resolved: (url=${linkPathname}) in source file path=${sourceFilePath} for version number=${version.versionName}`;
+            }
+            return permalink;
+          },
+        };
 
-      const docsMarkdownOptions: DocsMarkdownOption = {
-        siteDir,
-        sourceToPermalink: getSourceToPermalink(),
-        versionsMetadata,
-        onBrokenMarkdownLink: (brokenMarkdownLink) => {
-          logger.report(
-            siteConfig.onBrokenMarkdownLinks,
-          )`Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
-        },
-      };
-
-      function createMDXLoaderRule(): RuleSetRule {
-        const contentDirs = versionsMetadata
-          .flatMap(getContentPathList)
-          // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
-          .map(addTrailingPathSeparator);
         return {
-          test: /\.mdx?$/i,
-          include: contentDirs,
-          use: [
-            {
-              loader: require.resolve('@docusaurus/mdx-loader'),
-              options: {
-                admonitions: options.admonitions,
-                remarkPlugins,
-                rehypePlugins,
-                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 aliasedPath = aliasedSitePath(mdxPath, siteDir);
-                  return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
-                },
-                // Assets allow to convert some relative images paths to
-                // require(...) calls
-                createAssets: ({
-                  frontMatter,
-                }: {
-                  frontMatter: DocFrontMatter;
-                }) => ({
-                  image: frontMatter.image,
-                }),
-                markdownConfig: siteConfig.markdown,
-              },
-            },
-            {
-              loader: path.resolve(__dirname, './markdown/index.js'),
-              options: docsMarkdownOptions,
-            },
-          ].filter(Boolean),
+          loader: require.resolve('@docusaurus/mdx-loader'),
+          options: loaderOptions,
         };
       }
 
@@ -333,7 +333,13 @@ export default async function pluginContentDocs(
           },
         },
         module: {
-          rules: [createMDXLoaderRule()],
+          rules: [
+            {
+              test: /\.mdx?$/i,
+              include: contentDirs,
+              use: [createMDXLoader()],
+            },
+          ],
         },
       };
     },

package/src/types.ts

@@ -5,9 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {BrokenMarkdownLink, Tag} from '@docusaurus/utils';
+import type {Tag} from '@docusaurus/utils';
 import type {
-  VersionMetadata,
   LoadedVersion,
   CategoryGeneratedIndexMetadata,
 } from '@docusaurus/plugin-content-docs';
@@ -37,12 +36,3 @@ export type FullVersion = LoadedVersion & {
   sidebarsUtils: SidebarsUtils;
   categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
-
-export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
-
-export type DocsMarkdownOption = {
-  versionsMetadata: VersionMetadata[];
-  siteDir: string;
-  sourceToPermalink: SourceToPermalink;
-  onBrokenMarkdownLink: (brokenMarkdownLink: DocBrokenMarkdownLink) => void;
-};

package/src/versions/index.ts

@@ -6,7 +6,7 @@
  */
 
 import path from 'path';
-import {normalizeUrl, posixPath} from '@docusaurus/utils';
+import {getContentPathList, normalizeUrl, posixPath} from '@docusaurus/utils';
 import {CURRENT_VERSION_NAME} from '../constants';
 import {validateVersionsOptions} from './validation';
 import {
@@ -268,3 +268,20 @@ export function toFullVersion(version: LoadedVersion): FullVersion {
     }),
   };
 }
+
+export function getVersionFromSourceFilePath(
+  filePath: string,
+  versionsMetadata: VersionMetadata[],
+): VersionMetadata {
+  const versionFound = versionsMetadata.find((version) =>
+    getContentPathList(version).some((docsDirPath) =>
+      filePath.startsWith(docsDirPath),
+    ),
+  );
+  if (!versionFound) {
+    throw new Error(
+      `Unexpected error: file at "${filePath}" does not belong to any docs version!`,
+    );
+  }
+  return versionFound;
+}

package/lib/markdown/index.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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 { DocsMarkdownOption } from '../types';
-import type { LoaderContext } from 'webpack';
-export default function markdownLoader(this: LoaderContext<DocsMarkdownOption>, source: string): void;

package/lib/markdown/index.js

@@ -1,16 +0,0 @@
-"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 });
-const linkify_1 = require("./linkify");
-function markdownLoader(source) {
-    const fileString = source;
-    const callback = this.async();
-    const options = this.getOptions();
-    return callback(null, (0, linkify_1.linkify)(fileString, this.resourcePath, options));
-}
-exports.default = markdownLoader;

package/lib/markdown/linkify.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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 { DocsMarkdownOption } from '../types';
-export declare function linkify(fileString: string, filePath: string, options: DocsMarkdownOption): string;

package/lib/markdown/linkify.js

@@ -1,34 +0,0 @@
-"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.linkify = void 0;
-const utils_1 = require("@docusaurus/utils");
-function getVersion(filePath, options) {
-    const versionFound = options.versionsMetadata.find((version) => (0, utils_1.getContentPathList)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
-    // At this point, this should never happen, because the MDX loaders' paths are
-    // literally using the version content paths; but if we allow sourcing content
-    // from outside the docs directory (through the `include` option, for example;
-    // is there a compelling use-case?), this would actually be testable
-    if (!versionFound) {
-        throw new Error(`Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`);
-    }
-    return versionFound;
-}
-function linkify(fileString, filePath, options) {
-    const { siteDir, sourceToPermalink, onBrokenMarkdownLink } = options;
-    const { newContent, brokenMarkdownLinks } = (0, utils_1.replaceMarkdownLinks)({
-        siteDir,
-        fileString,
-        filePath,
-        contentPaths: getVersion(filePath, options),
-        sourceToPermalink,
-    });
-    brokenMarkdownLinks.forEach((l) => onBrokenMarkdownLink(l));
-    return newContent;
-}
-exports.linkify = linkify;

package/src/markdown/index.ts

@@ -1,20 +0,0 @@
-/**
- * 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 {linkify} from './linkify';
-import type {DocsMarkdownOption} from '../types';
-import type {LoaderContext} from 'webpack';
-
-export default function markdownLoader(
-  this: LoaderContext<DocsMarkdownOption>,
-  source: string,
-): void {
-  const fileString = source;
-  const callback = this.async();
-  const options = this.getOptions();
-  return callback(null, linkify(fileString, this.resourcePath, options));
-}

package/src/markdown/linkify.ts

@@ -1,47 +0,0 @@
-/**
- * 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 {replaceMarkdownLinks, getContentPathList} from '@docusaurus/utils';
-import type {DocsMarkdownOption} from '../types';
-
-function getVersion(filePath: string, options: DocsMarkdownOption) {
-  const versionFound = options.versionsMetadata.find((version) =>
-    getContentPathList(version).some((docsDirPath) =>
-      filePath.startsWith(docsDirPath),
-    ),
-  );
-  // At this point, this should never happen, because the MDX loaders' paths are
-  // literally using the version content paths; but if we allow sourcing content
-  // from outside the docs directory (through the `include` option, for example;
-  // is there a compelling use-case?), this would actually be testable
-  if (!versionFound) {
-    throw new Error(
-      `Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`,
-    );
-  }
-  return versionFound;
-}
-
-export function linkify(
-  fileString: string,
-  filePath: string,
-  options: DocsMarkdownOption,
-): string {
-  const {siteDir, sourceToPermalink, onBrokenMarkdownLink} = options;
-
-  const {newContent, brokenMarkdownLinks} = replaceMarkdownLinks({
-    siteDir,
-    fileString,
-    filePath,
-    contentPaths: getVersion(filePath, options),
-    sourceToPermalink,
-  });
-
-  brokenMarkdownLinks.forEach((l) => onBrokenMarkdownLink(l));
-
-  return newContent;
-}