Creating Docs Page

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.

/** @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;
    if (navNode) {
      tree.children = [
        h('', h('prose', nonNavNodes)),
        h('', navNode),
    return tree;
const withMDX = createWithMdx({
  options: {
    remarkPlugins: [],
    rehypePlugins: [
          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;
export default withMDX({
  //your regular next config


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:

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