Thursday, January 9th 2020
New Next.js DocumentationPosted by
We're excited to announce the new Next.js documentation, featuring:
- Improved Content: New sections explaining core concepts and features have been added.
- Search: Fuzzy search through the documentation using the new sidebar.
- API Reference One of the most requested documentation additions. The Next.js documentation now has a separate API reference.
- Part of the Next.js GitHub repository: The documentation content still lives in the Next.js repository. Ensuring updates to documentation are synchronous with new features.
In addition to the new and improved documentation, we've made some changes to nextjs.org/learn, making it even easier to get started using Next.js:
- Login is no longer required: We've removed the login with GitHub, so you can start learning right away. You can still earn points!
- New API Routes lesson: A new lesson explains the basics of creating an API endpoint with Next.js and how to fetch it with SWR.
Previously, the Next.js documentation lived in a single
readme.md document. Over the past 3 years the documentation consistently improved, growing in size to cover all areas of the framework.
Over time the documentation page became quite long and we started getting community feedback that it would be preferable for the documentation to be split into smaller chunks so that they could be independently consumed and searched for.
As with all our releases, we closely collaborated with community members to find the optimal page structure.
We decided to have a multi-page structure where every section explains a separate concept. Allowing users to find the relevant content quicker.
The sidebar was also updated to better sort the content with a focus on the core features and concepts, instead of showing everything and combining advanced features with basic ones.
In addition to improving the structure, a few new sections were added to the documentation. Most notably:
- nextjs.org/docs/pages/building-your-application/routing/pages-and-layouts: what
pagesare in Next.js and how they relate to static generation and server-side rendering.
- nextjs.org/docs/pages/building-your-application/routing: The different types of routes that are supported on the filesystem.
With moving to multi-page documentation you lose one important benefit of a single documentation page, being able to search using
cmd + f (or
ctrl + f on Windows/Linux).
We've added a new search input to the documentation sidebar that allows you to fuzzy search through all documentation pages.
This addition allows the documentation to still feel like a single page.
The sidebar now has a dedicated API Reference section. This addition to the documentation was frequently requested by companies and community members that use Next.js often and just wanted to look up what parameter to pass or which function to call.
Previously these references were interleaved with the explanation of the feature.
Since the beginning of the project, the single location for Next.js documentation has been the
readme.md living in the GitHub repository.
When the nextjs.org website launched, we would manually keep the documentation changes up to date by periodically copying the content from the Next.js GitHub repository to the website GitHub repository. The reason we had to do this was that page on the website was powered by MDX.
Manually copying is not ideal and we started investigating better solutions to the problem. We wanted the new way of contributing to the documentation to be as low-friction as the current way, updating markdown files in the Next.js GitHub repository without needing knowledge about how the website works.
By using Next.js' new support for static generation on a per-page basis (proposal) we were able to keep the documentation in the Next.js repository.
The markdown from the raw GitHub file url gets fetched and rendered to HTML in
We also wanted to make it easier to contribute to individual documentation pages. To achieve this we've added a "Edit this page on GitHub" link at the bottom of every documentation page.
When an update to the documentation is made, it'll be released with every new stable release automatically. Keeping the documentation always up to date with new releases.
The nextjs.org/learn website is an interactive learning experience that guides you through many of the features Next.js offers by default.
Every lesson that is completed you get points awarded. Sometimes a lesson can even have a quiz to reinforce your knowledge of the lesson.
To keep track of this progress and the points you've collected we previously asked users to login with their GitHub account.
Recently we've lifted this limitation and all lessons are now available without login. Allowing you to start learning Next.js immediately on nextjs.org/learn.
A new lesson was added that explains the basics of creating an API endpoint with Next.js and how to fetch it with SWR.
Special thanks to Next.js community member Amandeep Singh for contributing this new lesson.
We'll keep improving and iterating on the documentation based on user feedback. You can expect new sections about both high and low level concepts that Next.js helps you with.
If you have any feedback about the new documentation you can use the feedback input at the bottom of each page on nextjs.org/docs
We welcome any community contributions to the documentation. A good place to get started is the "Good first issue label" on GitHub.