chore(js): Extract Hugo params imports to single-purpose modules, fix environment-specific Hugo configs, use Hugo environments instead of specifying the config file, configure source maps and ESM for development and testing

Author: jstirnaman

.circleci/config.yml

@@ -41,7 +41,7 @@ jobs:
             - /home/circleci/bin
       - run:
           name: Hugo Build
-          command: npx hugo --config config/production/config.yml --logLevel info --minify --gc --destination workspace/public
+          command: yarn hugo --environment production --logLevel info --gc --destination workspace/public
       - persist_to_workspace:
           root: workspace
           paths:

.github/instructions/contributing.instructions.md

@@ -1730,11 +1730,30 @@ If you're adding UI functionality that requires JavaScript, follow these steps:
 
 ### Debugging JavaScript
 
-To debug JavaScript code used in the InfluxData documentation UI:
+To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods:
+
+- Use source maps and the Chrome DevTools debugger.
+- Use debug helpers that provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger.
+
+#### Using source maps and Chrome DevTools debugger
+
+1. In VS Code, select Run > Start Debugging.
+2. Select the "Debug Docs (source maps)" configuration.
+3. Click the play button to start the debugger.
+5. Set breakpoints in the JavaScript source files--files in the
+   `assets/js/ns-hugo-imp:` namespace-- in the
+   VS Code editor or in the Chrome Developer Tools Sources panel:
+
+   - In the VS Code Debugger panel > "Loaded Scripts" section, find the
+     `assets/js/ns-hugo-imp:` namespace.
+   - In the Chrome Developer Tools Sources panel, expand
+     `js/ns-hugo-imp:/<YOUR_WORKSPACE_ROOT>/assets/js/`.
+
+#### Using debug helpers
 
 1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`.
-   These helpers provide breakpoints and console logging as a workaround for
-   Hugo's lack of source map support in the asset pipeline.
+   These helpers provide breakpoints and console logging as a workaround or alternative for
+   using source maps and the Chrome DevTools debugger.
 2. Insert debug statements by calling the helper functions in your code--for example:
    
    ```js
@@ -1757,7 +1776,7 @@ To debug JavaScript code used in the InfluxData documentation UI:
    yarn hugo server
    ```
 
-4. In VS Code, go to Run > Start Debugging, and select the "Debug Docs (console-based)" configuration.
+4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration.
 
 Your system uses the configuration in `launch.json` to launch the site in Chrome
 and attach the debugger to the Developer Tools console.

.vscode/launch.json

@@ -2,7 +2,7 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Debug Docs (console-based)",
+      "name": "Debug JS (debug-helpers)",
       "type": "chrome",
       "request": "launch",
       "url": "http://localhost:1313",
@@ -13,6 +13,35 @@
       "sourceMaps": false,
       "trace": true,
       "smartStep": false
-    }
+    },
+    {
+      "name": "Debug JS (source maps)",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:1313",
+      "webRoot": "${workspaceFolder}",
+      "sourceMaps": true,
+      "sourceMapPathOverrides": {
+        "*": "${webRoot}/assets/js/*",
+        "main.js": "${webRoot}/assets/js/main.js",
+        "page-context.js": "${webRoot}/assets/js/page-context.js",
+        "ask-ai-trigger.js": "${webRoot}/assets/js/ask-ai-trigger.js",
+        "ask-ai.js": "${webRoot}/assets/js/ask-ai.js",
+        "utils/*": "${webRoot}/assets/js/utils/*",
+        "services/*": "${webRoot}/assets/js/services/*"
+      },
+      "skipFiles": [
+        "<node_internals>/**",
+        "node_modules/**",
+        "chrome-extension://**"
+      ],
+      "trace": true,
+      "smartStep": true,
+      "disableNetworkCache": true,
+      "userDataDir": "${workspaceFolder}/.vscode/chrome-user-data",
+      "runtimeArgs": [
+        "--disable-features=VizDisplayCompositor"
+      ]
+    },
   ]
 }

CONTRIBUTING.md

@@ -1718,11 +1718,30 @@ If you're adding UI functionality that requires JavaScript, follow these steps:
 
 ### Debugging JavaScript
 
-To debug JavaScript code used in the InfluxData documentation UI:
+To debug JavaScript code used in the InfluxData documentation UI, choose one of the following methods:
+
+- Use source maps and the Chrome DevTools debugger.
+- Use debug helpers that provide breakpoints and console logging as a workaround or alternative for using source maps and the Chrome DevTools debugger.
+
+#### Using source maps and Chrome DevTools debugger
+
+1. In VS Code, select Run > Start Debugging.
+2. Select the "Debug Docs (source maps)" configuration.
+3. Click the play button to start the debugger.
+5. Set breakpoints in the JavaScript source files--files in the
+   `assets/js/ns-hugo-imp:` namespace-- in the
+   VS Code editor or in the Chrome Developer Tools Sources panel:
+
+   - In the VS Code Debugger panel > "Loaded Scripts" section, find the
+     `assets/js/ns-hugo-imp:` namespace.
+   - In the Chrome Developer Tools Sources panel, expand
+     `js/ns-hugo-imp:/<YOUR_WORKSPACE_ROOT>/assets/js/`.
+
+#### Using debug helpers
 
 1. In your JavaScript module, import debug helpers from `assets/js/utils/debug-helpers.js`.
-   These helpers provide breakpoints and console logging as a workaround for
-   Hugo's lack of source map support in the asset pipeline.
+   These helpers provide breakpoints and console logging as a workaround or alternative for
+   using source maps and the Chrome DevTools debugger.
 2. Insert debug statements by calling the helper functions in your code--for example:
    
    ```js
