@temelj/mdx 0.1.6 → 0.1.8

package/README.md

@@ -26,7 +26,7 @@
 <br/>
 <br/>
 
-# Installation
+## Installation
 
 ```sh
 # npm
@@ -35,7 +35,82 @@ $ npm install @temelj/mdx
 $ deno add jsr:@temelj/mdx # or jsr add @temelj/mdx
 ```
 
-# About
+## Compile
+
+```ts
+import { assert, assertEquals } from "@std/assert";
+import {
+  type HastElement,
+  headingIdPlugin,
+  MdxCompiler,
+  syntaxHighlightPlugin,
+  treeProcessorPlugin,
+} from "@temelj/mdx";
+import { z } from "zod";
+
+const compiler = new MdxCompiler()
+  .withRehypePlugin(headingIdPlugin, {
+    prefix: "h-",
+  })
+  .withRehypePlugin(syntaxHighlightPlugin, {
+    highlight: {},
+    lineNumbers: {},
+    commandLine: {},
+    shikiHastOptions: {
+      // themes: {
+      //   light: lightTheme,
+      //   dark: darkTheme,
+      // },
+    },
+  });
+
+const source = `
+---
+title: Demo
+---
+# Hello
+
+This will compile MDX to a render-able artifact.
+With '@temelj/mdx-react' you can render it in an React app.
+
+You can validate the frontmatter with a zod schema.
+
+There are a few useful plugins:
+- Use 'headingIdPlugin' to update heading tags (h1, h2, etc.) with IDs generated by slugging their text content.
+This is useful for linking to headings in a page.
+- Use 'syntaxHighlightPlugin' to highlight code blocks using [Shiki](https://github.com/shikijs/shiki).
+You can highlight individual lines, show line numbers, or display a prompt.
+- Use 'treeProcessorPlugin' to modify the HAST tree.
+For example, change image URLs to point to a CDN.
+
+\`\`\`bash {"commandLine": "0"}
+whoamai
+@temelj/mdx
+\`\`\`
+`.trim();
+const artifact = await compiler.compile(source, {
+  frontmatterOnly: false,
+  frontmatterSchema: z.object({
+    title: z.string(),
+  }),
+  mdxOptions: {
+    rehypePlugins: [
+      [
+        treeProcessorPlugin,
+        {
+          process: (node: HastElement) => assert(typeof node.type === "string"),
+        },
+      ],
+    ],
+  },
+});
+assert(artifact.compiled !== undefined);
+assertEquals(artifact.frontmatter, {
+  title: "Demo",
+});
+```
+
+## About
 
 This package is part of [Temelj](https://github.com/flinect/temelj) - a big
 standard library for TypeScript.

package/esm/compiler.js

@@ -4,6 +4,9 @@ import remarkGfmPlugin from "remark-gfm";
 import { VFile } from "vfile";
 import { matter } from "vfile-matter";
 export { remarkFrontmatterPlugin, remarkGfmPlugin };
+/**
+ * A reusable compiler for compiling MDX.
+ */
 export class MdxCompiler {
     constructor(mdxOptions = {}) {
         Object.defineProperty(this, "mdxOptions", {
@@ -46,7 +49,7 @@ export class MdxCompiler {
         }
         return this;
     }
-    async compile(source, { frontmatterOnly = false, mdxOptions } = {}) {
+    async compile(source, { frontmatterOnly = false, frontmatterSchema, mdxOptions } = {}) {
         const vfile = new VFile({
             value: source,
             // Needed so vfile doesn't need to access fs.
@@ -66,17 +69,21 @@ export class MdxCompiler {
         }
         let compiled;
         if (!frontmatterOnly) {
-            compiled = await compileMdxJs(vfile, {
+            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: compiled?.value.toString(),
-            frontmatter: (vfile.data.matter ?? {}),
+            compiled,
+            frontmatter,
         };
     }
 }

package/esm/plugins/syntax-highlight/code-meta.js

@@ -6,8 +6,8 @@ export function extractCodeMeta(node) {
 }
 const metaSchema = z.object({
     highlight: z.string().optional(),
-    showLineNumbers: z.boolean().default(false),
-    commandLine: z.string().optional(),
+    showLineNumbers: z.boolean().or(z.string()).optional(),
+    commandLine: z.boolean().or(z.string()).optional(),
     fileName: z.string().optional(),
 });
 function parseMetaString(meta) {
@@ -43,7 +43,7 @@ function parseMetaString(meta) {
             options.commandLine = { commandRange: [] };
         }
     }
-    if (typeof parsed.fileName === "string") {
+    if (parsed.fileName !== undefined) {
         options.fileName = parsed.fileName.trim();
     }
     return options;

package/esm/plugins/syntax-highlight/plugin.js

@@ -4,6 +4,9 @@ import { visit } from "unist-util-visit";
 import { transformerNotationHighlight, } from "@shikijs/transformers";
 import { numericRangeContains } from "@temelj/iterator";
 import { extractCodeMeta } from "./code-meta.js";
+/**
+ * A plugin that highlights code blocks using Shiki.
+ */
 export function syntaxHighlightPlugin(options = {}) {
     return async (tree) => {
         const promises = [];
@@ -31,7 +34,7 @@ export function syntaxHighlightPlugin(options = {}) {
                     light: "github-light-default",
                     dark: "github-dark-default",
                 },
-                ...(options.shikiCodeToHastOptions ?? {}),
+                ...(options.shikiHastOptions ?? {}),
             };
             if (hastOptions.transformers === undefined) {
                 hastOptions.transformers = [];
@@ -62,7 +65,8 @@ export function syntaxHighlightPlugin(options = {}) {
                         }
                         if (options.commandLine &&
                             meta.commandLine &&
-                            numericRangeContains(meta.commandLine.commandRange, lineIndex)) {
+                            (meta.commandLine.commandRange.length === 0 ||
+                                numericRangeContains(meta.commandLine.commandRange, lineIndex))) {
                             this.addClassToHast(line, options.commandLine.className ?? "line-command");
                         }
                         lineIndex++;

package/esm/plugins/tree-processor/plugin.js

@@ -1,4 +1,8 @@
 import { visit } from "unist-util-visit";
+/**
+ * A plugin that allows to process MDX tree nodes.
+ * It can be async or sync.
+ */
 export function treeProcessorPlugin({ process } = { process: () => { } }) {
     return async (tree) => {
         const promises = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temelj/mdx",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Utilities for working with MDX.",
   "keywords": [
     "mdx"

package/types/compiler.d.ts

@@ -1,17 +1,32 @@
 import { type CompileOptions as MdxJsCompileOptions } from "@mdx-js/mdx";
 import remarkFrontmatterPlugin from "remark-frontmatter";
 import remarkGfmPlugin from "remark-gfm";
+import type { z } from "zod";
 import type { PluginFactory } from "./types.js";
 export { remarkFrontmatterPlugin, remarkGfmPlugin };
+/**
+ * Represents the source content for an MDX document.
+ */
 export type MdxSource = string | Uint8Array;
-export interface MdxCompileOptions {
+/**
+ * Options for compiling an MDX document.
+ */
+export interface MdxCompileOptions<TFrontmatter extends z.ZodSchema> {
     frontmatterOnly?: boolean | undefined;
+    frontmatterSchema?: TFrontmatter;
     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 declare class MdxCompiler {
     private readonly mdxOptions;
     private readonly remarkPlugins;
@@ -19,6 +34,6 @@ export declare class MdxCompiler {
     constructor(mdxOptions?: MdxJsCompileOptions);
     withRemarkPlugin<TOptions>(plugin: (options?: TOptions) => PluginFactory, options?: TOptions): MdxCompiler;
     withRehypePlugin<TOptions>(plugin: (options?: TOptions) => PluginFactory, options?: TOptions): MdxCompiler;
-    compile<TFrontmatter = Record<string, unknown>>(source: MdxSource, { frontmatterOnly, mdxOptions }?: MdxCompileOptions): Promise<MdxArtifact<TFrontmatter>>;
+    compile<TFrontmatterSchema extends z.ZodSchema>(source: MdxSource, { frontmatterOnly, frontmatterSchema, mdxOptions }?: MdxCompileOptions<TFrontmatterSchema>): Promise<MdxArtifact<z.output<TFrontmatterSchema>>>;
 }
 //# sourceMappingURL=compiler.d.ts.map

package/types/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,IAAI,mBAAmB,EAC3C,MAAM,aAAa,CAAC;AACrB,OAAO,uBAAuB,MAAM,oBAAoB,CAAC;AACzD,OAAO,eAAe,MAAM,YAAY,CAAC;AAKzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,CAAC;AAEpD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,WAAW,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,YAAY,CAAC;CAC3B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAG5C,UAAU,GAAE,mBAAwB;IAO/B,gBAAgB,CAAC,QAAQ,EAC9B,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,KAAK,aAAa,EAC7C,OAAO,CAAC,EAAE,QAAQ,GACjB,WAAW;IASP,gBAAgB,CAAC,QAAQ,EAC9B,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,KAAK,aAAa,EAC7C,OAAO,CAAC,EAAE,QAAQ,GACjB,WAAW;IASD,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,MAAM,EAAE,SAAS,EACjB,EAAE,eAAuB,EAAE,UAAU,EAAE,GAAE,iBAAsB,GAC9D,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;CAqCtC"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,IAAI,mBAAmB,EAC3C,MAAM,aAAa,CAAC;AACrB,OAAO,uBAAuB,MAAM,oBAAoB,CAAC;AACzD,OAAO,eAAe,MAAM,YAAY,CAAC;AAIzC,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAChC,YAAY,SAAS,CAAC,CAAC,SAAS;IAEhC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAEtC,iBAAiB,CAAC,EAAE,YAAY,CAAC;IACjC,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,EAAE,YAAY,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAG5C,UAAU,GAAE,mBAAwB;IAO/B,gBAAgB,CAAC,QAAQ,EAC9B,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,KAAK,aAAa,EAC7C,OAAO,CAAC,EAAE,QAAQ,GACjB,WAAW;IASP,gBAAgB,CAAC,QAAQ,EAC9B,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,KAAK,aAAa,EAC7C,OAAO,CAAC,EAAE,QAAQ,GACjB,WAAW;IASD,OAAO,CAClB,kBAAkB,SAAS,CAAC,CAAC,SAAS,EAEtC,MAAM,EAAE,SAAS,EACjB,EAAE,eAAuB,EAAE,iBAAiB,EAAE,UAAU,EAAE,GACxD,iBAAiB,CAAC,kBAAkB,CAAM,GAC3C,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC;CA0CtD"}

package/types/plugins/syntax-highlight/plugin.d.ts

@@ -1,24 +1,52 @@
 import { type BundledLanguage, type BundledTheme, type CodeToHastOptions } from "shiki";
 import { type TransformerNotationHighlightOptions } from "@shikijs/transformers";
 import type { PluginFactory } from "../../types.js";
-type ShikiCodeToHastOptions = Partial<CodeToHastOptions<BundledLanguage, BundledTheme>>;
+type ShikiHastOptions = Partial<CodeToHastOptions<BundledLanguage, BundledTheme>>;
 /**
  * Options for {@linkcode syntaxHighlightPlugin}.
  */
 export interface SyntaxHighlightPluginOptions {
+    /**
+     * A prefix for the language class name on the code tag.
+     */
     languageClassNamePrefix?: string;
+    /**
+     * 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;
     };
-    shikiCodeToHastOptions?: ShikiCodeToHastOptions;
+    /**
+     * Extra options for the Shiki hast transformer.
+     */
+    shikiHastOptions?: ShikiHastOptions;
 }
+/**
+ * A plugin that highlights code blocks using Shiki.
+ */
 export declare function syntaxHighlightPlugin(options?: SyntaxHighlightPluginOptions): PluginFactory;
 export {};
 //# sourceMappingURL=plugin.d.ts.map

package/types/plugins/syntax-highlight/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/syntax-highlight/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EAEjB,KAAK,iBAAiB,EACvB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,mCAAmC,EACzC,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAyB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG3E,KAAK,sBAAsB,GAAG,OAAO,CACnC,iBAAiB,CAAC,eAAe,EAAE,YAAY,CAAC,CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,SAAS,CAAC,EAAE;QACV,WAAW,CAAC,EAAE,mCAAmC,CAAC;KACnD,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CACjD;AAED,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,aAAa,CAqJf"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/syntax-highlight/plugin.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EAEjB,KAAK,iBAAiB,EACvB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,mCAAmC,EACzC,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAyB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG3E,KAAK,gBAAgB,GAAG,OAAO,CAC7B,iBAAiB,CAAC,eAAe,EAAE,YAAY,CAAC,CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC;;OAEG;IACH,SAAS,CAAC,EAAE;QACV,WAAW,CAAC,EAAE,mCAAmC,CAAC;KACnD,CAAC;IACF;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ;;;WAGG;QACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B;;WAEG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ;;WAEG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF;;OAEG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,aAAa,CAsJf"}

package/types/plugins/tree-processor/plugin.d.ts

@@ -7,6 +7,10 @@ type TreeProcessorPluginOptions = {
     /** The processor. */
     process: MdxTreeProcessor;
 };
+/**
+ * A plugin that allows to process MDX tree nodes.
+ * It can be async or sync.
+ */
 export declare function treeProcessorPlugin({ process }?: TreeProcessorPluginOptions): PluginFactory;
 export {};
 //# sourceMappingURL=plugin.d.ts.map

package/types/plugins/tree-processor/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/tree-processor/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAY,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;GAEG;AACH,KAAK,0BAA0B,GAAG;IAChC,qBAAqB;IACrB,OAAO,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF,wBAAgB,mBAAmB,CACjC,EAAE,OAAO,EAAE,GAAE,0BAAkD,GAC9D,aAAa,CAuBf"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/plugins/tree-processor/plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAY,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3E,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,WAAW,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;GAEG;AACH,KAAK,0BAA0B,GAAG;IAChC,qBAAqB;IACrB,OAAO,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,EAAE,OAAO,EAAE,GAAE,0BAAkD,GAC9D,aAAa,CAuBf"}