@amamo/mdx 0.1.6 → 0.3.0

package/README.md

@@ -1,50 +1,75 @@
 # @amamo/mdx
 
-Compile trusted MDX into JavaScript modules for a configurable JSX runtime (React by default),
-collection metadata, and JSON manifests. A Rust native binding handles parsing, validation, media
-rewriting, manifest projection, and persistent cache records; Shiki runs in JavaScript and feeds
-highlighted HAST back into the same compile pipeline.
+Build MDX collections for Vite 8, Next 16, or a custom Node.js build. Define each collection with
+the package's `z` schema builder, then import MDX as application modules or consume the generated
+collection registry and JSON manifests.
 
-The package exposes three import paths:
+`@amamo/mdx` provides:
 
-| Import            | Purpose                                            |
-| ----------------- | -------------------------------------------------- |
-| `@amamo/mdx`      | Configure and drive the compiler directly.         |
-| `@amamo/mdx/vite` | Compile MDX through Vite 8.                        |
-| `@amamo/mdx/next` | Compile MDX for Next 16 with Turbopack or Webpack. |
+- frontmatter validation and defaults;
+- JavaScript modules for a configurable JSX runtime, with React as the default;
+- fenced-code highlighting and Markdown media imports;
+- collection metadata with companion TypeScript declarations;
+- configurable JSON manifests and a persistent build cache.
 
