next.js : dynamic site sections with just one javascript module

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

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.