gethinode
diff --git a/‎.gitignore‎
Lines changed: 2 additions & 0 deletions b/‎.gitignore‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 180 additions & 69 deletions b/‎CLAUDE.md‎
Lines changed: 180 additions & 69 deletions
diff --git a/‎README.md‎
Lines changed: 19 additions & 4 deletions b/‎README.md‎
Lines changed: 19 additions & 4 deletions
@@ -4,6 +4,8 @@ node_modules/
 exampleSite/public
 exampleSite/resources
 _vendor/
+dist/
+data/fa-icons.yml
 
 .DS_store
 .hugo_build.lock
 
@@ -4,13 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-This is a Hugo module that provides Font Awesome icon integration for Hinode sites. It automatically fetches Font Awesome SVG files during installation and exposes them through Hugo shortcodes (`{{< icon >}}`, `{{< fa >}}`, `{{< fab >}}`, `{{< fas >}}`). The module supports both inline SVG embedding and web font approaches.
+This is a Hugo module that provides Font Awesome icon integration for Hinode sites using FontAwesome's official SVG+JS approach. The module supports both SVG rendering (using FontAwesome JavaScript) and webfont rendering (using FontAwesome CSS).
+
+**Version 4.0 Changes:** This module now uses FontAwesome's official SVG+JS architecture and mounts directly from node_modules. No more dist/ folder or build scripts.
 
 ## Development Commands
 
 ### Setup and Installation
 ```bash
-npm install              # Install dependencies and copy Font Awesome files to dist/
+npm install              # Install dependencies (FontAwesome is in node_modules)
 npm run mod:vendor      # Vendor Hugo modules into _vendor/
 npm run mod:tidy        # Tidy up Hugo modules
 ```
@@ -24,7 +26,6 @@ npm run clean           # Clean generated files (public/, resources/)
 
 ### Maintenance
 ```bash
-npm run meta            # Regenerate fa-icons.yml metadata file (run after updating Font Awesome)
 npm run mod:update      # Update all dependencies and Hugo modules
 npm run upgrade         # Check and update all npm packages
 npm test                # Build site (validates configuration and templates)
@@ -39,34 +40,78 @@ npx git-cz              # Prepare commit message (enforces Conventional Commits)
 
 ## Architecture
 
-### Key Components
+### Rendering Modes
+
+**SVG Mode (inline=true):**
+- Uses FontAwesome's official SVG+JS approach
+- Partial at `layouts/_partials/footer/fontawesome-js.html` loads FontAwesome JS files
+- Loads fontawesome.min.js + icon set JS files based on `styles` parameter
+- Icons output as `<i class="fas fa-heart"></i>` markup
+- FontAwesome JS converts to SVG at runtime in browser
+- Proper scaling, sizing, accessibility handled by FontAwesome
+
+**Webfont Mode (inline=false):**
+- Uses FontAwesome webfonts
+- Loads FontAwesome CSS files
+- Icons output as `<i class="fas fa-heart"></i>` markup
+- Rendered as webfonts via CSS (::before pseudo-elements)
+
+### Multi-Library Support
 
-**Font Awesome Integration:**
-- Font Awesome source files are downloaded as npm dependency (`@fortawesome/fontawesome-free`)
-- During `npm install`, post-install scripts copy SVG files to `dist/svgs/` organized by family (fas, fa, fab)
-- The `meta.sh` script generates `data/fa-icons.yml` listing all available icons
+The icon.html partial supports multiple icon libraries:
 
-**Hugo Module Structure:**
-- `layouts/_shortcodes/` - Public shortcodes users can call
-- `layouts/_partials/assets/icon.html` - Core logic for icon rendering (handles both inline SVG and web font modes)
-- `data/structures/icon.yml` - Argument validation schema for shortcodes
-- `dist/svgs/` - Font Awesome SVG files (organized as `{family}-{icon-name}.svg`)
-- `dist/scss/` - Font Awesome SCSS files (optional, for web font approach)
-- `_vendor/` - Vendored Hugo dependencies (created at build time)
+1. **FontAwesome (fas, fa, fab):** Always outputs `<i>` tags - rendered by FontAwesome JS or CSS
+2. **Bootstrap Icons (bi) and other libraries:**
+   - `inline=true`: Static SVG loaded from `assets/svgs/{family}/{name}.svg`
+   - `inline=false`: `<i>` tag rendered as webfont
+3. **Custom SVGs:** Always loaded via `resources.Get` using `src` parameter
+
+### Hugo Mounts
+
+The module mounts directly from node_modules (no build/copy step):
+- **SCSS:** `node_modules/@fortawesome/fontawesome-free/scss` → `assets/scss/modules/fontawesome`
+- **Webfonts:** `node_modules/@fortawesome/fontawesome-free/webfonts` → `static/webfonts`
+- **JS:** `node_modules/@fortawesome/fontawesome-free/js` → `static/js/fontawesome` (minified files only)
+
+This approach:
+- ✅ No dist/ folder to maintain
+- ✅ No postinstall build scripts
+- ✅ Smaller git repository
+- ✅ Direct dependency on FontAwesome npm package
 
 ### Configuration Options
 
-Set in `params.modules` of `config.toml`:
-- `fontawesome.inline` (default: true) - Use inline SVG instead of web fonts
-- `fontawesome.embed` (default: true) - Generate symbol map for embedded icons (with `inline`)
-- `fontawesome.debug` (default: false) - Output original icon code as comments
-- `fontawesome.skipMissing` (default: false) - Warn instead of error on missing icons
+Set in `params.modules.fontawesome` of your Hugo config:
+
+```toml
+[params.modules.fontawesome]
+  inline = true              # Use SVG+JS (true) or webfonts (false)
+  embed = false              # Use symbol maps for SVG icons (inline mode only)
+  debug = false              # Show original markup as comments (FontAwesome icons only)
+  skipMissing = false        # Warn vs. error on missing icons
+  styles = ["solid", "regular", "brands"]  # Optional: limit loaded JS files (inline=true only)
+```
+
+**Parameters:**
+- `inline` (boolean, default: true) - Rendering mode selection
+- `embed` (boolean, default: false) - Enable symbol maps for SVG icons. When enabled, icons are defined once in a hidden `<svg>` element and referenced via `<use>`. Only applies to inline SVG mode (custom icons, Bootstrap Icons, etc.). Reduces HTML size when icons are reused. Requires `{{- partial "assets/symbols.html" . -}}` in your layout.
+- `debug` (boolean, default: false) - Debug output for FontAwesome icons
+- `skipMissing` (boolean, default: false) - Error handling for missing icons
+- `styles` (array, optional) - Icon sets to load when `inline=true`. Valid values: "solid", "regular", "brands". Default: all three.
+
+**Removed parameters (from v3):**
+- `renderMode` - No mixed mode support in v4
+
+### Template Integration
+
+Sites using this module must include the FontAwesome JS loader partial in their layout:
 
-**Important:** When using webfonts (`inline = false`), Dart Sass is required to compile Font Awesome 7.x SCSS. Configure the transpiler in your stylesheet partial:
 ```html
