A List of Techniques To Render MDX in Astro and Next.js #1074

stefanprobst · 2024-04-14T17:57:21Z

stefanprobst
Apr 14, 2024

hi, i have compiled a list of different approaches to rendering mdx for myself, but maybe someone else finds it useful as well. still need to play a bit more with approach 4 (contentlayer/velite) - will update when i know more.

rendering mdx in astro and next.js

while the old rich-text widget (fields.document()) provided a way to render its content with the
built-in <DocumentRenderer>, this is no longer the case with the new mdx field (fields.mdx()).

the following tries to list different approaches for rendering .mdx documents with astro and next.js.

1. simple example

this example collection has a single title frontmatter field, and mdx content which allows a <RedText> custom component.

keystatic.config.tsx

import { collection, config, fields } from "@keystatic/core";
import { mark } from "@keystatic/core/content-components";
import { PaletteIcon } from "lucide-react";

export default config({
  storage: { kind: "local" },
  collections: {
    posts: collection({
      label: "Posts",
      path: "./src/content/posts/*",
      format: { contentField: "content" },
      slugField: "title",
      schema: {
        title: fields.slug({
          name: { label: "Title", validation: { isRequired: true } },
        }),
        content: fields.mdx({
          label: "Content",
          options: {
            image: {
              directory: "./public/assets/content/posts/",
              publicPath: "/assets/content/posts/",
            },
          },
          components: {
            RedText: mark({
              label: "RedText",
              icon: <PaletteIcon />,
              schema: {},
              style: { color: "red" },
            }),
          },
        }),
      },
    }),
  },
});

src/content/posts/test.mdx

---
title: My test post
---

This "post" has some **bold** text, a <RedText>custom component, which turns text red</RedText>, and a code block:

```ts
function hello() {
  return "world!";
}
```

1.1 approach 1: import `.mdx` documents directly

this relies on bundler integrations, which are provided by @astrojs/mdx and @next/mdx.

1.1.1 `@astrojs/mdx`

pnpm astro add mdx

with the @astrojs/mdx integration, mdx files can be directly imported. custom components can be provided via props. frontmatter is available as a named import.

astro.config.ts

import mdx from "@astrojs/mdx";
import node from "@astrojs/node";
import react from "@astrojs/react";
import keystatic from "@keystatic/astro";
import { defineConfig } from "astro/config";

export default defineConfig({
  adapter: node({ mode: "standalone" }),
  integrations: [keystatic(), mdx(), react()],
  markdown: {
    shikiConfig: { themes: { light: "github-light", dark: "github-dark" } },
  },
  output: "hybrid",
  server: { port: 3000 },
});

src/pages/index.astro

---
import Content, { frontmatter } from '../content/posts/test.mdx';
import RedText from '../components/red-text.astro';
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <Content components={{ RedText }} />
    <pre>{JSON.stringify(frontmatter)}</pre>
  </body>
</html>

1.1.2 `@next/mdx`

pnpm add @next/mdx @mdx-js/loader @types/mdx remark-frontmatter remark-mdx-frontmatter remark-gfm

with the @next/mdx integration, mdx files can be directly imported. custom components can be provided via mdx-components.tsx, or via props. frontmatter is available as a named import with the remark-mdx-frontmatter plugin.

next.config.mjs

import createMdxPlugin from "@next/mdx";
import withFrontmatter from "remark-frontmatter";
import withMdxFrontmatter from "remark-mdx-frontmatter";
import withGfm from "remark-gfm";

/** @typedef {import('next').NextConfig} NextConfig */

/** @type {NextConfig} */
const config = {};

/** @type {Array<(config: NextConfig) => NextConfig>} */
const plugins = [
  createMdxPlugin({
    options: {
      remarkPlugins: [withFrontmatter, withMdxFrontmatter, withGfm],
    },
  }),
];

export default plugins.reduce((config, plugin) => {
  return plugin(config);
}, config);

src/mdx-components.tsx

import type { MDXComponents } from "mdx/types";

import { RedText } from "./components/red-text";

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    RedText,
    ...components,
  };
}

src/app/page.tsx

