@temelj/mdx 0.8.0 → 0.8.2

package/compiler.ts

@@ -1,124 +0,0 @@
-import {
-  compile as compileMdxJs,
-  type CompileOptions as MdxJsCompileOptions,
-} from "@mdx-js/mdx";
-import remarkFrontmatterPlugin from "remark-frontmatter";
-import remarkGfmPlugin from "remark-gfm";
-import { VFile } from "vfile";
-import { matter } from "vfile-matter";
-import type { Pluggable, PluggableList, Plugin } from "unified";
-import type { z } from "zod";
-
-import type { HastNode } from "./types";
-
-export { remarkFrontmatterPlugin, remarkGfmPlugin };
-
-/**
- * Represents the source content for an MDX document.
- */
-export type MdxSource = string | Uint8Array;
-
-/**
- * Options for compiling an MDX document.
- */
-export interface MdxCompileOptions {
-  frontmatterOnly?: boolean | undefined;
-  mdxOptions?: MdxJsCompileOptions;
-}
-
-/**
- * The result of compiling an MDX document.
- * Compiled content is optional, because sometimes we only need the frontmatter.
- */
-export interface MdxArtifact<TFrontmatter = Record<string, unknown>> {
-  compiled?: string | undefined;
-  frontmatter: TFrontmatter;
-}
-
-/**
- * A reusable compiler for compiling MDX.
- */
-export class MdxCompiler {
-  private readonly mdxOptions: MdxJsCompileOptions;
-  private readonly remarkPlugins: PluggableList;
-  private readonly rehypePlugins: PluggableList;
-
-  public constructor(mdxOptions: MdxJsCompileOptions = {}) {
-    this.mdxOptions = mdxOptions;
-    this.remarkPlugins = [remarkFrontmatterPlugin, remarkGfmPlugin];
-    this.rehypePlugins = [];
-  }
-
-  public withRemarkPlugin<TOptions>(
-    plugin: Plugin<[TOptions?], HastNode, HastNode>,
-    options?: TOptions,
-  ): MdxCompiler {
-    if (options === undefined) {
-      this.remarkPlugins.push(plugin as Pluggable);
-    } else {
-      this.remarkPlugins.push([plugin, options] as Pluggable);
-    }
-    return this;
-  }
-
-  public withRehypePlugin<TOptions>(
-    plugin: Plugin<[TOptions?], HastNode, HastNode>,
-    options?: TOptions,
-  ): MdxCompiler {
-    if (options === undefined) {
-      this.rehypePlugins.push(plugin as Pluggable);
-    } else {
-      this.rehypePlugins.push([plugin, options] as Pluggable);
-    }
-    return this;
-  }
-
-  public async compile<TFrontmatterSchema extends z.ZodSchema>(
-    source: MdxSource,
-    { frontmatterOnly = false, mdxOptions }: MdxCompileOptions = {},
-    frontmatterSchema?: TFrontmatterSchema,
-  ): Promise<MdxArtifact<z.output<TFrontmatterSchema>>> {
-    const vfile = new VFile({
-      value: source,
-      // Needed so vfile doesn't need to access fs.
-      cwd: "/",
-      path: "/",
-      message: {},
-      messages: {},
-    });
-    matter(vfile, { strip: true });
-
-    const remarkPlugins = [
-      ...this.remarkPlugins,
-      ...(this.mdxOptions?.remarkPlugins ?? []),
-      ...(mdxOptions?.remarkPlugins ?? []),
-    ];
-    const rehypePlugins = [
-      ...this.rehypePlugins,
-      ...(this.mdxOptions?.rehypePlugins ?? []),
-      ...(mdxOptions?.rehypePlugins ?? []),
-    ];
-
-    let compiled: string | undefined;
-    if (!frontmatterOnly) {
-      const compiledFile = await compileMdxJs(vfile, {
-        outputFormat: "function-body",
-        ...(this.mdxOptions ?? {}),
-        ...(mdxOptions ?? {}),
-        remarkPlugins,
-        rehypePlugins,
-      });
-      compiled = compiledFile.value.toString();
-    }
-
-    const frontmatter =
-      frontmatterSchema === undefined
-        ? (vfile.data.matter ?? {})
-        : frontmatterSchema.parse(vfile.data.matter ?? {});
-
-    return {
-      compiled,
-      frontmatter: frontmatter as z.output<TFrontmatterSchema>,
-    };
-  }
-}

package/mod.ts

@@ -1,3 +0,0 @@
-export * from "./plugins/mod";
-export * from "./types";
-export * from "./compiler";

package/plugins/heading-id/plugin.ts

