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

package/src/remark/admonitions/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2020 Elvis Wolcott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/remark/admonitions/README.md

@@ -0,0 +1,3 @@
+# Docusaurus admonitions
+
+Code from [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) (MIT license) has been copied to this folder, and highly customized for Docusaurus needs.

package/src/remark/admonitions/index.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import type {Transformer, Plugin} from 'unified';
+import type {ContainerDirective} from 'mdast-util-directive';
+import type {Parent, Root} from 'mdast';
+
+export type AdmonitionOptions = {
+  keywords: string[];
+  extendDefaults: boolean;
+};
+
+export const DefaultAdmonitionOptions: AdmonitionOptions = {
+  keywords: [
+    'secondary',
+    'info',
+    'success',
+    'danger',
+    'note',
+    'tip',
+    'warning',
+    'important',
+    'caution',
+  ],
+  extendDefaults: true,
+};
+
+export function normalizeAdmonitionOptions(
+  providedOptions: Partial<AdmonitionOptions> | true,
+): AdmonitionOptions {
+  if (providedOptions === true) {
+    return DefaultAdmonitionOptions;
+  }
+
+  const options = {...DefaultAdmonitionOptions, ...providedOptions};
+
+  // By default it makes more sense to append keywords to the default ones
+  // Adding custom keywords is more common than disabling existing ones
+  if (options.extendDefaults) {
+    options.keywords = [
+      ...DefaultAdmonitionOptions.keywords,
+      ...options.keywords,
+    ];
+  }
+
+  return options;
+}
+
+type DirectiveLabel = Parent;
+type DirectiveContent = ContainerDirective['children'];
+
+function parseDirective(directive: ContainerDirective): {
+  directiveLabel: DirectiveLabel | undefined;
+  contentNodes: DirectiveContent;
+} {
+  const hasDirectiveLabel =
+    // @ts-expect-error: fine
+    directive.children?.[0]?.data?.directiveLabel === true;
+  if (hasDirectiveLabel) {
+    const [directiveLabel, ...contentNodes] = directive.children;
+    return {directiveLabel: directiveLabel as DirectiveLabel, contentNodes};
+  }
+  return {directiveLabel: undefined, contentNodes: directive.children};
+}
+
+function getTextOnlyTitle(directiveLabel: DirectiveLabel): string | undefined {
+  const isTextOnlyTitle =
+    directiveLabel?.children?.length === 1 &&
+    directiveLabel?.children?.[0]?.type === 'text';
+  return isTextOnlyTitle
+    ? // @ts-expect-error: todo type
+      (directiveLabel?.children?.[0].value as string)
+    : undefined;
+}
+
+const plugin: Plugin<Partial<AdmonitionOptions>[], Root> = function plugin(
+  this,
+  optionsInput = {},
+): Transformer<Root> {
+  const {keywords} = normalizeAdmonitionOptions(optionsInput);
+
+  return (root) => {
+    visit(root, (node) => {
+      if (node.type === 'containerDirective') {
+        const isAdmonition = keywords.includes(node.name);
+
+        if (!isAdmonition) {
+          return;
+        }
+
+        const {directiveLabel, contentNodes} = parseDirective(node);
+
+        const textOnlyTitle =
+          node.attributes?.title ??
+          (directiveLabel ? getTextOnlyTitle(directiveLabel) : undefined);
+
+        // Transform the mdast directive node to a hast admonition node
+        // See https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes
+        // TODO in MDX v2 we should transform the whole directive to
+        // mdxJsxFlowElement instead of using hast
+        node.data = {
+          hName: 'admonition',
+          hProperties: {
+            ...(textOnlyTitle && {title: textOnlyTitle}),
+            ...(node.attributes?.class && {
+              className: node.attributes.class.split(' '),
+            }),
+            ...(node.attributes?.id && {id: node.attributes.id}),
+            type: node.name,
+          },
+        };
+        node.children = contentNodes;
+
+        // TODO legacy MDX v1 <mdxAdmonitionTitle> workaround
+        // v1: not possible to inject complex JSX elements as props
+        // v2: now possible: use a mdxJsxFlowElement element
+        if (directiveLabel && !textOnlyTitle) {
+          const complexTitleNode = {
+            type: 'mdxAdmonitionTitle',
+            data: {
+              hName: 'mdxAdmonitionTitle',
+              hProperties: {},
+            },
+            children: directiveLabel.children,
+          };
+          // @ts-expect-error: invented node type
+          node.children.unshift(complexTitleNode);
+        }
+      }
+    });
+  };
+};
+
+export default plugin;

