Adds helpful comments throughout the app.

Author: codingfriend1

site.config.js

@@ -14,7 +14,16 @@ module.exports = {
   twitterCard: "summary_large_image",
   twitterCreator: "@your_twitter_username",
 
+  /**
+   * If you set a `facebook_id` then we will initialize facebook comments and likes
+   * The `facebook_id` is the App ID you would normally use in the meta tag
+   * ```html
+   * <meta property="fb:app_id" content="[[facebook_id]]"/>
+   * ````
+   */
   facebook_id: null,
+
+  
   googleAnalyticsId: "",
   mailChimpUrl: "",
 

the-magic/boot/async-data.js

@@ -1,3 +1,8 @@
+/**
+ * Runs client side only
+ * Before the component mounts or updates it's route, we want to finish running any requied AJAX requests that the component may depend on to load
+ */
+
 import Vue from "vue";
 
 Vue.mixin({

the-magic/boot/entry-server.js

@@ -1,5 +1,6 @@
 /**
  * Runs on server only
+ * When our `/the-magic/build/build.js` or `/the-magic/build/server.js` attempt to render our Vue and Markdown files into raw HTML files at `renderer.renderToString()` for better SEO, it critically depends on this file to determine which files to render for a given route, to load all necessary subcomponents for that route and render each, and add any data from our server side AJAX requests that need to be embedded in the raw HTML file. If the store is modified, we also need to deliver a copy of that state to the renderer so the client will initialize it's store in the same condition.
  */
 
 import Vue from "vue";
@@ -12,16 +13,29 @@ import colors from 'colors';
 global.fetch = require("node-fetch")
 
 export default context => {
+
+  /**
+   * It's ok to return a promise to the renderer
+   */
   return new Promise((resolve, reject) => {
 
     let { store, app, router } = require(`./index.js`).default;
 
+    /**
+     * Initialize Vue-Meta
+     */
     const meta = app.$meta();
 
     Object.assign(store, context);
 
+    /**
+     * The `context` argument provides the url the user is attempting to access in the browser with `context.file.url`. We tell the router to load this route and all it's necessary subcomponents
+     */
     router.push(context.file.url);
 
+    /**
+     * We wait for the router to finish loading all necessary components to this route
+     */
     router.onReady(() => {
       let matchedComponents = router.getMatchedComponents();
 
@@ -30,10 +44,16 @@ export default context => {
         return reject(colors.red(`${context.file.url}`) + colors.grey(` from `) + colors.red(context.file.path.replace(__dirname, '')) + colors.grey(` is not routed to any vue templates. Match a vue template to this url in the ` + colors.green(`site.config.js`) + ` routes.\n\r`)
         );
       }
-      // call `asyncData()` on all matched route components
+
+      /**
+       * For every subcomponent for this route, we check if any of them require AJAX requests to be run and completed before we render. This is helpful in the case that you want to fetch some data at the moment the user or Search Engine Bot load the page and embed the results in the rendered HTML file
+       * We provide each `asyncData()` function the store and current route in case that information is needed for making the AJAX request
+       */
       Promise.all(
         matchedComponents.map(Component => {
           if (Component.options.asyncData) {
+
+            // call `asyncData()` on all matched route components
             return Component.options.asyncData({
               store,
               route: router.currentRoute
@@ -42,7 +62,14 @@ export default context => {
         })
       )
         .then(() => {
+          /**
+           * AJAX requests or loading the components may have modified our server-side store. It's critical that the server rendering fully matches the client-side rendering on the each's initial render and to have matching pages the store needs to be in the same state on the client and server. Therefore, since our basic store may have been modified by our server-side rendering process, we need to provide the modifications to the context so the client can initialize it's store with the state the server renderer left it in.
+           */
           context.state = store;
+
+          /**
+           * We also need to provide our meta data rendered by Vue-Meta to our context object so we can inject these tags into our rendered HTML
+           */
           context.meta = meta;
           resolve(app);
         })

the-magic/boot/facebook-social.js

@@ -1,7 +1,14 @@
 import Vue from "vue";
 import config from "config";
 
+/**
+ * We only want to enable facebook comments if we are client-side and we haven't already initialized this script
+ */
 if (!Vue.prototype.$isServer && !window.fbAsyncInit) {
+
+    /**
+     * If you run `enableComments()` in your code it will download the remote facebook script to enable facebook comments and likes on your pages
+     */
     window.enableComments = function() {
         (function(d, s, id) {
             var js,
@@ -27,6 +34,9 @@ if (!Vue.prototype.$isServer && !window.fbAsyncInit) {
                     xfbml: true //Look for social plugins on the page
                 });
 
+                /**
+                 * If Google Analytics is loaded, we want to track if the user is logged in, if they liked/unliked, commented on, or shared a post
+                 */
                 if(typeof ga !== 'undefined') {
                     // //Logged In Users
                     FB.getLoginStatus(function(response) {

the-magic/boot/index.js

@@ -13,26 +13,36 @@ import meta_tags from './meta-tags.js';
 
 Vue.config.productionTip = false;
 
+/**
+ * Make our store, router, and site.config.js (`config`) global so it can be used instantly in any of our templates, js files or components
+ */
 global.store = store
 global.router = router
 global.config = config
 
 /**
- * This is our config.folderStructure.css entry file
+ * This is our config.folderStructure.css entry file in `/site.config.js`
  */
 require(main_css);
 
 /**
- * This is our config.folderStructure.vue entry file
+ * This is our `config.folderStructure.vue` entry file in `/site.config.js`
  */
 let Root = require(main_vue).default;
 
 Root = Object.assign({}, {
+
+  /**
+   * We assign our default meta tags in `./meta-tags.js` to our root component
+   */
   metaInfo() {
     return meta_tags
   },
 }, Root);
 
+/**
+ * Here we construct the root component and connect the Vue-Stash Store and Vue-Router
+ */
 global.app = new Vue(
   Object.assign(
     {
@@ -44,25 +54,45 @@ global.app = new Vue(
 );
 
 /**
- * This is our config.folderStructure.js entry file
+ * This is our config.folderStructure.js entry file from `/site.config.js`
  */
 require(main_js);
 
-// Check if user is logged in then launch the app unless we are rendering from the server
+
 if (Vue.prototype.$isServer) {
+  /**
+   * If we are rendering the component on the server we simply want to mount the root component without loading any server-side scripts
+   */
   app.$mount("#app");
 } else {
+
+  /**
+   * If we are rendering the root component on the client, we want to first complete any ajax requests and include their data in our rendered templates
+   */
   require("./async-data");
 
+  /**
+   * If the user has set `googleAnalyticsId` in `/site.config.js` and we are rendering client-side we want to load our `./analytics.js` script
+   */
   if(global.config.googleAnalyticsId) {
     require("./analytics.js")
   }
 
+  /**
+   * If the user has set a `facebook_id` in `/site.config.js` then we want to initialize facebook comments and likes
+   * The `facebook_id` is the App ID you would normally use in the meta tag
+   * ```html
+   * <meta property="fb:app_id" content="[[facebook_id]]"/>
+   * ````
+   */
   if(global.config.facebook_id) {
     require("./facebook-social.js")
   }
-  // Don't hydrate site if google bot is visiting because it may take the screen shot during the hydration phase when ajax content isn't present
+
   app.$mount("#app");
 }
 
+/**
+ * It's important that we export the our root component, router, and store 
+ */
 export default { app, router, store };

the-magic/boot/meta-tags.js

@@ -1,3 +1,8 @@
+/**
+ * To save a lot of typing in the developer's templates, we set the default meta tag configuration for the root object
+ * These properties can be overridden in subroutes
+ */
+
 import config from 'config';
 
 export default {

the-magic/boot/router.js

@@ -5,7 +5,11 @@ import config from "config";
 import camelCase from "lodash.camelcase";
 
 /**
- * Make our individual templates and partials available globally
+ * `the-magic/build/gulpfile.js` will automatically inject `.vue` files located in the specified `components` and `partials` folder paths (See `/site.config.js`) into this `components` constant between the comments:
+ * // globalize vue components
+ * and
+ * // end globalize vue components
+ * This makes our components available globally under the camelCase version of the file-name (without the extension)
  */
 const components = {
   // globalize vue components
@@ -20,7 +24,7 @@ const components = {
 };
 
 /**
- * Take routes in /site.config.js and attach the named components to them
+ * Takes the routes and their matching `string` component names in `/site.config.js`` and replaces with string with the component using the same name
  */
 const routes = config.routes
   .map(route => {
@@ -45,6 +49,7 @@ const router = new VueRouter({
 
       /**
        * Here is where you determine scroll position for the page you navigate to
+       * We are returning the scroll position to the top of the page between scrolls
        */
       resolve({x: 0, y: 0})
     })    

the-magic/boot/store-reconciliation.js

@@ -9,22 +9,42 @@ const defaultStore = config.store;
 
 let store = defaultStore;
 
+/**
+ * When our Vue and Markdown files are rendered into HTML, Server-Side Rendering will save the server-side rendered state of the store to the variable `window.__INITIAL_STATE__`
+ * We want to set our client-side store to initialize with whatever is in this variable, so the server and client store will be in sync
+ */
 try {
   if (typeof window !== "undefined" && window.__INITIAL_STATE__) {
     store = window.__INITIAL_STATE__;
   }
 } catch (err) {}
 
+
+/**
+ * Before loading the URL, finding the markdown file matching that URL and set the markdown's rendered HTML and metadata object as the `file` property of the store. If a markdown file cannot be found, then load a 404 page
+ */
 router.beforeEach((to, from, next) => {
   let path = to.path.replace('.html', '').replace('.htm', '');
   const found = store.files.find(post => post.url === path);
+
+  /**
+   * Setting `postBodyEl` will enable scroll tracking with Google Analytics on a page.
+   * Scrolling tracking is how we determine if the article was completely read (the user reaches the bottom of the article content).
+   * We want to reset this value between pages in case there's a page that we don't want to track
+   */
   if(typeof postBodyEl !== 'undefined') {
     global.postBodyEl = null;
   }
+
   if (!found) {
     router.replace("/404");
   } else {
+
     store.file = found;
+
+    /**
+     * `social_url` is used for matching Facebook Comments and Likes to the current page in the `:data-href="$store.social_url"` attribute
+     */
     store.social_url = config.site_url + store.file.url;
   }
   next();