fix(ci): Disable unnecessary SCSS processing when building JS assets.

- Build resources if not cached
- Ensure node_modules dependencies are available for asset processing
- Be more precise in the template when building assets in production mode and avoid conflicts with SCSS and CSS processing.
- Ignore node_modules when loading source maps
- Add .vscode/launch.json with debugging configuration for localhost:1313. In VSCode, go to Run and select the site to launch Chrome, connect to Developer Tools, and start debugging.
- Add support for debugging in VS Code without using source maps. Adds a debug helpers module for developers to use in IDE debugging and interact with the browser console. This is a workaround for lack of good source map support with js.Build and the Hugo asset pipeline.

Background:
Hugo and js.Build don't have good support for external source maps.
Internal source mapping is also unreliable; the base64 in the source map reference for some files is too long for the browser console to keep on 1 line--remaining characters are printed on the next line, resulting in a syntax error.

Author: jstirnaman

.circleci/config.yml

@@ -1,4 +1,4 @@
-version: 2
+version: 2.1
 jobs:
   build:
     docker:
@@ -68,7 +68,6 @@ jobs:
           when: on_success
 
 workflows:
-  version: 2
   build:
     jobs:
       - build

.gitignore

@@ -21,6 +21,7 @@ node_modules
 test-results.xml
 /influxdb3cli-build-scripts/content
 .vscode/*
+!.vscode/launch.json
 .idea
 **/config.toml
 package-lock.json

.vscode/launch.json

@@ -0,0 +1,18 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Docs (console-based)",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:1313",
+      "webRoot": "${workspaceFolder}",
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
+      "sourceMaps": false,
+      "trace": true,
+      "smartStep": false
+    }
+  ]
+}

assets/js/utils/debug-helpers.js

@@ -0,0 +1,38 @@
+/**
+ * Helper functions for debugging without source maps
+ * Example usage:
+ * In your code, you can use these functions like this:
+ * ```javascript
+ * import { debugLog, debugBreak, debugInspect } from './debug-helpers.js';
+ *
+ * const data = debugInspect(someData, 'Data');
+ * debugLog('Processing data', 'myFunction');
+ *
+ * function processData() {
+ *   // Add a breakpoint that works with DevTools
+ *   debugBreak();
+ *
+ *   // Your existing code...
+ * }
+ * ```
+ *
+ * @fileoverview DEVELOPMENT USE ONLY - Functions should not be committed to production
+ */
+
+/* eslint-disable no-debugger */
+/* eslint-disable-next-line */
+// NOTE: These functions are detected by ESLint rules to prevent committing debug code
+
+export function debugLog(message, context = '') {
+  const contextStr = context ? `[${context}]` : '';
+  console.log(`DEBUG${contextStr}: ${message}`);
+}
+
+export function debugBreak() {
+  debugger;
+}
+
+export function debugInspect(value, label = 'Inspect') {
+  console.log(`DEBUG[${label}]:`, value);
+  return value;
+}

config/production/config.yml

@@ -16,10 +16,25 @@ minify:
 # Production asset processing
 build:
   writeStats: false
-  useResourceCacheWhen: "always"
+  useResourceCacheWhen: "fallback"
   buildOptions:
     sourcemap: false
     target: "es2015"
 
+# Asset processing configuration
+assetDir: "assets"
+
+# Mount assets for production
+module:
+  mounts:
+    - source: assets
+      target: assets
+    - source: node_modules
+      target: assets/node_modules
+
 # Disable development server settings
-server: {}
+server: {}
+
+# Suppress the warning mentioned in the error
+ignoreLogs:
+  - 'warning-goldmark-raw-html'

config/testing/config.yml

@@ -15,29 +15,6 @@ preserveTaxonomyNames: true
 # Generate a robots.txt
 enableRobotsTXT: true
 
-# Override settings for testing
-buildFuture: true
-
-# Configure what content is built in testing env
-params:
-  env: testing
-  environment: testing
-  buildTestContent: true
-
-# Server configuration for testing
-server:
-  port: 1315
-  baseURL: 'http://localhost:1315/'
-  watchChanges: true
-  disableLiveReload: false
-
-# Keep your shared content exclusions
-ignoreFiles:
-  - "content/shared/.*"
-
-# Ignore specific warning logs
-ignoreLogs:
-  - warning-goldmark-raw-html
 
 # Markdown rendering options
 blackfriday:
