Authoring HTML directly is cumbersome, and people quickly made new formats to be able to write documents more easily. Markdown has invented quite early and it catch on quickly. It is the most used format for directly writing documents for the web and there are hundreds of libraries to parse it, process it and render it as HTML. There is also a nice guide and a great editor for it.

Markdown files resemble text with very light formatting. The following Markdown "code":

I will **tattoo** myself with the [NextJS](https://nextjs.org) logo

will render as

<p>
  I will <strong>tattoo</strong> myself with the
  <a href="https://nextjs.org">logo</a>
</p>

Format

Inline HTML

Being a format to make HTML authoring easier, in Markdown you can always write embedded HTML, so:

This is a regular paragraph

<table>
  <tr>
    <td>Foo</td>
  </tr>
</table>

This is another paragraph

MDX

MDX is MarkDown EXtended, so that we can use components inside Markdown files.

To use MDX in NextJS, first install needed packages:

npm install @next/mdx @mdx-js/loader @mdx-js/react @types/mdx

Then create a file mdx-components.tsx in the root of the project with:

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

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

Update next.config.js to use withMDX:

const withMDX = require("@next/mdx")(); // <-- add this line

/** @type {import('next').NextConfig} */
const nextConfig = {
  // v-- add this section
  experimental: {
    mdxRs: true, // <-- add this option
  },
};

module.exports = withMDX(nextConfig); // <-- wrap with withMDX here

Create .mdx files (and import any React components in them)

<!-- test.mdx -->

This is an **MDX file**!!

and use them in pages:

import Test from "./test.mdx";

export default function Page() {
  return <Test />;
}