docs: add next.js example for the rule folder-naming-convention

* add next.js example

* update the README file with the new pattern

* merge all info regarding the new pattern

* remove redundant newline

Author: milos-sikic-nimbus-tech

docs/rules/folder-naming-convention.md

@@ -8,9 +8,7 @@ This rule aims to format the name of the specified folder. This rule uses the gl
 
 There are six basic naming conventions built into this rule, including `CAMEL_CASE`, `PASCAL_CASE`, `SNAKE_CASE`, `KEBAB_CASE`, `SCREAMING_SNAKE_CASE` and `FLAT_CASE`.
 
-**Additionally, there is a naming convention called `NEXT_JS_APP_ROUTER_CASE` used to format folder names in Next.js projects that used App Router.** `NEXT_JS_APP_ROUTER_CASE` aims to support a wide range of named constructs in Next.js App Router projects, including Standard routes, Dynamic segments, Catch-all segments, Optional Catch-all Segments, Route groups, and Named slots.
-
-While `NEXT_JS_APP_ROUTER_CASE` covers many naming cases, it's possible that some cases may be missing. If you come across any missing cases, I encourage you to open an issue and provide the necessary details. Your feedback will help me improve and enhance the naming convention.
+Additionally, there is a naming convention called `NEXT_JS_APP_ROUTER_CASE` used to format folder names in Next.js projects that use the App Router. You can read more about it under [Built-in custom patterns](#built-in-custom-patterns).
 
 | Formatting  | Name                   |
 | ----------- | ---------------------- |
@@ -43,6 +41,8 @@ Examples of **correct** folder name for this rule:
 src/components/displayLabel/displayLabel.js
 ```
 
+## Custom patterns
+
 In addition to the built-in naming conventions, you can also set custom naming patterns using glob match syntax. The following code shows an example of how to ensure that all the folders under the `components` folder are named begin with `__`:
 
 ```js
@@ -53,6 +53,40 @@ In addition to the built-in naming conventions, you can also set custom naming p
 
 **Tip:** To exclude `__tests__` folder in `src`, use the glob expression `src/!(__tests__)/**/` to get the target folders.
 
+## Built-in custom patterns
+
+Some patterns are complex enough that they warrant their own definition within the lib.
+
+### Next.js custom pattern
+
+The `NEXT_JS_APP_ROUTER_CASE` aims to support a wide range of named constructs in Next.js App Router projects.
+
+If you would like to enforce a kebab-case naming convention for your folders, but also support Next.js' Standard routes, Dynamic segments, Catch-all segments, Optional Catch-all Segments, Route groups, and Named slots, this pattern is for you.
+
+When using the pattern, all your folders need to be kebab-cased, but you can also do dynamic segments with camel case, so that it flows more natural with the code, i.e.
+
+```
+/src/app/help-pages/[pageId]
+```
+
+This is powerful because it allows you to have consistent link names, i.e. the links will be kebab cased, which is the most natural way of naming URL path segments.
+
+But when you get in code and the dynamic segment needs to be passed to your component, you'll have a camel cased variable, i.e.
+
+```
+// /src/app/help-pages/[pageId]/page.tsx
+
+// If we have named our parameter "page-id", then you'd get "page-id" inside of
+// the params object, and you'd have to escape it, which would look nasty
+export const Page({ params: { pageId } }) { ... }
+```
+
+Besides this, the custom pattern should support all other Next.js naming conventions.
+
+You can read more about them [here](https://github.com/DukeLuo/eslint-plugin-check-file/pull/27#issuecomment-1582551071).
+
+While `NEXT_JS_APP_ROUTER_CASE` covers many naming cases, it's possible that some cases may be missing. If you come across any missing cases, I encourage you to open an issue and provide the necessary details. Your feedback will help me improve and enhance the naming convention.
+
 ### Options
 
 #### naming pattern object