From 3feebc0be691784f8931e0297fa19dc2edf6f1b7 Mon Sep 17 00:00:00 2001 From: Joe Pea Date: Sun, 22 Jan 2023 19:28:39 -0800 Subject: [PATCH 1/4] 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 61c3a9b3..1949caf9 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 Date: Sun, 22 Jan 2023 19:41:26 -0800 Subject: [PATCH 2/4] 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 1949caf9..4b238da7 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` From aaf55d3fa0e2d19d1d883aec9c75e927b533631e Mon Sep 17 00:00:00 2001 From: Paul Hibbitts Date: Tue, 11 Jul 2023 10:12:32 -0700 Subject: [PATCH 3/4] Update README.md Removed archived/old similar projects and replaced with more current/popular projects. --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c06b68f7..45941bbd 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,10 @@ Move to [awesome-docsify](https://github.com/docsifyjs/awesome-docsify#showcase) | Project | Description | | ------------------------------------------------ | ---------------------------------------- | -| [docute](https://github.com/egoist/docute) | 📜 Effortlessly documentation done right | -| [docpress](https://github.com/docpress/docpress) | Documentation website generator | +| [Docusaurus](https://docusaurus.io) | Docusaurus makes it easy to maintain Open Source documentation websites | +| [GitBook](https://www.gitbook.com) | Where technical teams document | +| [MkDocs](https://www.mkdocs.org) | Project documentation with Markdown | +| [VuePress](https://vuepress.vuejs.org) | Vue-powered Static Site Generator | ## Contributing From a69c22ac79f117f091fcfc96c46dc440ef151e48 Mon Sep 17 00:00:00 2001 From: Lu Fei <52o@qq52o.cn> Date: Fri, 14 Jul 2023 00:54:56 +0800 Subject: [PATCH 4/4] chore: remove codesandbox (#2130) --- .codesandbox/ci.json | 5 ----- sandbox.config.json | 4 ---- 2 files changed, 9 deletions(-) delete mode 100644 .codesandbox/ci.json delete mode 100644 sandbox.config.json diff --git a/.codesandbox/ci.json b/.codesandbox/ci.json deleted file mode 100644 index 7dd5f76d..00000000 --- a/.codesandbox/ci.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "sandboxes": ["2d17z"], - "packages": ["."], - "node": "16" -} diff --git a/sandbox.config.json b/sandbox.config.json deleted file mode 100644 index 8b8a95b7..00000000 --- a/sandbox.config.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "template": "node", - "node": "16" -}