Docs Contribution Guide

Welcome to the Next.js Docs Contribution Guide! We're excited to have you here.
This page provides instructions on how to edit the Next.js documentation. Our goal is to ensure that everyone in the community feels empowered to contribute and improve our docs.
Open-source work is never done, and neither is documentation. Contributing to docs is a good way for beginners to get involved in open-source and for experienced developers to clarify more complex topics while sharing their knowledge with the community.
By contributing to the Next.js docs, you're helping us build a more robust learning resource for all developers. Whether you've found a typo, a confusing section, or you've realized that a particular topic is missing, your contributions are welcomed and appreciated.
The docs content can be found on the Next.js repo. To contribute, you can edit the files directly on GitHub or clone the repo and edit the files locally.
If you're new to GitHub, we recommend reading the GitHub Open Source Guide to learn how to fork a repository, create a branch, and submit a pull request.
The underlying docs code lives in a private codebase that is synced to the Next.js public repo. This means that you can't preview the docs locally. However, you'll see your changes on nextjs.org after merging a pull request.
The docs are written in MDX, a markdown format that supports JSX syntax. This allows us to embed React components in the docs. See the GitHub Markdown Guide for a quick overview of markdown syntax.
VSCode has a built-in markdown previewer that you can use to see your edits locally. To enable the previewer for MDX files, you'll need to add a configuration option to your user settings.
Open the command palette (⌘ + ⇧ + P on Mac or Ctrl + Shift + P on Windows) and search for Preferences: Open User Settings (JSON).
Then, add the following line to your settings.json file:
Next, open the command palette again, and search for Markdown: Preview File or Markdown: Open Preview to the Side. This will open a preview window where you can see your formatted changes.
We also recommend the following extensions for VSCode users:
Once you've submitted your contribution, the Next.js or Developer Experience teams will review your changes, provide feedback, and merge the pull request when it's ready.
Please let us know if you have any questions or need further assistance in your PR's comments. Thank you for contributing to the Next.js docs and being a part of our community!
Run pnpm prettier-fix to run Prettier before submitting your PR.
The docs use file-system routing. Each folder and files inside /docs represent a route segment. These segments are used to generate the URL paths, navigation, and breadcrumbs.
The file structure reflects the navigation that you see on the site, and by default, navigation items are sorted alphabetically. However, we can change the order of the items by prepending a two-digit number (00-) to the folder or file name.
For example, in the functions API Reference, the pages are sorted alphabetically because it makes it easier for developers to find a specific function:
But, in the app router section, the files are prefixed with a two-digit number, sorted in the order developers should learn these concepts:
To quickly find a page, you can use ⌘ + P (Mac) or Ctrl + P (Windows) to open the search bar on VSCode. Then, type the slug of the page you're looking for. E.g. installation
Why not use a manifest?
We considered using a manifest file (another popular way to generate the docs navigation), but we found that a manifest would quickly get out of sync with the files. File-system routing forces us to think about the structure of the docs and feels more native to Next.js.
Each page has a metadata block at the top of the file separated by three dashes.
The following fields are required:
It's good practice to limit the page title to 2-3 words (e.g. Optimizing Images) and the description to 1-2 sentences (e.g. Learn how to optimize images in Next.js).
The following fields are optional:
Since most of the features in the App Router and Pages Router are completely different, their docs for each are kept in separate sections (02-app and 03-pages). However, there are a few features that are shared between them.
To avoid content duplication and risk the content becoming out of sync, we use the source field to pull content from one page into another. For example, the <Link> component behaves mostly the same in App and Pages. Instead of duplicating the content, we can pull the content from app/.../link.mdx into pages/.../link.mdx:
We can therefore edit the content in one place and have it reflected in both sections.
In shared pages, sometimes there might be content that is App Router or Pages Router specific. For example, the <Link> component has a shallow prop that is only available in Pages but not in App.
To make sure the content only shows in the correct router, we can wrap content blocks in an <AppOnly> or <PagesOnly> components:
You'll likely use these components for examples and code blocks.
Code blocks should contain a minimum working example that can be copied and pasted. This means that the code should be able to run without any additional configuration.
For example, if you're showing how to use the <Link> component, you should include the import statement and the <Link> component itself.
Always run examples locally before committing them. This will ensure that the code is up-to-date and working.
Code blocks should have a header that includes the language and the filename. For example:
For CLI commands, use the package prop to show the command for each package manager:
Most examples in the docs are written in tsx and jsx, and a few in bash. However, you can use any supported language, here's the full list.
When writing JavaScript code blocks, we use the following language and extension combinations.