package/src/remark/contentTitle/index.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 {toString} from 'mdast-util-to-string';
+import {visit, EXIT} from 'unist-util-visit';
+import type {Transformer, Plugin} from 'unified';
+import type {Heading, Parent, Root} from 'mdast';
+import type {MdxJsxFlowElement} from 'mdast-util-mdx';
+
+interface PluginOptions {
+  removeContentTitle?: boolean;
+}
+
+function wrapHeadingInJsxHeader(
+  headingNode: Heading,
+  parent: Parent,
+  index: number,
+) {
+  const header: MdxJsxFlowElement = {
+    type: 'mdxJsxFlowElement',
+    name: 'header',
+    attributes: [],
+    children: [headingNode],
+  };
+  parent.children[index] = header;
+}
+
+/**
+ * A remark plugin to extract the h1 heading found in Markdown files
+ * This is exposed as "data.contentTitle" to the processed vfile
+ * Also gives the ability to strip that content title (used for the blog plugin)
+ */
+const plugin: Plugin<PluginOptions[], Root> = function plugin(
+  options = {},
+): Transformer<Root> {
+  // content title is
+  const removeContentTitle = options.removeContentTitle ?? false;
+
+  return (root, vfile) => {
+    visit(root, ['heading', 'thematicBreak'], (node, index, parent) => {
+      if (!parent || index === undefined) {
+        return undefined;
+      }
+      if (node.type === 'heading') {
+        // console.log('headingNode:', headingNode);
+
+        if (node.depth === 1) {
+          vfile.data.contentTitle = toString(node);
+          if (removeContentTitle) {
+            parent.children.splice(index, 1);
+          } else {
+            // TODO in the future it might be better to export contentTitle as
+            // as JSX node to keep this logic a theme concern?
+            // See https://github.com/facebook/docusaurus/pull/10335#issuecomment-2250187371
+            wrapHeadingInJsxHeader(node, parent, index);
+          }
+          return EXIT; // We only handle the very first heading
+        }
+        // We only handle contentTitle if it's the very first heading found
+        if (node.depth >= 1) {
+          return EXIT;
+        }
+      }
+      // We only handle contentTitle when it's above the first thematic break
+      if (node.type === 'thematicBreak') {
+        return EXIT;
+      }
+      return undefined;
+    });
+  };
+};
+
+export default plugin;

package/src/remark/details/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import type {Transformer} from 'unified';
+
+import type {Root} from 'mdast';
+
+// Transform <details> to <Details>
+// MDX 2 doesn't allow to substitute html elements with the provider anymore
+export default function plugin(): Transformer<Root> {
+  return (root) => {
+    visit(root, 'mdxJsxFlowElement', (node) => {
+      if (node.name === 'details') {
+        node.name = 'Details';
+      }
+    });
+  };
+}

package/src/remark/head/index.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import type {Transformer} from 'unified';
+
+import type {Root} from 'mdast';
+
+// Transform <head> to <Head>
+// MDX 2 doesn't allow to substitute html elements with the provider anymore
+export default function plugin(): Transformer<Root> {
+  return (root) => {
+    visit(root, 'mdxJsxFlowElement', (node) => {
+      if (node.name === 'head') {
+        node.name = 'Head';
+      }
+    });
+  };
+}