@@ -55,7 +32,6 @@ taxonomies:
   influxdb3/enterprise/tag: influxdb3/enterprise/tags
   flux/v0/tag: flux/v0/tags
 
-# Markup configuration
 markup:
   goldmark:
     renderer:
@@ -66,7 +42,6 @@ markup:
       attribute:
         block: true
 
-# Privacy settings
 privacy:
   googleAnalytics:
     anonymizeIP: false
@@ -77,7 +52,6 @@ privacy:
     disable: false
     privacyEnhanced: true
 
-# Output formats
 outputFormats:
   json:
     mediaType: application/json
@@ -86,26 +60,47 @@ outputFormats:
 
 # Asset processing for testing (disable minification)
 build:
-  writeStats: true
+  writeStats: false
   useResourceCacheWhen: "fallback"
-  buildOptions:
-    sourcemap: "inline"
-    target: "es2020"
-
-# Disable minification for testing
-minify:
-  disableJS: true
-  disableCSS: true
-  disableHTML: true
-  minifyOutput: false
+  noJSConfigInAssets: false
 
 # Asset processing configuration
 assetDir: "assets"
 
-# Module mounts
 module:
   mounts:
     - source: assets
       target: assets
     - source: node_modules
-      target: assets/node_modules
+      target: assets/node_modules
+
+# Override settings for testing
+buildFuture: true
+
+# Configure what content is built in testing env
+params:
+  env: testing
+  environment: testing
+  buildTestContent: true
+
+# Configure the server for testing
+server:
+  port: 1315
+  baseURL: 'http://localhost:1315/'
+  watchChanges: true
+  disableLiveReload: false
+
+# Keep your shared content exclusions
+ignoreFiles:
+  - "content/shared/.*"
+
+# Ignore specific warning logs
+ignoreLogs:
+  - warning-goldmark-raw-html
+
+# Disable minification for testing
+minify:
+  disableJS: true
+  disableCSS: true
+  disableHTML: true
+  minifyOutput: false

eslint.config.js

@@ -106,6 +106,33 @@ export default [
     files: ['assets/js/**/*.js'],
     rules: {
       // Rules specific to JavaScript in Hugo assets
+      // Prevent imports from debug-helpers.js
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [
+            {
+              name: './utils/debug-helpers.js',
+              message:
+                'Remove debugging functions before committing. Debug helpers should not be used in production code.',
+            },
+            {
+              name: '/utils/debug-helpers.js',
+              message:
+                'Remove debugging functions before committing. Debug helpers should not be used in production code.',
+            },
+          ],
+        },
+      ],
+      // Prevent use of debug functions in production code
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'CallExpression[callee.name=/^debug(Log|Break|Inspect)$/]',
+          message:
+            'Remove debugging functions before committing. Debug helpers should not be used in production code.',
+        },
+      ],
     },
   },
   {

hugo.yml

@@ -49,6 +49,7 @@ privacy:
   youtube:
     disable: false
     privacyEnhanced: true
+
 outputFormats:
   json:
     mediaType: application/json
@@ -57,13 +58,8 @@ outputFormats:
 
 # Asset processing configuration for development
 build:
-  writeStats: true
+  writeStats: false 
   useResourceCacheWhen: "fallback"
-  # Enable source maps for debugging
-  buildOptions:
-    sourcemap: "inline"
-    target: "es2020"
-  # Disable asset bundling in development
   noJSConfigInAssets: false
 
 # Asset processing configuration
@@ -82,14 +78,17 @@ params:
   environment: development
 
 # Configure the server for development
-# Specify the port for development to avoid conflicts with testing
 server:
   port: 1313
   baseURL: 'http://localhost:1313/'
   watchChanges: true
   disableLiveReload: false
 
-# Disable minification and bundling for development
+# Ignore specific warning logs
+ignoreLogs:
+  - warning-goldmark-raw-html
+
+# Disable minification for development
 minify:
   disableJS: true
   disableCSS: true