add versions to all CDN link examples to prevent people from making websites that are at risk of breaking changes to Docsify, make it clear that the recommended approach is to use full versions in URLs, and fix formatting in any files that were modified

Author: trusktr

docs/cdn.md

@@ -1,48 +1,53 @@
 # CDN
 
-Recommended: [jsDelivr](//cdn.jsdelivr.net), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [cdn.jsdelivr.net/npm/docsify/](//cdn.jsdelivr.net/npm/docsify/).
+Recommended: [jsDelivr](//cdn.jsdelivr.net). You can also browse the source of the npm package at [cdn.jsdelivr.net/npm/docsify/](//cdn.jsdelivr.net/npm/docsify/).
 
-## Latest version
+## Specific version (RECOMMENDED)
 
 ```html
 <!-- load css -->
-<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
+<link
+  rel="stylesheet"
+  href="//cdn.jsdelivr.net/npm/[email protected]/lib/themes/vue.css"
+/>
 
 <!-- load script -->
-<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/docsify.min.js"></script>
 ```
 
-Alternatively, use [compressed files](#compressed-file).
+## Latest version (_NOT_ RECOMMENDED!)
 
-## Specific version
+We highly recommend you do **not** use this method.
 
-```html
-<!-- load css -->
-<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/[email protected]/themes/vue.css">
-
-<!-- load script -->
-<script src="//cdn.jsdelivr.net/npm/[email protected]/lib/docsify.js"></script>
-```
-
-## Compressed file
+Using the latest version can break your app when docsify is updated due to
+breaking changes, either when accidental bugs are introduced, or when a new
+major version is realeased with altered features.
 
 ```html
 <!-- load css -->
-<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
+<link
+  rel="stylesheet"
+  href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css"
+/>
 
 <!-- load script -->
 <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
 ```
 
+## Uncompressed files for debugging
+
 ```html
 <!-- load css -->
-<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/[email protected]/lib/themes/vue.css">
+<link
+  rel="stylesheet"
+  href="//cdn.jsdelivr.net/npm/[email protected]/themes/vue.css"
+/>
 
 <!-- load script -->
-<script src="//cdn.jsdelivr.net/npm/docsify@4.10.2/lib/docsify.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/docsify.js"></script>
 ```
 
-## Other CDN
+## Other CDNs
 
 - https://www.bootcdn.cn/docsify/
 - https://cdn.jsdelivr.net/npm/docsify/

docs/cover.md

@@ -11,10 +11,10 @@ Set `coverpage` to **true**, and create a `_coverpage.md`:
 
 <script>
   window.$docsify = {
-    coverpage: true
-  }
+    coverpage: true,
+  };
 </script>
-<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/docsify.min.js"></script>
 ```
 
 ```markdown
@@ -81,7 +81,7 @@ Now, you can set
 
 ```js
 window.$docsify = {
-  coverpage: ['/', '/zh-cn/']
+  coverpage: ['/', '/zh-cn/'],
 };
 ```
 
@@ -91,7 +91,7 @@ Or a special file name
 window.$docsify = {
   coverpage: {
     '/': 'cover.md',
-    '/zh-cn/': 'cover.md'
-  }
+    '/zh-cn/': 'cover.md',
+  },
 };
 ```

docs/custom-navbar.md

@@ -27,17 +27,17 @@ Alternatively, you can create a custom markdown-based navigation file by setting
 
 <script>
   window.$docsify = {
-    loadNavbar: true
-  }
+    loadNavbar: true,
+  };
 </script>
-<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/docsify.min.js"></script>
 ```
 
 ```markdown
 <!-- _navbar.md -->
 
-* [En](/)
-* [chinese](/zh-cn/)
+- [En](/)
+- [chinese](/zh-cn/)
 ```
 
 !> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore.
@@ -51,19 +51,19 @@ You can create sub-lists by indenting items that are under a certain parent.
 ```markdown
 <!-- _navbar.md -->
 
-* Getting started
+- Getting started
 
-  * [Quick start](quickstart.md)
-  * [Writing more pages](more-pages.md)
-  * [Custom navbar](custom-navbar.md)
-  * [Cover page](cover.md)
+  - [Quick start](quickstart.md)
+  - [Writing more pages](more-pages.md)
+  - [Custom navbar](custom-navbar.md)
+  - [Cover page](cover.md)
 
-* Configuration
-  * [Configuration](configuration.md)
-  * [Themes](themes.md)
-  * [Using plugins](plugins.md)
-  * [Markdown configuration](markdown.md)
-  * [Language highlight](language-highlight.md)
+- Configuration
+  - [Configuration](configuration.md)
+  - [Themes](themes.md)
+  - [Using plugins](plugins.md)
+  - [Markdown configuration](markdown.md)
+  - [Language highlight](language-highlight.md)
 ```
 
 renders as
@@ -80,17 +80,17 @@ If you use the [emoji plugin](plugins#emoji):
 <script>
   window.$docsify = {
     // ...
-  }
+  };
 </script>
-<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
-<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/docsify.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/plugins/emoji.min.js"></script>
 ```
 
 you could, for example, use flag emojis in your custom navbar Markdown file:
 
 ```markdown
 <!-- _navbar.md -->
 
-* [:us:, :uk:](/)
-* [:cn:](/zh-cn/)
+- [:us:, :uk:](/)
+- [:cn:](/zh-cn/)
 ```

docs/index.html

@@ -20,24 +20,24 @@
     />
     <link
       rel="stylesheet"
-      href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css"
+      href="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/themes/vue.css"
       title="vue"
     />
     <link
       rel="stylesheet"
-      href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css"
+      href="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/themes/dark.css"
       title="dark"
       disabled
     />
     <link
       rel="stylesheet"
-      href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/buble.css"
+      href="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/themes/buble.css"
       title="buble"
       disabled
     />
     <link
       rel="stylesheet"
-      href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/pure.css"
+      href="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/themes/pure.css"
       title="pure"
       disabled
     />
@@ -55,7 +55,7 @@
 
   <body>
     <div id="app">Loading ...</div>
-    <script src="//cdn.jsdelivr.net/npm/docsify-plugin-carbon@1/index.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify-plugin-carbon@1.0.7/index.js"></script>
     <script>
       // Set html "lang" attribute based on URL
       var lang = location.hash.match(/#\/(de-de|es|ru-ru|zh-cn)\//);
@@ -118,7 +118,7 @@
             '/zh-cn/': '搜索',
             '/': 'Search',
           },
-          pathNamespaces: ['/es', '/de-de', '/ru-ru', '/zh-cn']
+          pathNamespaces: ['/es', '/de-de', '/ru-ru', '/zh-cn'],
         },
         vueComponents: {
           'button-counter': {
@@ -211,12 +211,12 @@
         ],
       };
     </script>
-    <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
-    <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
-    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
-    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
-    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-nginx.min.js"></script>
-    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/docsify.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/docsify@4.12.2/lib/plugins/search.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1.26.0/components/prism-bash.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1.26.0/components/prism-markdown.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1.26.0/components/prism-nginx.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1.26.0/components/prism-php.min.js"></script>
     <script>
       (function() {
         function loadJS(src, attrs) {
@@ -227,12 +227,14 @@
 
         // Public site only
         if (/docsify/.test(location.host)) {
-          loadJS('//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/ga.min.js');
-          loadJS('//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/matomo.min.js');
+          loadJS('//cdn.jsdelivr.net/npm/[email protected]/lib/plugins/ga.min.js');
+          loadJS(
+            '//cdn.jsdelivr.net/npm/[email protected]/lib/plugins/matomo.min.js'
+          );
         }
       })();
     </script>
-    <script src="//cdn.jsdelivr.net/npm/vue@2/dist/vue.min.js"></script>
-    <!-- <script src="//cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script> -->
+    <script src="//cdn.jsdelivr.net/npm/vue@2.6.14/dist/vue.min.js"></script>
+    <!-- <script src="//cdn.jsdelivr.net/npm/vue@3.2.29/dist/vue.global.prod.js"></script> -->
   </body>
 </html>

docs/language-highlight.md

@@ -2,16 +2,16 @@
 
 Docsify uses [Prism](https://prismjs.com) to highlight code blocks in your pages. Prism supports the following languages by default:
 
-* Markup - `markup`, `html`, `xml`, `svg`, `mathml`, `ssml`, `atom`, `rss`
-* CSS - `css`
-* C-like - `clike`
-* JavaScript - `javascript`, `js`
+- Markup - `markup`, `html`, `xml`, `svg`, `mathml`, `ssml`, `atom`, `rss`
+- CSS - `css`
+- C-like - `clike`
+- JavaScript - `javascript`, `js`
 
 Support for [additional languages](https://prismjs.com/#supported-languages) is available by loading the language-specific [grammar files](https://cdn.jsdelivr.net/npm/prismjs@1/components/) via CDN:
 
 ```html
-<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
-<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/prismjs@1.26.0/components/prism-bash.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/prismjs@1.26.0/components/prism-php.min.js"></script>
 ```
 
 To enable syntax highlighting, wrap each code block in triple backticks with the [language](https://prismjs.com/#supported-languages) specified on the first line:
@@ -27,7 +27,7 @@ echo "hello"
 ```
 
 ```php
-function getAdder(int $x): int 
+function getAdder(int $x): int
 {
     return 123;
 }
@@ -46,18 +46,19 @@ echo "hello"
 ```
 
 ```php
-function getAdder(int $x): int 
+function getAdder(int $x): int
 {
     return 123;
 }
 ```
 
 ## Highlighting Dynamic Content
+
 Code blocks [dynamically created from javascript](https://docsify.js.org/#/configuration?id=executescript) can be highlighted using the method `Prism.highlightElement` like so:
 
 ```javascript
-var code = document.createElement("code");
+var code = document.createElement('code');
 code.innerHTML = "console.log('Hello World!')";
-code.setAttribute("class", "lang-javascript");
+code.setAttribute('class', 'lang-javascript');
 Prism.highlightElement(code);
 ```

docs/markdown.md

@@ -9,10 +9,10 @@ window.$docsify = {
     renderer: {
       link: function() {
         // ...
-      }
-    }
-  }
-}
+      },
+    },
+  },
+};
 ```
 
 ?> Configuration Options Reference: [marked documentation](https://marked.js.org/#/USING_ADVANCED.md)
@@ -24,17 +24,16 @@ window.$docsify = {
   markdown: function(marked, renderer) {
     // ...
 
-    return marked
-  }
-}
+    return marked;
+  },
+};
 ```
 
 ## Supports mermaid
 
 ```js
-// Import mermaid
-//  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.css">
-//  <script src="//cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+// First include mermaid in your page with:
+//   <script src="//cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
 
 var num = 0;
 mermaid.initialize({ startOnLoad: false });
@@ -43,14 +42,16 @@ window.$docsify = {
   markdown: {
     renderer: {
       code: function(code, lang) {
-        if (lang === "mermaid") {
+        if (lang === 'mermaid') {
           return (
-            '<div class="mermaid">' + mermaid.render('mermaid-svg-' + num++, code) + "</div>"
+            '<div class="mermaid">' +
+            mermaid.render('mermaid-svg-' + num++, code) +
+            '</div>'
           );
         }
         return this.origin.code.apply(this, arguments);
-      }
-    }
-  }
-}
+      },
+    },
+  },
+};
 ```