aleph-plugin-mdx

MDX 2 plugin for Aleph.js

Usage

// aleph.config.ts
import mdx from "https://deno.land/x/aleph_plugin_mdx@$VERSION/mod.ts";
import type { Config } from "https://deno.land/x/aleph@v0.3.0-beta.19/types.d.ts";

export default <Config> {
  plugins: [mdx()],
};

then, modify import_map.json.

{
  "imports": {
    ...,
    "react/jsx-runtime": "https://esm.sh/react@17.0.2/jsx-runtime"
  }
}

Why need import map?

By default, .mdx files are JSX transformed into the @jsx-runtime format.

It includes the following imports.

import {
  Fragment as _Fragment,
  jsx as _jsx,
  jsxs as _jsxs,
} from "react/jsx-runtime";

As you know, Deno imports remote modules with URL schema. This means that you need to change react/jsx-runtime to the correct URL.

Fortunately, Aleph.js has import map resolution enabled by default, so we will use that.

:construction: This process may be automated in the future.

Examples

_example

API

This package exports default as plugin. It uses the same style as the official plugin.

default(options?)

options.rewritePagePath

Rewrite the page path

declare function rewritePagePath: (path: string) => string | undefined;

example:

pages
├── get_started.mdx
└── index.tsx

// aleph.config.ts
import mdx from "https://deno.land/x/aleph_plugin_mdx@$VERSION/mod.ts";
import type { Config } from "https://deno.land/x/aleph@v0.3.0-beta.19/types.d.ts";
export default <Config> {
  plugins: [mdx({
    rewritePagePath(path) {
      return path.replaceAll("_", "-");
    },
  })],
};

output:

▲ SSG
  /
  /get-started

options.pageProps

Define props to page components.

declare const pageProps = Record<string | number, unknown>;

example:

// aleph.config.ts
import mdx from "https://deno.land/x/aleph_plugin_mdx@$VERSION/mod.ts";
import type { Config } from "https://deno.land/x/aleph@v0.3.0-beta.19/types.d.ts";
export default <Config> {
  plugins: [
    mdx({
      pageProps: { nav: [{ path: "/" }, { path: "/docs" }] },
    }),
  ],
};

pages
├── docs
│   └── installation.mdx
└── docs.tsx

// docs.tsx
import type { MDXContent } from "https://esm.sh/@types/mdx/types.d.ts";
export type DocsProps = {
  Page?: MDXContent & { nav: { path: string }[] };
};
export default function Docs({ Page }: DocsProps) {
  if (!Page) return <></>;

  // Page.nav
  return <Page />;
}

others:

Passes the @mdx-js/mdx#compile options as is. For details, see compile options.

Note

This plugin depends on xdm@1.12.2.

After xdm@1.6.0, it cannot be used as it is with the Deno runtime from Registry such as esm.sh and skypack.

Therefore, we are intentionally adjusting the dependencies.

xdm already has a 3.x.x version, It is not possible to follow the version any further by simply adjusting the version of the dependencies.

License

Released under the MIT license