feat(v2): allow home page for docs (#2652)

* feat(v2): allow home page for docs

* Refactor

* Remove debugging info 🤦‍♂️

* Add sort routes for first test case

* Sort child routes for consistency

website/docs/docs.md

@@ -29,6 +29,42 @@ id: part1
 Lorem ipsum
 ```
 
+## Home page docs
+
+Using the `homePageId` property, you can create a home page of your docs. To do this, you can create a new document, especially for this purpose with the id as `_index`, or you could specify an existing document id.
+
+```js {8} title="docusaurus.config.js"
+module.exports = {
+  // ...
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          homePageId: 'getting-started', // Defaults to `_index`
+          // ...
+        },
+      },
+    ],
+  ],
+  // ...
+};
+```
+
+Given the example above, now when you navigate to the path `/docs` you will see that the document content with id is `getting-started`. This functionality also works for docs with versioning enabled.
+
+:::important
+
+The document id of `_index` is reserved exclusively for the home doc page, so it will not work as a standalone route.
+
+:::
+
+:::note
+
+The page `docs` that you created (eg. `src/pages/docs.js`)  will take precedence over the route generated via the `homePageId` option.
+
+:::
+
 ## Sidebar
 
 To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
@@ -258,11 +294,17 @@ module.exports = {
 
 ## Docs-only mode
 
-If you just want the documentation feature, you can follow the instructions for a "docs-only mode":
+If you just want the documentation feature, you can enable "docs-only mode".
 
-1. Set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site:
+To achieve this, set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site, and also in that object set the `homePageId` property with the value of the document ID that you show as root of the docs.
 
-```js {8} title="docusaurus.config.js"
+:::note
+
+More details on functionality of home page for docs can be found in [appropriate section](#home-page-docs).
+
+:::
+
+```js {8-9} title="docusaurus.config.js"
 module.exports = {
   // ...
   presets: [
@@ -271,6 +313,7 @@ module.exports = {
       {
         docs: {
           routeBasePath: '/', // Set this value to '/'.
+          homePageId: 'getting-started', // Set to existing document id.
           // ...
         },
       },
@@ -280,21 +323,6 @@ module.exports = {
 };
 ```
 
-2. Set up a redirect to the initial document on the home page in `/src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs.
-
-```jsx title="src/pages/index.js"
-import React from 'react';
-
-import {Redirect} from '@docusaurus/router';
-import useBaseUrl from '@docusaurus/useBaseUrl';
-
-function Home() {
-  return <Redirect to={useBaseUrl('/getting-started')} />;
-}
-
-export default Home;
-```
-
 Now, when visiting your site, it will show your initial document instead of a landing page.
 
 :::tip

website/docs/lifecycle-apis.md

@@ -52,6 +52,10 @@ module.exports = function (context, options) {
 
 Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data (optional).
 
+## `async routesLoaded(routes)`
+
+Plugins can modify the routes that were generated by all plugins. `routesLoaded` is called after `contentLoaded` hook.
+
 ### `content`
 
 `contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`.
@@ -373,6 +377,11 @@ module.exports = function (context, opts) {
       // actions are set of functional API provided by Docusaurus. e.g: addRoute
     },
 
+    async routesLoaded(routes) {
+      // routesLoaded hook is done after contentLoaded hook is done
+      // This can be useful if you need to change any route.
+    },
+
     async postBuild(props) {
       // after docusaurus <build> finish
     },

website/docs/using-plugins.md

@@ -236,6 +236,7 @@ module.exports = {
          * do not include trailing slash
          */
         routeBasePath: 'docs',
+        homePageId: '_index', // Document id for docs home page.
         include: ['**/*.md', '**/*.mdx'], // Extensions to include.
         /**
          * Path to sidebar configuration for showing a list of markdown pages.