-{{- $options := (dict "transpiler" "dartsass" "targetPath" $target) -}}
+{{- partial "footer/fontawesome-js.html" . -}}
 ```
 
+This should be placed before the closing `</body>` tag. The partial only outputs scripts when `inline=true`.
+
 ### Shortcode Usage
 
 All shortcodes delegate to the core `icon.html` partial:
@@ -75,75 +120,141 @@ All shortcodes delegate to the core `icon.html` partial:
 - `{{< fa "heart" >}}` - Regular icon (shorthand for fa-regular)
 - `{{< fab "github" >}}` - Brand icon
 - `{{< fas "star" >}}` - Solid icon
-- `{{< icon "fas heart" wrapper="..." scale="1.15" inline-style="..." >}}` - With options
+- `{{< icon "fas heart" wrapper="..." inline-style="..." >}}` - With options
 
 ### Icon Resolution Process
 
+**For FontAwesome icons:**
 1. User calls shortcode with icon name (e.g., `fas heart`)
 2. `icon.html` partial extracts family and icon name
-3. If `inline` is true: load SVG from `dist/svgs/{family}-{name}.svg`
-4. Strip comments and inject classes/attributes into SVG
-5. If `embed` is true: convert to symbol for symbol map inclusion
-6. If `inline` is false: output `<i>` tag for Font Awesome web font
+3. Outputs simple `<i class="fas fa-heart"></i>` tag
+4. If `inline=true`: FontAwesome JS converts to SVG at runtime in browser
+5. If `inline=false`: CSS renders as webfont with ::before pseudo-element
 
-## Important Implementation Details
+**For other icon libraries (Bootstrap Icons, etc.):**
+1. If `inline=true`: Load static SVG from `assets/svgs/{family}/{name}.svg`
+2. If `inline=false`: Output `<i>` tag for webfont rendering
 
-**SVG Embedding Process:**
-- Comments are stripped from SVG content using regex: `<!--(.*?)-->`
-- The `xmlns` attribute is replaced to inject icon classes and styling
-- Optional `data-scale` attribute is added when scale parameter is specified
-- Custom icons (in `assets/svgs/{custom}/{name}.svg`) have width/height removed to allow CSS sizing
+**For custom SVGs (src parameter):**
+1. Always load via `resources.Get` with basic SVG processing
+2. No mode-specific behavior
 
-**Symbol Map (when embed=true):**
-- Converted to `<symbol>` elements with ID format: `{family}-{name}`
-- Included via `{{< partial "assets/symbols.html" >}}` (requires page context)
-- Symbols are collected in `page.Scratch.icons` during partial execution
+## Important Implementation Details
 
-**Dependency Management:**
-- Hinode core utilities are available as vendored module `mod-utils`
-- Uses `utilities/InitArgs.html` for argument validation
-- Uses `utilities/LogErr.html` and `utilities/LogWarn.html` for error handling
+**FontAwesome JS Loading (SVG mode):**
+- Core library (fontawesome.min.js) loaded first
+- Icon set JS files loaded conditionally based on `styles` parameter
+- Scripts only loaded when `inline=true`
+- No JS output when `inline=false` (webfont mode)
+
+**CSS Loading:**
+- SVG mode (`inline=true`): Loads `svg-with-js.scss` only
+- Webfont mode (`inline=false`): Loads full FontAwesome CSS (fontawesome, regular, solid, brands)
+- No CSS conflicts between modes (simple if/else)
+
+**Removed Features (from v3):**
+- Custom scaling logic - FontAwesome JS handles this automatically
+- Symbol embedding with page.Scratch - Not needed with FontAwesome JS
+- renderMode per-family configuration - No mixed mode support
+- Static SVG generation for FontAwesome - Uses official JS approach instead
+
+## Breaking Changes from v3
+
+1. **Removed renderMode config** - No per-family mixed mode support
+2. **Removed embed parameter** - FontAwesome JS handles symbol creation
+3. **Removed custom scaling** - FontAwesome JS handles this
+4. **Changed mounting** - Now mounts directly from node_modules
+5. **Requires partial inclusion** - Sites must add fontawesome-js.html partial to layouts
+6. **No dist/ folder** - FontAwesome files mounted directly from node_modules
+
+## Migration from v3 to v4
+
+**1. Update configuration:**
+```toml
+# OLD v3 config (remove this)
+[params.modules.fontawesome]
+  embed = true
+  inline = true
+  [params.modules.fontawesome.renderMode]
+    fab = "font"
+
+# NEW v4 config
+[params.modules.fontawesome]
+  inline = true              # SVG+JS mode
+  debug = false
+  skipMissing = false
+  styles = ["solid", "brands"]  # Optional
+```
+
+**2. Add JS loader to layout:**
+```html
+<!-- In baseof.html or footer template, before </body> -->
+{{- partial "footer/fontawesome-js.html" . -}}
+```
 
-## Release Process
+**3. Update Hugo minimum version:**
+```toml
+[module.hugoVersion]
+  min = "0.153.0"
+```
 
-Uses semantic-release with conventional commits. Releases are triggered automatically on push to `main` branch:
-- Commit format determines version bump (fix:, feat:, BREAKING CHANGE:)
-- `dist/` and package.json are committed as part of release
-- No manual version bumping needed
+**4. Benefits:**
+- Proper FontAwesome SVG rendering with official JS
+- No CSS conflicts
+- Smaller git repository (no dist/ folder)
+- Simpler configuration
+- Better performance
 
 ## File Organization
 
 ```
 ├── layouts/
 │   ├── _shortcodes/          # Public shortcodes (icon.html, fa.html, fab.html, fas.html)
 │   └── _partials/