package/src/remark/headings/index.ts

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+
+/* Based on remark-slug (https://github.com/remarkjs/remark-slug) and gatsby-remark-autolink-headers (https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-remark-autolink-headers) */
+
+import {toString} from 'mdast-util-to-string';
+import {visit} from 'unist-util-visit';
+import {parseMarkdownHeadingId, createSlugger} from '@docusaurus/utils';
+import type {Plugin, Transformer} from 'unified';
+import type {Heading, Root, Text} from 'mdast';
+
+export interface PluginOptions {
+  anchorsMaintainCase: boolean;
+}
+
+function getCommentContentHeadingId(comment: string): string | undefined {
+  // If the comment has spaces, we only consider the first part
+  const firstPart = comment.trim().split(' ')[0];
+  // We ignore comments that don't start with # on purpose
+  // Forcing users to use a leading # is more explicit
+  // In the future it's possible we'd want to allow other types of comments
+  // For example class comments like {/* .my-class */}
+  if (firstPart?.startsWith('#')) {
+    return firstPart.slice(1) || undefined;
+  }
+  return undefined;
+}
+
+function getCommentHeadingId(heading: Heading): string | undefined {
+  const lastChild = heading.children.at(-1);
+
+  // MDX comment: {/* my-id */} or {/* #my-id */}
+  if (
+    lastChild &&
+    lastChild.type === 'mdxTextExpression' &&
+    lastChild.data?.estree
+  ) {
+    const program = lastChild.data.estree;
+    // We only extract the id from single-comment MDX expressions
+    // ✅ {/* #my-id */}
+    // ❌ {/* #my-id */ /* #my-id2 */}
+    // ❌ {someExpression /* #my-id */}
+    if (program.body.length === 0 && program.comments?.length === 1) {
+      const commentContent = program.comments[0]!.value;
+      return getCommentContentHeadingId(commentContent);
+    }
+  }
+
+  // HTML comment: <!-- my-id --> or <!-- #my-id -->
+  if (lastChild?.type === 'html') {
+    const match = /^<!--(?<comment>[\s\S]*)-->$/.exec(
+      (lastChild as unknown as {value: string}).value,
+    );
+    if (match?.groups?.comment) {
+      const commentContent = match.groups.comment;
+      return getCommentContentHeadingId(commentContent);
+    }
+  }
+
+  return undefined;
+}
+
+// Try to find an explicit id in MD/MDX comments
+function extractCommentId(heading: Heading) {
+  const commentId = getCommentHeadingId(heading);
+  if (commentId) {
+    // Remove the last comment node
+    heading.children.pop();
+    // Trim the trailing space from the last text node ("text " → "text")
+    const newLast = heading.children.at(-1);
+    if (newLast?.type === 'text') {
+      newLast.value = newLast.value.trimEnd();
+    }
+    return commentId;
+  }
+  return undefined;
+}
+
+// Try to find an explicit id in the heading text (classic {#id} syntax)
+function extractClassicSyntaxHeadingId(heading: Heading, headingText: string) {
+  const parsedHeading = parseMarkdownHeadingId(headingText, 'classic');
+  // Remove the heading text from its id (legacy syntax)
+  if (parsedHeading.id) {
+    // When there's an id, it is always in the last child node
+    const lastNode = heading.children.at(-1) as Text;
+    if (heading.children.length > 1) {
+      const lastNodeText = parseMarkdownHeadingId(
+        lastNode.value,
+        'classic',
+      ).text;
+      // When the last part contains text + id, remove the id
+      if (lastNodeText) {
+        lastNode.value = lastNodeText;
+      }
+      // When last part contains only the id: completely remove that node
+      else {
+        heading.children.pop();
+      }
+    } else {
+      lastNode.value = parsedHeading.text;
+    }
+    return parsedHeading.id;
+  }
+  return undefined;
+}
+
+const plugin: Plugin<PluginOptions[], Root> = function plugin({
+  anchorsMaintainCase,
+}): Transformer<Root> {
+  return (root) => {
+    function getHeadingText(heading: Heading) {
+      const headingTextNodes = heading.children.filter(
+        ({type}) => !['html', 'jsx'].includes(type),
+      );
+      return toString(headingTextNodes.length > 0 ? headingTextNodes : heading);
+    }
+
+    const slugs = createSlugger();
+    visit(root, 'heading', (heading) => {
+      const data = heading.data ?? (heading.data = {});
+      const properties = data.hProperties ?? (data.hProperties = {});
+
+      // Gives the ability to provide/write a remark plugin that sets an id
+      // When an id is already set, we use it instead of running our own plugin
+      function extractAlreadyExistingId() {
+        if (properties.id) {
+          // Not sure why we need to slugify here, historical code
+          return slugs.slug(properties.id, {maintainCase: true});
+        }
+        return undefined;
+      }
+
+      function extractIdFromText() {
+        const headingText = getHeadingText(heading);
+        return (
+          extractClassicSyntaxHeadingId(heading, headingText) ??
+          slugs.slug(headingText, {maintainCase: anchorsMaintainCase})
+        );
+      }
+
+      // All the ways we can extract an id, ordered by priority
+      // /!\ the extraction methods can perform AST cleanup side effects
+      const id =
+        extractAlreadyExistingId() ??
+        extractCommentId(heading) ??
+        extractIdFromText();
+
+      data.id = id;
+      properties.id = id;
+    });
+  };
+};
+
+export default plugin;

package/src/remark/mdx1Compat/codeCompatPlugin.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import type {Transformer, Plugin} from 'unified';
+import type {Root} from 'mdast';
+
+// Solution inspired by https://github.com/pomber/docusaurus-mdx-2/blob/main/packages/mdx-loader/src/remark/codeCompat/index.ts
+// TODO after MDX 2 we probably don't need this - remove soon?
+// Only fenced code blocks are swapped by pre/code MDX components
+// Using <pre><code> in JSX shouldn't use our MDX components anymore
+
+// To make theme-classic/src/theme/MDXComponents/Pre work
+// we need to fill two properties that mdx v2 doesn't provide anymore
+const plugin: Plugin<unknown[], Root> = function plugin(): Transformer<Root> {
+  return (root) => {
+    visit(root, 'code', (node) => {
+      node.data = node.data || {};
+
+      node.data.hProperties = node.data.hProperties || {};
+      node.data.hProperties.metastring = node.meta;
+
+      // TODO Docusaurus v4: remove special case
+      // Retrocompatible support for live codeblock metastring
+      // Not really the appropriate place to handle that :s
+      node.data.hProperties.live = node.meta?.split(' ').includes('live');
+    });
+  };
+};
+
+export default plugin;

