Markdown allows text content to be written with implicit formatting that nearly matches how one would write text without thought of formatting. A lot of web content is also simply text content; a lot of web content is built on the ReactJS library; and NextJS has become a popular framework, extending ReactJS. With that, I was motivated to use the Markdown content of my NextJS web app, but I had trouble simply relying on their documentation, so I thought I would document what I got working.

1. Use Markdown for a text-heavy portion of a page of my web app, and
2. To be able to have an entire page of content come from a single Markdown page

The former is a feature of NextJS to allow markdown content to be imported as a “component,” which can be rendered like any component in ReactJs.

The latter would rely NextJS’s App Router that assumes many URL paths for the app parallel the file/directory hierarchy of the app itself. So, merely placing a “page” file in the app’s directory will create a new URL path for the website. That means that you can create a “page.md” or “page.mdx” file with Markdown text content to define the content for that URL. .mdx files also allow JSX syntax so that React/Next components can be embedded within the Markdown.

Setup

The first issue was getting things set up. Here were the steps that worked for me.

1. Add packages. The highlighted line was missing from the documentation.

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

2. Update next.config.ts from:

   import type {NextConfig} from 'next';
   
   const nextConfig: NextConfig = {
     typescript: {
       ignoreBuildErrors: true,
     },
     eslint: {
       ignoreDuringBuilds: true,
     },
   };
   
   export default nextConfig;

   Add

   1. import withMDX from "@next/mdx";
   2. Add “md” (optional) and “mdx” extensions for App Router support: nextConfig.pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx']
   3. Create, then wrap the Next config with mdx-configwithMDX = createMDX({})…export default withMDX(nextConfig)

   to get:

   import type {NextConfig} from 'next';
   import withMDX from "@next/mdx";
   
   const nextConfig: NextConfig = {
     pageExtensions: ["js", "jsx", "mdx", "ts", "tsx"],
     typescript: {
       ignoreBuildErrors: true,
     },
     eslint: {
       ignoreDuringBuilds: true,
     },
   };
   
   const withMdxConfig = withMDX({
     options: {
       remarkPlugins: [],
       rehypePlugins: [],
       // providerImportSource: "@mdx-js/react",  // To use `MDXProvider`, uncomment this line
     },
   });
   
   export default withMdxConfig(nextConfig);

3. Add an mdx-components.tsx file to src/.  See mdx-components.js for more details.

   import type { MDXComponents } from 'mdx/types'
   
   export function useMDXComponents(components: MDXComponents): MDXComponents {
      return {
         ...components,
      }
   }
   

4. Help VSCode resolve imports
   1. Open settings
   2. Search for “file associations”
   3. Add item key = *.mdx, value = markdown-react
5. Styles will need to be defined for all the generated HTML tags. I’m still playing with this, but there are three approaches
   1. wrapper()
   2. className definitions
   3. Import a style sheet

Defining Markdown Output Style

Markdown syntax is translated to HTML. By default, the HTML tags have had their formatting stripped, for some reason. That means that the tags need to have style/class definitions applied to render properly. See How to use markdown and MDX in Next.js, for the official word.

The following are tags that correspond to Markdown syntax:

Wrapper

import type { MDXComponents } from 'mdx/types' 

export function useMDXComponents(components: MDXComponents): MDXComponents { 
   return { 
      ...components, 
      wrapper: ({ children }) => <div style={{ ... }}>{children}</div>,
   } 
}

Import Style Sheet

This is the easiest solution, but with the least containment and control. The problem is that it affects tags on the whole page. Stay tuned as I figure out whether this can be contained. This can be added to the mdx-components.tsx or within the mdx file itself with import ./mdxstyle.css (or what/where-ever you define this file)

/* This is a more aggressive reset, consider if you need it */
/* * {
  all: unset;
  display: revert; // Revert display to its default based on tag
} */

h1, h2, h3, h4, h5, h6 {
  all: unset; /* Reset all styles */
  display: block; /* Ensure headings are block elements */
  font-weight: bold; /* Make headings bold */
  margin-inline-start: 0; /* Reset left margin */
  margin-inline-end: 0; /* Reset right margin */
}

h1 {
  display: block;
  font-weight: bold;
  margin-inline-start: 0;
  margin-inline-end: 0;
  font-size: 2em;
}
h2 {
  display: block;
  font-weight: bold;
  margin-inline-start: 0;
  margin-inline-end: 0;
  font-size: 1.5em;
}

h3 {
  display: block;
  font-weight: bold;
  margin-inline-start: 0;
  margin-inline-end: 0;
  font-size: 1.17em;
}

h4 {
  display: block;
  font-weight: bold;
  margin-inline-start: 0;
  margin-inline-end: 0;
}

h5 {
  display: block;
  font-weight: bold;
  margin-inline-start: 0;
  margin-inline-end: 0;
  font-size: .83em;
}
h6 {
  display: block;
  font-weight: bold;
  margin-inline-start: 0;
  margin-inline-end: 0;
  font-size: .67em;
}

p {
  display: block;
  margin-inline-start: 0;
  margin-inline-end: 0;
}

a {
  all: unset;
  color: -webkit-link; /* Restore default link color */
  text-decoration: underline; /* Restore default underline */
  cursor: pointer; /* Restore default cursor */
}

ul {
  display: block;
  list-style-type: disc;
  padding-inline-start: 40px;
}

ol {
  display: block;
  list-style-type: decimal;
  padding-inline-start: 40px
}

li {
  display: list-item;
}

blockquote {
  display: block;
  margin-left: 40px;
  margin-right: 40px;
}

code {
  font-family: monospace; /* Restore default monospace font */
}

pre {
  display: block;
  font-family: monospace;
  margin-top: 1em;
  margin-bottom: 1em;
  white-space: pre; /* Restore default pre-formatted text handling */
}

img {
  all: unset;
  display: inline-block; /* Images are inline-block by default */
  max-width: 100%; /* A common and helpful default for responsive images */
  height: auto; /* Maintain aspect ratio */
}

 /* Add resets for other tags as needed */

import type { MDXComponents } from 'mdx/types'

import './resets.css';

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

Now,

• App Router will render page.mdx files.
• NextJS modules can render mdx file as components:

  // src/app/updates/page.tsx
  
  import UpdateContent from "./updates.mdx"
  
  export default async function UpdatesPage() {
  
  return (
    <>
       <h1>Updated News</h1>
       <UpdateContent/>
    </>
  )
  

   

Note that:

• - [ ] checkboxes do not work
• Markdown tables do not work