Skip to content

Latest commit

 

History

History
205 lines (160 loc) · 4.5 KB

readme.md

File metadata and controls

205 lines (160 loc) · 4.5 KB
Raw
Mintlify Logo

Mint

Open source docs builder that's beautiful, fast, and easy to work with.

contributions welcome Tweet

Mintlify's markdown parser

@mintlify/mdx is a thin layer on top of next-mdx-remote-client 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.

  1. Call the serialize function inside getStaticProps and return the mdxSource object.

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

  if ('error' in mdxSource) {
   // handle error case
  }

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

  2. Pass the mdxSource object as props inside the MDXComponent.

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

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

  1. Use the MDXRemote component directly inside your async React Server Component.

    import { MDXRemote } from '@mintlify/mdx';

export default async function Home() {
  const source: `---
   title: Title
   ---

   ## Markdown H2
   `;

  return (
    <article className="prose mx-auto py-8">
      <MDXRemote source={source} parseFrontmatter />
    </article>
  );
}

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

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

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-client, this package exports the following APIs:

  • serialize - a function that compiles MDX source to SerializeResult.
  • MDXClient - a component that renders SerializeSuccess on the client.
  • MDXRemote - a component that both serializes and renders the source - should be used inside async React Server Component.

serialize

import { serialize } from '@mintlify/mdx';

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

MDXClient

'use client';

import { MDXClient } from '@mintlify/mdx';

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

MDXRemote

import { MDXRemote } from '@mintlify/mdx';

<MDXRemote
  source="## Markdown H2"
  mdxOptions={{
    remarkPlugins: [
      // Remark plugins
    ],
    rehypePlugins: [
      // Rehype plugins
    ],
  }}
  components={{
    // Your custom components
  }}
/>;

Built with ❤︎ by Mintlify