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
API
mdx(options)
Plugin for mdx
// 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()],
};
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
others
Passes the @mdx-js/mdx#compile
options as is. For details, see
compile options.
remarkFrontmatterProps(options?)
A remark plugin to expose frontmatter to ssrProps
. This will allow you to
retrieve frontmatter from pageProps
.
This is useful for layout pages.
This package depends on the AST output by remark-frontmatter.
// aleph.config.ts
import {
mdx,
remarkFrontmatterProps,
} from "https://deno.land/x/aleph_plugin_mdx@$VERSION/mod.ts";
import remarkFrontmatter from "https://esm.sh/remark-frontmatter";
import type { Config } from "https://deno.land/x/aleph@v0.3.0-beta.19/types.d.ts";
export default <Config> {
plugins: [
mdx({
remarkPlugins: [remarkFrontmatter, remarkFrontmatterProps],
}),
],
};
// pages/docs/installation.mdx
---
title: Installation
---
output:
// .aleph/pages/docs/installation.js
export const ssr = {
props: () => ({ "meta": { "title": "Installation" } }),
};
function MDXContent(props = {}) {
...
}
export default MDXContent;
example
pages
├── docs
│ └── installation.mdx
└── docs.tsx
// docs.tsx
import type { MDXContent } from "https://esm.sh/@types/mdx/types.d.ts";
type Meta = { title: string };
export type DocsProps = {
Page?: MDXContent;
pageProps: {
meta?: Partial<Meta>;
};
};
export default function Docs({ Page, pageProps }: DocsProps) {
if (!Page) return <></>;
// pageProps.meta?.title
return <Page />;
}
options.name
Define export name. The default export name is meta
// aleph.config.ts
import {
mdx,
remarkFrontmatterProps,
} from "https://deno.land/x/aleph_plugin_mdx@$VERSION/mod.ts";
import remarkFrontmatter from "https://esm.sh/remark-frontmatter";
import type { Config } from "https://deno.land/x/aleph@v0.3.0-beta.19/types.d.ts";
export default <Config> {
plugins: [
mdx({
remarkPlugins: [remarkFrontmatter, [remarkFrontmatterProps, {
name: "frontmatter",
}]],
}),
],
};
output:
// .aleph/pages/docs/installation.js
export const ssr = {
props: () => ({ "frontmatter": { "title": "Installation" } }),
};
function MDXContent(props = {}) {
...
}
export default MDXContent;
remarkTocProps(options?)
A remark plugin to expose table of contents to ssrProps
.
This is useful for layout pages.
// aleph.config.ts
import {
mdx,
remarkTocProps,
} 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({
remarkPlugins: [remarkTocProps],
}),
],
};
// pages/docs/installation.mdx
# h1
## h2
### h3
#### h4
output:
// .aleph/pages/docs/installation.js
export const ssr = {
props: () => ({
"tableOfContents": {
"items": [
{
"url": "#h1",
"title": "h1",
"items": [
{
"url": "#h2",
"title": "h2",
"items": [
{
"url": "#h3",
"title": "h3",
"items": [
{
"url": "#h4",
"title": "h4",
},
],
},
],
},
],
},
],
},
}),
};
function MDXContent(props = {}) {}
export default MDXContent;
example
pages
├── docs
│ └── installation.mdx
└── docs.tsx
// docs.tsx
import type { MDXContent } from "https://esm.sh/@types/mdx/types.d.ts";
import type { TableOfContents } from "https://deno.land/x/aleph_plugin_mdx@$VERSION/mod.ts";
type TocProps = {
tableOfContents?: TableOfContents;
};
function Toc({ tableOfContents }: TocProps) {
return tableOfContents?.items?.length
? (
<ul>
{tableOfContents.items.map((item) => {
return (
<li key={item.title}>
<a href={item.url}>{item.title}</a>
{item.items?.length ? <Toc tableOfContents={item} /> : null}
</li>
);
})}
</ul>
)
: null;
}
export type DocsProps = {
Page?: MDXContent;
pageProps: {
tableOfContents?: TableOfContents;
};
};
export default function Docs({ Page, pageProps }: DocsProps) {
if (!Page) return <></>;
return (
<>
<Page />
<aside>
<Toc tableOfContents={pageProps.tableOfContents}>
</aside>
</>
);
}
options
Passes the mdast-util-toc
options as is. For details, see
toc options.
// aleph.config.ts
import {
mdx,
remarkTocProps,
} 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({
remarkPlugins: [[remarkTocProps, {
maxDepth: 4,
}]],
}),
],
};
Note
This plugin depends on @mdx-js/mdx@2.0.0.
License
Copyright © 2021-present TomokiMiyauci.
Released under the MIT license