Introduction

This guide will walk you through creating, customizing, and deploying a new documentation site powered by Doctocat on Next.js.

1. Create a new Next.js installation

Start by creating a new Next.js project using the Next.js CLI.

Select “Yes” for the question: “Would you like to use App Router?“

2. Install Doctocat (Next.js) and relevant dependencies

Next, install Doctocat and its dependencies:

npm install --save @primer/doctocat-nextjs next

3. Update your Next.js configuration

Update your next.config.js file to use the Doctocat theme:

// next.config.js
/** @type {import('next').NextConfig} */
import withDoctocat from '@primer/doctocat-nextjs/doctocat.config.js'
 
export default {
  ...withDoctocat({
    transpilePackages: ['@primer/doctocat-nextjs'],
  }),
}

Optional: GitHub Pages configuration

If you plan to deploy your site to GitHub Pages, you’ll need to add the following to your next.config.js file:

{
  output: 'export'
}

4. Add required environment variables

NEXT_PUBLIC_SITE_TITLE = Documentation # required: for site metadata and header title
NEXT_PUBLIC_REPO = https://github.com/org/repo # required: for edit links
NEXT_PUBLIC_REPO_SRC_PATH = # optional:  path for monorepos that do not store .mdx in the project root

5. Add the Doctocat stylesheets

Add the required Doctocat stylesheets to your pages/_app.(tsx|jsx) file:

import { AppProps } from "next/app";
import "@primer/doctocat-nextjs/css/global.css";
 
function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}
 
export default App;

6. Update homepage

Rename pages/index.tsx to pages/index.md and replace the file contents with:

---
title: Your homepage tile
---
 
Welcome to your homepage content.
 
This is a markdown file that will be rendered as a page on your site.
 
You can edit this file to change the content of your homepage.

Optional: Add other content

Next, go ahead and put any additional Markdown documents (.md or .mdx) in pages/ using subfolders. Documents in pages/ automatically become pages with URLs based on their path relative to pages/. For example, if you create a pages/my-folder/my-page.md file, Doctocat will use that file to create a /my-folder/my-page page.

Important:

• You must use .md or .mdx extensions for your documents.
• Folders must contain an index.md or index.mdx file for breadcrumbs to work correctly. The contents of this file can be left empty

7. Update Frontmatter on all pages

Side navigation for your site is generated automatically from the frontmatter of your pages. To add a page to the side navigation, you must add a title and description to the frontmatter of your page. For example:

---
title: My page title
description: My page description
---

8. Optional: Add an LLMs.txt file

Add an llms.txt file to make your site content easily discoverable to AI tools like GitHub Copilot. This file will be automatically generated at build time, and help your Agents discover your content much more efficiently.

To enable this feature, you simply need to copy the following code into a new file at the following location: app/llms.txt/route.ts:

import {generateLLMsTxt} from '@primer/doctocat-nextjs/llms'
 
export const dynamic = 'force-static'
 
export async function GET() {
  const content = await generateLLMsTxt()
 
  return new Response(content, {
    headers: {'Content-Type': 'text/plain; charset=utf-8'},
  })
}

The title and description are automatically inferred from your homepage frontmatter.

The resulting /llms.txt will list every page on your site with its title, description, and any keywords from your frontmatter.

To help discoverability, be sure to add relevant keywords to your page frontmatter:

---
title: My page title
description: My page description
keywords: ['synonyms', 'alternative', 'search terms']
---

9. Deploy to GitHub Pages

After you’ve customized the content of your site, you’re ready to deploy. There are many ways to deploy your site, but we currently use GitHub Pages for most of our sites, and have found it to be an easy way to get sites up and running quickly.

Congrats! You’ve shipped your first Doctocat site on Next.js 🎉