Docusaurus: [V2] Handle /docs route

[jamiedavenport]

🚀 Feature

Currently navigating to /docs will result in a not found page being shown (unless pages/docs/index exists). I'm proposing that we handle this gracefully by redirecting to the first doc page.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

Showing a not found page isn't very helpful to a user that's likely searching for the documentation.

In most cases, I can imagine the user wanting to be redirected to valid documentation.

Pitch

• Better UX for the end-user.
• Can link to /docs instead of a specific page which allows us to change or remove that page without breaking the links.
• Looking at the existing V2 showcase, they all link to the first page of docs anyway.

If we agree on a solution, I'd also be happy to implement it and open a PR.

[endiliey]

Determining the first “docs page” is very confusing. We allow multiple sidebar or no sidebar at all. How do we know which one is the first doc page ? Do we sort by alphabet ? Or do we sort by first item in sidebar ? If there is sidebar A and sidebar B, which one to choose ? What if user doesnt have a sidebar ? (not all doc site has sidebar)

Some people might want their own custom docs page using “src/pages/docs/index.js” as well. With that, you can also create a redirect to the right page.

Or if you prefer 301 html redirect, create a docs/index.html in static folder

[endiliey]

Check https://docusaurus.io/ itself

There are Docs and Tutorial Section in headerlinks. Both have different sidebars. If i go to /docs, how do we know which one to choose ?

More problems go even more when versioning and translation came in. Do we go to /docs/en or /docs/ko or /docs/en/next or /docs/en/1.0.0 ?

The best solution is still creating your own “src/pages/docs/index.js” which is very flexible and let user decide

[lex111]

Some people might want their own custom docs page using “src/pages/docs/index.js” as well. With that, you can also create a redirect to the right page.

LGTM, maybe we should even reflect it in docs.

[binarylogic]

There are Docs and Tutorial Section in headerlinks. Both have different sidebars. If i go to /docs, how do we know which one to choose ?

Re-iterating my comment here: https://github.com/facebook/docusaurus/issues/1941#issuecomment-550393562. I don't know how many people are actually doing this beyond the Docusaurus site. Moreover, it deviates from the URL structure. The navbar is representing top-level categories but the URL structure is not the same. As mentioned in my comment, it would be better to support drop-down items under "Docs". Infima appears to support this.

[binarylogic]

Oh, and as a work around we did the following:

Add a src/pages/docs.js file with the following contents:

import React from 'react';
import {Redirect} from '@docusaurus/router';
function Docs() {
  return <Redirect to="/docs/my-doc" />;
}
export default Docs;

[yangshun]

Maybe there can be a new config option for docusaurus-plugin-docs to redirect/render a specific page when /<routeBasePath> is accessed. WDYT?

[binarylogic]

That makes sense. My above work around works well for now. You can also setup a redirect with your host (Netlify).

[jamiedavenport]

@yangshun Is there a benefit to having a config option for this over implementing a src/pages/docs.js page?

What about a combination of documentation and a default docs.js page in the template as the solution?

[aeneasr]

The proposed workaround does not work when using docs only mode. The missing index.md feature also affects subdirectories - see #2537