feat: change Vue router's mode from "hash" to "history" to support search engine indexing

giladgd · giladgd · commit ec15d517d2e8 · 2022-03-24T23:36:52.000+02:00
In order to support loading a deep url without getting a 404 error, a custom 404.html page is implemented to redirect back to index.html which uses history api to load the original url without a refresh. Based on typeorm#36
diff --git a/404.html b/404.html
@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en" data-framework="typescript">
+<head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <script>
+        // since the site is a single page application,
+        // replace the current url to point to index.html with the entire path as a query property
+        // so index.html could put the path back into the current url wia the history api
+        window.location.replace(
+            window.location.origin + "/?path=" + encodeURIComponent(window.location.href.substring(window.location.origin.length))
+        );
+    </script>
+
+    <link rel="apple-touch-icon" sizes="180x180" href="image/favicon/apple-touch-icon.png">
+    <link rel="icon" type="image/png" sizes="32x32" href="image/favicon/favicon-32x32.png">
+    <link rel="icon" type="image/png" sizes="16x16" href="image/favicon/favicon-16x16.png">
+    <link rel="manifest" href="image/favicon/manifest.json">
+    <link rel="mask-icon" href="image/favicon/safari-pinned-tab.svg" color="#666666">
+    <meta name="theme-color" content="#ffffff">
+    <title>
+        TypeORM - Amazing ORM for TypeScript and JavaScript (ES7, ES6, ES5). Supports MySQL, PostgreSQL, MariaDB, SQLite, MS SQL Server, Oracle, WebSQL databases. Works in NodeJS, Browser, Ionic, Cordova and Electron platforms.
+    </title>
+</head>
+<body>
+</body>
+</html>
diff --git a/index.html b/index.html
@@ -5,6 +5,14 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
 
+    <script>
+        // if the current page was redirected from 404.html, put the path back in the url via the history api
+        if (window.location.href.substring(window.location.origin.length).startsWith("/?path="))
+            window.history.replaceState(null, document.title, window.location.origin + decodeURIComponent(
+                window.location.href.substring(window.location.origin.length + "/?path=".length)
+            ));
+    </script>
+
     <link rel="stylesheet"
           href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.1/css/bootstrap.min.css"
           integrity="sha384-WskhaSGFgHYWDcbwN70/dfYBj47jz9qbsMId/iRN3ewGhXQFZCSftd1LZCfmhktB"
diff --git a/script/component/DocumentPage.js b/script/component/DocumentPage.js
@@ -1,7 +1,7 @@
 const DocumentPage = {
     template: `
 <div class="document">
-    <markdown-reader :file="readUrl" :fragment="fragment"></markdown-reader>
+    <markdown-reader :file="readUrl" :hash="hash"></markdown-reader>
     
     <div class="contribute small">
         {{$t("contribute")}} <a :href="editUrl">{{$t("edit")}}</a>
@@ -11,7 +11,7 @@ const DocumentPage = {
     data: function() {
         return {
             document: this.$route.params.document,
-            fragment: this.$route.params.fragment,
+            hash: this.$route.hash,
             locale: $cookies.get("locale") || "en",
             readLink: "https://raw.githubusercontent.com/typeorm/typeorm/master/",
             editLink: "https://github.com/typeorm/typeorm/edit/master/"
@@ -20,7 +20,7 @@ const DocumentPage = {
     watch: {
         '$route': function(to, from) {
             this.document = to.params.document;
-            this.fragment = to.params.fragment;
+            this.hash = to.hash;
             this.updateTitle();
         }
     },
@@ -58,4 +58,4 @@ const DocumentPage = {
             }
         }
     }
-};
+};
diff --git a/script/component/MarkdownReader.js b/script/component/MarkdownReader.js
@@ -1,6 +1,6 @@
 const MarkdownReader = {
     template: `<div v-html="html"></div>`,
-    props: ["file", "fragment"],
+    props: ["file", "hash"],
     data: function() {
         return {
             html: "",
@@ -12,27 +12,31 @@ const MarkdownReader = {
             this.setDocument();
             this.loadFile(file)
                 .then(() => {
-                    this.scrollToFragment(this.fragment);
+                    this.scrollToHash(this.hash);
                 });
         },
-        'fragment': function(fragment) {
-            this.scrollToFragment(fragment);
+        'hash': function(hash) {
+            this.scrollToHash(hash);
         }
     },
     created: function () {
         this.setDocument();
         this.loadFile(this.file)
             .then(() => {
-                this.scrollToFragment(this.fragment);
+                this.scrollToHash(this.hash);
             });
     },
     methods: {
-        scrollToFragment: function(fragment) {
-            const fragmentElement = document.getElementById(fragment);
-            if (fragmentElement)
-                fragmentElement.scrollIntoView();
-            else
-                window.scrollTo(0, 0);
+        scrollToHash: function(hash) {
+            if (hash) {
+                const fragmentElement = document.getElementById(hash.substring("#".length));
+                if (fragmentElement) {
+                    fragmentElement.scrollIntoView();
+                    return;
+                }
+            }
+
+            window.scrollTo(0, 0);
         },
         setDocument: function () {
             if(this.$route.params.document) {
@@ -51,7 +55,7 @@ const MarkdownReader = {
 
                     showdown.extension('header-anchors', () => {
 
-                        var ancTpl = '$1<a id="user-content-$3" class="anchor" href="#' + this.$route.params.document + '/$3" aria-hidden="true">#</a> $4';
+                        var ancTpl = '$1<a id="user-content-$3" class="anchor" href="#$3" aria-hidden="true">#</a> $4';
 
                         return [{
                             type: "html",
@@ -64,15 +68,15 @@ const MarkdownReader = {
                         return [{
                             type: "html",
                             regex: /<a href="#(.*)">/g,
-                            replace: "<a href='#/" + this.document + "/$1'>"
+                            replace: "<a href='/" + this.document + "#$1'>"
                         }];
                     });
 
                     showdown.extension('other-page-links-replacer', () => {
                         return [{
                             type: "html",
                             regex: /<a href="\.?\/?(docs\/)?(.*?)\.md\#?(.*?)">/g,
-                            replace: "<a href='#/$2/$3'>"
+                            replace: "<a href='/$2#$3'>"
                         }];
                     });
 
diff --git a/script/index.js b/script/index.js
@@ -11,14 +11,30 @@ const i18n = new VueI18n({
   messages // set locale messages
 })
 
+const router = new VueRouter({
+  mode: "history",
+  routes: [
+    { path: "/:document?/:fragment?", component: DocumentPage },
+  ]
+});
+
+// Because the documentation previously used "hash" mode in the Router, paths
+// starting with a hash will be redirected to prevent breaking old permalinks.
+router.beforeEach((to, from, next) => {
+  if (to.fullPath.startsWith("/#/")) {
+    // Remove leading hash and replace following slash with hash.
+    // Before: https://typeorm.io/#/entities/entity-columns
+    // After:  https://typeorm.io/entities#entity-columns
+    const path = "/" + to.fullPath.substring("/#/".length).replace("/", "#");
+    next(path);
+  } else
+    next();
+});
+
 new Vue({
   el: "#app",
   i18n,
-  router: new VueRouter({
-    routes: [
-      { path: "/:document?/:fragment?", component: DocumentPage },
-    ]
-  }),
+  router: router,
   components: {
     "main-page": MainPage,
     "markdown-reader": MarkdownReader,
@@ -27,4 +43,4 @@ new Vue({
     i18n.locale = $cookies.get("locale") || "en";
     document.title = this.$t("title");
   }
-});
+});
