@amamo/mdx 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +67 -67
  2. package/package.json +14 -11
package/README.md CHANGED
@@ -1,21 +1,31 @@
1
1
  # @amamo/mdx
2
2
 
3
- An independent MDX content compiler with a Rust core, official Shiki highlighting, JSON Schema validation, media imports, deterministic manifests, and content-addressed caching. The same compiler state powers the root API, Vite 8, and Next 16.
3
+ Compile trusted MDX into JavaScript modules for a configurable JSX runtime (React by default),
4
+ collection metadata, and JSON manifests. A Rust native binding handles parsing, validation, media
5
+ rewriting, manifest projection, and persistent cache records; Shiki runs in JavaScript and feeds
6
+ highlighted HAST back into the same compile pipeline.
4
7
 
5
- ## Install
8
+ The package exposes three import paths:
9
+
10
+ | Import | Purpose |
11
+ | ----------------- | -------------------------------------------------- |
12
+ | `@amamo/mdx` | Configure and drive the compiler directly. |
13
+ | `@amamo/mdx/vite` | Compile MDX through Vite 8. |
14
+ | `@amamo/mdx/next` | Compile MDX for Next 16 with Turbopack or Webpack. |
15
+
16
+ ## Quick start
6
17
 
7
18
  ```sh
8
19
  pnpm add @amamo/mdx
9
20
  ```
10
21
 
