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

package/src/remark/toc/index.ts

@@ -0,0 +1,183 @@
+/**
+ * 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 {toString} from 'mdast-util-to-string';
+import {
+  addTocSliceImportIfNeeded,
+  createTOCExportNodeAST,
+  findDefaultImportName,
+  getImportDeclarations,
+  isMarkdownImport,
+  isNamedExport,
+} from './utils';
+import type {Heading, Root} from 'mdast';
+import type {Plugin, Transformer} from 'unified';
+import type {MdxjsEsm, MdxJsxFlowElement} from 'mdast-util-mdx';
+import type {TOCItems} from './types';
+import type {ImportDeclaration} from 'estree';
+
+interface PluginOptions {
+  name?: string;
+}
+
+// ComponentName (default export) => ImportDeclaration mapping
+type MarkdownImports = Map<string, {declaration: ImportDeclaration}>;
+
+// MdxjsEsm node representing an already existing "export const toc" declaration
+type ExistingTOCExport = MdxjsEsm | null;
+
+function createTocSliceImportName({
+  tocExportName,
+  componentName,
+}: {
+  tocExportName: string;
+  componentName: string;
+}) {
+  // The name of the toc slice import alias doesn't matter much
+  // We just need to ensure it's valid and won't conflict with other names
+  return `__${tocExportName}${componentName}`;
+}
+
+function collectImportsExports({
+  root,
+  tocExportName,
+}: {
+  root: Root;
+  tocExportName: string;
+}): {
+  markdownImports: MarkdownImports;
+  existingTocExport: ExistingTOCExport;
+} {
+  const markdownImports = new Map<string, {declaration: ImportDeclaration}>();
+  let existingTocExport: MdxjsEsm | null = null;
+
+  visit(root, 'mdxjsEsm', (node) => {
+    if (!node.data?.estree) {
+      return;
+    }
+    if (isNamedExport(node, tocExportName)) {
+      existingTocExport = node;
+    }
+
+    getImportDeclarations(node.data.estree).forEach((declaration) => {
+      if (!isMarkdownImport(declaration)) {
+        return;
+      }
+      const componentName = findDefaultImportName(declaration);
+      if (!componentName) {
+        return;
+      }
+      markdownImports.set(componentName, {
+        declaration,
+      });
+    });
+  });
+
+  return {markdownImports, existingTocExport};
+}
+
+function collectTOCItems({
+  root,
+  tocExportName,
+  markdownImports,
+}: {
+  root: Root;
+  tocExportName: string;
+  markdownImports: MarkdownImports;
+}): {
+  // The toc items we collected in the tree
+  tocItems: TOCItems;
+} {
+  const tocItems: TOCItems = [];
+
+  visit(root, (child) => {
+    if (child.type === 'heading') {
+      visitHeading(child);
+    } else if (child.type === 'mdxJsxFlowElement') {
+      visitJSXElement(child);
+    }
+  });
+
+  return {tocItems};
+
+  // Visit Markdown headings
+  function visitHeading(node: Heading) {
+    const value = toString(node);
+    // depth:1 headings are titles and not included in the TOC
+    if (!value || node.depth < 2) {
+      return;
+    }
+    tocItems.push({
+      type: 'heading',
+      heading: node,
+    });
+  }
+
+  // Visit JSX elements, such as <Partial/>
+  function visitJSXElement(node: MdxJsxFlowElement) {
+    const componentName = node.name;
+    if (!componentName) {
+      return;
+    }
+    const importDeclaration = markdownImports.get(componentName)?.declaration;
+    if (!importDeclaration) {
+      return;
+    }
+
+    const tocSliceImportName = createTocSliceImportName({
+      tocExportName,
+      componentName,
+    });
+
+    tocItems.push({
+      type: 'slice',
+      importName: tocSliceImportName,
+    });
+
+    addTocSliceImportIfNeeded({
+      importDeclaration,
+      tocExportName,
+      tocSliceImportName,
+    });
+  }
+}
+
+const plugin: Plugin<PluginOptions[], Root> = function plugin(
+  options = {},
+): Transformer<Root> {
+  const tocExportName = options.name || 'toc';
+
+  return (root) => {
+    const {markdownImports, existingTocExport} = collectImportsExports({
+      root,
+      tocExportName,
+    });
+
+    // If user explicitly writes "export const toc" in his mdx file
+    // We keep it as is do not override their explicit toc structure
+    // See https://github.com/facebook/docusaurus/pull/7530#discussion_r1458087876
+    if (existingTocExport) {
+      return;
+    }
+
+    const {tocItems} = collectTOCItems({
+      root,
+      tocExportName,
+      markdownImports,
+    });
+
+    root.children.push(
+      createTOCExportNodeAST({
+        tocExportName,
+        tocItems,
+      }),
+    );
+  };
+};
+
+export default plugin;

package/src/remark/toc/types.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 {Heading} from 'mdast';
+
+// Note: this type is exported from mdx-loader and used in theme
+// Need to keep it retro compatible
+export type TOCItem = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+};
+
+export type TOCHeading = {
+  readonly type: 'heading';
+  readonly heading: Heading;
+};
+
+// A TOC slice represents a TOCItem[] imported from a partial
+export type TOCSlice = {
+  readonly type: 'slice';
+  readonly importName: string;
+};
+
+export type TOCItems = (TOCHeading | TOCSlice)[];

package/src/remark/toc/utils.ts

@@ -0,0 +1,243 @@
+/**
+ * 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 {valueToEstree} from 'estree-util-value-to-estree';
+import escapeHtml from 'escape-html';
+import type {Node, Parent} from 'unist';
+import type {
+  MdxjsEsm,
+  MdxJsxAttribute,
+  MdxJsxTextElement,
+} from 'mdast-util-mdx';
+import type {TOCHeading, TOCItem, TOCItems, TOCSlice} from './types';
+import type {
+  Program,
+  SpreadElement,
+  ImportDeclaration,
+  ImportSpecifier,
+} from 'estree';
+import type {Heading, PhrasingContent} from 'mdast';
+
+export function getImportDeclarations(program: Program): ImportDeclaration[] {
+  return program.body.filter(
+    (item): item is ImportDeclaration => item.type === 'ImportDeclaration',
+  );
+}
+
+export function isMarkdownImport(node: Node): node is ImportDeclaration {
+  if (node.type !== 'ImportDeclaration') {
+    return false;
+  }
+  const importPath = (node as ImportDeclaration).source.value;
+  return typeof importPath === 'string' && /\.mdx?$/.test(importPath);
+}
+
+export function findDefaultImportName(
+  importDeclaration: ImportDeclaration,
+): string | undefined {
+  return importDeclaration.specifiers.find(
+    (o: Node) => o.type === 'ImportDefaultSpecifier',
+  )?.local.name;
+}
+
+function findNamedImportSpecifier(
+  importDeclaration: ImportDeclaration,
+  localName: string,
+): ImportSpecifier | undefined {
+  return importDeclaration?.specifiers.find(
+    (specifier): specifier is ImportSpecifier =>
+      specifier.type === 'ImportSpecifier' &&
+      specifier.local.name === localName,
+  );
+}
+
+// Before: import Partial from "partial"
+// After: import Partial, {toc as __tocPartial} from "partial"
+export function addTocSliceImportIfNeeded({
+  importDeclaration,
+  tocExportName,
+  tocSliceImportName,
+}: {
+  importDeclaration: ImportDeclaration;
+  tocExportName: string;
+  tocSliceImportName: string;
+}): void {
+  // We only add the toc slice named import if it doesn't exist already
+  if (!findNamedImportSpecifier(importDeclaration, tocSliceImportName)) {
+    importDeclaration.specifiers.push({
+      type: 'ImportSpecifier',
+      imported: {type: 'Identifier', name: tocExportName},
+      local: {type: 'Identifier', name: tocSliceImportName},
+    });
+  }
+}
+
+export function isNamedExport(
+  node: Node,
+  exportName: string,
+): node is MdxjsEsm {
+  if (node.type !== 'mdxjsEsm') {
+    return false;
+  }
+  const program = (node as MdxjsEsm).data?.estree;
+  if (!program) {
+    return false;
+  }
+  if (program.body.length !== 1) {
+    return false;
+  }
+  const exportDeclaration = program.body[0]!;
+  if (exportDeclaration.type !== 'ExportNamedDeclaration') {
+    return false;
+  }
+  const variableDeclaration = exportDeclaration.declaration;
+  if (variableDeclaration?.type !== 'VariableDeclaration') {
+    return false;
+  }
+  const {id} = variableDeclaration.declarations[0]!;
+  if (id.type !== 'Identifier') {
+    return false;
+  }
+
+  return id.name === exportName;
+}
+
+export function createTOCExportNodeAST({
+  tocExportName,
+  tocItems,
+}: {
+  tocExportName: string;
+  tocItems: TOCItems;
+}): MdxjsEsm {
+  function createTOCSliceAST(tocSlice: TOCSlice): SpreadElement {
+    return {
+      type: 'SpreadElement',
+      argument: {type: 'Identifier', name: tocSlice.importName},
+    };
+  }
+
+  function createTOCHeadingAST({heading}: TOCHeading) {
+    const value: TOCItem = {
+      value: toHeadingHTMLValue(heading),
+      id: heading.data!.id!,
+      level: heading.depth,
+    };
+    return valueToEstree(value);
+  }
+
+  function createTOCItemAST(tocItem: TOCItems[number]) {
+    switch (tocItem.type) {
+      case 'slice':
+        return createTOCSliceAST(tocItem);
+      case 'heading':
+        return createTOCHeadingAST(tocItem);
+      default: {
+        throw new Error(`unexpected toc item type`);
+      }
+    }
+  }
+
+  return {
+    type: 'mdxjsEsm',
+    value: '', // See https://github.com/facebook/docusaurus/pull/9684#discussion_r1457595181
+    data: {
+      estree: {
+        type: 'Program',
+        body: [
+          {
+            type: 'ExportNamedDeclaration',
+            attributes: [],
+            declaration: {
+              type: 'VariableDeclaration',
+              declarations: [
+                {
+                  type: 'VariableDeclarator',
+                  id: {
+                    type: 'Identifier',
+                    name: tocExportName,
+                  },
+                  init: {
+                    type: 'ArrayExpression',
+                    elements: tocItems.map(createTOCItemAST),
+                  },
+                },
+              ],
+              kind: 'const',
+            },
+            specifiers: [],
+            source: null,
+          },
+        ],
+        sourceType: 'module',
+      },
+    },
+  };
+}
+
+function stringifyChildren(node: Parent): string {
+  return (node.children as PhrasingContent[])
+    .map(toHeadingHTMLValue)
+    .join('')
+    .trim();
+}
+
+// TODO This is really a workaround, and not super reliable
+// For now we only support serializing tagName, className and content
+// Can we implement the TOC with real JSX nodes instead of html strings later?
+function mdxJsxTextElementToHtml(element: MdxJsxTextElement): string {
+  const tag = element.name;
+
+  // See https://github.com/facebook/docusaurus/issues/11003#issuecomment-2733925363
+  if (tag === 'img') {
+    return '';
+  }
+
+  const attributes = element.attributes.filter(
+    (child): child is MdxJsxAttribute => child.type === 'mdxJsxAttribute',
+  );
+
+  const classAttribute =
+    attributes.find((attr) => attr.name === 'className') ??
+    attributes.find((attr) => attr.name === 'class');
+
+  const classAttributeString = classAttribute
+    ? `class="${escapeHtml(String(classAttribute.value))}"`
+    : ``;
+
+  const allAttributes = classAttributeString ? ` ${classAttributeString}` : '';
+
+  const content = stringifyChildren(element);
+
+  return `<${tag}${allAttributes}>${content}</${tag}>`;
+}
+
+export function toHeadingHTMLValue(
+  node: PhrasingContent | Heading | MdxJsxTextElement,
+): string {
+  switch (node.type) {
+    case 'mdxJsxTextElement': {
+      return mdxJsxTextElementToHtml(node as MdxJsxTextElement);
+    }
+    case 'text':
+      return escapeHtml(node.value);
+    case 'heading':
+      return stringifyChildren(node);
+    case 'inlineCode':
+      return `<code>${escapeHtml(node.value)}</code>`;
+    case 'emphasis':
+      return `<em>${stringifyChildren(node)}</em>`;
+    case 'strong':
+      return `<strong>${stringifyChildren(node)}</strong>`;
+    case 'delete':
+      return `<del>${stringifyChildren(node)}</del>`;
+    case 'link':
+      return stringifyChildren(node);
+    default:
+      return toString(node);
+  }
+}