From ab5fc3ce955f8d56fc857f923eaf76bc99c548fe Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Thu, 28 May 2026 13:32:28 +0000 Subject: [PATCH 01/11] Add documentation for building CSS and frontend assets Document the SCSS build workflow using SymfonyCasts Sass Bundle that replaces the previous Grunt/LESS approach. Covers development commands (sass:build, sass:watch), production asset generation, Bootstrap source location, and Symfony Asset Mapper architecture. --- .../building_assets.rst | 52 +++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 53 insertions(+) create mode 100644 docs/development-environment/building_assets.rst diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst new file mode 100644 index 00000000..05101763 --- /dev/null +++ b/docs/development-environment/building_assets.rst @@ -0,0 +1,52 @@ +Building CSS and frontend assets +################################ + +Mautic uses SCSS for styling core UI components and the SymfonyCasts Sass Bundle to compile them during development and for production builds. + +Building SCSS during development +================================ + +To compile Sass files, run: + +.. code-block:: bash + + composer sass:build + +To automatically rebuild on file changes during development: + +.. code-block:: bash + + composer sass:watch + +The SCSS source files live in ``app/bundles/CoreBundle/Assets/css/``. The watch command recompiles when files in this directory change. + +Building assets for production +============================== + +To build all frontend assets for production: + +.. code-block:: bash + + composer generate-assets + +This builds the Sass files, compiles Asset Mapper assets, and generates minified CSS and JavaScript files in the ``media/`` directory. + +You can also run the console command directly: + +.. code-block:: bash + + bin/console mautic:assets:generate + +Running ``composer install`` automatically compiles the Sass files, so fresh installations include built CSS by default. + +Bootstrap framework +=================== + +Mautic uses Bootstrap 3.4.1 for its UI framework. The Bootstrap source files come from the ``twbs/bootstrap-sass`` Composer package and are available for importing in your SCSS files. + +Asset architecture +================== + +Mautic uses Symfony Asset Mapper and Importmap for managing frontend JavaScript modules. The Asset Mapper configuration lives in ``app/config/config.php`` and the import map in ``importmap.php``. + +Compiled CSS outputs to ``var/sass/``. Asset Mapper serves it through Symfony's asset system in development. Production builds copy finalized assets to ``media/css/``. diff --git a/docs/index.rst b/docs/index.rst index d238be96..b5421089 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,6 +67,7 @@ There are several ways to support Mautic other than contributing with code. development-environment/how_to_install_with_ddev development-environment/setup development-environment/environments + development-environment/building_assets .. toctree:: :maxdepth: 2 From a580392063fab362b3c54a737a7c70ded57238fb Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Sun, 31 May 2026 13:25:33 +0000 Subject: [PATCH 02/11] Address PR review feedback on asset documentation - Capitalize "Assets" when referring to Mautic feature - Capitalize "UI Components" in intro text - Add vale off/on directives around SCSS heading and general asset text - Replace "recompiles" with "rebuilds CSS automatically" - Clarify Asset Mapper compilation output locations --- .../building_assets.rst | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index 05101763..b7587eac 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -1,11 +1,15 @@ -Building CSS and frontend assets -################################ +Building CSS and frontend Assets +################################# -Mautic uses SCSS for styling core UI components and the SymfonyCasts Sass Bundle to compile them during development and for production builds. +Mautic uses SCSS for styling core UI Components and the SymfonyCasts Sass Bundle to compile them during development and for production builds. + +.. vale off Building SCSS during development ================================ +.. vale on + To compile Sass files, run: .. code-block:: bash @@ -18,18 +22,18 @@ To automatically rebuild on file changes during development: composer sass:watch -The SCSS source files live in ``app/bundles/CoreBundle/Assets/css/``. The watch command recompiles when files in this directory change. +The SCSS source files live in ``app/bundles/CoreBundle/Assets/css/``. The watch command rebuilds CSS automatically when files in this directory change. -Building assets for production +Building Assets for production ============================== -To build all frontend assets for production: +To build all frontend Assets for production: .. code-block:: bash composer generate-assets -This builds the Sass files, compiles Asset Mapper assets, and generates minified CSS and JavaScript files in the ``media/`` directory. +This builds the Sass files, compiles Assets through Asset Mapper to ``var/assets/`` and ``public/assets/``, and generates minified CSS and JavaScript files in the ``media/`` directory. You can also run the console command directly: @@ -49,4 +53,8 @@ Asset architecture Mautic uses Symfony Asset Mapper and Importmap for managing frontend JavaScript modules. The Asset Mapper configuration lives in ``app/config/config.php`` and the import map in ``importmap.php``. +.. vale off + Compiled CSS outputs to ``var/sass/``. Asset Mapper serves it through Symfony's asset system in development. Production builds copy finalized assets to ``media/css/``. + +.. vale on From b92bb652c031e1d8784a20701ca343366fd5e6ea Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Sun, 31 May 2026 13:29:24 +0000 Subject: [PATCH 03/11] Add vale directives around Building Assets heading Address reviewer feedback to add vale off/on around the "Building Assets for production" heading. --- docs/development-environment/building_assets.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index b7587eac..99700f49 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -24,9 +24,13 @@ To automatically rebuild on file changes during development: The SCSS source files live in ``app/bundles/CoreBundle/Assets/css/``. The watch command rebuilds CSS automatically when files in this directory change. +.. vale off + Building Assets for production ============================== +.. vale on + To build all frontend Assets for production: .. code-block:: bash From ccf05dc5b974c96957a4c9f643c19a5509353372 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Sun, 31 May 2026 13:40:19 +0000 Subject: [PATCH 04/11] Add vale directives around Importmap term Wrap the Asset architecture section heading and the paragraph containing "Importmap" with vale off/on directives to suppress the Vale spelling error. --- docs/development-environment/building_assets.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index 99700f49..5eeeedf5 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -52,11 +52,19 @@ Bootstrap framework Mautic uses Bootstrap 3.4.1 for its UI framework. The Bootstrap source files come from the ``twbs/bootstrap-sass`` Composer package and are available for importing in your SCSS files. +.. vale off + Asset architecture ================== +.. vale on + +.. vale off + Mautic uses Symfony Asset Mapper and Importmap for managing frontend JavaScript modules. The Asset Mapper configuration lives in ``app/config/config.php`` and the import map in ``importmap.php``. +.. vale on + .. vale off Compiled CSS outputs to ``var/sass/``. Asset Mapper serves it through Symfony's asset system in development. Production builds copy finalized assets to ``media/css/``. From 97ff276d92552ae221a8351d64a0aed7eec6e2e2 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Sun, 31 May 2026 13:44:55 +0000 Subject: [PATCH 05/11] Add Importmap to Vale vocabulary and remove vale directives Add "Importmap" to the Vale accept.txt vocabulary file since it's a standard web/Symfony technical term. Remove the vale off/on statements that were wrapping references to Importmap in the building_assets.rst documentation. --- .github/styles/config/vocabularies/Mautic/accept.txt | 1 + docs/development-environment/building_assets.rst | 8 -------- 2 files changed, 1 insertion(+), 8 deletions(-) diff --git a/.github/styles/config/vocabularies/Mautic/accept.txt b/.github/styles/config/vocabularies/Mautic/accept.txt index 8593017e..0365859e 100644 --- a/.github/styles/config/vocabularies/Mautic/accept.txt +++ b/.github/styles/config/vocabularies/Mautic/accept.txt @@ -76,6 +76,7 @@ HTTPS HubSpot IDP IMAP +Importmap infographics Initialisms initialisms diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index 5eeeedf5..9f881156 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -59,14 +59,6 @@ Asset architecture .. vale on -.. vale off - Mautic uses Symfony Asset Mapper and Importmap for managing frontend JavaScript modules. The Asset Mapper configuration lives in ``app/config/config.php`` and the import map in ``importmap.php``. -.. vale on - -.. vale off - Compiled CSS outputs to ``var/sass/``. Asset Mapper serves it through Symfony's asset system in development. Production builds copy finalized assets to ``media/css/``. - -.. vale on From 91cb571622e7f1012d5243e25c15ad728521547c Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Fri, 5 Jun 2026 13:31:39 +0000 Subject: [PATCH 06/11] Fix capitalization: use lowercase 'assets' for Symfony frontend assets All uses of 'asset' in building_assets.rst refer to Symfony's Asset Mapper and generic frontend assets (CSS, JavaScript files), not Mautic's Asset feature (downloadable marketing files). Use lowercase consistently per reviewer feedback. Renamed the 'Asset architecture' section to 'Asset Mapper architecture' for clarity. --- docs/development-environment/building_assets.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index 9f881156..29b9a271 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -1,4 +1,4 @@ -Building CSS and frontend Assets +Building CSS and frontend assets ################################# Mautic uses SCSS for styling core UI Components and the SymfonyCasts Sass Bundle to compile them during development and for production builds. @@ -26,18 +26,18 @@ The SCSS source files live in ``app/bundles/CoreBundle/Assets/css/``. The watch .. vale off -Building Assets for production +Building assets for production ============================== .. vale on -To build all frontend Assets for production: +To build all frontend assets for production: .. code-block:: bash composer generate-assets -This builds the Sass files, compiles Assets through Asset Mapper to ``var/assets/`` and ``public/assets/``, and generates minified CSS and JavaScript files in the ``media/`` directory. +This builds the Sass files, compiles assets through Asset Mapper to ``var/assets/`` and ``public/assets/``, and generates minified CSS and JavaScript files in the ``media/`` directory. You can also run the console command directly: @@ -54,8 +54,8 @@ Mautic uses Bootstrap 3.4.1 for its UI framework. The Bootstrap source files com .. vale off -Asset architecture -================== +Asset Mapper architecture +========================= .. vale on From 84aea562ab24c2df3f14887e33bccf0f1b99ac43 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Fri, 5 Jun 2026 14:10:05 +0000 Subject: [PATCH 07/11] Wrap assets paragraph with vale off/on per reviewer request Adds vale directives to suppress linting for the paragraph where "assets" refers to generic Symfony frontend assets rather than Mautic's downloadable files feature. --- docs/development-environment/building_assets.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index 29b9a271..11c2f303 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -61,4 +61,8 @@ Asset Mapper architecture Mautic uses Symfony Asset Mapper and Importmap for managing frontend JavaScript modules. The Asset Mapper configuration lives in ``app/config/config.php`` and the import map in ``importmap.php``. +.. vale off + Compiled CSS outputs to ``var/sass/``. Asset Mapper serves it through Symfony's asset system in development. Production builds copy finalized assets to ``media/css/``. + +.. vale on From 32aad1d10660f8629198ce1de21e1d888bd89fef Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Mon, 22 Jun 2026 15:42:47 +0000 Subject: [PATCH 08/11] Document offline.css compatibility stylesheet from SCSS production build --- docs/development-environment/building_assets.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index 11c2f303..f9c31dc9 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -47,6 +47,8 @@ You can also run the console command directly: Running ``composer install`` automatically compiles the Sass files, so fresh installations include built CSS by default. +The production build also generates ``css/offline.css``, a compatibility stylesheet that combines the compiled Sass output with ``app.css``. Standalone pages that can't load assets through Asset Mapper's normal page head, such as the offline page, link to this single stylesheet directly. + Bootstrap framework =================== From 45229baaf74f31617abbe3832e1202177f0c8367 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Mon, 22 Jun 2026 15:57:26 +0000 Subject: [PATCH 09/11] Wrap asset build prose in Vale suppression markers per review --- docs/development-environment/building_assets.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index f9c31dc9..b48cd57f 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -31,14 +31,22 @@ Building assets for production .. vale on +.. vale off + To build all frontend assets for production: +.. vale on + .. code-block:: bash composer generate-assets +.. vale off + This builds the Sass files, compiles assets through Asset Mapper to ``var/assets/`` and ``public/assets/``, and generates minified CSS and JavaScript files in the ``media/`` directory. +.. vale on + You can also run the console command directly: .. code-block:: bash @@ -47,7 +55,11 @@ You can also run the console command directly: Running ``composer install`` automatically compiles the Sass files, so fresh installations include built CSS by default. -The production build also generates ``css/offline.css``, a compatibility stylesheet that combines the compiled Sass output with ``app.css``. Standalone pages that can't load assets through Asset Mapper's normal page head, such as the offline page, link to this single stylesheet directly. +.. vale off + +The production build also generates ``css/offline.css``, a compatibility stylesheet that combines the compiled Sass output with ``app.css``. Standalone pages that can't load assets through Asset Mapper's normal page head, such as the offline page, link to this single style sheet directly. + +.. vale on Bootstrap framework =================== From 21d1343ababe0c255b47e266937e74c0b9d89291 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Fri, 17 Jul 2026 09:04:58 +0000 Subject: [PATCH 10/11] Suppress FeatureList false positive on build-assets title Address @adiati98 review: the Mautic.FeatureList rule flags 'assets' in the page title, but here it means compiled frontend build output, not the Mautic Asset feature. A '.. vale off' block alone couldn't scope the document's H1 (Vale promotes the first title to the doc title), so add a leading RST comment inside the suppressed region so the '.. vale off'/'.. vale on' pair covers the title. Vale is now clean on the file. --- docs/development-environment/building_assets.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index b48cd57f..25ee48fd 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -1,6 +1,15 @@ +.. vale off + +.. + + 'assets' in the title below refers to compiled frontend build output, not the + Mautic Asset feature, so the Mautic.FeatureList substitution rule is suppressed here. + Building CSS and frontend assets ################################# +.. vale on + Mautic uses SCSS for styling core UI Components and the SymfonyCasts Sass Bundle to compile them during development and for production builds. .. vale off From d76b27a7a1afd0430be2921fabccf629246d7815 Mon Sep 17 00:00:00 2001 From: "promptless[bot]" Date: Fri, 17 Jul 2026 09:45:14 +0000 Subject: [PATCH 11/11] Address review: remove note, reword title to avoid FeatureList false positive Remove the explanatory RST comment note per @adiati98's request. A .. vale off on the first line of the file does not suppress the Mautic.FeatureList finding on 'assets' in the H1 title (reproduced on Vale 3.7.1 and 3.15.1), which is why the note was priming it. Reword the title to 'Building CSS and frontend files' so it no longer trips the rule, dropping the note and the ineffective top wrap. All other generic 'assets' prose stays lowercase inside working vale off/on blocks. --- docs/development-environment/building_assets.rst | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/docs/development-environment/building_assets.rst b/docs/development-environment/building_assets.rst index 25ee48fd..239db11b 100644 --- a/docs/development-environment/building_assets.rst +++ b/docs/development-environment/building_assets.rst @@ -1,14 +1,5 @@ -.. vale off - -.. - - 'assets' in the title below refers to compiled frontend build output, not the - Mautic Asset feature, so the Mautic.FeatureList substitution rule is suppressed here. - -Building CSS and frontend assets -################################# - -.. vale on +Building CSS and frontend files +############################### Mautic uses SCSS for styling core UI Components and the SymfonyCasts Sass Bundle to compile them during development and for production builds.