[TASK] Introduce grunt command for debugging

Author: linawolf

.ddev/commands/web/npm-build

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+cd packages/typo3-docs-theme
+npm run build

.ddev/commands/web/npm-ci

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+cd packages/typo3-docs-theme
+npm ci

.ddev/commands/web/npm-debug

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+cd packages/typo3-docs-theme
+npm run debug

Documentation/Developer/ThemeCustomization.rst

@@ -40,6 +40,39 @@ To build the public assets execute the following commands:
     npm ci
     npm run build
 
+Or use the custom ddev commands:
+
+..  code-block:: shell
+
+    ddev npm-ci
+    ddev npm-build
+
+
+Debug assets
+============
+
+You can build the assets for debugging with the following commands:
+
+..  code-block:: shell
+
+    ddev ssh
+    cd packages/typo3-docs-theme
+    npm ci
+    npm run debug
+
+Or use the custom ddev commands:
+
+..  code-block:: shell
+
+    ddev npm-ci
+    ddev npm-debug
+
+The generated assets are copied directly into :file:`Documentation-GENERATED-temp/_resources`
+and source maps are not removed. Upon inspection in the browsers web developer
+tools you can therefore see in which source scss file certain styles were
+defined. Before committing you must run :shell:`npm run build` so that you can
+commit the generated asset files into the theme.
+
 
 ..  _Bootstrap: https://getbootstrap.com/
 ..  _phpDocumentor/guides: https://github.com/phpDocumentor/guides

packages/typo3-docs-theme/Gruntfile.js

@@ -30,7 +30,8 @@ module.exports = function (grunt) {
     pkg: grunt.file.readJSON('package.json'),
     paths: {
       source: 'assets/',
-      output: 'resources/public/'
+      output: 'resources/public/',
+      debugDestination: '../../Documentation-GENERATED-temp/_resources/',
     },
 
     // copy
@@ -76,7 +77,18 @@ module.exports = function (grunt) {
             dest: '<%= paths.output %>js/bootstrap.min.js'
           }
         ]
-      }
+      },
+
+      debug: {
+        files: [
+          {
+            expand: true,
+            cwd: '<%= paths.source %>', // Adjust the source directory
+            src: ['**/*'],
+            dest: '<%= paths.debugDestination %>', // Use the debug destination variable
+          },
+        ],
+      },
     },
 
     // stylelint
@@ -102,6 +114,18 @@ module.exports = function (grunt) {
           '<%= paths.output %>css/theme.css': '<%= paths.source %>sass/theme.scss',
           '<%= paths.output %>css/webfonts.css': '<%= paths.source %>sass/webfonts.scss'
         }
+      },
+
+      debug: {
+        options: {
+          sourceMap: true, // Enable sourcemaps for debugging
+        },
+        files: {
+          '<%= paths.debugDestination %>css/codeblock.css': '<%= paths.source %>sass/codeblock.scss',
+          '<%= paths.debugDestination %>css/fontawesome.css': '<%= paths.source %>sass/fontawesome.scss',
+          '<%= paths.debugDestination %>css/theme.css': '<%= paths.source %>sass/theme.scss',
+          '<%= paths.debugDestination %>css/webfonts.css': '<%= paths.source %>sass/webfonts.scss'
+        }
       }
     },
 
@@ -174,4 +198,5 @@ module.exports = function (grunt) {
   grunt.registerTask('default', ['clean', 'update', 'stylelint', 'sass', 'js', 'removesourcemap']);
   grunt.registerTask('build', ['default']);
   grunt.registerTask('render', ['clean:build']);
+  grunt.registerTask('debug', ['clean', 'update', 'stylelint', 'sass:debug', 'js', 'copy:debug', 'removesourcemap']);
 };

packages/typo3-docs-theme/package.json

@@ -21,7 +21,8 @@
         "stylelint": "^15.11.0"
     },
     "scripts": {
-        "build": "grunt build"
+        "build": "grunt build",
+        "debug": "grunt debug"
     },
     "engines": {
         "node": ">=18.15.0 <21.0.0"