@@ -1,42 +0,0 @@
-import GithubSlugger from "github-slugger";
-import { toString as hastToString } from "hast-util-to-string";
-import { visit } from "unist-util-visit";
-import type { Plugin } from "unified";
-
-import type { HastElement, HastNode } from "../../types";
-
-/**
- * Options for {@linkcode headingIdPlugin}.
- */
-export interface HeadingIdPluginOptions {
-  /** Prefix for title slugs. */
-  prefix?: string;
-}
-
-/**
- * A rehype plugin that adds IDs to heading tags.
- */
-export const headingIdPlugin: Plugin<
-  [HeadingIdPluginOptions?],
-  HastNode,
-  HastNode
-> = ({ prefix } = {}) => {
-  const slugger = new GithubSlugger();
-  return (tree) => {
-    slugger.reset();
-    visit(
-      tree,
-      "element",
-      function visitor(
-        node: HastElement,
-        index: number,
-        parent: HastElement,
-      ): void {
-        if (!parent || index === null || !node.tagName.startsWith("h")) return;
-        const id = (prefix ?? "") + slugger.slug(hastToString(node));
-        node.properties.id = id;
-      },
-    );
-    return tree;
-  };
-};

package/plugins/mod.ts

@@ -1,4 +0,0 @@
-export * from "./heading-id/plugin";
-export * from "./syntax-highlight/plugin";
-export * from "./tree-processor/plugin";
-export * from "./remove-imports-exports";

package/plugins/remove-imports-exports.ts

@@ -1,18 +0,0 @@
-import { remove } from "unist-util-remove";
-import type { Plugin } from "unified";
-
-import type { HastNode } from "../types";
-
-/**
- * A remark plugin which removes all import and export statements.
- */
-export const removeImportsExportsPlugin: Plugin<
-  [unknown],
-  HastNode,
-  HastNode
-> = () => {
-  return (tree: HastNode) => {
-    remove(tree, "mdxjsEsm");
-    return tree;
-  };
-};

package/plugins/syntax-highlight/code-meta.test.ts

@@ -1,22 +0,0 @@
-import { expect, test } from "vitest";
-
-import { extractCodeMeta } from "./code-meta";
-
-test("code meta - extract", () => {
-  expect(
-    extractCodeMeta({
-      type: "element",
-      tagName: "pre",
-      properties: {},
-      children: [],
-      data: {
-        meta: '{"highlight": "3..5", "showLineNumbers":true, "fileName":"test"}',
-      },
-    }),
-    {
-      highlight: { lineRange: [{ from: 3, to: 4 }] },
-      showLineNumbers: { lineRange: [] },
-      fileName: "test",
-    },
-  );
-});

package/plugins/syntax-highlight/code-meta.ts

@@ -1,76 +0,0 @@
-import { type NumericRange, parseNumericRange } from "@temelj/iterator";
-import { z } from "zod";
-
-import type { HastElement } from "../../types";
-
-export interface MdxCodeMeta {
-  highlight?: MdxCodeMetaHighlightLine;
-  showLineNumbers?: MdxCodeMetaLineNumbers;
-  commandLine?: MdxCodeMetaCommandLine;
-  fileName?: string;
-}
-
-export type MdxCodeMetaHighlightLine = {
-  lineRange: NumericRange;
-};
-
-export type MdxCodeMetaLineNumbers = {
-  lineRange: NumericRange;
-};
-
-export type MdxCodeMetaCommandLine = {
-  commandRange: NumericRange;
-};
-
-export function extractCodeMeta(node: HastElement): MdxCodeMeta {
-  const meta = node?.data?.meta ?? node?.properties?.metastring ?? "";
-  return parseMetaString(meta as string);
-}
-
-const metaSchema = z.object({
-  highlight: z.optional(z.string()),
-  showLineNumbers: z.optional(z.union([z.boolean(), z.string()])),
-  commandLine: z.optional(z.union([z.boolean(), z.string()])),
-  fileName: z.optional(z.string()),
-});
-
-function parseMetaString(meta: string): MdxCodeMeta {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(meta.trim());
-  } catch {
-    return {};
-  }
-  const parsed = metaSchema.parse(raw);
-  const options: MdxCodeMeta = {};
-
-  if (parsed.highlight !== undefined) {
-    options.highlight = { lineRange: parseNumericRange(parsed.highlight) };
-  }
-
-  if (parsed.showLineNumbers !== undefined) {
-    if (typeof parsed.showLineNumbers === "string") {
-      options.showLineNumbers = {
-        lineRange: parseNumericRange(parsed.showLineNumbers),
-      };
-    } else if (parsed.showLineNumbers) {
-      options.showLineNumbers = { lineRange: [] };
-    }
-  }
-
-  if (parsed.commandLine !== undefined) {
-    if (typeof parsed.commandLine === "string") {
-      options.commandLine = {
-        commandRange: parseNumericRange(parsed.commandLine),
-      };
-    } else if (parsed.commandLine) {
-      options.commandLine = { commandRange: [] };
-    }
-  }
-
-  if (parsed.fileName !== undefined) {
-    options.fileName = parsed.fileName.trim();
-  }
-
-  return options;
-}

