[v2] Support index.md filenames / IDs

[aeneasr]

🚀 Feature

Docusaurus v1 had a feature where creating an index.md file would generate an index.html file at the same, relative, directory path:

+ docs
   + getting-started
      + index.md (id: index)

generates

+ docs
   + getting-started
      + index.html

In v2, creating - using the docs plugin - an index.md file results in a structure of index/index.html.

+ docs
   + getting-started
      + index.md (id: index)

generates

+ docs
   + getting-started
      + index
        + index.html

This requires calling http://foo.bar/docs/getting-started/index or even http://foo.bar/docs/getting-started/index.html which is probably not intentional.

Have you read the Contributing Guidelines on issues?

yes

Motivation

Directory structure is important for SEO. Additionally, the index behavior is weird and (I think) unintentional as one ends up with urls like: http://foo.bar/docs/getting-started/index or http://foo.bar/docs/getting-started/index.html.

Pitch

I think Docusaurus v1 solved this correctly and this should be ported into v2 as well!

[yangshun]

Sure, we're open to this. But why don't you create getting-started.md instead?

[aeneasr]

Maybe getting-started was a bad example, let's take:

+ docs
  + index.md <- this one especially
  + sdks
    + index.md
    + golang.md
    + node.md
+ ...

[yangshun]

Makes sense 👍

[aeneasr]

I could try to help, although I would need pointers because I've never worked with docusaurus internals.

[aeneasr]

This becomes more acute when we run Docusaurus in "docs only" mode because we can't generate the index.html of the root directory. There's also #1973 which is a symptom of this issue IMO, but the proposed workaround #1973 (comment) does not work when using docs only mode!

[maximousblk]

A solution similar to vuepress would be nice. If the /docs directory has a README.md file it should be at foo.bar/docs/ and not foo.bar/docs/README. And in 'docs only' mode, The README.md contents should be displayed at foo.bar/. This would be only if there is a README.md file in the docs/ directory

[slorber]

This issue totally make sense, it will likely be implemented as part of the "sidebar category index" feature: #2643

[slorber]

Implemented as part of #5830

[slorber]

please test it in the latest canary and tell us if it works