Guides
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.
/** @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