From 5a2dde162451f69533c813856c6ce3f7fbca5f32 Mon Sep 17 00:00:00 2001
From: John Hildenbiddle <john@hildenbiddle.com>
Date: Tue, 20 Oct 2020 17:45:34 -0500
Subject: [PATCH] Update docs

---
 docs/configuration.md | 113 +++++++++++++++++++--
 docs/index.html       |  29 ++++--
 docs/vue.md           | 226 ++++++++++++++++++++++++++++++------------
 3 files changed, 289 insertions(+), 79 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 7a65553..54d6720 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -494,15 +494,15 @@ window.$docsify = {
 ```
 
 ## crossOriginLinks
-- type: `Array`  
 
-When `routerMode: 'history'`, you may face the cross-origin issues, See [#1379](https://github.com/docsifyjs/docsify/issues/1379).  
-In Markdown content, there is a simple way to solve it, see extends Markdown syntax `Cross-Origin link` in [helpers](helpers.md).  
+- type: `Array`
+
+When `routerMode: 'history'`, you may face the cross-origin issues, See [#1379](https://github.com/docsifyjs/docsify/issues/1379).
+In Markdown content, there is a simple way to solve it, see extends Markdown syntax `Cross-Origin link` in [helpers](helpers.md).
+
 ```js
 window.$docsify = {
-  crossOriginLinks:[
-      "https://example.com/cross-origin-link",
-   ],
+  crossOriginLinks: ['https://example.com/cross-origin-link'],
 };
 ```
 
@@ -629,3 +629,104 @@ window.$docsify = {
   topMargin: 90, // default: 0
 };
 ```
+
+## vueComponents
+
+- type: `Object`
+
+Registers Vue components using the component name as the key with an object containing Vue options as the value.
+
+```js
+window.$docsify = {
+  vueComponents: {
+    'button-counter': {
+      template: `
+        <button @click="count += 1">
+          You clicked me {{ count }} times
+        </button>
+      `,
+      data() {
+        return {
+          count: 0,
+        };
+      },
+    },
+  },
+};
+```
+
+```markdown
+<button-counter></button-counter>
+```
+
+<output data-lang="output">
+  <button-counter></button-counter>
+</output>
+
+## vueGlobalOptions
+
+- type: `Object`
+
+Specifies Vue options to be shared throughout your site. These options will be used when Docsify detects Vue content in the main content area that has not been previously mounted via [vueOptions](#vueoptions), [vueComponents](#vuecomponents), or a markdown `<script>`.
+
+```js
+window.$docsify = {
+  vueGlobalOptions: {
+    data() {
+      return {
+        count: 0,
+      };
+    },
+  },
+};
+```
+
+```markdown
+<p>
+  <button v-on:click="count -= 1">-</button>
+  {{ count }}
+  <button v-on:click="count += 1">+</button>
+</p>
+```
+
+<output data-lang="output">
+  <p>
+    <button v-on:click="count -= 1">-</button>
+    {{ count }}
+    <button v-on:click="count += 1">+</button>
+  </p>
+</output>
+
+## vueOptions
+
+- type: `Object`
+
+Specifies Vue mount elements and their associated options. Mount elements are specified using a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) as the key with an object containing Vue options as their value.
+
+```js
+window.$docsify = {
+  vueOptions: {
+    '#counter': {
+      data() {
+        return {
+          count: 0,
+        };
+      },
+    },
+  },
+};
+```
+
+```markdown
+<div id="counter">
+  <button v-on:click="count -= 1">-</button>
+  {{ count }}
+  <button v-on:click="count += 1">+</button>
+</div>
+```
+
+<output id="counter">
+  <button v-on:click="count -= 1">-</button>
+  {{ count }}
+  <button v-on:click="count += 1">+</button>
+</output>
diff --git a/docs/index.html b/docs/index.html
index d1f27d4..8e6e537 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -106,8 +106,28 @@
             return {
               count: 0,
               message: 'Hello, World!',
+              // Fake API response
+              images: [
+                { title: 'Image 1', url: 'https://picsum.photos/150?random=1' },
+                { title: 'Image 2', url: 'https://picsum.photos/150?random=2' },
+                { title: 'Image 3', url: 'https://picsum.photos/150?random=3' },
+              ],
             };
           },
+          computed: {
+            timeOfDay() {
+              const date = new Date();
+              const hours = date.getHours();
+
+              if (hours < 12) {
+                return 'morning';
+              } else if (hours < 18) {
+                return 'afternoon';
+              } else {
+                return 'evening';
+              }
+            },
+          },
           methods: {
             hello: function() {
               alert(this.message);
@@ -121,15 +141,6 @@
                 count: 0,
               };
             },
