@azerion/bunosaurus-mdx-loader 0.0.0-stage → 4.0.0

package/src/remark/transformImage/index.ts

@@ -0,0 +1,268 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import {
+  toMessageRelativeFilePath,
+  posixPath,
+  escapePath,
+  findAsyncSequential,
+  getFileLoaderUtils,
+  parseURLOrPath,
+  parseLocalURLPath,
+} from '@docusaurus/utils';
+import {imageSizeFromFile} from 'image-size/fromFile';
+import logger from '@docusaurus/logger';
+import {pathExists} from '@docusaurus/fs';
+import {
+  assetRequireAttributeValue,
+  formatNodePositionExtraMessage,
+  transformNode,
+} from '../utils';
+import type {Plugin, Transformer} from 'unified';
+import type {MdxJsxTextElement} from 'mdast-util-mdx';
+import type {Image, Root} from 'mdast';
+import type {Parent} from 'unist';
+import type {
+  MarkdownConfig,
+  OnBrokenMarkdownImagesFunction,
+} from '@docusaurus/types';
+
+export type PluginOptions = {
+  staticDirs: string[];
+  siteDir: string;
+  onBrokenMarkdownImages: MarkdownConfig['hooks']['onBrokenMarkdownImages'];
+};
+
+type Context = {
+  staticDirs: PluginOptions['staticDirs'];
+  siteDir: PluginOptions['siteDir'];
+  onBrokenMarkdownImages: OnBrokenMarkdownImagesFunction;
+  filePath: string;
+  inlineMarkdownImageFileLoader: string;
+};
+
+function asFunction(
+  onBrokenMarkdownImages: PluginOptions['onBrokenMarkdownImages'],
+): OnBrokenMarkdownImagesFunction {
+  if (typeof onBrokenMarkdownImages === 'string') {
+    const extraHelp =
+      onBrokenMarkdownImages === 'throw'
+        ? logger.interpolate`\nTo ignore this error, use the code=${'siteConfig.markdown.hooks.onBrokenMarkdownImages'} option, or apply the code=${'pathname://'} protocol to the broken image URLs.`
+        : '';
+    return ({sourceFilePath, url: imageUrl, node}) => {
+      const relativePath = toMessageRelativeFilePath(sourceFilePath);
+      if (imageUrl) {
+        logger.report(
+          onBrokenMarkdownImages,
+        )`Markdown image with URL code=${imageUrl} in source file path=${relativePath}${formatNodePositionExtraMessage(
+          node,
+        )} couldn't be resolved to an existing local image file.${extraHelp}`;
+      } else {
+        logger.report(
+          onBrokenMarkdownImages,
+        )`Markdown image with empty URL found in source file path=${relativePath}${formatNodePositionExtraMessage(
+          node,
+        )}.${extraHelp}`;
+      }
+    };
+  } else {
+    return (params) =>
+      onBrokenMarkdownImages({
+        ...params,
+        sourceFilePath: toMessageRelativeFilePath(params.sourceFilePath),
+      });
+  }
+}
+
+type Target = [node: Image, index: number, parent: Parent];
+
+async function toImageRequireNode(
+  [node]: Target,
+  imagePath: string,
+  context: Context,
+) {
+  // MdxJsxTextElement => see https://github.com/facebook/docusaurus/pull/8288#discussion_r1125871405
+  const jsxNode = node as unknown as MdxJsxTextElement;
+  const attributes: MdxJsxTextElement['attributes'] = [];
+
+  let relativeImagePath = posixPath(
+    path.relative(path.dirname(context.filePath), imagePath),
+  );
+  relativeImagePath = `./${relativeImagePath}`;
+
+  const parsedUrl = parseURLOrPath(node.url);
+  const hash = parsedUrl.hash ?? '';
+  const search = parsedUrl.search ?? '';
+  const requireString = `${context.inlineMarkdownImageFileLoader}${
+    escapePath(relativeImagePath) + search
+  }`;
+  if (node.alt) {
+    attributes.push({
+      type: 'mdxJsxAttribute',
+      name: 'alt',
+      value: node.alt,
+    });
+  }
+
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'src',
+    value: assetRequireAttributeValue(requireString, hash),
+  });
+
+  if (node.title) {
+    attributes.push({
+      type: 'mdxJsxAttribute',
+      name: 'title',
+      value: node.title,
+    });
+  }
+
+  try {
+    const size = (await imageSizeFromFile(imagePath))!;
+    if (size.width) {
+      attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'width',
+        value: String(size.width),
+      });
+    }
+    if (size.height) {
+      attributes.push({
+        type: 'mdxJsxAttribute',
+        name: 'height',
+        value: String(size.height),
+      });
+    }
+  } catch (err) {
+    console.error(err);
+    // Workaround for https://github.com/yarnpkg/berry/pull/3889#issuecomment-1034469784
+    // TODO remove this check once fixed in Yarn PnP
+    if (!process.versions.pnp) {
+      logger.warn`The image at path=${imagePath} can't be read correctly. Please ensure it's a valid image.
+${(err as Error).message}`;
+    }
+  }
+
+  transformNode(jsxNode, {
+    type: 'mdxJsxTextElement',
+    name: 'img',
+    attributes,
+    children: [],
+  });
+}
+
+async function getLocalImageAbsolutePath(
+  originalImagePath: string,
+  {siteDir, filePath, staticDirs}: Context,
+) {
+  if (originalImagePath.startsWith('@site/')) {
+    const imageFilePath = path.join(
+      siteDir,
+      originalImagePath.replace('@site/', ''),
+    );
+    if (!(await pathExists(imageFilePath))) {
+      return null;
+    }
+    return imageFilePath;
+  } else if (path.isAbsolute(originalImagePath)) {
+    // Absolute paths are expected to exist in the static folder.
+    const possiblePaths = staticDirs.map((dir) =>
+      path.join(dir, originalImagePath),
+    );
+    const imageFilePath = await findAsyncSequential(possiblePaths, pathExists);
+    if (!imageFilePath) {
+      return null;
+    }
+    return imageFilePath;
+  } else {
+    // relative paths are resolved against the source file's folder
+    const imageFilePath = path.join(path.dirname(filePath), originalImagePath);
+    if (!(await pathExists(imageFilePath))) {
+      return null;
+    }
+    return imageFilePath;
+  }
+}
+
+async function processImageNode(target: Target, context: Context) {
+  const [node] = target;
+
+  if (!node.url) {
+    node.url =
+      context.onBrokenMarkdownImages({
+        url: node.url,
+        sourceFilePath: context.filePath,
+        node,
+      }) ?? node.url;
+    return;
+  }
+
+  const localUrlPath = parseLocalURLPath(node.url);
+  if (!localUrlPath) {
+    // pathname:// is an escape hatch, in case the user does not want images to
+    // be converted to require calls going through webpack loader
+    if (parseURLOrPath(node.url).protocol === 'pathname:') {
+      node.url = node.url.replace('pathname://', '');
+    }
+    return;
+  }
+
+  // We decode it first because Node Url.pathname is always encoded
+  // while the image file-system path are not.
+  // See https://github.com/facebook/docusaurus/discussions/10720
+  const decodedPathname = decodeURIComponent(localUrlPath.pathname);
+
+  // We try to convert image urls without protocol to images with require calls
+  // going through webpack ensures that image assets exist at build time
+  const localImagePath = await getLocalImageAbsolutePath(
+    decodedPathname,
+    context,
+  );
+  if (localImagePath === null) {
+    node.url =
+      context.onBrokenMarkdownImages({
+        url: node.url,
+        sourceFilePath: context.filePath,
+        node,
+      }) ?? node.url;
+  } else {
+    await toImageRequireNode(target, localImagePath, context);
+  }
+}
+
+const plugin: Plugin<PluginOptions[], Root> = function plugin(
+  options,
+): Transformer<Root> {
+  const onBrokenMarkdownImages = asFunction(options.onBrokenMarkdownImages);
+
+  return async (root, vfile) => {
+    const fileLoaderUtils = getFileLoaderUtils(
+      vfile.data.compilerName === 'server',
+    );
+    const context: Context = {
+      ...options,
+      filePath: vfile.path!,
+      inlineMarkdownImageFileLoader:
+        fileLoaderUtils.loaders.inlineMarkdownImageFileLoader,
+      onBrokenMarkdownImages,
+    };
+
+    const promises: Promise<void>[] = [];
+    visit(root, 'image', (node, index, parent) => {
+      if (!parent || index === undefined) {
+        return;
+      }
+      promises.push(processImageNode([node, index, parent!], context));
+    });
+    await Promise.all(promises);
+  };
+};
+
+export default plugin;