11
- Node.js 20.19 or newer is required. A supported native package is installed through `optionalDependencies`; there is no JavaScript or WASI fallback.
22
+ `@amamo/mdx` requires Node.js 20.19 or newer and a [supported native
23
+ target](https://jikkai.github.io/mdx/native-targets/). It has no JavaScript or WASI fallback.
12
24
 
13
- ## Configure
25
+ Create a serializable config:
14
26
 
15
- Configuration is plain serializable data. Functions and executable plugins are intentionally rejected.
16
-
17
- ```ts
18
- // amamo.config.ts
27
+ ```js
28
+ // amamo.config.mjs
19
29
  import { defineConfig } from '@amamo/mdx'
20
30
 
21
31
  export default defineConfig({
@@ -26,94 +36,84 @@ export default defineConfig({
26
36
  schema: {
27
37
  $schema: 'https://json-schema.org/draft/2020-12/schema',
28
38
  type: 'object',
29
- properties: {
30
- title: { type: 'string' },
31
- password: { type: 'string' },
32
- },
39
+ properties: { title: { type: 'string' } },
33
40
  required: ['title'],
34
41
  },
35
- sensitive: ['password'],
36
- },
37
- },
38
- highlight: {
39
- provider: 'shiki',
40
- engine: 'oniguruma',
41
- themes: { light: 'vitesse-light', dark: 'vitesse-dark' },
42
- unknownLanguage: 'plain',
43
- },
44
- media: { missing: 'warn' },
45
- manifests: {
46
- public: {
47
- output: '.amamo-mdx/public.json',
48
- fields: { key: 'key', title: 'title' },
49
- },
50
- server: {
51
- output: '.amamo-mdx/server.json',
52
- key: 'key',
53
- fields: {
54
- key: 'key',
55
- protected: { from: 'password', transform: 'exists' },
56
- passwordHash: { from: 'password', transform: 'sha256' },
57
- },
58
42
  },
59
43
  },
60
44
  })
61
45
  ```
62
46
 
63
- The default highlighter keeps official Shiki in JavaScript and uses its Oniguruma WASM engine. Set `engine: 'javascript'` when avoiding Oniguruma is more important than grammar compatibility. Relative Markdown media URLs become static imports; authored JSX is left untouched. `unknownLanguage` and `media.missing` accept `error` or their permissive `plain`/`warn` policies.
47
+ Then choose the integration that owns the build.
64
48
 
65
- ## Compiler API
49
+ ### Vite
66
50
 
67
51
  ```ts
68
- import { createCompiler } from '@amamo/mdx'
69
- import config from './amamo.config.js'
52
+ // vite.config.ts
53
+ import { amamoMdx } from '@amamo/mdx/vite'
54
+ import { defineConfig } from 'vite'
70
55
 
71
- const compiler = await createCompiler(config)
72
- await compiler.build()
73
- await compiler.transform('content/posts/hello.mdx')
74
- await compiler.remove('content/posts/deleted.mdx')
75
- await compiler.dispose()
76
- ```
56
+ import amamo from './amamo.config.mjs'
77
57
 
78
- `build()` produces `.amamo-mdx/collections.mjs`, its declaration file, the private loader index, and configured manifests. Unchanged bytes are not rewritten.
58
+ export default defineConfig({ plugins: [amamoMdx(amamo)] })
59
+ ```
79
60
 
80
- ## Vite 8
61
+ ### Next
81
62
 
82
63
  ```ts
83
- import { defineConfig } from 'vite'
84
- import { amamoMdx } from '@amamo/mdx/vite'
85
- import amamo from './amamo.config.js'
64
+ // next.config.ts
65
+ import { withAmamoMdx } from '@amamo/mdx/next'
86
66
 
87
- export default defineConfig({ plugins: [amamoMdx(amamo)] })
67
+ import amamo from './amamo.config.mjs'
68
+
69
+ export default withAmamoMdx(amamo)({ reactStrictMode: true })
88
70
  ```
89
71
 
90
- The adapter joins Vite environments onto one startup build and uses Vite's existing watcher for add, change, and delete events.
72
+ ### Direct compiler API
91
73
 
92
- ## Next 16
74
+ ```ts
75
+ import { createCompiler } from '@amamo/mdx'
93
76
 
94
- ```js
95
- // next.config.mjs
96
- import { withAmamoMdx } from '@amamo/mdx/next'
97
- import amamo from './amamo.config.js'
77
+ import amamo from './amamo.config.mjs'
98
78
 
99
- export default withAmamoMdx(amamo)({ reactStrictMode: true })
79
+ const compiler = await createCompiler(amamo)
80
+ try {
81
+ const result = await compiler.build()
82
+ console.log(result)
83
+ } finally {
84
+ await compiler.dispose()
85
+ }
100
86
  ```
101
87
 
102
- The same private read-only loader is registered for default Turbopack and opt-in Webpack. The config wrapper also accepts and awaits an existing Next config function.
88
+ The first build writes these compiler-owned files under `generatedDirectory` (default
89
+ `.amamo-mdx`):
90
+
91
+ - `collections.mjs` — collection metadata with lazy imports of the source MDX files.
92
+ - `collections.d.ts` — a companion declaration output for the collection registry.
93
+ - `index.json` — the private index used by the Next loader.
94
+
95
+ Cache and manifest paths are configured separately and are resolved from `root`.
103
96
 
104
- ## Security
97
+ ## Security boundary
105
98
 
106
- MDX can contain executable JavaScript. Compile only content from trusted authors. Schema validation is not a sandbox. Fields marked `sensitive` are removed before modules, cache records, and public frontmatter are serialized; manifests may only inspect them with `exists` or hash them with `sha256`.
99
+ MDX modules can execute JavaScript when the host imports or renders them. Compile only content from
100
+ trusted authors; schema validation is not a sandbox. Mark top-level frontmatter fields as
101
+ `sensitive` to keep their plaintext out of compiled modules, cache records, and manifests. See the
102
+ [security model](https://jikkai.github.io/mdx/security/) before handling secrets.
107
103
 
108
- Relative media imports are confined to the configured root, including symlink resolution. Cache and generated output writes use same-directory temporary files and atomic rename.
104
+ ## Documentation
109
105
 
110
- ## Native targets
106
+ The complete English and Simplified Chinese documentation covers:
111
107
 
112
- - macOS arm64 and x64
113
- - Linux arm64 and x64, glibc and musl
114
- - Windows x64 MSVC
108
+ - [Getting started](https://jikkai.github.io/mdx/getting-started/)
109
+ - [Configuration reference](https://jikkai.github.io/mdx/configuration/)
110
+ - [Compiler API](https://jikkai.github.io/mdx/compiler-api/)
111
+ - [Vite integration](https://jikkai.github.io/mdx/vite/)
112
+ - [Next integration](https://jikkai.github.io/mdx/next/)
113
+ - [Native targets](https://jikkai.github.io/mdx/native-targets/)
115
114
 
116
- Unsupported targets fail during native binding load. No WASI or JavaScript fallback is shipped.
115
+ See the [contributing guide](https://github.com/jikkai/mdx/blob/main/CONTRIBUTING.md) to build and
116
+ verify the repository locally.
117
117
 
118
118
  ## License
119
119
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@amamo/mdx",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "A native MDX content compiler with Vite and Next adapters",
5
5
  "homepage": "https://jikkai.github.io/mdx/",
6
6
  "license": "MIT",
@@ -38,6 +38,8 @@
38
38
  "build:native": "napi build --platform --output-dir . --no-js --dts native.d.ts",
39
39
  "build:ts": "tsc -p tsconfig.json",
40
40
  "build": "pnpm run build:native && pnpm run build:ts",
41
+ "docs:dev": "pnpm --filter @amamo/mdx-docs dev",
42
+ "docs:build": "pnpm --filter @amamo/mdx-docs build",
41
43
  "format": "oxfmt . && cargo fmt",
42
44
  "format:check": "oxfmt --check . && cargo fmt --check",
43
45
  "lint": "oxlint .",
@@ -46,7 +48,8 @@
46
48
  "test": "pnpm run build && vitest run src/__tests__",
47
49
  "test:rust": "cargo test",
48
50
  "typecheck": "tsc -p tsconfig.json --noEmit",
49
- "check": "pnpm run format:check && pnpm run lint && cargo clippy --all-targets -- -D warnings && cargo test && pnpm run typecheck && pnpm run test",
51
+ "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",
52
+ "check:docs": "pnpm --filter @amamo/mdx-docs types:check && pnpm --filter @amamo/mdx-docs build",
50
53
  "release": "verso"
51
54
  },
52
55
  "dependencies": {
@@ -54,7 +57,7 @@
54
57
  },
55
58
  "devDependencies": {
56
59
  "@amamo/oxlint-config": "1.0.0",
57
- "@amamo/verso": "1.0.0",
60
+ "@amamo/verso": "1.0.1",
58
61
  "@napi-rs/cli": "3.8.2",
59
62
  "@types/node": "26.1.2",
60
63
  "@types/react": "19.2.18",
@@ -67,7 +70,7 @@
67
70
  "react-dom": "19.2.8",
68
71
  "simple-git-hooks": "2.13.1",
69
72
  "typescript": "7.0.2",
70
- "vite": "8.2.0",
73
+ "vite": "8.2.1",
71
74
  "vitest": "4.1.10"
72
75
  },
73
76
  "peerDependencies": {
@@ -113,12 +116,12 @@
113
116
  },
114
117
  "packageManager": "pnpm@11.20.0",
115
118
  "optionalDependencies": {
116
- "@amamo/mdx-darwin-arm64": "0.1.4",
117
- "@amamo/mdx-darwin-x64": "0.1.4",
118
- "@amamo/mdx-linux-arm64-gnu": "0.1.4",
119
- "@amamo/mdx-linux-x64-gnu": "0.1.4",
120
- "@amamo/mdx-linux-arm64-musl": "0.1.4",
121
- "@amamo/mdx-linux-x64-musl": "0.1.4",
122
- "@amamo/mdx-win32-x64-msvc": "0.1.4"
119
+ "@amamo/mdx-darwin-arm64": "0.1.6",
120
+ "@amamo/mdx-darwin-x64": "0.1.6",
121
+ "@amamo/mdx-linux-arm64-gnu": "0.1.6",
122
+ "@amamo/mdx-linux-x64-gnu": "0.1.6",
123
+ "@amamo/mdx-linux-arm64-musl": "0.1.6",
124
+ "@amamo/mdx-linux-x64-musl": "0.1.6",
125
+ "@amamo/mdx-win32-x64-msvc": "0.1.6"
123
126
  }
124
127
  }