import Content, { frontmatter } from "../content/posts/test.mdx";

export default function IndexPage() {
  return (
    <main>
      <Content />
      <pre>{JSON.stringify(frontmatter)}</pre>
    </main>
  );
}

Note

while the astro mdx integration by default adds a couple of plugins to support syntax highlighting in code blocks, typographic quotes, and headings ids, the next.js plugin does not add any plugins by default.

to match the default astro behavior:

pnpm add rehype-slug remark-smartypants @shikijs/rehype

next.config.mjs

import createMdxPlugin from "@next/mdx";
import withFrontmatter from "remark-frontmatter";
import withMdxFrontmatter from "remark-mdx-frontmatter";
import withGfm from "remark-gfm";
import withTypographicQuotes from "remark-smartypants";
import withSyntaxHighlighter from "@shikijs/rehype";
import withHeadingIds from "rehype-slug";

/** @typedef {import('next').NextConfig} NextConfig */

/** @type {NextConfig} */
const config = {};

/** @type {Array<(config: NextConfig) => NextConfig>} */
const plugins = [
  createMdxPlugin({
    options: {
      remarkPlugins: [
        withFrontmatter,
        withMdxFrontmatter,
        withGfm,
        withTypographicQuotes,
      ],
      rehypePlugins: [
        withHeadingIds,
        [
          withSyntaxHighlighter,
          { themes: { light: "github-light", dark: "github-dark" } },
        ],
      ],
    },
  }),
];

export default plugins.reduce((config, plugin) => {
  return plugin(config);
}, config);

Tip

when using typescript, the frontmatter import can be typed:

src/types/mdx.d.ts

declare module "*.mdx" {
  export const frontmatter: {
    title: string;
  };
}

1.2 approach 2: astro content collections

pnpm astro add mdx

with astro content collections, use getCollection() and getEntry() utilities to get mdx content and frontmatter. optionally, frontmatter can be validated with a schema provided via src/content/content.config.ts. custom components are provided via props.

astro.config.ts

import mdx from "@astrojs/mdx";
import node from "@astrojs/node";
import react from "@astrojs/react";
import keystatic from "@keystatic/astro";
import { defineConfig } from "astro/config";

export default defineConfig({
  adapter: node({ mode: "standalone" }),
  integrations: [keystatic(), mdx(), react()],
  markdown: {
    shikiConfig: { themes: { light: "github-light", dark: "github-dark" } },
  },
  output: "hybrid",
  server: { port: 3000 },
});

src/pages/index.astro

---
import { getEntry } from 'astro:content';

import RedText from '../components/red-text.astro';

const entry = await getEntry('posts', "test");
const frontmatter = entry.data;
const { Content } = await entry.render();
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <Content components={{ RedText }} />
    <pre>{JSON.stringify(frontmatter)}</pre>
  </body>
</html>

1.3 approach 3: use keystatic reader, and compile with `@mdx-js/mdx`

this uses the keystatic reader to get document content, and the @mdx-js/mdx processor to transform mdx into javascript. custom components can be passed directly to the processor.

pnpm add @mdx-js/mdx

src/lib/content/reader.ts

import { createReader } from "@keystatic/core/reader";

import config from "../../../keystatic.config";

export function reader() {
  return createReader(process.cwd(), config);
}

1.3.1 with astro jsx runtime

src/lib/content/mdx.ts

import { evaluate } from "@mdx-js/mdx";
import * as runtime from "astro/jsx-runtime";

import type { ProcessorOptions } from "@mdx-js/mdx";
import withSyntaxHighlighter from "@shikijs/rehype";
// import withFrontmatter from "remark-frontmatter";
import withGfm from "remark-gfm";
// import withMdxFrontmatter from "remark-mdx-frontmatter";
import withTypographicQuotes from "remark-smartypants";
import withHeadingIds from "rehype-slug";

import RedText from "../../components/red-text.astro";

