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;
});
};
}
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:
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