package/plugins/syntax-highlight/plugin.ts

@@ -1,266 +0,0 @@
-import { toString as hastToString } from "hast-util-to-string";
-import {
-  type BundledLanguage,
-  type BundledTheme,
-  codeToHast,
-  type CodeToHastOptions,
-  ShikiError,
-} from "shiki";
-import { visit } from "unist-util-visit";
-import {
-  transformerNotationHighlight,
-  type TransformerNotationHighlightOptions,
-} from "@shikijs/transformers";
-import { numericRangeContains } from "@temelj/iterator";
-import type { Plugin } from "unified";
-import type { Properties } from "hast";
-
-import type { HastElement, HastNode } from "../../types";
-
-import { extractCodeMeta } from "./code-meta";
-
-type ShikiHastOptions = Partial<
-  CodeToHastOptions<BundledLanguage, BundledTheme>
->;
-
-type SyntaxDataAttribute = "source-code" | "language" | "line-count";
-
-/**
- * Options for {@linkcode syntaxHighlightPlugin}.
- */
-export interface SyntaxHighlightPluginOptions {
-  /**
-   * Include these data attributes on the `<pre>` element.
-   * These might be useful to have when building custom code components.
-   */
-  includeDataAttributes?: SyntaxDataAttribute[];
-
-  /**
-   * Options for the highlight transformer.
-   */
-  highlight?: {
-    transformer?: TransformerNotationHighlightOptions;
-  };
-
-  /**
-   * Options for line numbers.
-   */
-  lineNumbers?: {
-    /**
-     * The name of the variable that contains the line number width.
-     * This is used for padding the line numbers so that they align.
-     */
-    widthVariableName?: string;
-    /**
-     * A class name to be added to the line numbers.
-     */
-    className?: string;
-  };
-
-  /**
-   * Options for command line.
-   */
-  commandLine?: {
-    /**
-     * A class name to be added to the prompt line.
-     */
-    className?: string;
-  };
-
-  /**
-   * Extra options for the Shiki hast transformer.
-   */
-  shikiHastOptions?: ShikiHastOptions;
-}
-
-/**
- * A plugin that highlights code blocks using Shiki.
- */
-export const syntaxHighlightPlugin: Plugin<
-  [SyntaxHighlightPluginOptions?],
-  HastNode,
-  HastNode
-> = (options: SyntaxHighlightPluginOptions = {}) => {
-  return async (tree) => {
-    const promises: Promise<void>[] = [];
-
-    async function visitor(
-      node: HastElement,
-      index: number,
-      parent: HastElement,
-    ): Promise<void> {
-      if (!parent || index === null || node.tagName !== "pre") {
-        return;
-      }
-
-      const codeNode = node.children[0];
-      if (
-        !codeNode ||
-        codeNode.type !== "element" ||
-        codeNode.tagName !== "code" ||
-        !codeNode.properties
-      ) {
-        return;
-      }
-
-      const lang = getNodeLanguage(codeNode);
-      if (typeof lang !== "string") {
-        return;
-      }
-
-      const meta = extractCodeMeta(codeNode);
-
-      const sourceCode = hastToString(codeNode).trim();
-
-      const hastOptions: CodeToHastOptions<BundledLanguage, BundledTheme> = {
-        tokenizeTimeLimit: 10_000,
-        lang,
-        themes: {
-          light: "github-light-default",
-          dark: "github-dark-default",
-        },
-        ...(options.shikiHastOptions ?? {}),
-      };
-      if (hastOptions.transformers === undefined) {
-        hastOptions.transformers = [];
-      }
-
-      if (options.highlight) {
-        hastOptions.transformers.push(
-          transformerNotationHighlight({
-            ...(options.highlight.transformer ?? {}),
-            matchAlgorithm: "v3",
-          }),
-        );
-      }
-
-      let lineCount = 0;
-      hastOptions.transformers.push({
-        code(node): void {
-          let lineIndex = 0;
-          for (const line of node.children.filter(
-            (node: HastNode) => node.type === "element",
-          ) as HastElement[]) {
-            line.properties["data-line"] = lineIndex + 1;
-
-            if (options.highlight) {
-              if (
-                meta.highlight &&
-                numericRangeContains(meta.highlight.lineRange, lineIndex)
-              ) {
-                this.addClassToHast(
-                  line,
-                  options.highlight.transformer?.classActiveLine ??
-                    "highlighted",
-                );
-              }
-            }
-
-            if (
-              options.lineNumbers &&
-              meta.showLineNumbers &&
-              (meta.showLineNumbers.lineRange.length === 0 ||
-                numericRangeContains(meta.showLineNumbers.lineRange, lineIndex))
-            ) {
-              this.addClassToHast(
-                line,
-                options.lineNumbers.className ?? "line-number",
-              );
-            }
-
-            if (
-              options.commandLine &&
-              meta.commandLine &&
-              (meta.commandLine.commandRange.length === 0 ||
-                numericRangeContains(meta.commandLine.commandRange, lineIndex))
-            ) {
-              this.addClassToHast(
-                line,
-                options.commandLine.className ?? "line-command",
-              );
-            }
-
-            lineIndex++;
-          }
-
-          lineCount = lineIndex;
-
-          if (meta.showLineNumbers) {
-            if (typeof node.properties.style !== "string") {
-              node.properties.style = "";
-            }
-            node.properties.style += `--${
-              options.lineNumbers?.widthVariableName ?? "line-number-width"
-            }:${1 + Math.floor(Math.log10(this.lines.length))}ch;`;
-          }
-        },
-      });
-
-      try {
-        const hast = await codeToHast(sourceCode, hastOptions);
-
-        // Insert highlighted code into parent
-        const hastPre = hast.children[0] as HastElement;
-
-        const properties: Properties = {
-          ...hastPre.properties,
-          dataFileName: meta.fileName,
-        };
-        if (options.includeDataAttributes) {
-          if (options.includeDataAttributes.includes("language")) {
-            properties.dataLanguage = lang;
-          }
-          if (options.includeDataAttributes.includes("source-code")) {
-            properties.dataSourceCode = sourceCode;
-          }
-          if (options.includeDataAttributes.includes("line-count")) {
-            properties.dataLineCount = lineCount;
-          }
-        }
-
-        parent.children.splice(index, 1, {
-          ...hastPre,
-          properties,
-        });
-      } catch (error) {
-        if (error instanceof ShikiError) {
-          if (
-            error.message.includes(
-              "Language `math` is not included in this bundle",
-            )
-          ) {
-            // Skip if the block is math block.
-            return;
-          }
-        }
-        throw error;
-      }
-    }
-
-    visit(
-      tree,
-      "element",
-      (node: HastElement, index: number, parent: HastElement) => {
-        promises.push(visitor(node, index, parent));
-      },
-    );
-
-    await Promise.all(promises);
-
-    return tree;
-  };
-};
-
-function getNodeLanguage(node: HastElement): string | undefined {
-  if (!Array.isArray(node.properties.className)) {
-    return undefined;
-  }
-  const prefix = "language-";
-  const language = node.properties.className.find(
-    (name) => typeof name === "string" && name.startsWith(prefix),
-  ) as string | undefined;
-  if (typeof language === "string") {
-    return language.slice(prefix.length);
-  }
-  return language;
-}

