code commenting / cleanup

Author: markzegarelli

scripts/checklinks-external.js

@@ -1,21 +1,24 @@
+// A script to check all external links on the docs site
+
 const globby = require('globby')
 const posthtml = require('posthtml')
 const fs = require('fs')
 const server = require('browser-sync').create()
 const checkLinks = require('check-links')
-const {
-  $dataMetaSchema
-} = require('ajv')
 const ora = require('ora')
 
 
 
 const checkForDeadExternalUrls = async () => {
   try {
+    // Grab all the files from the specified directory, add their paths to a new set 
     const files = await globby('_site/**/*.html')
     const throbber = ora('Link Check Starting').start()
+    // Use a set here for efficiency, no duplicate values!
     const urls = new Set()
 
+    // Because we're checking for external URLs only, add every URL that does not start with a `/`,
+    // or point to 0.0.0.0. Also exclude segmentio GitHub URLs
     const ph = posthtml([
       require('posthtml-urls')({
         eachURL: (url) => {
@@ -28,40 +31,32 @@ const checkForDeadExternalUrls = async () => {
     throbber.succeed()
     throbber.start('Processing files')
 
+    // Run the above logic on each file 
     files.forEach((file) => {
       ph.process(fs.readFileSync(file))
     })
-    throbber.succeed()
-    throbber.start('Starting server')
-    await new Promise((resolve) => {
-      server.init({
-          port: 3000,
-          server: {
-            baseDir: '_site',
-          },
-          open: false,
-          logLevel: 'silent',
-        },
-        resolve,
-      )
-      throbber.succeed()
-    })
-    
+
+   
+    // Check all the links collected in the section above
     throbber.start('Checking the links')
     const results = await checkLinks(
       Array.from(urls).map((url) =>
         url
       ),
     )
+    // If a link returns 'dead' (404), add it to an array
     const deadUrls = Array.from(urls).filter(
       (url) => results[url].status === 'dead',
     )
-
+    
+    // If there are dead URLs, list them here, along with the count. Exit status 1 to indicate an error.
     if (deadUrls.length > 0) {
       throbber.fail(`Dead URLS: ${deadUrls.length}\n\n`)
       console.log(`Dead URLS: ${deadUrls.length}\n\n${deadUrls.join('\n')}`)
       process.exit(1)
-    } else {
+    } 
+    // Otherwise, claim that all the links work, and exit the process normally.
+    else {
       console.log('All links work!')
       process.exit
     }

scripts/checklinks-internal.js

@@ -1,3 +1,5 @@
+// A script the check all local links on the docs site
+
 const globby = require('globby')
 const posthtml = require('posthtml')
 const fs = require('fs')
@@ -8,10 +10,14 @@ const ora = require('ora')
 
 const checkForDeadLocalUrls = async () => {
   try {
+    // Grab all the files from the specified directory, add their paths to a new set 
     const files = await globby('_site/**/*.html')
     const throbber = ora('Link Check Starting').start()
+    // Use a set here for efficiency, no duplicate values!
     const urls = new Set()
 
+    // Logic for collecting the list of URLs to check
+    // If the link starts with `/docs/`, replace that with a localhost:3000 domain, and add it to the list.
     const ph = posthtml([
       require('posthtml-urls')({
         eachURL: (url) => {
@@ -22,14 +28,16 @@ const checkForDeadLocalUrls = async () => {
       }),
     ])
     throbber.succeed()
-    throbber.start('Processing files')
 
+    // Using the logic above, iterate through the entire list of files
+    throbber.start('Processing files')
     files.forEach((file) => {
       ph.process(fs.readFileSync(file))
     })
     throbber.succeed()
-    throbber.start('Starting server')
 
+    // Spin up a lightweight browsersync server to check each URL
+    throbber.start('Starting server')
     await new Promise((resolve) => {
       server.init({
           port: 3000,
@@ -44,17 +52,20 @@ const checkForDeadLocalUrls = async () => {
       throbber.succeed()
     })
 
+    // Check the links against the local browsersync site
     const results = await checkLinks(
       Array.from(urls).map((url) =>
         url
       ),
     )
+
+    // If a link returns 'dead' (404), add it to an array
     const deadUrls = Array.from(urls).filter(
       (url) => results[url].status === 'dead',
     )
 
+    // For ease of checking, replace the localhost domain with the live domain, add those to a new array.
     let broke = []
-
     deadUrls.forEach(url => {
       link = url.replace('http://localhost:3000', 'https://segment.com/docs')
       if (!link.endsWith('/')){
@@ -64,17 +75,27 @@ const checkForDeadLocalUrls = async () => {
     });
 
 
-
+    // Sometimes, we redirect urls based on jekyll settings, or a setting an app-nginx. 
+    // For those, we want to remove them from the list of dead links, because they aren't dead.
+    
+    // app-nginx redirects
     const redirects = ['https://segment.com/docs/guides/usage-and-billing/','https://segment.com/docs/connections/sources/catalog/libraries/website/plugins/', 'https://segment.com/docs/assets/docs.bundle.js/']
+    
+    // Redirects generated by Jekyll
+    // Pull the redirects json file
     const data = require('../_site/redirects.json')
+    // Grab the 'from' redirect
     Object.keys(data).forEach(key => {
       if (!key.endsWith('/')){
         key = key+'/'
       }
       redirects.push('https://segment.com/docs'+key.replace('/docs',''))
     })
+    // Remove the redirect urls from the list of broken URLs
     broke = broke.filter(val => !redirects.includes(val));
 
+    // If there are dead URLs, list them here, along with the count. Exit status 1 to indicate an error.
+
     if (broke.length > 0) {
       throbber.fail(`Dead URLS: ${broke.length}\n\n`)
       console.log(`Dead URLS: ${broke.length}\n\n${broke.join('\n')}`)