Refine index.md handling

[gossi]

Is your feature request related to a problem? Please describe.

We have no control over how our links are shared, precisly whether they contain a trailing slash or not. However, for vitepress this is vital in finding the correct page or throwing a 404 not found error.

Here is a sample file structure:

/docs
|- topic.md
`- /topic
   |- subpage1.md
   `- subpage2.md

Which will give these links:

• /topic
• /topic/subpage1

But organization wise, I have a disconnect between the folder and the "index" page. I'd rather would like to keep it organized like this:

/docs
`- /topic
   |- index.md
   |- subpage1.md
   `- subpage2.md

that does work as of today, but will generate these links:

• /topic/ (note the trailing slash)
• /topic/subpage1

Problem here, if I access /topic, this is a 404 - which is the problem, when sharing links and remove those trailing slashes. Also for me, this is somewhat an aesthetic thing to drop off the trailing slash (maybe for others, too) - and I realized I do truncate trailing slashes when sharing links 😅

---

Advanced problem:

I'll make another topic, that shares the same name, let's say topic-advanced. Also with its own folder:

/docs
|- topic-advanced.md
`- /topic-advanced
   |- subpage1.md
   `- subpage2.md

Here the problem lies somewhere else, this is when and how to match the active link in the nav, like with this theme config:

{
  nav: [
    { text: 'Topic', link: '/topic', activeMatch: '/topic' },
    { text: 'Topic Advanced', link: '/topic-advanced', activeMatch: '/topic-advanced' },
  ]
}

Now, when I navigate to /topic-advanced both links are matched active. When both activeMatch take a trailing slash, then neither of these "index" pages is matched active, but all their subpages.

Describe the solution you'd like

Allow to organize your files logically consistent in one folder:

/docs
`- /topic
   |- index.md
   |- subpage1.md
   `- subpage2.md

--- OR ---

# keep it readable on github
/docs
`- /topic
   |- README.md
   |- subpage1.md
   `- subpage2.md

Give index.md (or README.md) of these folders some attention. I could imagine a cleanUrls option, to handle this - and also an option, which file to consider as "index".

---

About the activeMatch: As I read up, regex is not an option here. I'm not sure, whether this is matched against URL or file path? In any case, would make sense to provide more fine graind control: activeMatchFile and activeMatchURL - though I'm not sure whether this is a good design, shooting from the hip right now.

Describe alternatives you've considered

No response

Additional context

No response

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[brc-dd]

With cleanUrls: 'without-subfolders':

/docs
`- /topic
   |- index.md
   |- subpage1.md
   `- subpage2.md

will generate /topic/, /topic/subpage1 as you wrote, but if someone writes /topic it will open the page too (in production, there might be hydration errors if your server doesn't check for /topic/index.html as a fallback while serving /topic). Another caveat is if you have some relative links in that page, they will be broken as they are resolved by the browser. So, the recommended way is to just configure redirects wherever you've deployed your docs.

Third part of your question (specifying which file to consider as index) will be soon fixed by #1798.

Regarding activeMatch, it supports regex too IIRC, you just have to pass regex as string (the way you pass to Regexp constructor) as we need site data to be serializable.