Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mintlify/mdx

Mintlify markdown parser
https://github.com/mintlify/mdx

mdx next

Last synced: 2 months ago
JSON representation

Mintlify markdown parser

Awesome Lists containing this project

README

        



Mintlify Logo







Mint





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


![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen?logo=github) [![Tweet](https://img.shields.io/twitter/url?url=https%3A%2F%2Fmintlify.com%2F)](https://twitter.com/intent/tweet?url=&text=Check%20out%20%40mintlify)


# Mintlify's markdown parser

**@mintlify/mdx** is a thin layer on top of [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote) that provides a better developer experience for Next.js users by adding support for syntax highlighting.

## Installation

```bash
# 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](https://github.com/mintlify/mdx/tree/main/examples/pages-router).

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

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

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

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

```tsx
export default function Page({ mdxSource }: InferGetStaticPropsType) {
return ;
}
```

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

```tsx
import '@mintlify/mdx/dist/styles.css';
import { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
return ;
}
```

### Next.js app router

[You can check the example app here](https://github.com/mintlify/mdx/tree/main/examples/app-router).

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

```tsx
import { getCompiledServerMdx } from '@mintlify/mdx';

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

## Markdown H2
`,
});

return (

{String(frontmatter.title)}

{content}

);
}
```

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

```tsx
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 (

{children}

);
}
```

## APIs

Similar to [next-mdx-remote](https://github.com/hashicorp/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

```tsx
import { getCompiledMdx } from '@mintlify/mdx';

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

### MDXComponent

```tsx
import { MDXComponent } from '@mintlify/mdx';

;
```

### getCompiledServerMdx

```tsx
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

```tsx
import { MDXServerComponent } from '@mintlify/mdx';

;
```




Built with ❤︎ by

Mintlify