const config: ProcessorOptions = {
  elementAttributeNameCase: "html",
  remarkPlugins: [
    // Frontmatter plugins are not necessary when using the keystatic reader,
    // which passes only the mdx body to the mdx processor.
    // withFrontmatter,
    // withMdxFrontmatter,
    withGfm,
    withTypographicQuotes,
  ],
  rehypePlugins: [
    withHeadingIds,
    [
      withSyntaxHighlighter,
      {
        themes: {
          light: "github-light",
          dark: "github-dark",
        },
      },
    ],
  ],
};

function useMDXComponents() {
  return {
    RedText,
  };
}

export function processMdx(content: string) {
  // @ts-expect-error
  return evaluate(content, { ...runtime, ...config, useMDXComponents });
}

src/pages/index.astro

---
import { processMdx } from '../lib/content/mdx';
import { reader } from '../lib/content/reader';

const { content, ...frontmatter } = await reader().collections.posts.readOrThrow("test");
const { default: Content } = await processMdx(await content());
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <Content />
    <pre>{JSON.stringify(frontmatter)}</pre>
  </body>
</html>

1.3.2 with react jsx runtime

src/lib/content/mdx.ts

import "server-only";

import { evaluate } from "@mdx-js/mdx";
import * as runtime from "react/jsx-runtime";

import type { ProcessorOptions } from "@mdx-js/mdx";
import withSyntaxHighlighter from "@shikijs/rehype";
// import withFrontmatter from "remark-frontmatter";
import withGfm from "remark-gfm";
// import withMdxFrontmatter from "remark-mdx-frontmatter";
import withTypographicQuotes from "remark-smartypants";
import withHeadingIds from "rehype-slug";

import { useMDXComponents } from "../../mdx-components";

const config: ProcessorOptions = {
  remarkPlugins: [
    // Frontmatter plugins are not necessary when using the keystatic reader,
    // which passes only the mdx body to the mdx processor.
    // withFrontmatter,
    // withMdxFrontmatter,
    withGfm,
    withTypographicQuotes,
  ],
  rehypePlugins: [
    withHeadingIds,
    [
      withSyntaxHighlighter,
      {
        themes: {
          light: "github-light",
          dark: "github-dark",
        },
      },
    ],
  ],
};

export function processMdx(content: string) {
  // @ts-expect-error
  return evaluate(content, { ...runtime, ...config, useMDXComponents });
}

src/app/page.tsx

import { reader } from "../lib/content/reader";
import { processMdx } from "../lib/content/mdx";

export default async function IndexPage() {
  const { content, ...frontmatter } = await reader().collections.posts.readOrThrow("test");
  const { default: Content } = await processMdx(await content());

  return (
    <main>
      <Content />
      <pre>{JSON.stringify(frontmatter)}</pre>
    </main>
  );
}

1.4 approach 4: pre-compile mdx

TODO

2. complex example

this example collection uses fields.blocks() and field.array() with potentially multiple mdx fields per entry.

keystatic.config.tsx

import { collection, config, fields } from "@keystatic/core";
import { mark } from "@keystatic/core/content-components";
import { PaletteIcon } from "lucide-react";

export default config({
  storage: { kind: "local" },
  collections: {
    blocks: collection({
      label: "Blocks",
      path: "./src/content/blocks/*",
      format: { data: "json" },
      slugField: "title",
      schema: {
        title: fields.slug({
          name: {
            label: "Title",
            validation: { isRequired: true },
          },
        }),
        blocks: fields.blocks(
          {
            cardsSection: {
              label: "Cards section",
              schema: fields.object({
                title: fields.text({
                  label: "Section title",
                  validation: { isRequired: true },
                }),
                cards: fields.array(
                  fields.object({
                    title: fields.text({
                      label: "Card title",
                      validation: { isRequired: true },
                    }),
                    content: fields.mdx({
                      label: "Card content",
                      options: {
                        image: {
                          directory: "./public/assets/content/blocks/",
                          publicPath: "/assets/content/blocks/",
                        },
                      },
                      components: {
                        RedText: mark({
                          label: "RedText",
                          icon: <PaletteIcon />,
                          schema: {},
                          style: {
                            color: "red",
                          },
                        }),
                      },
                    }),
                  }),
                  {
                    label: "Cards",
                    itemLabel(props) {
                      return props.fields.title.value;
                    },
                    validation: { length: { min: 1 } },
                  }
                ),
              }),
            },
            imageSection: {
              label: "Image section",
              schema: fields.object({
                title: fields.text({
                  label: "Section title",
                  validation: { isRequired: true },
                }),
                image: fields.image({
                  label: "Image",
                  directory: "./public/assets/content/blocks/",
                  publicPath: "/assets/content/blocks/",
                  validation: { isRequired: true },
                }),
              }),
            },
          },
          {
            label: "Blocks",
            validation: { length: { min: 1 } },
          }
        ),
      },
    }),
  },
});