-│       └── assets/           # Core rendering logic (icon.html, symbols.html)
+│       ├── assets/           # Core rendering logic (icon.html, symbols.html)
+│       └── footer/           # FontAwesome JS loader (fontawesome-js.html)
+├── assets/
+│   └── scss/                 # Module SCSS (fontawesome.scss)
 ├── data/
-│   ├── structures/           # Argument validation schemas (icon.yml)
-│   └── fa-icons.yml          # Generated list of available icons
-├── dist/
-│   ├── svgs/                 # Font Awesome SVG files (generated from npm install)
-│   └── scss/                 # Font Awesome SCSS (optional)
+│   └── structures/           # Argument validation schemas (icon.yml)
 ├── exampleSite/              # Hugo example site for testing
-├── package.json              # npm scripts and dependencies
-└── hugo.toml                 # Module configuration (if exists)
+├── config.toml               # Module configuration with Hugo mounts
+└── package.json              # npm scripts and dependencies
 ```
 
+**Note:** The dist/ folder and data/fa-icons.yml are no longer used in v4.
+
 ## Common Tasks
 
-**Adding a new icon variant or configuration:**
-- Modify `layouts/_partials/assets/icon.html` to adjust rendering logic
-- Update `data/structures/icon.yml` to document new parameters
-- Test with `npm start` and check the example site
-
-**Updating Font Awesome:**
-- Update version in `package.json` (@fortawesome/fontawesome-free)
-- Run `npm install` (copies new SVG files to dist/)
-- Run `npm run meta` to regenerate icon list
-- Test with `npm test`
-
-**Fixing icon rendering issues:**
-- Check if SVG content is being loaded correctly (inspect `dist/svgs/`)
-- Verify scale parameter behavior in `icon.html` and JavaScript
-- Test with `inline` and `embed` settings in config
+**Testing in SVG mode:**
+```bash
+# Set inline = true in exampleSite/hugo.toml
+npm run build
+# Verify JS files in public/js/fontawesome/
+# Verify <script> tags in HTML
+# Test in browser - icons should render as <svg> after JS processing
+```
+
+**Testing in webfont mode:**
+```bash
+# Set inline = false in exampleSite/hugo.toml
+npm run build
+# Verify NO JS files/script tags
+# Verify webfont CSS in public/css/
+# Test in browser - icons should render with ::before pseudo-elements
+```
+
+**Updating FontAwesome:**
+```bash
+# Update version in package.json
+npm install
+# Test both rendering modes
+npm test
+```
+
+**Troubleshooting icon rendering:**
+- Check `inline` parameter setting
+- Verify fontawesome-js.html partial is included in layout
+- Check browser console for JS errors (SVG mode)
 - Use `debug` setting to see original vs. rendered output
+- Verify Hugo mounts in config.toml point to node_modules
@@ -43,10 +43,25 @@ This module supports the following parameters (see the section `params.modules`
 
 | Setting                 | Default | Description |
 |-------------------------|---------|-------------|
-| fontawesome.embed      | true    | If set, generates a symbol map with embedded vector images. Only works in conjunction with `inline`. Include the symbol with the partial `assets/symbols.html` (requires the current page context).|
-| fontawesome.inline      | true    | If set, uses inline vector images instead of web fonts. Both methods support Font Awesome styling and animation. However, when using vector images you cannot use aliases. Instead, use the default name of the icon. |
-| fontawesome.debug       | true    | If set, prints the original code `<i class="[...]" style=[...]></i>` as comments next to the inline vector image. |
-| fontawesome.skipMissing | false   | If set, displays a warning when an icon cannot be found. The missing icon is replaced with a dummy. By default, Hinode exits with an error when an icon is missing. |
+| fontawesome.embed      | false   | If set, generates a symbol map with embedded vector images. Only works with inline SVG mode (`inline = true`). Icons are defined once in a hidden `<svg>` element and referenced via `<use>`, reducing HTML size when icons are reused. Requires including the partial `{{- partial "assets/symbols.html" . -}}` in your layout (requires the current page context).|
+| fontawesome.inline      | true    | If set, uses inline SVG mode with FontAwesome JS. If false, uses web fonts via CSS. Both methods support Font Awesome styling and animation. |
+| fontawesome.debug       | false   | If set, prints debug information as comments in the generated HTML. |
+| fontawesome.skipMissing | false   | If set, displays a warning when an icon cannot be found instead of exiting with an error. |
+| fontawesome.styles      | ["solid", "regular", "brands"] | Array of FontAwesome icon sets to load when `inline=true`. Valid values: "solid", "regular", "brands". Omit this parameter to load all three. |
+
+**Example configuration:**
+
+```toml
+[params.modules.fontawesome]
+  inline = true  # Default to SVG mode
+
+  # Per-family overrides
+  [params.modules.fontawesome.renderMode]
+    fas = "svg"   # FontAwesome Solid uses SVG (explicit)
+    fa = "svg"    # FontAwesome Regular uses SVG (explicit)
+    fab = "font"  # FontAwesome Brands uses webfont (override)
+    bi = "font"   # Bootstrap Icons use webfont (override)
+```
 
 ## Notes