-## Quick start
+## Requirements
+
+- Node.js 20.19 or newer.
+- A [supported native target](https://jikkai.github.io/mdx/native-targets/). There is no JavaScript
+  or WASI fallback for MDX compilation.
+- React 19 when using the default JSX runtime.
+
+MDX can contain imports, expressions, and JSX. Compile content from authors who are allowed to add
+application code.
+
+## Install
 
 ```sh
 pnpm add @amamo/mdx
 ```
 
-`@amamo/mdx` requires Node.js 20.19 or newer and a [supported native
-target](https://jikkai.github.io/mdx/native-targets/). It has no JavaScript or WASI fallback.
+The package manager installs the platform package for the current operating system and CPU. Install
+dependencies again after moving the project to a different platform instead of copying
+`node_modules`.
+
+## Define a collection
 
-Create a serializable config:
+Create `amamo.config.mjs`:
 
 ```js
-// amamo.config.mjs
-import { defineConfig } from '@amamo/mdx'
+import { defineConfig, z } from '@amamo/mdx'
 
 export default defineConfig({
   root: import.meta.dirname,
   collections: {
     posts: {
       directory: 'content/posts',
-      schema: {
-        $schema: 'https://json-schema.org/draft/2020-12/schema',
-        type: 'object',
-        properties: { title: { type: 'string' } },
-        required: ['title'],
-      },
+      schema: z.object({
+        title: z.string(),
+        publishedAt: z.string().optional(),
+      }),
     },
   },
 })
 ```
 
-Then choose the integration that owns the build.
+Then add `content/posts/hello.mdx`:
+
+```mdx
+---
+title: Hello
+publishedAt: 2026-08-15
+---
+
+# Hello
+
+This document is compiled by @amamo/mdx.
+```
+
+The collection directory must exist before the first full build. Relative collection, cache,
+generated, and manifest paths are resolved from `root`.
+
+## Choose an integration
 
 ### Vite
 
@@ -55,7 +80,9 @@ import { defineConfig } from 'vite'
 
 import amamo from './amamo.config.mjs'
 
-export default defineConfig({ plugins: [amamoMdx(amamo)] })
+export default defineConfig({
+  plugins: [amamoMdx(amamo)],
+})
 ```
 
 ### Next
@@ -66,17 +93,21 @@ import { withAmamoMdx } from '@amamo/mdx/next'
 
 import amamo from './amamo.config.mjs'
 
-export default withAmamoMdx(amamo)({ reactStrictMode: true })
+export default withAmamoMdx(amamo)({
+  reactStrictMode: true,
+})
 ```
 
 ### Direct compiler API
 
-```ts
+```js
+// build-content.mjs
 import { createCompiler } from '@amamo/mdx'
 
 import amamo from './amamo.config.mjs'
 
 const compiler = await createCompiler(amamo)
+
 try {
   const result = await compiler.build()
   console.log(result)
@@ -85,25 +116,57 @@ try {
 }
 ```
 
-The first build writes these compiler-owned files under `generatedDirectory` (default
-`.amamo-mdx`):
+Run the script with `node build-content.mjs`.
 
-- `collections.mjs` — collection metadata with lazy imports of the source MDX files.
-- `collections.d.ts` — a companion declaration output for the collection registry.
-- `index.json` — the private index used by the Next loader.
+## Use compiled content
 
-Cache and manifest paths are configured separately and are resolved from `root`.
+With the Vite plugin or Next wrapper configured, import an MDX file like an application module:
 
-## Security boundary
+```tsx
+import Post, { frontmatter } from './content/posts/hello.mdx'
 
-MDX modules can execute JavaScript when the host imports or renders them. Compile only content from
-trusted authors; schema validation is not a sandbox. Mark top-level frontmatter fields as
-`sensitive` to keep their plaintext out of compiled modules, cache records, and manifests. See the
-[security model](https://jikkai.github.io/mdx/security/) before handling secrets.
+export function Page() {
+  return (
+    <main>
+      <h1>{frontmatter.title}</h1>
+      <Post />
+    </main>
+  )
+}
+```
 
-## Documentation
+Or load a document from the generated registry:
+
+```ts
+import { collections } from './.amamo-mdx/collections.mjs'
+
+const hello = collections.posts.find((document) => document.slug === 'hello')
+const module = await hello?.load()
+```
+
+Registry `load()` functions import the source MDX file, so they must run through the configured Vite
+plugin or Next loader.
 
-The complete English and Simplified Chinese documentation covers:
+## Generated files
+
+The first build writes these files under `generatedDirectory`, which defaults to `.amamo-mdx`:
+
+- `collections.mjs` — sorted collection metadata and lazy source imports;
+- `collections.d.ts` — TypeScript declarations for the registry;
+- `index.json` — the source-to-cache index used by the Next loader.
+
+Cache and manifest paths are configured separately from `generatedDirectory`. Add `.amamo-mdx/` to
+the host repository's ignore file unless the application deliberately tracks generated output.
+
+## Package entry points
+
+| Import            | Use it for                                 |
+| ----------------- | ------------------------------------------ |
+| `@amamo/mdx`      | Configuration and the direct compiler API. |
+| `@amamo/mdx/vite` | Vite 8 development and production builds.  |
+| `@amamo/mdx/next` | Next 16 development and production builds. |
+
+## Documentation
 
 - [Getting started](https://jikkai.github.io/mdx/getting-started/)
 - [Configuration reference](https://jikkai.github.io/mdx/configuration/)

package/dist/config.d.ts

@@ -1,3 +1,5 @@
+import * as z from 'zod';
+export { z };
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
@@ -13,20 +15,32 @@ export interface ILocaleConfig {
 export interface ISlugConfig {
     indexNames?: string[];
 }
+export interface IFrontmatterSchema {
+    readonly shape: Readonly<Record<string, unknown>>;
+    toJSONSchema(): unknown;
+}
 export interface ICollectionConfig {
     directory: string;
     extensions?: string[];
     locales?: ILocaleConfig;
-    schema: {
-        [key: string]: JsonValue;
-    };
-    sensitive?: string[];
+    schema: IFrontmatterSchema;
     slug?: ISlugConfig;
 }
+export interface IMathConfig {
+    macros?: Record<string, string>;
+    singleDollar?: boolean;
+}
+export interface IMdxExtensionsConfig {
+    footnotes?: boolean;
+    headingIds?: boolean;
+    taskLists?: boolean;
+}
 export interface IMdxConfig {
+    extensions?: IMdxExtensionsConfig;
     gfm?: boolean;
     hardBreaks?: boolean;
     jsxImportSource?: string;
+    math?: false | IMathConfig;
     providerImportSource?: string;
 }
 export interface IHighlightConfig {
@@ -79,7 +93,6 @@ export interface INormalizedCollectionConfig {
     schema: {
         [key: string]: JsonValue;
     };
-    sensitive: string[];
     slug: {
         indexNames: string[];
     };
@@ -105,7 +118,7 @@ export interface INormalizedManifestConfig extends Omit<IManifestConfig, 'collec
     collections: string[];
     output: string;
 }
-export interface INormalizedConfig {
+export interface IAmamoMDXConfig {
     cache: {
         directory: string;
         enabled: boolean;
@@ -115,9 +128,20 @@ export interface INormalizedConfig {
     generatedDirectory: string;
     highlight: INormalizedHighlightConfig;
     manifests: Record<string, INormalizedManifestConfig>;
-    mdx: Required<IMdxConfig>;
+    mdx: {
+        extensions: Required<IMdxExtensionsConfig>;
+        gfm: boolean;
+        hardBreaks: boolean;
+        jsxImportSource: string;
+        math: {
+            enabled: boolean;
+            macros: Record<string, string>;
+            singleDollar: boolean;
+        };
+        providerImportSource: string;
+    };
     media: INormalizedMediaConfig;
     root: string;
 }
 export declare function defineConfig<T extends IAmamoMdxConfig>(config: T): T;
-export declare function normalizeConfig(config: IAmamoMdxConfig): INormalizedConfig;
+export declare function normalizeConfig(config: IAmamoMdxConfig): IAmamoMDXConfig;

package/dist/config.js

@@ -1,5 +1,8 @@
+import { Buffer } from 'node:buffer';
 import { existsSync, realpathSync } from 'node:fs';
 import path from 'node:path';
+import * as z from 'zod';
+export { z };
 const DEFAULT_MEDIA_ATTRIBUTES = {
     audio: ['src'],
     embed: ['src'],
@@ -9,10 +12,15 @@ const DEFAULT_MEDIA_ATTRIBUTES = {
     track: ['src'],
     video: ['src', 'poster'],
 };
+const MATH_MACRO_NAME = /^\\(?:[A-Za-z@]+|[^\s])$/u;
+const MAX_MATH_MACRO_BYTES = 1024;
+const MAX_MATH_MACROS_BYTES = 16 * 1024;
 function notSerializable(location, reason) {
     throw new TypeError(`AMAMO_CONFIG_NOT_SERIALIZABLE: ${location} ${reason}`);
 }
-function assertPlainData(value, location, active) {
+function assertPlainData(value, location, active, segments = []) {
+    if (segments.length === 3 && segments[0] === 'collections' && segments[2] === 'schema')
+        return;
     if (value === null || typeof value === 'string' || typeof value === 'boolean')
         return;
     if (typeof value === 'number') {
@@ -35,7 +43,7 @@ function assertPlainData(value, location, active) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (!descriptor || !('value' in descriptor))
             notSerializable(`${location}.${key}`, 'contains an accessor');
-        assertPlainData(descriptor.value, `${location}.${key}`, active);
+        assertPlainData(descriptor.value, `${location}.${key}`, active, [...segments, key]);
     }
     active.delete(value);
 }
@@ -53,14 +61,32 @@ function normalizeCollection(root, name, config) {
         throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.locales.default must be listed in names`);
     }
     const directory = path.resolve(root, requireNonEmpty(config.directory, `collections.${name}.directory`));
+    if (typeof config.schema?.shape !== 'object' ||
+        config.schema.shape === null ||
+        typeof config.schema.toJSONSchema !== 'function') {
+        throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.schema must be a compatible object schema`);
+    }
+    let schema;
+    try {
+        schema = JSON.parse(JSON.stringify(config.schema.toJSONSchema()));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : 'could not be converted to JSON Schema';
+        throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.schema ${reason}`, {
+            cause: error,
+        });
+    }
+    if (schema.type !== 'object') {
+        throw new TypeError(`AMAMO_CONFIG_INVALID: collections.${name}.schema must convert to an object schema`);
+    }
+    assertPlainData(schema, `collections.${name}.schema`, new WeakSet());
     return {
         directory: existsSync(directory) ? realpathSync.native(directory) : directory,
         extensions: [...extensions],
         locales: config.locales
             ? { default: config.locales.default, names: [...config.locales.names] }
             : undefined,
-        schema: config.schema,
-        sensitive: [...(config.sensitive ?? [])],
+        schema,
         slug: { indexNames: [...(config.slug?.indexNames ?? ['index', 'page'])] },
     };
 }
