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