package/src/remark/mermaid/index.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import {transformNode} from '../utils';
+
+import type {Transformer} from 'unified';
+import type {Root} from 'mdast';
+
+// TODO: this plugin shouldn't be in the core MDX loader
+// After we allow plugins to provide Remark/Rehype plugins (see
+// https://github.com/facebook/docusaurus/issues/6370), this should be provided
+// by theme-mermaid itself
+export default function plugin(): Transformer<Root> {
+  return (root) => {
+    visit(root, 'code', (node) => {
+      if (node.lang === 'mermaid') {
+        // TODO migrate to mdxJsxFlowElement? cf admonitions
+        transformNode(node, {
+          type: 'mermaidCodeBlock',
+          data: {
+            hName: 'mermaid',
+            hProperties: {
+              value: node.value,
+            },
+          },
+        });
+      }
+    });
+  };
+}

package/src/remark/resolveMarkdownLinks/index.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 {visit} from 'unist-util-visit';
+import {
+  parseLocalURLPath,
+  serializeURLPath,
+  toMessageRelativeFilePath,
+  type URLPath,
+} from '@docusaurus/utils';
+import logger from '@docusaurus/logger';
+
+import {formatNodePositionExtraMessage} from '../utils';
+import type {Plugin, Transformer} from 'unified';
+import type {Definition, Link, Root} from 'mdast';
+import type {
+  MarkdownConfig,
+  OnBrokenMarkdownLinksFunction,
+} from '@docusaurus/types';
+
+type ResolveMarkdownLinkParams = {
+  /**
+   * Absolute path to the source file containing this Markdown link.
+   */
+  sourceFilePath: string;
+  /**
+   * The Markdown link pathname to resolve, as found in the source file.
+   * If the link is "./myFile.mdx?qs#hash", this will be "./myFile.mdx"
+   */
+  linkPathname: string;
+};
+
+export type ResolveMarkdownLink = (
+  params: ResolveMarkdownLinkParams,
+) => string | null;
+
+export interface PluginOptions {
+  resolveMarkdownLink: ResolveMarkdownLink;
+  onBrokenMarkdownLinks: MarkdownConfig['hooks']['onBrokenMarkdownLinks'];
+}
+
+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);
+      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 {
+    return (params) =>
+      onBrokenMarkdownLinks({
+        ...params,
+        sourceFilePath: toMessageRelativeFilePath(params.sourceFilePath),
+      });
+  }
+}
+
+const HAS_MARKDOWN_EXTENSION = /\.mdx?$/i;
+
+function parseMarkdownLinkURLPath(link: string): URLPath | null {
+  const urlPath = parseLocalURLPath(link);
+
+  // If it's not local, we don't resolve it even if it's a Markdown file
+  // Example, we don't resolve https://github.com/project/README.md
+  if (!urlPath) {
+    return null;
+  }
+
+  // Ignore links without a Markdown file extension (ignoring qs/hash)
+  if (!HAS_MARKDOWN_EXTENSION.test(urlPath.pathname)) {
+    return null;
+  }
+  return urlPath;
+}
+
+/**
+ * A remark plugin to extract the h1 heading found in Markdown files
+ * This is exposed as "data.contentTitle" to the processed vfile
+ * Also gives the ability to strip that content title (used for the blog plugin)
+ */
+// TODO merge this plugin with "transformLinks"
+//  in general we'd want to avoid traversing multiple times the same AST
+const plugin: Plugin<PluginOptions[], Root> = function plugin(
+  options,
+): Transformer<Root> {
+  const {resolveMarkdownLink} = options;
+
+  const onBrokenMarkdownLinks = asFunction(options.onBrokenMarkdownLinks);
+
+  return (root, file) => {
+    visit(root, ['link', 'definition'], (node) => {
+      const link = node as unknown as Link | Definition;
+      const linkURLPath = parseMarkdownLinkURLPath(link.url);
+      if (!linkURLPath) {
+        return;
+      }
+
+      const sourceFilePath = file.path;
+
+      const permalink = resolveMarkdownLink({
+        sourceFilePath,
+        linkPathname: linkURLPath.pathname,
+      });
+
+      if (permalink) {
+        // This reapplies the link ?qs#hash part to the resolved pathname
+        link.url = serializeURLPath({
+          ...linkURLPath,
+          pathname: permalink,
+        });
+      } else {
+        link.url =
+          onBrokenMarkdownLinks({
+            url: link.url,
+            sourceFilePath,
+            node: link,
+          }) ?? link.url;
+      }
+    });
+  };
+};
+
+export default plugin;