docs: elaborate on "docs-only" and "blog-only" (#6131)

* rephrased documentation

* Rewording

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

website/docs/blog.mdx

@@ -328,7 +328,7 @@ authors:
 The configuration file can be localized, just create a localized copy of it at:
 
 ```bash
-website/i18n/<locale>/docusaurus-plugin-content-blog/authors.yml
+website/i18n/{{locale}}/docusaurus-plugin-content-blog/authors.yml
 ```
 
 </details>
@@ -522,19 +522,21 @@ https://example.com/blog/feed.json
 
 ### Blog-only mode {#blog-only-mode}
 
-You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.
+You can run your Docusaurus 2 site without a dedicated landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to serve the blog through the root route `example.com/` instead of the subroute `example.com/blog/`.
 
-```js {10} title="docusaurus.config.js"
+```js title="docusaurus.config.js"
 module.exports = {
   // ...
   presets: [
     [
       '@docusaurus/preset-classic',
       {
-        docs: false,
+        // highlight-next-line
+        docs: false, // Optional: disable the docs plugin
         blog: {
-          path: './blog',
+          // highlight-next-line
-          routeBasePath: '/', // Set this value to '/'.
+          routeBasePath: '/', // Serve the blog at the site's root
+          /* other blog options */
         },
       },
     ],
@@ -548,6 +550,12 @@ Don't forget to delete the existing homepage at `./src/pages/index.js` or else t
 
 :::
 
+:::tip
+
+There's also a "Docs-only mode" for those who only want to use the docs. Read [Docs-only mode](./guides/docs/docs-introduction.md) for detailed instructions or a more elaborated explanation of `routeBasePath`.
+
+:::
+
 ### Multiple blogs {#multiple-blogs}
 
 By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`.

website/docs/guides/docs/docs-introduction.md

@@ -22,7 +22,7 @@ For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/he
 ```bash
 website # Root directory of your site
 └── docs
-   ├── greeting.md
+   ├── greeting.md
    └── guide
       └── hello.md
 ```
@@ -69,16 +69,89 @@ Lorem ipsum
 
 ## Docs-only mode {#docs-only-mode}
 
-If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.
+A freshly initialized Docusaurus site has the following structure:
 
-To enable docs-only mode, set the docs plugin `routeBasePath: '/'`, and use the frontmatter `slug: /` on the document that should be the index page ([more info](#home-page-docs)).
+```
+example.com/                                -> generated from `src/pages/index.js`
+
+example.com/docs/intro                      -> generated from `docs/intro.md`
+example.com/docs/tutorial-basics/...        -> generated from `docs/tutorial-basics/...`
+...
+
+example.com/blog/2021/08/26/welcome         -> generated from `blog/2021-08-26-welcome/index.md`
+example.com/blog/2021/08/01/mdx-blog-post   -> generated from `blog/2021-08-01-mdx-blog-post.mdx`
+...
+```
+
+All docs will be served under the subroute `docs/`. But what if **your site only has docs**, or you want to prioritize your docs by putting it at the root?
+
+Assume that you have the following in your configuration:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  // ...
+  presets: [
+    '@docusaurus/preset-classic',
+    {
+      docs: {
+        /* docs plugin options */
+      },
+      blog: {
+        /* blog plugin options */
+      },
+      // ...
+    },
+  ],
+};
+```
+
+To enter docs-only mode, change it to like this:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  // ...
+  presets: [
+    '@docusaurus/preset-classic',
+    {
+      docs: {
+        // highlight-next-line
+        routeBasePath: '/', // Serve the docs at the site's root
+        /* other docs plugin options */
+      },
+      // highlight-next-line
+      blog: false, // Optional: disable the blog plugin
+      // ...
+    },
+  ],
+};
+```
+
+Note that you **don't necessarily have to give up on using blog** or other plugins; all that `routeBasePath: '/'` does is that instead of serving the docs through `https://example.com/docs/some-doc`, they are now at the site root: `https://example.com/some-doc`. The blog, if enabled, can still be accessed through the `blog/` subroute.
+
+Don't forget to put some page at the root (`https://example.com/`) through adding the front matter:
+
+```yml title="docs/intro.md"
+---
+# highlight-next-line
+slug: /
+---
+This page will be the home page when users visit https://example.com/.
+```
 
 :::caution
 
-You should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
+If you added `slug: /` to a doc to make it the homepage, you should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
 
 :::
 
+Now, the site's structure will be like the following:
+
+```
+example.com/                       -> generated from `docs/intro.md`
+example.com/tutorial-basics/...    -> generated from `docs/tutorial-basics/...`
+...
+```
+
 :::tip
 
 There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).