Feature: Organizing Files

[yousinix]

Currently there's no way to put files in a directory for organization purposes without it affecting the href of that page.

For example, if you want to put all your root tab's files under one directory, to separate it from other tabs, that won't be possible.

It will be great to have something like Route Groups from NextJS, which allows more flexibility.

Approaches

Given the following directory structure, the docs.json can have different possible configuration to enable such a feature.

docs/
  (root)/
    index.mdx
    guides/
      quick-start.mdx

Approach I: path Property

Then a path property would be needed in docs.json if the href is different than the location of the file. This allows full-flexibility (i.e. the href can be totally cha, but on the other hand it's also a bit verbose.

{
  "sidebar": [
    {
      "tab": "root",
      "pages": [
        {
          "title": "Introduction",
          "path": "/(root)/index.mdx", // or "/(root)/"
          "href": "/"
        },
        {
          "title": "Quick Start",
          "path": "/(root)/guides/quick-start.mdx",
          "href": "/guides/foo" // can also be used to fully customize URLs
        }
      ]
    }
  ]
}

Pros	Cons
More flexible, as href can be changed to something other than the file name	More verbose

Approach II: Resolving Paths

Instead of forcing the user to manually type the path and href, they can just use the existing syntax, but the href path resolution will change.

This means that the href of /guides/quick-start can be located in any of the following files:

1. docs/guides/quick-start.mdx
2. docs/guides/quick-start/index.mdx
3. docs/(**)/guides/quick-start.mdx
4. docs/(**)/(**)/guides/quick-start.mdx
5. docs/(**)/(**)/guides/(**)/quick-start.mdx

Pros	Cons
Backwards compatible	Possible resolution conflicts, in case two groups have the same path
Less verbose