@@ -1745,7 +1764,7 @@ To debug JavaScript code used in the InfluxData documentation UI:
    yarn hugo server
    ```
 
-4. In VS Code, go to Run > Start Debugging, and select the "Debug Docs (console-based)" configuration.
+4. In VS Code, go to Run > Start Debugging, and select the "Debug JS (debug-helpers)" configuration.
 
 Your system uses the configuration in `launch.json` to launch the site in Chrome
 and attach the debugger to the Developer Tools console.

assets/js/api-libs.js

@@ -2,7 +2,7 @@
 ///////////////// Preferred Client Library programming language  ///////////////
 ////////////////////////////////////////////////////////////////////////////////
 import { activateTabs, updateBtnURLs } from './tabbed-content.js';
-import { getPreference, setPreference } from './local-storage.js';
+import { getPreference, setPreference } from './services/local-storage.js';
 
 function getVisitedApiLib() {
   const path = window.location.pathname.match(

assets/js/ask-ai.js

@@ -8,29 +8,31 @@ function setUser(userid, email) {
   window[NAMESPACE] = {
     user: {
       uniqueClientId: userid,
-      email: email, 
-    }
-  }
+      email: email,
+    },
+  };
 }
 
 // Initialize the chat widget
-function initializeChat({onChatLoad, chatAttributes}) {
-  /* See https://docs.kapa.ai/integrations/website-widget/configuration for 
+function initializeChat({ onChatLoad, chatAttributes }) {
+  /* See https://docs.kapa.ai/integrations/website-widget/configuration for
    * available configuration options.
    * All values are strings.
    */
-  // If you make changes to data attributes here, you also need to port the changes to the api-docs/template.hbs API reference template.
+  // If you make changes to data attributes here, you also need to
+  // port the changes to the api-docs/template.hbs API reference template.
   const requiredAttributes = {
     websiteId: 'a02bca75-1dd3-411e-95c0-79ee1139be4d',
     projectName: 'InfluxDB',
     projectColor: '#020a47',
     projectLogo: '/img/influx-logo-cubo-white.png',
-  }
+  };
 
   const optionalAttributes = {
-
-    modalDisclaimer: 'This AI can access [documentation for InfluxDB, clients, and related tools](https://docs.influxdata.com). Information you submit is used in accordance with our [Privacy Policy](https://www.influxdata.com/legal/privacy-policy/).',
-    modalExampleQuestions: 'Use Python to write data to InfluxDB 3,How do I query using SQL?,How do I use MQTT with Telegraf?',
+    modalDisclaimer:
+      'This AI can access [documentation for InfluxDB, clients, and related tools](https://docs.influxdata.com). Information you submit is used in accordance with our [Privacy Policy](https://www.influxdata.com/legal/privacy-policy/).',
+    modalExampleQuestions:
+      'Use Python to write data to InfluxDB 3,How do I query using SQL?,How do I use MQTT with Telegraf?',
     buttonHide: 'true',
     exampleQuestionButtonWidth: 'auto',
     modalOpenOnCommandK: 'true',
@@ -52,28 +54,32 @@ function initializeChat({onChatLoad, chatAttributes}) {
     modalHeaderBorderBottom: 'none',
     modalTitleColor: '#fff',
     modalTitleFontSize: '1.25rem',
-  }
+  };
 
   const scriptUrl = 'https://widget.kapa.ai/kapa-widget.bundle.js';
   const script = document.createElement('script');
   script.async = true;
   script.src = scriptUrl;
-  script.onload = function() {
+  script.onload = function () {
     onChatLoad();
     window.influxdatadocs.AskAI = AskAI;
   };
-  script.onerror = function() {
+  script.onerror = function () {
     console.error('Error loading AI chat widget script');
   };
 
-  const dataset = {...requiredAttributes, ...optionalAttributes, ...chatAttributes};
-  Object.keys(dataset).forEach(key => {
-     // Assign dataset attributes from the object
+  const dataset = {
+    ...requiredAttributes,
+    ...optionalAttributes,
+    ...chatAttributes,
+  };
+  Object.keys(dataset).forEach((key) => {
+    // Assign dataset attributes from the object
     script.dataset[key] = dataset[key];
   });
 
   // Check for an existing script element to remove
-  const oldScript= document.querySelector(`script[src="${scriptUrl}"]`);
+  const oldScript = document.querySelector(`script[src="${scriptUrl}"]`);
   if (oldScript) {
     oldScript.remove();
   }
@@ -82,22 +88,21 @@ function initializeChat({onChatLoad, chatAttributes}) {
 
 function getProductExampleQuestions() {
   const questions = productData?.product?.ai_sample_questions;
-    return questions?.join(',') || '';
+  return questions?.join(',') || '';
 }
 
-/** 
+/**
  * chatParams: specify custom (for example, page-specific) attribute values for the chat, pass the dataset key-values (collected in ...chatParams). See https://docs.kapa.ai/integrations/website-widget/configuration for available configuration options.
  * onChatLoad: function to call when the chat widget has loaded
  * userid: optional, a unique user ID for the user (not currently used for public docs)
-*/
+ */
 export default function AskAI({ userid, email, onChatLoad, ...chatParams }) {
-  
   const modalExampleQuestions = getProductExampleQuestions();
   const chatAttributes = {
     ...(modalExampleQuestions && { modalExampleQuestions }),
     ...chatParams,
-  }
-  initializeChat({onChatLoad, chatAttributes});
+  };
+  initializeChat({ onChatLoad, chatAttributes });
 
   if (userid) {
     setUser(userid, email);

assets/js/code-controls.js

@@ -1,8 +1,9 @@
 import $ from 'jquery';
+import { debugBreak } from './utils/debug-helpers.js';
 
 function initialize() {
   var codeBlockSelector = '.article--content pre';
-  var codeBlocks = $(codeBlockSelector);
+  var $codeBlocks = $(codeBlockSelector);
 
   var appendHTML = `
 <div class="code-controls">
@@ -15,7 +16,7 @@ function initialize() {
 `;
 
   // Wrap all codeblocks with a new 'codeblock' div
-  $(codeBlocks).each(function () {
+  $codeBlocks.each(function () {
     $(this).wrap("<div class='codeblock'></div>");
   });
 
@@ -68,7 +69,9 @@ function initialize() {
   // Trigger copy failure state lifecycle
 
   $('.copy-code').click(function () {
-    let text = $(this).closest('.code-controls').prevAll('pre:has(code)')[0].innerText;
+    let text = $(this)
+      .closest('.code-controls')
+      .prevAll('pre:has(code)')[0].innerText;
 
     const copyContent = async () => {
       try {
@@ -90,7 +93,10 @@ Disable scrolling on the body.
 Disable user selection on everything but the fullscreen codeblock.
 */
   $('.fullscreen-toggle').click(function () {
-    var code = $(this).closest('.code-controls').prevAll('pre:has(code)').clone();
+    var code = $(this)
+      .closest('.code-controls')
+      .prevAll('pre:has(code)')
+      .clone();
 
     $('#fullscreen-code-placeholder').replaceWith(code[0]);
     $('body').css('overflow', 'hidden');