Skip to content

fix: updated advanced_usage.md for better understanding#158

Merged
dermatz merged 1 commit intomainfrom
fix/update-advanced-usage.md
Apr 10, 2026
Merged

fix: updated advanced_usage.md for better understanding#158
dermatz merged 1 commit intomainfrom
fix/update-advanced-usage.md

Conversation

@dermatz
Copy link
Copy Markdown
Member

@dermatz dermatz commented Apr 10, 2026

This pull request updates the docs/advanced_usage.md documentation 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:

  • Expanded documentation for Avanta B2B themes, explaining automatic Hyvä detection and usage instructions for building Avanta themes with MageForge (bin/magento mageforge:theme:build Vendor/avanta). All Hyvä builder features are now clearly listed as applicable to Avanta themes.
  • Added instructions for building multiple themes in a single command and for building all themes from a vendor prefix, improving developer efficiency.
  • Added explanation and usage examples for watch mode to speed up development feedback loops.
  • Clarified that vendor themes installed via Composer are detected and built instantly, skipping Node.js and Grunt steps.
  • Documented that themes without Node.js/Grunt files skip the Node.js pipeline for faster builds.

Command Reference and Aliases:

  • Removed references to shortcodes (e.g., m:t:b) in favor of alternative aliases, and added a pointer to bin/magento mageforge for a full command list.

Documentation Accuracy:

  • Fixed case error in file listing for Grunt detection, changing gruntfile.js to Gruntfile.js for consistency with standard naming.

Copilot AI review requested due to automatic review settings April 10, 2026 06:26
@github-actions github-actions bot added the documentation Improvements or additions to documentation label Apr 10, 2026
@dermatz dermatz merged commit 956efe4 into main Apr 10, 2026
8 checks passed
@dermatz dermatz deleted the fix/update-advanced-usage.md branch April 10, 2026 06:27
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Comment thread docs/advanced_usage.md
- `frontend:build` for `mageforge:theme:build`
- `frontend:watch` for `mageforge:theme:watch`

Check `bin/magento mageforge` for a full list of available commands.
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
Check `bin/magento mageforge` for a full list of available commands.
Check `bin/magento list mageforge` for a full list of available commands.

Copilot uses AI. Check for mistakes.
Comment thread docs/advanced_usage.md
- `package.json`
- `package-lock.json`
- `gruntfile.js`
- `Gruntfile.js`
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- `Gruntfile.js`
- `gruntfile.js`

Copilot uses AI. Check for mistakes.
Comment thread docs/advanced_usage.md
### 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.
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.
Comment thread docs/advanced_usage.md

### 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.
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
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.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants