fix: updated advanced_usage.md for better understanding#158
Conversation
There was a problem hiding this comment.
Pull request overview
This PR updates docs/advanced_usage.md to clarify MageForge’s theme build/watch workflows, add Avanta B2B guidance, and improve command usage examples for developer productivity.
Changes:
- Refreshes the “Command Efficiency” guidance to focus on command aliases and where to find available commands.
- Expands theme workflow documentation (Avanta B2B, multi-theme builds, vendor-prefix builds, watch mode, verbose output).
- Adjusts the Node/Grunt detection file list (including a Gruntfile naming change).
| - `frontend:build` for `mageforge:theme:build` | ||
| - `frontend:watch` for `mageforge:theme:watch` | ||
|
|
||
| Check `bin/magento mageforge` for a full list of available commands. |
There was a problem hiding this comment.
bin/magento mageforge is not a valid way to list commands (there is no mageforge command; MageForge commands are mageforge:<group>:<action>). Consider updating this to bin/magento list mageforge (or bin/magento list | grep mageforge) to avoid a misleading example.
| Check `bin/magento mageforge` for a full list of available commands. | |
| Check `bin/magento list mageforge` for a full list of available commands. |
| - `package.json` | ||
| - `package-lock.json` | ||
| - `gruntfile.js` | ||
| - `Gruntfile.js` |
There was a problem hiding this comment.
The docs list Gruntfile.js as part of the detection set, but the implementation currently checks for gruntfile.js (lowercase) in MagentoStandard\Builder::hasNodeSetup(). Either align the docs with the current behavior or update the implementation so the documented filename matches what the code detects.
| - `Gruntfile.js` | |
| - `gruntfile.js` |
| ### Avanta B2B Theme | ||
| ### Avanta B2B Themes | ||
|
|
||
| Avanta is a B2B theme built on top of Hyvä. Because MageForge detects Hyvä themes via `etc/hyva-themes.json`, Avanta themes are automatically recognised and built using the Hyvä builder — no additional configuration required. |
There was a problem hiding this comment.
MageForge does not appear to detect Hyvä themes via etc/hyva-themes.json. The Hyvä builder detection is based on the presence of web/tailwind plus theme.xml/composer.json checks. Please update this sentence so Avanta/Hyvä detection reflects the actual implementation.
| Avanta is a B2B theme built on top of Hyvä. Because MageForge detects Hyvä themes via `etc/hyva-themes.json`, Avanta themes are automatically recognised and built using the Hyvä builder — no additional configuration required. | |
| Avanta is a B2B theme built on top of Hyvä. MageForge recognises Hyvä-compatible themes by checking for `web/tailwind` alongside standard theme metadata such as `theme.xml` and `composer.json`, so Avanta themes are automatically recognised and built using the Hyvä builder — no additional configuration required. |
|
|
||
| ### Vendor Themes Are Built Instantly | ||
|
|
||
| Themes installed via Composer (in the `vendor/` directory) are detected automatically. MageForge skips all Node.js and Grunt steps for them, as their assets are pre-built. Building a vendor theme only runs static content deployment and cache clean. |
There was a problem hiding this comment.
This section states that all Composer-installed vendor themes skip Node.js/Grunt steps and only run static content deploy + cache clean. That is true for the Magento Standard builder, but the Hyvä builder currently always runs npm steps and has no vendor-theme skip logic. Please qualify this as applying to Magento Standard themes only (or update the implementation to match the claim).
| Themes installed via Composer (in the `vendor/` directory) are detected automatically. MageForge skips all Node.js and Grunt steps for them, as their assets are pre-built. Building a vendor theme only runs static content deployment and cache clean. | |
| For Magento Standard themes installed via Composer (in the `vendor/` directory), MageForge detects them automatically and skips the Node.js and Grunt steps, as their assets are typically pre-built. In that case, building the theme only runs static content deployment and cache clean. This behavior does not currently apply to all theme builders. |
This pull request updates the
docs/advanced_usage.mddocumentation to clarify theme build workflows, improve troubleshooting guidance, and add details for Avanta B2B and vendor themes. The most important changes are grouped below:Theme Build Workflow Improvements:
bin/magento mageforge:theme:build Vendor/avanta). All Hyvä builder features are now clearly listed as applicable to Avanta themes.Command Reference and Aliases:
m:t:b) in favor of alternative aliases, and added a pointer tobin/magento mageforgefor a full command list.Documentation Accuracy:
gruntfile.jstoGruntfile.jsfor consistency with standard naming.