package/plugins/tree-processor/plugin.ts

@@ -1,54 +0,0 @@
-import { visit } from "unist-util-visit";
-import type { Plugin } from "unified";
-
-import type { HastElement, HastNode } from "../../types";
-
-export type MdxTreeProcessor = (
-  node: HastElement,
-  index: number,
-  parent: HastElement,
-) => void | Promise<void>;
-
-/**
- * Options for {@linkcode treeProcessorPlugin}.
- */
-type TreeProcessorPluginOptions = {
-  /** The processor. */
-  process: MdxTreeProcessor;
-};
-
-/**
- * A plugin that allows to process MDX tree nodes.
- * It can be async or sync.
- */
-export const treeProcessorPlugin: Plugin<
-  [TreeProcessorPluginOptions?],
-  HastNode,
-  HastNode
-> = ({ process } = { process: () => {} }) => {
-  return async (tree) => {
-    const promises: Promise<void>[] = [];
-
-    visit(
-      tree,
-      "element",
-      function visitor(
-        node: HastElement,
-        index: number,
-        parent: HastElement,
-      ): void {
-        const p = process(node, index, parent);
-        if (
-          p instanceof Promise ||
-          Object.prototype.toString.call(p) === "[object Promise]"
-        ) {
-          promises.push(p as Promise<void>);
-        }
-      },
-    );
-
-    await Promise.allSettled(promises);
-
-    return tree;
-  };
-};

package/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "outDir": "./dist",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "paths": {
-      "@temelj/iterator": ["../iterator/src/mod"]
-    }
-  },
-  "include": ["./**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts"]
-}

package/types.ts

@@ -1,3 +0,0 @@
-import type { Element, Node } from "hast";
-
-export type { Element as HastElement, Node as HastNode };