package/src/remark/transformLinks/index.ts

@@ -0,0 +1,291 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import {
+  toMessageRelativeFilePath,
+  posixPath,
+  escapePath,
+  findAsyncSequential,
+  getFileLoaderUtils,
+  parseURLOrPath,
+  parseLocalURLPath,
+} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
+import {fs} from '@docusaurus/fs';
+import {
+  assetRequireAttributeValue,
+  formatNodePositionExtraMessage,
+  transformNode,
+} from '../utils';
+import type {Plugin, Transformer} from 'unified';
+import type {MdxJsxTextElement} from 'mdast-util-mdx';
+import type {Parent} from 'unist';
+import type {Link, Root} from 'mdast';
+import type {
+  MarkdownConfig,
+  OnBrokenMarkdownLinksFunction,
+} from '@docusaurus/types';
+
+export type PluginOptions = {
+  staticDirs: string[];
+  siteDir: string;
+  onBrokenMarkdownLinks: MarkdownConfig['hooks']['onBrokenMarkdownLinks'];
+};
+
+type Context = PluginOptions & {
+  staticDirs: string[];
+  siteDir: string;
+  onBrokenMarkdownLinks: OnBrokenMarkdownLinksFunction;
+  filePath: string;
+  inlineMarkdownLinkFileLoader: string;
+};
+
+type Target = [node: Link, index: number, parent: Parent];
+
+function asFunction(
+  onBrokenMarkdownLinks: PluginOptions['onBrokenMarkdownLinks'],
+): OnBrokenMarkdownLinksFunction {
+  if (typeof onBrokenMarkdownLinks === 'string') {
+    const extraHelp =
+      onBrokenMarkdownLinks === 'throw'
+        ? logger.interpolate`\nTo ignore this error, use the code=${'siteConfig.markdown.hooks.onBrokenMarkdownLinks'} option, or apply the code=${'pathname://'} protocol to the broken link URLs.`
+        : '';
+
+    return ({sourceFilePath, url: linkUrl, node}) => {
+      const relativePath = toMessageRelativeFilePath(sourceFilePath);
+      if (linkUrl) {
+        logger.report(
+          onBrokenMarkdownLinks,
+        )`Markdown link with URL code=${linkUrl} in source file path=${relativePath}${formatNodePositionExtraMessage(
+          node,
+        )} couldn't be resolved.
+Make sure it references a local Markdown file that exists within the current plugin.${extraHelp}`;
+      } else {
+        logger.report(
+          onBrokenMarkdownLinks,
+        )`Markdown link with empty URL found in source file path=${relativePath}${formatNodePositionExtraMessage(
+          node,
+        )}.${extraHelp}`;
+      }
+    };
+  } else {
+    return (params) =>
+      onBrokenMarkdownLinks({
+        ...params,
+        sourceFilePath: toMessageRelativeFilePath(params.sourceFilePath),
+      });
+  }
+}
+
+/**
+ * Transforms the link node to a JSX `<a>` element with a `require()` call.
+ */
+function toAssetRequireNode(
+  [node]: Target,
+  assetPath: string,
+  context: Context,
+) {
+  // MdxJsxTextElement => see https://github.com/facebook/docusaurus/pull/8288#discussion_r1125871405
+  const jsxNode = node as unknown as MdxJsxTextElement;
+  const attributes: MdxJsxTextElement['attributes'] = [];
+
+  // require("assets/file.pdf") means requiring from a package called assets
+  const relativeAssetPath = `./${posixPath(
+    path.relative(path.dirname(context.filePath), assetPath),
+  )}`;
+
+  const parsedUrl = parseURLOrPath(node.url);
+  const hash = parsedUrl.hash ?? '';
+  const search = parsedUrl.search ?? '';
+
+  const requireString = `${
+    // A hack to stop Webpack from using its built-in loader to parse JSON
+    path.extname(relativeAssetPath) === '.json'
+      ? `${relativeAssetPath.replace('.json', '.raw')}!=`
+      : ''
+  }${context.inlineMarkdownLinkFileLoader}${
+    escapePath(relativeAssetPath) + search
+  }`;
+
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'target',
+    value: '_blank',
+  });
+
+  // Assets are not routes, and are required by Webpack already
+  // They should not trigger the broken link checker
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'data-noBrokenLinkCheck',
+    value: {
+      type: 'mdxJsxAttributeValueExpression',
+      value: 'true',
+      data: {
+        estree: {
+          type: 'Program',
+          body: [
+            {
+              type: 'ExpressionStatement',
+              expression: {
+                type: 'Literal',
+                value: true,
+                raw: 'true',
+              },
+            },
+          ],
+          sourceType: 'module',
+          comments: [],
+        },
+      },
+    },
+  });
+
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'href',
+    value: assetRequireAttributeValue(requireString, hash),
+  });
+
+  if (node.title) {
+    attributes.push({
+      type: 'mdxJsxAttribute',
+      name: 'title',
+      value: node.title,
+    });
+  }
+
+  const {children} = node;
+
+  transformNode(jsxNode, {
+    type: 'mdxJsxTextElement',
+    name: 'a',
+    attributes,
+    children,
+  });
+}
+
+/**
+ * Checks if the given file path exists and is a file.
+ * Returns true if it exists, false otherwise.
+ */
+async function isExistingFile(filePath: string): Promise<boolean> {
+  try {
+    return (await fs.stat(filePath)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function getLocalFileAbsolutePath(
+  assetPath: string,
+  {siteDir, filePath, staticDirs}: Context,
+) {
+  if (assetPath.startsWith('@site/')) {
+    const assetFilePath = path.join(siteDir, assetPath.replace('@site/', ''));
+    if (await isExistingFile(assetFilePath)) {
+      return assetFilePath;
+    }
+  } else if (path.isAbsolute(assetPath)) {
+    const assetFilePath = await findAsyncSequential(
+      staticDirs.map((dir) => path.join(dir, assetPath)),
+      isExistingFile,
+    );
+    if (assetFilePath) {
+      return assetFilePath;
+    }
+  } else {
+    const assetFilePath = path.join(path.dirname(filePath), assetPath);
+    if (await isExistingFile(assetFilePath)) {
+      return assetFilePath;
+    }
+  }
+  return null;
+}
+
+async function processLinkNode(target: Target, context: Context) {
+  const [node] = target;
+  if (!node.url) {
+    node.url =
+      context.onBrokenMarkdownLinks({
+        url: node.url,
+        sourceFilePath: context.filePath,
+        node,
+      }) ?? node.url;
+    return;
+  }
+
+  const localUrlPath = parseLocalURLPath(node.url);
+  if (!localUrlPath) {
+    // Don't process pathname:// here, it's used by the <Link> component
+    return;
+  }
+
+  const hasSiteAlias = localUrlPath.pathname.startsWith('@site/');
+  const hasAssetLikeExtension =
+    path.extname(localUrlPath.pathname) &&
+    !localUrlPath.pathname.match(/\.(?:mdx?|html)(?:#|$)/);
+  if (!hasSiteAlias && !hasAssetLikeExtension) {
+    return;
+  }
+
+  const localFilePath = await getLocalFileAbsolutePath(
+    decodeURIComponent(localUrlPath.pathname),
+    context,
+  );
+
+  if (localFilePath) {
+    toAssetRequireNode(target, localFilePath, context);
+  } else {
+    // The @site alias is the only way to believe that the user wants an asset.
+    if (hasSiteAlias) {
+      node.url =
+        context.onBrokenMarkdownLinks({
+          url: node.url,
+          sourceFilePath: context.filePath,
+          node,
+        }) ?? node.url;
+    } else {
+      // Even if the url has a dot, and it looks like a file extension
+      // it can be risky to throw and fail fast by default
+      // It's perfectly valid for a route path segment to look like a filename
+    }
+  }
+}
+
+const plugin: Plugin<PluginOptions[], Root> = function plugin(
+  options,
+): Transformer<Root> {
+  const onBrokenMarkdownLinks = asFunction(options.onBrokenMarkdownLinks);
+
+  return async (root, vfile) => {
+    const fileLoaderUtils = getFileLoaderUtils(
+      vfile.data.compilerName === 'server',
+    );
+
+    const context: Context = {
+      ...options,
+      filePath: vfile.path!,
+      inlineMarkdownLinkFileLoader:
+        fileLoaderUtils.loaders.inlineMarkdownLinkFileLoader,
+      onBrokenMarkdownLinks,
+    };
+
+    const promises: Promise<void>[] = [];
+    visit(root, 'link', (node, index, parent) => {
+      if (!parent || index === undefined) {
+        return;
+      }
+      promises.push(processLinkNode([node, index, parent], context));
+    });
+    await Promise.all(promises);
+  };
+};
+
+export default plugin;