Creating Docs Page

Guide on how to create a docs page in a Next.js application such as in Nextbase.

Docs pages are generated at build time. To create a docs page, create a markdown file in the src/(static-pages)/(developer-resources)/docs folder. The pages should be written in mdx. Nextbase is configured to use mdx within next.config.mjs and custom components are configured using the src/mdx-components.tsx file. MDX is also configured to use rehype and remark plugins to allow for syntax highlighting and other features.

Here is the relevant next.config.mjs configuration.

next.config.mjs

/** @type {import('next').NextConfig} */
 
import createWithMdx from '@next/mdx';
import { h } from 'hastscript';
import rehypeSlug from 'rehype-slug';
import rehypeToc from 'rehype-toc';
 
function rehypeWrapMainContent() {
  // This generates a table of contents unit for docs page
  return (tree) => {
    let navNode;
    const nonNavNodes = tree.children?.filter((node) => {
      if (node.type === 'element' && node.tagName === 'TocNav') {
        navNode = node;
        return false;
      }
      return true;
    });
  };
}
 
const withMDX = createWithMdx({
  options: {
    remarkPlugins: [],
    rehypePlugins: [
      rehypeSlug,
      [
        rehypeToc,
        {
          headings: ['h2', 'h3'],
          customizeTOC: (toc) => {
            // change element from nav to TOCNav
            // We need this to be able to render a custom component in mdx-components
            // to replace the `a` tags with `Link` components
            toc.tagName = 'TocNav';
            return toc;
          },
        },
      ],
      rehypeWrapMainContent,
    ],
  },
});
 
export default withMDX({
  //your regular next config
});

SEO

You can add SEO to your mdx page in the same way you would add to a typescript page.tsx component, using metadata.

Here is an example:

some-page.mdx

export const metadata = {
  title: 'Creating Docs Page',
  description:
    'How to create a docs page in a Next.js application such as in Nextbase.',
};
 
# A page
 
Some content

SEO

On this page