an example entry will consist of a json file, and multiple mdx files (one for each card):

src/content/my-test-post.json

{
  "title": "My test post",
  "blocks": [
    {
      "discriminant": "imageSection",
      "value": {
        "title": "The image section",
        "image": "/assets/content/blocks/my-test-post/blocks/0/value/image.jpg"
      }
    },
    {
      "discriminant": "cardsSection",
      "value": {
        "title": "The cards section",
        "cards": [
          {
            "title": "The first card"
          },
          {
            "title": "The second card"
          }
        ]
      }
    }
  ]
}

src/content/my-test-post/blocks/1/value/cards/0/content.mdx

This is the **first** card.

src/content/my-test-post/blocks/1/value/cards/1/content.mdx

This is the **second** card, with <RedText>red text</RedText>.

2.1 approach 1: import `.mdx` documents directly

not really viable, because you would need to know how content is saved by keystatic: import "../content/blocks/my-test-post/blocks/1/value/cards/0/content.mdx"

2.2 approach 2: astro content collections

astro content collections do not allow this kind of collection schema.

2.3 approach 3: use keystatic reader, and compile with `@mdx-js/mdx`

works (although without HMR)

2.3.1 astro

content must not live in src/content because this will throw a content collection error, but otherwise works.

src/pages/index.astro

---
import { processMdx } from '../lib/content/mdx';
import { reader } from '../lib/content/reader';

const entry = await reader().collections.blocks.readOrThrow("my-test-post");
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <h1>{entry.title}</h1>
    {entry.blocks.map((block, index) => {
      switch (block.discriminant) {
        case "cardsSection": {
          return (
            <section>
              <h2>{block.value.title}</h2>
              <ul>
                {block.value.cards.map(async (card, index) => {
                  const { default: Content } = await processMdx(await card.content());

                  return (
                    <li>
                      <article>
                        <h3>{card.title}</h3>
                        <Content />
                      </article>
                    </li>
                  );
                })}
              </ul>
            </section>
          );
        }

        case "imageSection": {
          return (
            <section>
              <h2>{block.value.title}</h2>
              <img alt="" src={block.value.image} />
            </section>
          );
        }
      }
    })}
  </body>
</html>

2.3.2 next.js

src/app/page.tsx

import { reader } from "../lib/content/reader";
import { processMdx } from "../lib/content/mdx";

export default async function IndexPage() {
  const entry = await reader().collections.blocks.readOrThrow("my-test-post");

  return (
    <main>
      <h1>{entry.title}</h1>
      {entry.blocks.map((block, index) => {
        switch (block.discriminant) {
          case "cardsSection": {
            return (
              <section key={index}>
                <h2>{block.value.title}</h2>
                <ul>
                  {block.value.cards.map(async (card, index) => {
                    const { default: Content } = await processMdx(await card.content());

                    return (
                      <li key={index}>
                        <article>
                          <h3>{card.title}</h3>
                          <Content />
                        </article>
                      </li>
                    );
                  })}
                </ul>
              </section>
            );
          }

          case "imageSection": {
            return (
              <section key={index}>
                <h2>{block.value.title}</h2>
                <img alt="" src={block.value.image} />
              </section>
            );
          }
        }
      })}
    </main>
  );
}

2.4 approach 4: pre-compile mdx

TODO

3. previews with draft mode (next.js only)

in draft mode, use the keystatic github reader to get a mdx string.

3.1 approach 1: import `.mdx` documents directly

does not work, nothing to import.

3.2 approach 2: astro content collections

does not work with mdx strings.

