@mintlify/mdx NPM

Mintlify's markdown parser

@mintlify/mdx is a thin layer on top of next-mdx-remote that provides a better developer experience for Next.js users by adding support for syntax highlighting.

Installation

# using npm
npm i @mintlify/mdx

# using yarn
yarn add @mintlify/mdx

# using pnpm
pnpm add @mintlify/mdx

Examples

Next.js pages router

You can check the example app here.

Call the getCompiledMdx function inside getStaticProps and return the mdxSource object.

export const getStaticProps = (async () => {
  const mdxSource = await getCompiledMdx({
    source: "## Markdown H2",
  });

  return {
    props: {
      mdxSource,
    },
  };
}) satisfies GetStaticProps<{
  mdxSource: MDXCompiledResult;
}>;

Pass the mdxSource object as props inside the MDXComponent.

export default function Page({
  mdxSource,
}: InferGetStaticPropsType<typeof getStaticProps>) {
  return <MDXComponent {...mdxSource} />;
}

Import @mintlify/mdx/dist/styles.css inside your _app.tsx file. This file contains the styles for the code syntax highlighting.

import "@mintlify/mdx/dist/styles.css";

import { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

Next.js app router

You can check the example app here.

Call the getCompiledServerMdx function inside your async React Server Component which will give you the frontmatter and content.

import { getCompiledServerMdx } from "@mintlify/mdx";

export default async function Home() {
  const { content, frontmatter } = await getCompiledServerMdx({
    source: `---
      title: Title
      ---

      ## Markdown H2
    `,
  });

  return (
    <article className="prose mx-auto py-8">
      <h1>{String(frontmatter.title)}</h1>

      {content}
    </article>
  );
}

Import @mintlify/mdx/dist/styles.css inside your layout.tsx file. This file contains the styles for the code syntax highlighting.

import type { Metadata } from "next";
import "@mintlify/mdx/dist/styles.css";

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

APIs

Similar to next-mdx-remote, this package exports the following APIs:

getCompiledMdx - a function that compiles MDX source to MDXCompiledResult.
MDXComponent - a component that renders MDXCompiledResult.
getCompiledServerMdx - a function that compiles MDX source to return content and frontmatter and should be used inside async React Server Component.
MDXServerComponent - a component that renders content and frontmatter and should be used inside async React Server Component.

getCompiledMdx

import { getCompiledMdx } from "@mintlify/mdx";

const mdxSource = await getCompiledMdx({
  source: "## Markdown H2",
  mdxOptions: {
    remarkPlugins: [
      // Remark plugins
    ],
    rehypePlugins: [
      // Rehype plugins
    ],
  },
});

MDXComponent

import { MDXComponent } from "@mintlify/mdx";

<MDXComponent
  components={
    {
      // Your custom components
    }
  }
  {...mdxSource}
/>;

getCompiledServerMdx

import { getCompiledServerMdx } from "@mintlify/mdx";

const { content, frontmatter } = await getCompiledServerMdx({
  source: `---
    title: Title
    ---

    ## Markdown H2
  `,
  mdxOptions: {
    remarkPlugins: [
      // Remark plugins
    ],
    rehypePlugins: [
      // Rehype plugins
    ],
  },
  components: {
    // Your custom components
  },
});

MDXServerComponent

import { MDXServerComponent } from "@mintlify/mdx";

<MDXServerComponent
  source="## Markdown H2"
  components={
    {
      // Your custom components
    }
  }
/>;

hast-util-to-string next-mdx-remote refractor rehype-katex remark-gfm remark-math remark-smartypants unist-util-visit

@everything-registry/sub-chunk-607 @mintlify/common

4 months ago

4 months ago

4 months ago

4 months ago

4 months ago