@@ -69,6 +95,9 @@ export function defineConfig(config) {
 }
 export function normalizeConfig(config) {
     assertPlainData(config, 'config', new WeakSet());
+    if (Object.hasOwn(config, 'math')) {
+        throw new TypeError('AMAMO_CONFIG_INVALID: math moved to mdx.math');
+    }
     if (!config.collections || Object.keys(config.collections).length === 0) {
         throw new TypeError('AMAMO_CONFIG_INVALID: collections must not be empty');
     }
@@ -89,7 +118,26 @@ export function normalizeConfig(config) {
         },
     ]));
     const highlight = config.highlight === false ? undefined : config.highlight;
+    const math = config.mdx?.math === false ? undefined : config.mdx?.math;
     const media = config.media === false ? undefined : config.media;
+    const gfm = config.mdx?.gfm ?? true;
+    let macroBytes = 0;
+    for (const [name, expansion] of Object.entries(math?.macros ?? {})) {
+        if (!name.startsWith('\\')) {
+            throw new TypeError(`AMAMO_CONFIG_INVALID: mdx.math.macros.${name} must start with a backslash`);
+        }
+        if (!MATH_MACRO_NAME.test(name)) {
+            throw new TypeError(`AMAMO_CONFIG_INVALID: mdx.math.macros.${name} must be one TeX control sequence`);
+        }
+        const expansionBytes = Buffer.byteLength(expansion);
+        if (expansionBytes > MAX_MATH_MACRO_BYTES) {
+            throw new TypeError(`AMAMO_CONFIG_INVALID: mdx.math.macros.${name} exceeds the ${MAX_MATH_MACRO_BYTES}-byte limit`);
+        }
+        macroBytes += Buffer.byteLength(name) + expansionBytes;
+        if (macroBytes > MAX_MATH_MACROS_BYTES) {
+            throw new TypeError(`AMAMO_CONFIG_INVALID: mdx.math.macros exceeds the ${MAX_MATH_MACROS_BYTES}-byte total limit`);
+        }
+    }
     return {
         cache: {
             directory: path.resolve(root, config.cache === false
@@ -116,9 +164,19 @@ export function normalizeConfig(config) {
         },
         manifests,
         mdx: {
-            gfm: config.mdx?.gfm ?? true,
+            extensions: {
+                footnotes: config.mdx?.extensions?.footnotes ?? gfm,
+                headingIds: config.mdx?.extensions?.headingIds ?? false,
+                taskLists: config.mdx?.extensions?.taskLists ?? gfm,
+            },
+            gfm,
             hardBreaks: config.mdx?.hardBreaks ?? false,
             jsxImportSource: config.mdx?.jsxImportSource ?? 'react',
+            math: {
+                enabled: config.mdx?.math !== undefined && config.mdx.math !== false,
+                macros: { ...math?.macros },
+                singleDollar: math?.singleDollar ?? true,
+            },
             providerImportSource: config.mdx?.providerImportSource ?? '',
         },
         media: {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { IAmamoMdxConfig, ICacheConfig, ICollectionConfig, IDerivedConfig, IHighlightConfig, ILocaleConfig, IManifestConfig, IMdxConfig, IMediaConfig, INormalizedConfig, JsonValue, ManifestField, } from './config.js';
-export { defineConfig, normalizeConfig } from './config.js';
+export type { IAmamoMDXConfig, IAmamoMdxConfig, ICacheConfig, ICollectionConfig, IDerivedConfig, IFrontmatterSchema, IHighlightConfig, ILocaleConfig, IManifestConfig, IMathConfig, IMdxConfig, IMdxExtensionsConfig, IMediaConfig, JsonValue, ManifestField, } from './config.js';
+export { defineConfig, normalizeConfig, z } from './config.js';
 export type { IBuildResult, ICompiler, ITransformResult } from './compiler.js';
 export { createCompiler } from './compiler.js';
 export type { IDiagnostic } from './native.js';

package/dist/index.js

@@ -1,2 +1,2 @@
-export { defineConfig, normalizeConfig } from './config.js';
+export { defineConfig, normalizeConfig, z } from './config.js';
 export { createCompiler } from './compiler.js';

package/dist/native.d.ts

@@ -1,4 +1,4 @@
-import type { INormalizedConfig, JsonValue } from './config.js';
+import type { IAmamoMDXConfig, JsonValue } from './config.js';
 export interface ISourcePoint {
     column: number;
     line: number;
@@ -65,7 +65,7 @@ export declare class AmamoMdxError extends Error {
     readonly diagnostics: IDiagnostic[];
     constructor(diagnostics: IDiagnostic[]);
 }
-export declare function configurationFingerprint(config: INormalizedConfig): string;
-export declare function prepareNativeBatch(config: INormalizedConfig, inputs: INativeDocumentInput[]): IPreparedNativeBatch;
+export declare function configurationFingerprint(config: IAmamoMDXConfig): string;
+export declare function prepareNativeBatch(config: IAmamoMDXConfig, inputs: INativeDocumentInput[]): IPreparedNativeBatch;
 export declare function pruneNativeCache(cacheDirectory: string, keepKeys: string[]): number;
-export declare function renderNativeManifests(config: INormalizedConfig, records: IDocumentRecord[]): IRenderedManifest[];
+export declare function renderNativeManifests(config: IAmamoMDXConfig, records: IDocumentRecord[]): IRenderedManifest[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amamo/mdx",
-  "version": "0.1.6",
+  "version": "0.3.0",
   "description": "A native MDX content compiler with Vite and Next adapters",
   "homepage": "https://jikkai.github.io/mdx/",
   "license": "MIT",
@@ -48,24 +48,27 @@
     "test": "pnpm run build && vitest run src/__tests__",
     "test:rust": "cargo test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "check": "pnpm run format:check && pnpm run lint && cargo clippy --all-targets -- -D warnings && cargo test && pnpm run typecheck && pnpm run test && pnpm run check:docs",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run check:rust && pnpm run check:npm && pnpm run check:docs",
     "check:docs": "pnpm --filter @amamo/mdx-docs types:check && pnpm --filter @amamo/mdx-docs build",
+    "check:npm": "pnpm run typecheck && pnpm run test",
+    "check:rust": "cargo clippy --all-targets -- -D warnings && pnpm run test:rust",
     "release": "verso"
   },
   "dependencies": {
-    "shiki": "4.4.2"
+    "shiki": "4.4.3",
+    "zod": "4.4.3"
   },
   "devDependencies": {
-    "@amamo/oxlint-config": "1.0.0",
-    "@amamo/verso": "1.0.1",
-    "@napi-rs/cli": "3.8.2",
-    "@types/node": "26.1.2",
+    "@amamo/oxlint-config": "1.1.0",
+    "@amamo/verso": "1.1.0",
+    "@napi-rs/cli": "3.8.6",
+    "@types/node": "26.2.0",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.4",
     "lint-staged": "17.3.0",
-    "next": "16.3.0",
-    "oxfmt": "0.62.0",
-    "oxlint": "1.77.0",
+    "next": "16.3.1",
+    "oxfmt": "0.63.0",
+    "oxlint": "1.78.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "simple-git-hooks": "2.13.1",
@@ -116,12 +119,12 @@
   },
   "packageManager": "pnpm@11.20.0",
   "optionalDependencies": {
-    "@amamo/mdx-darwin-arm64": "0.1.6",
-    "@amamo/mdx-darwin-x64": "0.1.6",
-    "@amamo/mdx-linux-arm64-gnu": "0.1.6",
-    "@amamo/mdx-linux-x64-gnu": "0.1.6",
-    "@amamo/mdx-linux-arm64-musl": "0.1.6",
-    "@amamo/mdx-linux-x64-musl": "0.1.6",
-    "@amamo/mdx-win32-x64-msvc": "0.1.6"
+    "@amamo/mdx-darwin-arm64": "0.3.0",
+    "@amamo/mdx-darwin-x64": "0.3.0",
+    "@amamo/mdx-linux-arm64-gnu": "0.3.0",
+    "@amamo/mdx-linux-x64-gnu": "0.3.0",
+    "@amamo/mdx-linux-arm64-musl": "0.3.0",
+    "@amamo/mdx-linux-x64-musl": "0.3.0",
+    "@amamo/mdx-win32-x64-msvc": "0.3.0"
   }
 }