ultimate-jekyll-manager 0.0.117 → 0.0.119

package/CLAUDE.md

@@ -1,41 +1,214 @@
-# Identity
-This is Ultimate Jekyll, it is a template project that other "consuming" projects can use to build a Jekyll site. It comes installed as an NPM module and is helpful for setting up, configuring, and maintaining a Jekyll site with best practices in mind.
+# Ultimate Jekyll Manager
 
-It is not a stand-alone project, but rather a collection of components that can be used to build a Jekyll site quickly and efficiently.
-* You cannot use `npm start` or `npm run build` in this project.
+## Project Overview
 
-## Structure
-Ultimate Jekll has the following structure:
-src/gulp/tasks = Gulp tasks that are used to build the Jekyll site.
-src/defaults/src = Default source files that can be used as a starting point for a Jekyll site and ARE meant to be edited by the user. They are copied to the consuming project's "src" directory.
-src/defaults/dist = Default distribution files that can be used as a starting point for a Jekyll site and NOT meant to be edited by the user. They are copied to the consuming project's "dist" directory.
+Ultimate Jekyll Manager is a template framework that consuming projects install as an NPM module to build Jekyll sites quickly and efficiently. It provides best-practice configurations, default components, themes, and build tools.
 
-The "consuming" project has the following structure:
-"src" = Compiled to "dist" with npm
-"dist" = Compiled to "_site" with Jekyll.
+**Important:** This is NOT a standalone project. You cannot run `npm start` or `npm run build` directly in this repository.
+
+## Project Structure
+
+### Directory Organization
+- `src/gulp/tasks` - Gulp tasks for building Jekyll sites
+- `src/defaults/src` - Default source files (editable by users, copied to consuming project's `src/`)
+- `src/defaults/dist` - Default distribution files (not editable by users, copied to consuming project's `dist/`)
+- `src/assets/css` - Stylesheets (global, pages, themes)
+- `src/assets/js` - JavaScript modules (core, pages, libraries)
+- `src/assets/themes` - Theme SCSS and JS files
+
+### Consuming Project Structure
+- `src/` - Compiled to `dist/` via npm
+- `dist/` - Compiled to `_site/` via Jekyll
 
 ## Local Development
-When working with a consuming project, the local development server URL can be found in the `.temp/_config_browsersync.yml` file in the consuming project's root directory. You should read this file to determine the correct local URL for browsing and testing the site.
 
-## Other Ultimate Jekyll Components:
-src/assets/css/ultimate-jekyll-manager.scss = Main stylesheet used by Ultimate Jekyll to style the site
-src/assets/css/global = Global styles that are used by Ultimate Jekyll
-src/assets/css/pages = Page-specific styles that are used by Ultimate Jekyll
-* If you are making a page, put the styles in this directory like so: `src/assets/css/pages/[page-name]/index.scss`
+The local development server URL is stored in `.temp/_config_browsersync.yml` in the consuming project's root directory. Read this file to determine the correct URL for browsing and testing.
+
+## Asset Organization
+
+### Ultimate Jekyll Manager Files (THIS project)
+
+**CSS:**
+- `src/assets/css/ultimate-jekyll-manager.scss` - Main UJ stylesheet (provides core styles)
+- `src/assets/css/global/` - Global UJ styles
+- `src/assets/css/pages/` - Page-specific styles provided by UJ
+  - Format: `src/assets/css/pages/[page-name]/index.scss`
+  - Example: `src/assets/css/pages/download/index.scss`
+
+**JavaScript:**
+- `src/assets/js/ultimate-jekyll-manager.js` - Main UJ JavaScript entry point (provides core functionality)
+- `src/assets/js/core/` - Core UJ modules
+- `src/assets/js/pages/` - Page-specific JavaScript provided by UJ
+  - Format: `src/assets/js/pages/[page-name]/index.js`
+  - Example: `src/assets/js/pages/download/index.js`
+- `src/assets/js/libs/` - UJ library modules (prerendered-icons, form-manager, authorized-fetch, etc.)
+
+**Default Pages & Layouts:**
+
+UJ provides default page templates and layouts in `src/defaults/dist/` that are copied to consuming projects. These are NOT meant to be edited by users.
+
+- Format: `src/defaults/dist/_layouts/themes/[theme-id]/frontend/pages/[page-name].html`
+- Examples:
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/download.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/pricing.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/payment/checkout.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/payment/confirmation.html`
+  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/contact.html`
+- Core layouts:
+  - `src/defaults/dist/_layouts/core/root.html` - Root HTML wrapper
+  - `src/defaults/dist/_layouts/themes/[theme-id]/frontend/core/base.html` - Theme base layout
+
+**Complete UJ Page Example:**
+- **HTML:** `src/defaults/dist/_layouts/themes/classy/frontend/pages/download.html`
+- **CSS:** `src/assets/css/pages/download/index.scss`
+- **JS:** `src/assets/js/pages/download/index.js`
+
+These files serve as blueprints and reference implementations. When building custom pages in consuming projects, reference these for patterns and best practices.
+
+**IMPORTANT:** Consuming projects CAN create files with the same paths in their own `src/` directory to override UJ defaults, but this should ONLY be done when absolutely necessary. Prefer using `src/pages/` and `src/_layouts/` for custom pages instead of overriding UJ default files.
+
+### Section Configuration Files (JSON)
+
+UJ provides JSON configuration files for common sections like navigation and footer. These JSON files are consumed by corresponding HTML templates during the build process.
+
+**Configuration Files:**
+- `src/defaults/src/_includes/frontend/sections/nav.json` - Navigation configuration
+- `src/defaults/src/_includes/frontend/sections/footer.json` - Footer configuration
+
+**How It Works:**
+1. JSON files contain structured data (links, labels, settings)
+2. HTML templates in `src/defaults/dist/_includes/themes/[theme-id]/frontend/sections/` read and render this data
+3. The build process converts `.json` → data loaded by `.html` templates
+
+**Customizing Navigation/Footer:**
+
+Consuming projects should create their own JSON files in `src/_includes/frontend/sections/`:
+- `src/_includes/frontend/sections/nav.json`
+- `src/_includes/frontend/sections/footer.json`
+
+**Example: Footer Configuration**
+
+```json
+{
+  logo: {
+    href: '/',
+    class: 'filter-adaptive',
+    text: '{{ site.brand.name }}',
+    description: '{{ site.meta.description }}',
+  },
+  links: [
+    {
+      label: 'Company',
+      href: null,
+      links: [
+        {
+          label: 'About Us',
+          href: '/about',
+        },
+        {
+          label: 'Pricing',
+          href: '/pricing',
+        },
+      ],
+    },
+  ],
+  socials: {
+    enabled: true,
+  },
+  copyright: {
+    enabled: true,
+    text: null,
+  },
+}
+```
+
+**Note:** These are JSON5 files (support comments, trailing commas, unquoted keys). The corresponding HTML templates automatically process these files during the build.
+
+### Customizing Default Pages via Frontmatter
+
+**BEST PRACTICE:** UJ default pages are designed to be customized through frontmatter WITHOUT writing any HTML. Consuming projects can create a simple page that includes ONLY frontmatter to configure the default page's behavior.
+
+**How It Works:**
+1. UJ default pages use `page.resolved` to access merged frontmatter (site → layout → page)
+2. **IMPORTANT:** Before customizing, READ the UJ default page in `src/defaults/dist/_layouts/` to understand available frontmatter options and how they're used
+3. Consuming projects create a page in `src/pages/` with custom frontmatter
+4. The page uses a UJ layout (e.g., `blueprint/pricing`)
+5. Frontmatter overrides default values without any HTML
+
+**Example: Customizing the Pricing Page**
+
+**Step 1:** Read the UJ default pricing page to see available frontmatter options:
+- File: `src/defaults/dist/_layouts/themes/classy/frontend/pages/pricing.html`
+- Look for frontmatter at the top and how `page.resolved.pricing` is used in the HTML
+
+**Step 2:** In consuming project, create `src/pages/pricing.html`:
+
+```yaml
+---
+### ALL PAGES ###
+layout: blueprint/pricing
+permalink: /pricing
+
+### PAGE CONFIG ###
+pricing:
+  price_per_unit:
+    enabled: true
+    feature_id: "credits"
+    label: "credit"
+  plans:
+    - id: "basic"
+      name: "Basic"
+      tagline: "best for getting started"
+      url: "/download"
+      pricing:
+        monthly: 0
+        annually: 0
+      features:
+        - id: "credits"
+          name: "Credits"
+          value: 1
+          icon: "sparkles"
+    ...
+---
+```
+
+That's it! No HTML needed. The UJ pricing layout reads `page.resolved.pricing` and renders the plans accordingly.
+
+**When to Use Frontmatter Customization:**
+- ✅ Customizing UJ default pages (pricing, contact, download, etc.)
+- ✅ Changing configuration without touching HTML
+- ✅ Maintaining upgradability when UJ updates
 
-src/assets/css/main.scss
-* This file runs on EVERY page and should be edited to contain site-wide CSS styles.
+**When to Create Custom Pages:**
+- ❌ Building entirely new page types
+- ❌ Needing custom HTML structure
+- ❌ Pages with unique layouts not provided by UJ
 
+### Consuming Project Files
 
-src/assets/js/ultimate-jekyll-manager.js = Main JavaScript file used by Ultimate Jekyll to manage the site
-src/assets/js/pages = Page-specific JavaScript files that are used by Ultimate Jekyll
-* If you are making a page, put the JavaScript in this directory like so: `src/assets/js/pages/[page-name]/index.js`
-* The page-specific JS and CSS files are automatically included in the page based on the page's canonical path.
-* You need to use our standardized structure:
-  * Notice how how the helpers are outside the main export function.
-```js
+**CSS:**
+- `src/assets/css/main.scss` - Site-wide custom styles (runs on every page, edits by consuming project)
+- `src/assets/css/pages/` - Page-specific custom styles
+  - Format: `src/assets/css/pages/[page-name]/index.scss`
+
+**JavaScript:**
+- `src/assets/js/main.js` - Site-wide custom JavaScript (runs on every page, edits by consuming project)
+- `src/assets/js/pages/` - Page-specific custom JavaScript
+  - Format: `src/assets/js/pages/[page-name]/index.js`
+
+**Pages & Layouts:**
+- `src/pages/` - Individual page HTML/Markdown files
+- `src/_layouts/` - Custom layouts for the consuming project
+
+**Asset Loading:** Page-specific CSS/JS files are automatically included based on the page's canonical path. Override with `asset_path` frontmatter.
+
+### Page Module Structure
+
+All page modules must follow this standardized pattern:
+
+```javascript
 /**
- * XXX Page JavaScript
+ * [Page Name] Page JavaScript
  */
 
 // Libraries
@@ -50,7 +223,7 @@ export default (Manager) => {
     // Initialize when DOM is ready
     await webManager.dom().ready();
 
-    // We just need to pause videos when switching tabs for better UX
+    // Page initialization logic
     helper1();
 
     // Resolve after initialization
@@ -60,155 +233,460 @@ export default (Manager) => {
 
 // Helper functions
 function helper1() {
-  // ...
+  // Helper implementation
 }
 ```
 
-/src/assets/js/main.js
-* This file runs on EVERY page and should be edited to contain site-wide JavaScript functionality.
+**Key Points:**
+- Helpers are defined outside the main export function
+- Use `webManager` shortcuts for common operations
+- Always wait for DOM ready before manipulating elements
+
+## Layouts and Pages
+
+### Page Types
+- **One-off pages** (e.g., `/categories`, `/sitemap`) - Create as pages without custom layouts; use existing layouts
+- **Repeating page types** (e.g., blog posts, category pages) - Create a dedicated layout (e.g., `_layouts/category.html`)
+
+### Layout Requirements
+All layouts and pages must eventually require a theme entry point:
+```yaml
+layout: themes/[ site.theme.id ]/frontend/core/base
+```
+
+**Note:** The `[ site.theme.id ]` syntax is correct and allows dynamic theme selection.
+
+### Asset Path Configuration
+
+For pages sharing the same assets, use the `asset_path` frontmatter variable:
+
+```yaml
+---
+# Instead of deriving path from page.canonical.path
+asset_path: categories/category
+---
+```
+
+**Example:**
+- One-off page: `pages/categories.html` → `src/assets/css/pages/categories/index.scss`
+- Repeating layout: `_layouts/category.html` → `src/assets/css/pages/categories/category.scss` (set `asset_path: categories/category` in layout frontmatter)
+
+## UJ Powertools (Jekyll Plugin)
+
+Ultimate Jekyll uses the `jekyll-uj-powertools` gem for custom Liquid functionality.
+
+**Documentation:** `/Users/ian/Developer/Repositories/ITW-Creative-works/jekyll-uj-powertools/README.md`
+
+### Available Features
+- **Filters:** `uj_strip_ads`, `uj_json_escape`, `uj_title_case`, `uj_content_format`
+- **Tags:** `iftruthy`, `iffalsy`, `uj_icon`, `uj_logo`, `uj_image`, `uj_member`, `uj_post`, `uj_readtime`, `uj_social`, `uj_translation_url`, `uj_fake_comments`, `uj_language`
+- **Global Variables:** `site.uj.cache_breaker`
+- **Page Variables:** `page.random_id`, `page.extension`, `page.layout_data`, `page.resolved`
+
+**Always check the README before assuming functionality.**
+
+### Key Liquid Functions
+
+#### `uj_content_format`
+Formats content by first liquifying it, then markdownifying it (if markdown file).
+
+#### `iftruthy` / `iffalsy`
+Custom tags that check JavaScript truthiness (not null, undefined, or empty string).
+
+```liquid
+{% iftruthy variable %}
+  <!-- Content -->
+{% endiftruthy %}
+```
+
+**Limitations:**
+- Does NOT support logical operators
+- Does NOT support `else` statements
+- CAN contain nested sub-statements
+
+#### `page.resolved`
+A deeply merged object containing all site, layout, and page variables. Precedence: page > layout > site. Enables a system of defaults with progressive overrides.
+
+#### `uj_icon`
+Inserts Font Awesome icons:
+
+```liquid
+{% uj_icon icon-name, "fa-md" %}
+{% uj_icon "rocket", "fa-3xl" %}
+```
+
+**Parameters:**
+1. Icon name (string or variable, without "fa-" prefix)
+2. CSS classes (optional, defaults to "fa-3xl")
+
+#### `asset_path` Override
+Override default page-specific CSS/JS path derivation:
+
+```yaml
+---
+asset_path: blog/post
+---
+```
+
+Uses `/assets/css/pages/{{ asset_path }}.bundle.css` instead of deriving from `page.canonical.path`. Useful when multiple pages share assets (e.g., all blog posts).
+
+## Icon System
+
+Ultimate Jekyll uses Font Awesome icons but does NOT include the Font Awesome JavaScript or CSS library. All icons must be rendered server-side using Jekyll's `{% uj_icon %}` tag.
+
+### When to Use `{% uj_icon %}` vs Prerendered Icons
+
+**IMPORTANT:** Use the correct method based on WHERE the icon will be used:
+
+#### Use `{% uj_icon %}` in HTML/Liquid Templates
+
+When icons are part of the static HTML template, use `{% uj_icon %}` directly:
+
+```liquid
+<!-- Alerts -->
+<div class="alert alert-success">
+  {% uj_icon "circle-check", "fa-sm" %} Success message
+</div>
+
+<!-- Buttons -->
+<button class="btn btn-primary">
+  {% uj_icon "paper-plane", "fa-md me-2" %}
+  Send
+</button>
+
+<!-- Labels -->
+<label>
+  {% uj_icon "envelope", "fa-sm me-1 text-info" %}
+  Email
+</label>
+```
+
+**Use this when:**
+- The icon is in a Jekyll template (.html file)
+- The icon is static and known at build time
+- The icon is part of the page structure
+
+#### Use Prerendered Icons in JavaScript
+
+When icons need to be dynamically inserted via JavaScript, pre-render them in frontmatter and access them via the library:
+
+**1. Add icons to page frontmatter:**
+```yaml
+---
+prerender_icons:
+  - name: "mobile"
+    class: "fa-sm me-1"
+  - name: "envelope"
+    class: "fa-sm me-1"
+  - name: "bell"
+    class: "fa-sm me-1"
+---
+```
+
+**2. Import the library in JavaScript:**
+```javascript
+import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js';
+```
+
+**3. Use in your code:**
+```javascript
+const iconHTML = getPrerenderedIcon('mobile');
+$badge.innerHTML = `${iconHTML}Push Notification`;
+```
+
+**Use this when:**
+- Icons are dynamically inserted via JavaScript
+- Icons are part of dynamically generated content
+- Icons are added to elements created with `document.createElement()`
+
+### What NOT to Do
+
+**NEVER use manual icon HTML in JavaScript:**
+```javascript
+// ❌ WRONG - Bootstrap Icons (we don't use Bootstrap Icons)
+$el.innerHTML = '<i class="bi bi-check-circle"></i> Text';
+
+// ❌ WRONG - Manual Font Awesome (we don't have FA JS/CSS)
+$el.innerHTML = '<i class="fa-solid fa-check"></i> Text';
+
+// ✅ CORRECT - Use prerendered icons
+const iconHTML = getPrerenderedIcon('circle-check');
+$el.innerHTML = `${iconHTML} Text`;
+```
 
-src/assets/themes = Theme scss and js files that are can be picked and used by the consuming project.
+### Benefits
+- Icons are rendered server-side with proper Font Awesome classes
+- No client-side icon generation overhead
+- Consistent icon styling across the application
+- No Font Awesome JavaScript/CSS library needed
 
-## UJ Powertools
-Ultimate Jekyll uses the `jekyll-uj-powertools` gem which provides many custom Liquid filters, tags, and variables. You should review the full documentation to understand all available tools: `/Users/ian/Developer/Repositories/ITW-Creative-works/jekyll-uj-powertools/README.md`
+## CSS Guidelines
 
-Key features include:
-* **Filters**: `uj_strip_ads`, `uj_json_escape`, `uj_title_case`, `uj_content_format`
-* **Tags**: `iftruthy`, `iffalsy`, `uj_icon`, `uj_logo`, `uj_image`, `uj_member`, `uj_post`, `uj_readtime`, `uj_social`, `uj_translation_url`, `uj_fake_comments`, `uj_language`
-* **Global Variables**: `site.uj.cache_breaker`
-* **Page Variables**: `page.random_id`, `page.extension`, `page.layout_data`, `page.resolved`
+### Theme-Adaptive Classes
 
-ALWAYS check the README before assuming a filter or tag exists or how it works.
+**DO NOT USE:** `bg-light`, `bg-dark`, `text-light`, `text-dark`
 
-## SOME SPECIAL LIQUID FUNCTIONS:
-* uj_content_format = A custom liquid filter that formats the content like so: first, it LIQUIFIES the content, then, if it's a markdown file, it runs MARKDOWNIFY.
-* iftruthy = a custom liquid tag that checks if a variable is truthy in JavaScript terms, meaning it checks if the variable is not null, undefined, or an empty string. Use it like this: `{% iftruthy variable %}`. But it DOES NOT SUPPORT any logical operators and does not support `else` statements. But you CAN put sub-statements inside it.
-* iffalsy = same but opposite of iftruthy.
-* page.resolved = a custom page object property of all site, layout, and page variables deeply merged together, with page variables taking precedence over layout, and layout variables taking precedence over site variables. This allows a system of site defaults, layout overrides, and page-specific overrides.
+Ultimate Jekyll supports both light and dark modes. Use adaptive classes instead:
 
-### Specifics:
-* {% uj_icon icon-name, "fa-md" %} = Custom tag for inserting fontawesome icons. "icon-name" can be a string or a variable. If its a string, put it in quotes like "rocket" (dont include "fa-")
-* Set `asset_path: path/to/asset` for layouts or pages to override the default page-specific CSS/JS path. When set, it uses `/assets/css/pages/{{ asset_path }}.bundle.css` instead of deriving the path from `page.canonical.path`. Useful when multiple pages share the same assets like all blog posts using `asset_path: blog/post`.
+**Backgrounds:**
+- `bg-body` - Primary background
+- `bg-body-secondary` - Secondary background
+- `bg-body-tertiary` - Tertiary background
 
-## Layouts and Pages in Consuming Projects
-When creating pages in the consuming project, follow these guidelines:
-* **One-off pages** (like `/categories`, `/sitemap`, etc.) should be created directly as pages (e.g., `pages/categories.html`) WITHOUT their own custom layout. These pages should use an existing layout.
-* **Repeating page types** (like individual category pages, individual blog posts, etc.) should have a dedicated layout that all instances use (e.g., `_layouts/category.html` used by all category pages).
-* **All layouts and pages** must eventually require one of the theme entry points, such as `layout: themes/[ site.theme.id ]/frontend/core/base`. This ensures consistent theming across the site.
-  * YES, the "[[ site.theme.id ]]" syntax is correct here; it allows dynamic selection of the theme based on site configuration.
-* This approach keeps the codebase maintainable by reusing layouts for similar pages while avoiding unnecessary layout files for unique pages.
-* So you should put assets like CSS and JS for a one-off page like `categories.html` in `src/assets/css/pages/categories/index.scss` and `src/assets/js/pages/categories/index.js` respectively, and for repeating page types like an individual category that uses a LAYOUT, put them in `src/assets/css/pages/categories/category.scss` and `src/assets/js/pages/categories/category.js` (and you will of course set the `asset_path: categories/category` frontmatter variable on the layout so that the correct assets are loaded).
+**Text:**
+- `text-body` - Body text color
 
-## CSS
-DO NOT USE `bg-light`, `bg-dark`, `text-light`, or `text-dark`. We support BOTH light and dark mode, so instead use `bg-body`, `bg-body-secondary`, `bg-body-tertiary`, `text-body` and for buttons you can use `btn-adaptive` or `btn-outline-adaptive`.
-These classes adapt to light and dark mode automatically.
+**Buttons:**
+- `btn-adaptive` - Adaptive button
+- `btn-outline-adaptive` - Adaptive outline button
 
-## Page Loading State & Button Protection
-Ultimate Jekyll implements a sophisticated system to prevent premature button clicks during page initialization. This prevents race conditions and ensures JavaScript is fully loaded before users can trigger actions.
+These classes automatically adapt to the current theme mode.
 
-### How It Works:
-1. **Initial State**: The HTML element starts with `data-page-loading="true"` and `aria-busy="true"` attributes (set in `src/defaults/dist/_layouts/core/root.html`)
-2. **Protection During Load**: While `data-page-loading` is present, certain elements are automatically disabled via CSS and JavaScript
-3. **Ready State**: When JavaScript initialization completes, these attributes are removed by `src/assets/js/core/complete.js`
+## Page Loading Protection System
 
-### What Gets Protected:
-When `data-page-loading` is active, the following elements are automatically protected from clicks:
+Ultimate Jekyll prevents race conditions by disabling buttons during JavaScript initialization.
 
-- **All form buttons**: `<button>`, `<input type="submit">`, `<input type="button">`, `<input type="reset">`
-- **Elements with `.btn` class**: Standard Bootstrap buttons
-- **Elements with `.btn-action` class**: Custom action triggers (see below)
-- **Always disabled**: Any element with `disabled` attribute, `.disabled` class, or `:disabled` state
+### How It Works
+1. HTML element starts with `data-page-loading="true"` and `aria-busy="true"` (`src/defaults/dist/_layouts/core/root.html`)
+2. Protected elements are automatically disabled during this state
+3. Attributes are removed when JavaScript completes (`src/assets/js/core/complete.js`)
 
-### The `.btn-action` Class:
-Use the `.btn-action` class to selectively protect non-standard elements that trigger important actions:
+### Protected Elements
+- All form buttons (`<button>`, `<input type="submit">`, `<input type="button">`, `<input type="reset">`)
+- Elements with `.btn` class (Bootstrap buttons)
+- Elements with `.btn-action` class (custom action triggers)
+
+### The `.btn-action` Class
+
+Selectively protect non-standard elements that trigger important actions:
 
 ```html
-<!-- These will be protected during page load -->
+<!-- Protected during page load -->
 <a href="/api/delete" class="custom-link btn-action">Delete Item</a>
 <div class="card-action btn-action" onclick="processData()">Process</div>
-<span class="text-link btn-action" data-action="save">Save Changes</span>
 
-<!-- These will NOT be protected (regular navigation/UI) -->
+<!-- NOT protected (regular navigation/UI) -->
 <a href="/about" class="btn btn-primary">About Us</a>
 <button data-bs-toggle="modal">Show Info</button>
-<button data-bs-toggle="collapse">Toggle Details</button>
 ```
 
-### When to Use `.btn-action`:
-- **Use it for**: API calls, form submissions, data modifications, payment processing, destructive actions
-- **Don't use it for**: Navigation links, UI toggles, modals, accordions, tabs, harmless interactions
+**Use `.btn-action` for:**
+- API calls
+- Form submissions
+- Data modifications
+- Payment processing
+- Destructive actions
+
+**Don't use for:**
+- Navigation links
+- UI toggles (modals, accordions, tabs)
+- Harmless interactions
 
-### Implementation Files:
-- **CSS Styles**: `src/assets/css/core/utilities.scss` - Applies `cursor: not-allowed` and disabled styling
-- **Click Prevention**: `src/defaults/dist/_includes/core/body.html` - Inline script that prevents clicks
-- **State Removal**: `src/assets/js/core/complete.js` - Removes `data-page-loading` when ready
+### Implementation
+- **CSS:** `src/assets/css/core/utilities.scss` - Disabled styling
+- **Click Prevention:** `src/defaults/dist/_includes/core/body.html` - Inline script
+- **State Removal:** `src/assets/js/core/complete.js` - Removes loading state
 
-This system ensures a smooth, error-free user experience by preventing premature interactions while maintaining full flexibility for developers.
+## Lazy Loading System
 
-## Lazy Loading
-Ultimate Jekyll uses a custom lazy loading system powered by web-manager. Elements can be lazy-loaded using the `data-lazy` attribute with the following format:
+Ultimate Jekyll uses a custom lazy loading system powered by web-manager.
 
+### Syntax
 ```html
 data-lazy="@type value"
 ```
 
-### Supported Types:
-* `@src` - Lazy load the `src` attribute (for images, iframes, videos, source elements)
-  ```html
-  <img data-lazy="@src /assets/images/hero.jpg" alt="Hero">
-  <iframe data-lazy="@src https://example.com/embed"></iframe>
-  ```
+### Supported Types
 
-* `@srcset` - Lazy load the `srcset` attribute (for responsive images)
-  ```html
-  <img data-lazy="@srcset /img/small.jpg 480w, /img/large.jpg 1024w">
-  ```
+#### `@src` - Lazy load src attribute
+```html
+<img data-lazy="@src /assets/images/hero.jpg" alt="Hero">
+<iframe data-lazy="@src https://example.com/embed"></iframe>
+```
 
-* `@bg` - Lazy load background images via `background-image` CSS
-  ```html
-  <div data-lazy="@bg /assets/images/background.jpg"></div>
-  ```
+#### `@srcset` - Lazy load srcset attribute
+```html
+<img data-lazy="@srcset /img/small.jpg 480w, /img/large.jpg 1024w">
+```
 
-* `@class` - Lazy add CSS classes when element comes into view (useful for animations)
-  ```html
-  <div data-lazy="@class animation-fade-in">Content</div>
-  ```
+#### `@bg` - Lazy load background images
+```html
+<div data-lazy="@bg /assets/images/background.jpg"></div>
+```
 
-* `@html` - Lazy inject HTML content
-  ```html
-  <div data-lazy="@html <p>Lazy loaded content</p>"></div>
-  ```
+#### `@class` - Lazy add CSS classes
+```html
+<div data-lazy="@class animation-fade-in">Content</div>
+```
+
+#### `@html` - Lazy inject HTML content
+```html
+<div data-lazy="@html <p>Lazy loaded content</p>"></div>
+```
 
-* `@script` - Lazy load external scripts with JSON configuration
-  ```html
-  <div data-lazy='@script {"src": "https://example.com/widget.js", "attributes": {"async": true}}'></div>
-  ```
+#### `@script` - Lazy load external scripts
+```html
+<div data-lazy='@script {"src": "https://example.com/widget.js", "attributes": {"async": true}}'></div>
+```
 
-### Features:
-* Automatically adds cache busters to URLs using `buildTime`
-* Uses IntersectionObserver for performance (starts loading 50px before element enters viewport)
-* Adds CSS classes during loading states: `lazy-loading`, `lazy-loaded`, `lazy-error`
-* Handles video/audio sources intelligently by observing the parent element
-* Automatically re-scans DOM for dynamically added elements
+### Features
+- Automatic cache busting via `buildTime`
+- IntersectionObserver for performance (50px threshold)
+- Loading state CSS classes: `lazy-loading`, `lazy-loaded`, `lazy-error`
+- Intelligent handling of video/audio sources
+- Automatic DOM re-scanning for dynamic elements
 
-See implementation: [src/assets/js/core/lazy-loading.js](src/assets/js/core/lazy-loading.js)
+**Implementation:** `src/assets/js/core/lazy-loading.js`
 
-## Libraries
-I have some library preferences that I want you to follow:
+## JavaScript Libraries
 
 ### WebManager
-We use a custom library called `web-manager` to manage various aspects of the site. Please make yourself familiar with it by reviewing it: `/Users/ian/Developer/Repositories/ITW-Creative-Works/web-manager/src`
-It offers various ultities like webManager.auth(), webManager.utilities(), webManager.sentry(), webManager.dom(). You should be using these utilities instead of writing your own code all the time.
-DO NOT JUST ASSUME THAT webManager has a function, though, you should CHECK THE SOURCE CODE to see what functions are available and how to use them or check the README: `/Users/ian/Developer/Repositories/ITW-Creative-Works/web-manager/README.md`
-
-## FormManager
-We use a custom library called `form-manager` to manage forms on the site. Please make yourself familiar with it by reviewing it: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/src/assets/js/libs/form-manager.js`
-* A good example of how to use it is the contact page
-  * HTML: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/src/defaults/dist/_layouts/themes/classy/frontend/pages/contact.html`
-  * JS: `/Users/ian/Developer/Repositories/ITW-Creative-Works/ultimate-jekyll-manager/src/assets/js/pages/contact/index.js`
-
-## Audits
-I may ask you to help me fix problems identified by the AUDIT TASK (@src/gulp/tasks/audit.js)
-* In that case, please LOOK AT THE AUDIT FILES (Which I will provide the location to) and help me fix the issues ONE BY ONE.
-* Make a TODO list for each category in the audit, then read the ENTIRE AUDIT file and make a plan for what items in that category need to be fixed.
-* Remember, these are BIG AUDIT FILES, so you will have to tackle them in parts. DO NOT TRY TO FIX EVERYTHING AT ONCE.
+
+Custom library for site management functionality.
+
+**Documentation:** `/Users/ian/Developer/Repositories/ITW-Creative-Works/web-manager/README.md`
+
+**Available Utilities:**
+- `webManager.auth()` - Authentication management
+- `webManager.utilities()` - Utility functions
+- `webManager.sentry()` - Error tracking
+- `webManager.dom()` - DOM manipulation
+
+**Important:** Always check the source code or README before assuming a function exists. Do not guess at API methods.
+
+### Ultimate Jekyll Libraries
+
+Ultimate Jekyll provides helper libraries in `src/assets/js/libs/` that can be imported as needed.
+
+#### Prerendered Icons Library
+
+Provides access to icons defined in page frontmatter and rendered server-side.
+
+**Import:**
+```javascript
+import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js';
+```
+
+**Usage:**
+```javascript
+const iconHTML = getPrerenderedIcon('apple');
+```
+
+**Reference:** `src/assets/js/libs/prerendered-icons.js`
+
+#### Authorized Fetch Library
+
+Simplifies authenticated API requests by automatically adding Firebase authentication tokens via Authorization Bearer header.
+
+**Import:**
+```javascript
+import authorizedFetch from '__main_assets__/js/libs/authorized-fetch.js';
+```
+
+**Usage:**
+```javascript
+const response = await authorizedFetch(url, options);
+```
+
+**Key Benefits:**
+- No need to manually call `webManager.auth().getIdToken()`
+- Automatic token injection as Authorization Bearer header
+- Centralized authentication handling
+
+**Reference:** `src/assets/js/libs/authorized-fetch.js`
+
+#### FormManager Library
+
+Form handling library with built-in state management and validation.
+
+**Import:**
+```javascript
+import { FormManager } from '__main_assets__/js/libs/form-manager.js';
+```
+
+**Usage:**
+```javascript
+const formManager = new FormManager('#my-form', options);
+```
+
+**Reference:** `src/assets/js/libs/form-manager.js`
+**Example:** `src/assets/js/pages/contact/index.js`
+
+## Analytics & Tracking
+
+Ultimate Jekyll uses three tracking platforms: Google Analytics (gtag), Facebook Pixel (fbq), and TikTok Pixel (ttq).
+
+### Tracking Guidelines
+
+**IMPORTANT Rules:**
+- Track important user events with `gtag()`, `fbq()`, and `ttq()` functions
+- NEVER add conditional checks for tracking functions (e.g., `if (typeof gtag !== 'undefined')`)
+- Always assume tracking functions exist - they're globally available or stubbed
+- Reference standard events documentation before implementing custom tracking
+
+**Standard Events Documentation:**
+- **Google Analytics GA4:** https://developers.google.com/analytics/devguides/collection/ga4/reference/events
+- **Facebook Pixel:** https://www.facebook.com/business/help/402791146561655?id=1205376682832142
+- **TikTok Pixel:** https://ads.tiktok.com/help/article/standard-events-parameters?redirected=2
+
+### Platform-Specific Requirements
+
+#### TikTok Pixel Requirements
+TikTok has strict validation requirements:
+
+**Required Parameters:**
+- `content_id` - MUST be included in all events
+
+**Valid Content Types:**
+- `"product"`
+- `"product_group"`
+- `"destination"`
+- `"hotel"`
+- `"flight"`
+- `"vehicle"`
+
+Any other content type will generate a validation error.
+
+**Example:**
+```javascript
+// ✅ CORRECT
+ttq.track('ViewContent', {
+  content_id: 'product-123',
+  content_type: 'product'
+});
+
+// ❌ WRONG - Missing content_id
+ttq.track('ViewContent', {
+  content_type: 'product'
+});
+
+// ❌ WRONG - Invalid content_type
+ttq.track('ViewContent', {
+  content_id: 'product-123',
+  content_type: 'custom'  // Not in approved list
+});
+```
+
+### Tracking Implementation
+
+**IMPORTANT:** Always track events to ALL THREE platforms in this order:
+1. Google Analytics (gtag)
+2. Facebook Pixel (fbq)
+3. TikTok Pixel (ttq)
+
+Track events directly without existence checks. All three tracking calls should be made together for every event.
+
+**Development Mode:**
+In development mode, all tracking calls are intercepted and logged to the console for debugging. See `src/assets/js/libs/dev.js` for implementation.
+
+## Audit Workflow
+
+When fixing issues identified by the audit task (`src/gulp/tasks/audit.js`):
+
+1. Review the audit file location provided
+2. Create a TODO list for each audit category
+3. Read the ENTIRE audit file and plan fixes for each category
+4. Tackle issues incrementally - DO NOT attempt to fix everything at once
+5. Work through one category at a time
+
+**Remember:** Audit files are large. Systematic, incremental fixes prevent errors and ensure thoroughness.