-            computed: {
-              message: function() {
-                const date = new Date();
-                const hours = date.getHours();
-                const greeting = hours < 12 ? 'morning' : 'day';
-
-                return `Good ${greeting}!`;
-              },
-            },
           },
         },
         vueComponents: {
diff --git a/docs/vue.md b/docs/vue.md
index c4ef629..6b70654 100644
--- a/docs/vue.md
+++ b/docs/vue.md
@@ -1,97 +1,193 @@
 # Vue compatibility
 
-Docsify allows Vue content to be added directly to you Markdown files. This can greatly simplify working with data and adding reactivity to your site.
+Docsify allows Vue content to be added directly to you markdown pages. This can greatly simplify working with data and adding reactivity to your site.
 
-To get started, add Vue [2.x](https://vuejs.org) or [3.x](https://v3.vuejs.org) to your `index.html` file:
+To get started, add either Vue [2.x](https://vuejs.org) or [3.x](https://v3.vuejs.org) to your `index.html` file:
 
 ```html
-<!-- Vue 2.x -->
+<!-- Vue 2.x (production)-->
 <script src="//cdn.jsdelivr.net/npm/vue@2/dist/vue.min.js"></script>
 
-<!-- Vue 3.x -->
+<!-- Vue 3.x (production) -->
 <script src="//cdn.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
 ```
 
-The URLs above will load a production version of Vue which is optimized for performance. Alternatively, development versions of Vue are larger but offer helpful console warnings and [Vue.js devtools](https://github.com/vuejs/vue-devtools) support:
+The URLs above will load a **production** version of Vue which has been optimized for performance. Alternatively, **development** versions of Vue are available that are larger in size but offer helpful console warnings and [Vue.js devtools](https://github.com/vuejs/vue-devtools) support:
 
 ```html
-<!-- Vue 2.x -->
+<!-- Vue 2.x (development) -->
 <script src="//cdn.jsdelivr.net/npm/vue@2/dist/vue.js"></script>
 
-<!-- Vue 3.x -->
+<!-- Vue 3.x (development) -->
 <script src="//cdn.jsdelivr.net/npm/vue@3/dist/vue.global.js"></script>
 ```
 
 ## Template syntax
 
-Vue [template syntax](https://vuejs.org/v2/guide/syntax.html) can be added directly to your markdown pages. This syntax can be used to generate dynamic content without additional configuration using [JavaScript expressions](https://vuejs.org/v2/guide/syntax.html#Using-JavaScript-Expressions) and Vue [directives](https://vuejs.org/v2/guide/syntax.html#Directives).
+Vue [template syntax](https://vuejs.org/v2/guide/syntax.html) is used to create dynamic content. With no additinal configuration, this syntax offers several useful features like support for [JavaScript expressions](https://vuejs.org/v2/guide/syntax.html#Using-JavaScript-Expressions) and Vue [directives](https://vuejs.org/v2/guide/syntax.html#Directives) for loops and conditional rendering.
 
 ```markdown
-<!-- JavaScript expressions -->
-<p>2 + 2 = {{ 2 + 2 }}</p>
-
-<!-- Hide in docsify, show everywhere else (e.g. GitHub) -->
+<!-- Hide in docsify, show elsewhere (e.g. GitHub) -->
 <p v-if="false">Text for GitHub</p>
 
-<!-- Sequenced content -->
+<!-- Sequenced content (i.e. loop)-->
 <ul>
   <li v-for="i in 3">Item {{ i }}</li>
 </ul>
+
+<!-- JavaScript expressions -->
+<p>2 + 2 = {{ 2 + 2 }}</p>
 ```
 
 <output data-lang="output">
-  <p>2 + 2 = {{ 2 + 2 }}</p>
-
   <p v-if="false">Text for GitHub</p>
 
   <ul>
     <li v-for="i in 3">Item {{ i }}</li>
   </ul>
+
+  <p>2 + 2 = {{ 2 + 2 }}</p>
 </output>
 
-[View markdown on GitHub](https://github.com/docsifyjs/docsify/blob/develop/docs/vue.md#template-syntax)
+[View output on GitHub](https://github.com/docsifyjs/docsify/blob/develop/docs/vue.md#template-syntax)
 
-Vue content becomes more interesting when data, methods, lifecycle hooks, and computed properties are used. These options can be specified as [global options](#global-options), [instance options](#instance-options), or within [components](#components).
+Vue content becomes more interesting when [data](#data), [computed properties](#computed-properties), [methods](#methods), and [lifecycle hooks](#lifecycle-hooks) are used. These options can be specified as [global options](#global-options), [instance options](#instance-options), or within [components](#components).
+
+### Data
 
 ```js
 {
   data() {
     return {
-      message: 'Hello, World!',
+      message: 'Hello, World!'
+    };
+  }
+}
+```
+
+<!-- prettier-ignore-start -->
+```markdown
+<!-- Show message in docsify, show "{{ message }}" elsewhere (e.g. GitHub)  -->
+{{ message }}
+
+<!-- Show message in docsify, hide elsewhere (e.g. GitHub)  -->
+<p v-text="message"></p>
+
+<!-- Show message in docsify, show text elsewhere (e.g. GitHub)  -->
+<p v-text="message">Text for GitHub</p>
+```
+<!-- prettier-ignore-end -->
+
+<output data-lang="output">
+
+{{ message }}
+
+  <p v-text="message"></p>
+  <p v-text="message">Text for GitHub</p>
+</output>
+
+[View output on GitHub](https://github.com/docsifyjs/docsify/blob/develop/docs/vue.md#data)
+
+### Computed properties
+
+```js
+{
+  computed: {
+    timeOfDay() {
+      const date = new Date();
+      const hours = date.getHours();
+
+      if (hours < 12) {
+        return 'morning';
+      }
+      else if (hours < 18) {
+        return 'afternoon';
+      }
+      else {
+        return 'evening'
+      }
+    }
+  },
+}
+```
+
+```markdown
+Good {{ timeOfDay }}!
+```
+
+<output data-lang="output">
+
+Good {{ timeOfDay }}!
+
+</output>
+
+### Methods
+
+```js
+{
+  data() {
+    return {
+      message: 'Hello, World!'
     };
   },
   methods: {
     hello() {
       alert(this.message);
     }
-  }
+  },
 }
 ```
 
-```markdown
-<!-- Show message in docsify, hide on GitHub  -->
-<p v-text="message"></p>
-
-<!-- Show message in docsify, Show text on GitHub  -->
-<p v-text="message">Text for GitHub</p>
-
-<!-- Invoke hello method -->
-<p>
-  <button v-on:click="hello">Say Hello</button>
-</p>
-```
-
 <output data-lang="output">
-  <p v-text="message"></p>
-  <p v-text="message">Text for GitHub</p>
   <p><button v-on:click="hello">Say Hello</button></p>
 </output>
 
-[View markdown on GitHub](https://github.com/docsifyjs/docsify/blob/develop/docs/vue.md#options)
+### Lifecycle Hooks
+
+```js
+{
+  data() {
+    return {
+      images: null,
+    };
+  },
+  created() {
+    fetch('https://api.domain.com/')
+      .then(response => response.json())
+      .then(data => (this.images = data))
+      .catch(err => console.log(err));
+  }
+}
+
+// API response:
+// [
+//   { title: 'Image 1', url: 'https://domain.com/1.jpg' },
+//   { title: 'Image 2', url: 'https://domain.com/2.jpg' },
+//   { title: 'Image 3', url: 'https://domain.com/3.jpg' },
+// ];
+```
+
+```markdown
+<div style="display: flex;">
+  <figure style="flex: 1;">
+    <img v-for="image in images" :src="image.url" :title="image.title">
+    <figcaption>{{ image.title }}</figcaption>
+  </figure>
+</div>
+```
+
+<output data-lang="output">
+  <div style="display: flex;">
+    <figure v-for="image in images" style="flex: 1; text-align: center;">
+      <img :src="image.url">
+      <figcaption>{{ image.title }}</figcaption>
+    </figure>
+  </div>
+</output>
 
 ## Global options
 
-Use `vueGlobalOptions` to share data, methods, lifecycle hooks, and computed properties throughout your site. These options will be available to Vue content not explicitly mounted via [instance options](#instance-options), [components](#components), or a markdown `<script>`.
+Use `vueGlobalOptions` to share Vue options throughout your site. These options will be used when Docsify detects Vue content in the main content area that has not been previously mounted via [instance options](#instance-options), [components](#components), or a [markdown script](#markdown-script). Global `data()` is shared and changes will persist as users navigate the site.
 
 ```js
 window.$docsify = {
@@ -113,7 +209,7 @@ window.$docsify = {
 </p>
 ```
 
-Keep in mind that global `data()` is shared, so changes made in one location will affect all locations where global `data()` is used. These changes will also persist as users navigate your site. To demonstrate, let's render the above counter twice.
+Notice the behavior when multilpe global counters are rendered below: changes made to one counter affect the other because both instances reference the global `count` value.
 
 <output data-lang="output">
   <p>
@@ -128,54 +224,43 @@ Keep in mind that global `data()` is shared, so changes made in one location wil
   </p>
 </output>
 
-Notice how changes made to one counter affect the other. This is because both counters reference the global `count` value. Now, navigate to a new page and return to this page to see how these changes persists.
+Now, navigate to a new page and return to this section to see how changes made to global data persist.
 
 ## Instance options
 
-Use `vueOptions` to specify DOM elements to mount as Vue instances and their associated options as `key:value` pairs. DOM elements are specified using [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) as the key. Selectors are limited in scope to the main content area
+Use `vueOptions` to specify Vue mount elements and their associated options. Mount elements are specified using a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) as the key with an object containing Vue options as their value. Docsify will mount the first matching element in the main content area (`#main, .markdown-section`) each time a new page is loaded. Instance data is not shared and changes will not persist as users navigate the site.
 
 ```js
 window.$docsify = {
   vueOptions: {
-    "#counter": {
+    '#counter': {
       data() {
         return {
-          count: 0
+          count: 0,
         };
-      }
-      computed: {
-        message() {
-          const date = new Date();
-          const hours = date.getHours();
-          const greeting = hours < 12 ? 'morning' : 'day';
-
-          return `Good ${greeting}!`;
-        }
-      }
-    }
-  }
+      },
+    },
+  },
 };
 ```
 
 ```markdown
 <div id="counter">
-  <p>{{ message }}</p>
-  <button v-on:click="count -= 10">-</button>
+  <button v-on:click="count -= 1">-</button>
   {{ count }}
-  <button v-on:click="count += 10">+</button>
+  <button v-on:click="count += 1">+</button>
 </div>
 ```
 
 <output id="counter">
-  <p>{{ message }}</p>
-  <button v-on:click="count -= 10">-</button>
+  <button v-on:click="count -= 1">-</button>
   {{ count }}
-  <button v-on:click="count += 10">+</button>
+  <button v-on:click="count += 1">+</button>
 </output>
 
 ## Components
 
-Docsify provides components
+Use `vueComponents` to register Vue components using the component name as the key with an object containing Vue options as the value. Components data is not shared and changes will not persist as users navigate the site.
 
 ```js
 window.$docsify = {
@@ -198,22 +283,26 @@ window.$docsify = {
 
 ```markdown
 <button-counter></button-counter>
+<button-counter></button-counter>
 ```
 
 <output data-lang="output">
   <button-counter></button-counter>
+  <button-counter></button-counter>
 </output>
 
 ## Markdown script
 
-TBD
+Vue content can mounted using a `<script>` tag in your markdown pages.
+
+!> Only the first `<script>` tag in a markdown file is executed. If you are working with multiple Vue components, all `Vue` instances must be created within the first `<script>` tag in your markdown.
 
 ```html
 <!-- Vue 2.x  -->
 <script>
   new Vue({
     el: '#example',
-    // ...
+    // Options...
   });
 </script>
 ```
@@ -222,9 +311,18 @@ TBD
 <!-- Vue 3.x  -->
 <script>
   Vue.createApp({
-    // ...
+    // Options...
   }).mount('#example');
 </script>
 ```
 
-!> Only the first `<script>` tag in a markdown file is executed. If you are working with multiple Vue components, all `Vue` instances must be created within this tag.
+## Technical Notes
+
+- Docsify processes Vue content in the following order:
+  1. markdown script,
+  1. `vueOptions`
+  1. `vueGlobalOptions`
+- Docsify will not mount an element that is already a Vue instance or contains a Vue instance.
+- Docsify will automatically destroy/unmount all Vue instances it creates.
+- When processing `vueGlobalOptions`, docsify parses each root element of the main content area and mounts the element if Vue content is detected. Docsify does not parse each individual node within the main content area.
+- When processing `vueGlobalOptions`, docsify detects the full `v-` attribute syntax (e.g `v-bind:href` or `v-on:click`) but not the [shorthand](https://vuejs.org/v2/guide/syntax.html#Shorthands) syntax (e.g. `:href`or `@click`).