next.js has become a very simple and quiet tool to build showcase sites or documentation pages.
The contract for writing pages only consists in writing ecmascript modules, which is widely accepted granularity in many node.js frameworks today.
The next.js configuration almost resides entirely in the root directory, and you only have a few things that you have to pull from the code itself (next/link to create a hyperlink, or next/image to incorporate an image).
It is quite flexible, but when it comes to automatically index content (just like you would with gatsby.js), it comes at the price of writing some boilerplate code.
Indeed, next.js by default is not designed to automatically scan blog posts or documentation sections by itself.
Usually you would use a sidebar.js file or a manual index of the site by yourself.
…How boring…
Fortunately, there is another way to do that without maintaining the links.
Create a directory called [part] (keep the brackets in the name) and immediately inside create a file called [page].tsx .
In this file, copy the content of that gist :
https://gist.github.com/libetl/829636e98b8fcd923f0130d075d8194f
Then go to line 219 and choose the directory names to include, these directories should only contain .md or .mdx files (markdown or markdown + react).
Most important and last step, add your content in each directory that you have specified in line 219,
example :
--- id: BlogPosts linkName: blog-posts name: Blog Posts part: wiki section: Reference --- We use blog posts primarily to alert users of upcoming breaking changes, but also for other important announcements. ## Setup: *Remember to follow similar naming conventions as other files/entries* - Create a new file in `./blog/`. For example: `2020-09-01-my-blog-post.md` - Navigate to `https://localhost/blog/2020-09-01-my-blog-post`. This page will auto reflect your changes on save (via HMR) ## Writing your blog: You can always take direction from previous examples, but this should work as a general guideline: - Make sure to include the heading: ``` --- id: BlogPosts linkName: blog-posts name: Blog Posts author: John doe part: blog date: September 1, 2020 --- ``` - Follow a structure and use examples via codeblocks: - Explain the problem and the solution - Explain the current implementation (with examples) - Explain the new implementation (with the breaking change example) - Conclusion
That is it, you can run your next.js project as a documentation site.
If you want to go further and use more elegant styles, change the tagging in the components object that is located in [page].tsx