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.6.0.

This is the latest version of the module that can be compiled into MDX 2 and used with the Deno runtime.

There is already a 3.x.x version, but unfortunately it is not available for Deno. For more information, please refer to Failed to import - xdm #135

Known Issues

xdm@1.6.0 contains the following problem.

Multiple JSX children in “paragraph”

This has been fixed in xdm@1.8.0.Fix multiple JSX children in “paragraph”

# Hello
<div>
  <div></div>
  <div></div>
</div>

to(@jsx-runtime -> HTML)

<h1>Hello</h1>
<div>
  <p>
    <div></div>
    <div></div>
  </p>
</div>

License

Released under the MIT license