3.3 approach 3: use keystatic reader, and compile with `@mdx-js/mdx`

works, just need to use @keystatic/core/reader/github instead of @keystatic/core/reader

3.4 approach 4: pre-compile mdx

TODO

simonswiss · 2024-04-16T06:23:15Z

simonswiss
Apr 16, 2024

This is a great collection of approaches, thanks for sharing this Stefan! 🤙

0 replies

shmmh · 2024-09-28T13:37:14Z

shmmh
Sep 28, 2024

Thank you so much for the guide. I added keystatic to my Astro blog a few days ago, everything was working fine until I added Latex support with rehype-katex, remark-marth plugin.

I was getting a parsing error with the MDX plugin integration in my VS code but everything renders perfectly with Astro once you add the relevant plugins to mdx() configuration and add remark-math plugin into mdx config in tsconfig.json. See [MDX repo]

After I added keystatic, it looks like its having the same issue as the MDX VS code plugin.

Looks like the issue is with Mdx rendering and escaping curly braces. But this breaks a lot of things in my workflow. Can I add plguins to mdx parser in keystatic ??? I might be missing something here.

0 replies

ismaelrumzan · 2024-10-19T19:20:00Z

ismaelrumzan
Oct 19, 2024

So far, I've been loving keystatic. Easy to implement and flexible. I was having challenges rendering custom components with markdoc using the new markdoc fields and content components. I ended up switching to mdx for those. The strategies above did not work for me in next.js because my content is dynamic.
next-mdx-remote worked well.
So in the above example, it would be something like this

File: mdx-remote.tsx

import { MDXRemote } from "next-mdx-remote/rsc";

export function CustomMDX(props) {
  const components = {
    RedText: (props) => (
      <div className="bg-red">{props.label}</div>
    ),
  };
  return <MDXRemote {...props} components={components} />;
}

import {CustomMDX} from './mdx-remote`;

const myContent = await reader.collections.mycoll.read();
const mdxContent = await myContext.content();

return (
<CustomMDX source={mdxContent} />
)

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

A List of Techniques To Render MDX in Astro and Next.js #1074

Uh oh!

{{title}}

Uh oh!

Replies: 3 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

A List of Techniques To Render MDX in Astro and Next.js #1074

Uh oh!

stefanprobst Apr 14, 2024

rendering mdx in astro and next.js

1. simple example

1.1 approach 1: import .mdx documents directly

1.1.1 @astrojs/mdx

1.1.2 @next/mdx

1.2 approach 2: astro content collections

1.3 approach 3: use keystatic reader, and compile with @mdx-js/mdx

1.3.1 with astro jsx runtime

1.3.2 with react jsx runtime

1.4 approach 4: pre-compile mdx

2. complex example

2.1 approach 1: import .mdx documents directly

2.2 approach 2: astro content collections

2.3 approach 3: use keystatic reader, and compile with @mdx-js/mdx

2.3.1 astro

2.3.2 next.js

2.4 approach 4: pre-compile mdx

3. previews with draft mode (next.js only)

3.1 approach 1: import .mdx documents directly

3.2 approach 2: astro content collections

3.3 approach 3: use keystatic reader, and compile with @mdx-js/mdx

3.4 approach 4: pre-compile mdx

Replies: 3 comments

Uh oh!

simonswiss Apr 16, 2024

Uh oh!

Uh oh!

shmmh Sep 28, 2024

Uh oh!

ismaelrumzan Oct 19, 2024

stefanprobst
Apr 14, 2024

1.1 approach 1: import `.mdx` documents directly

1.1.1 `@astrojs/mdx`

1.1.2 `@next/mdx`

1.3 approach 3: use keystatic reader, and compile with `@mdx-js/mdx`

2.1 approach 1: import `.mdx` documents directly

2.3 approach 3: use keystatic reader, and compile with `@mdx-js/mdx`

3.1 approach 1: import `.mdx` documents directly

3.3 approach 3: use keystatic reader, and compile with `@mdx-js/mdx`

simonswiss
Apr 16, 2024

shmmh
Sep 28, 2024

ismaelrumzan
Oct 19, 2024