From 3feebc0be691784f8931e0297fa19dc2edf6f1b7 Mon Sep 17 00:00:00 2001
From: Joe Pea <joe@trusktr.io>
Date: Sun, 22 Jan 2023 19:28:39 -0800
Subject: [PATCH 1/2] add notes on "hash" vs "history" routing in the config
 docs

---
 docs/configuration.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/configuration.md b/docs/configuration.md
index 61c3a9b3e..1949caf9a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -659,6 +659,8 @@ window.$docsify = {
 
 ## routerMode
 
+Configure the URL format that the paths of your site will use.
+
 - Type: `String`
 - Default: `'hash'`
 
@@ -668,6 +670,43 @@ window.$docsify = {
 };
 ```
 
+For statically-deployed sites (f.e. on GitHub Pages) hash-based routing is
+simpler to set up. For websites that can re-write URLs, the history-based format
+is better (especially for search-engine optimization, hash-based routing is not
+so search-engine friendly)
+
+Hash-based routing means all URL paths will be prefixed with `/#/` in the
+address bar. This is a trick that allows the site to load `/index.html`, then it
+uses the path that follows the `#` to determine what markdown files to load. For
+example, a complete hash-based URL may look like this:
+`https://example.com/#/path/to/page`. The browser will actually load
+`https://example.com` (assuming your static server serves
+`index.html` by default, as most do), and then the Docsify JavaScript code will
+look at the `/#/...` and determine the markdown file to load and render.
+Additionally, when clicking on a link, the Docsify router will change the
+content after the hash dynamically. The value of `location.pathname` will still be
+`/` no matter what. The parts of a hash path are _not_ sent to the server when
+visiting such a URL in a browser.
+
+On the other hand, history-based routing means the Docsify JavaScript will use
+the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API)
+to dynamically change the URL without using a `#`. This means that all URLs will
+be considered "real" by search engines, and the full path will be sent to the
+server when visiting the URL in your browser. For example, a URL may look like
+`https://example.com/path/to/page`. The browser will try to load that full URL
+directly from the server, not just `https://example.com`. The upside of this is
+that these types of URLs are much more friendly for search engines, and can be
+indexed (yay!). The downside, however, is that your server, or the place where
+you host your site files, has to be able to handle these URLs. Various static
+website hosting services allow "rewrite rules" to be configured, such that a
+server can be configured to always send back `/index.html` no matter what path
+is visited. The value of `location.pathname` will show `/path/to/page`, because
+it was actually sent to the server.
+
+TLDR: start with `hash` routing (the default). If you feel adventurous, learn
+how to configure a server, then switch to `history` mode for better experience
+without the `#` in the URL and SEO optimization.
+
 ## routes
 
 - Type: `Object`

From e07060ad14c6c3b2711e97a888526be77aa57870 Mon Sep 17 00:00:00 2001
From: Joe Pea <joe@trusktr.io>
Date: Sun, 22 Jan 2023 19:41:26 -0800
Subject: [PATCH 2/2] add a note about making an `alias` for `_sidebar.md` when
 using `routerMode: 'history'`

---
 docs/configuration.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/configuration.md b/docs/configuration.md
index 1949caf9a..4b238da76 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -44,11 +44,16 @@ window.$docsify = {
     '/zh-cn/changelog': '/changelog',
     '/changelog':
       'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
+
+    // You may need this if you use routerMode:'history'.
     '/.*/_sidebar.md': '/_sidebar.md', // See #301
   },
 };
 ```
 
+> **Note** If you change [`routerMode`](#routermode) to `'history'`, you may
+> want to configure an alias for your `_sidebar.md` and `_navbar.md` files.
+
 ## auto2top
 
 - Type: `Boolean`
@@ -707,6 +712,20 @@ TLDR: start with `hash` routing (the default). If you feel adventurous, learn
 how to configure a server, then switch to `history` mode for better experience
 without the `#` in the URL and SEO optimization.
 
+> **Note** If you use `routerMode: 'history'`, you may want to add an
+> [`alias`](#alias) to make your `_sidebar.md` and `_navbar.md` files always be
+> loaded no matter which path is being visited.
+>
+> ```js
+> window.$docsify = {
+>   routerMode: 'history',
+>   alias: {
+>     '/.*/_sidebar.md': '/_sidebar.md',
+>     '/.*/_navbar.md': '/_navbar.md',
+>   },
+> };
+> ```
+
 ## routes
 
 - Type: `Object`