ultimate-jekyll-manager 1.7.2 → 1.8.0

package/docs/layouts-and-pages.md

@@ -29,3 +29,149 @@ 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)
+
+## Customizing Default Pages (blueprints)
+
+Default pages live in `src/defaults/dist/_layouts/themes/[theme-id]/frontend/pages/`. Consumers customize them through frontmatter only — see [assets.md → Customizing Default Pages via Frontmatter](assets.md#customizing-default-pages-via-frontmatter) for the mechanism (`page.resolved`, reading the default layout first).
+
+For each relevant default page:
+
+1. Create a page in the consuming project's `src/pages/` directory
+2. Use ONLY frontmatter to customize — NO HTML content needed
+3. Set `layout: blueprint/[page-name]` (e.g., `layout: blueprint/pricing`)
+4. Customize the frontmatter values to match the brand and purpose
+
+### File Extension Rules
+
+- `.md` — Use for frontmatter-only customization (no HTML content)
+- `.html` — Use only when adding custom HTML content beyond the layout
+
+### Frontmatter Rules
+
+- Default pages (blueprint layouts): Do NOT include `meta.title` or `meta.description` — already set in the layout
+- Do NOT include `theme` config (e.g., `theme.main.class`) unless explicitly changing from defaults
+- `superheadline`: Homepage keeps default icon AND text; other pages may customize `text` but keep the default `icon`
+
+### Page Exclusions
+
+Do NOT modify these pages:
+
+- `auth/*` — Authentication pages (signin, signup, reset, oauth2)
+- `payment/*` — Payment pages (checkout, confirmation)
+- `account/*` — Account management pages
+- `app.html` — App page
+- `404.html` — Error page
+
+## Default Pages — Customization Levels
+
+| Page | File | Layout | Level | Customize | Keep defaults |
+|------|------|--------|-------|-----------|---------------|
+| Homepage | `src/pages/index.md` | `blueprint/index` | Full | `hero`, `features`, `testimonials`, `stats`, `cta` | `superheadline` (icon AND text) |
+| Pricing | `src/pages/pricing.md` | `blueprint/pricing` | Full | plan `features`/`pricing`/`definitions`/`price_per_unit`, `testimonials`, `faqs` | plan `id`/`name`/`tagline`, plan order |
+| About | `src/pages/about.md` | `blueprint/about` | Full | `hero`, `mission`, `vision`, `story`, `values`, `team` | — |
+| Contact | `src/pages/contact.md` | `blueprint/contact` | Minimal | `testimonials`, `faqs` ONLY | `hero`, `contact_methods`, `contact_form`, `stats` |
+| Download | `src/pages/download.md` | `blueprint/download` | Minimal | `testimonials`, `faqs` ONLY | `hero`, `platforms`, `features`, `system_requirements` |
+
+### Homepage hero specifics
+
+Always use the tagline format `tagline: "Introducing {{ site.brand.name }}"`. The hero supports optional display modes via `hero.display` — use only if the site benefits from an in-hero demo, CTA, or video:
+
+```yaml
+hero:
+  display:
+    type: input  # or: form, video, custom
+    view: side   # or: bottom (default)
+```
+
+- `bottom` (default) — content stacked vertically, display element below text; `side` — side-by-side, display element on the right
+- Types: `input` (single field + button, e.g. email signup), `form` (multiple fields), `video` (embedded player), `custom` (only for something the others can't achieve)
+- Reference examples: `src/defaults/dist/pages/test/components/hero-demo-{input,form,video,side,custom}.html`
+
+### Pricing plan features
+
+Use YAML comments to separate feature types in each plan's `features` array:
+
+- `# Common features` — listed in EVERY plan, displayed aligned across all plan cards
+- `# Additional features` — features introduced in THIS plan only, appear in the "Everything in X, plus:" section
+
+Do NOT repeat additional features that are unchanged from the previous plan (they're inherited automatically).
+
+### Testimonials (any page)
+
+Each testimonial requires `quote` (1-2 sentences max), `author`, `role`, `company`, `initial` (first letter of name, shown in avatar). Use 3 for balanced display, keep quotes relevant to the page (pricing → value/ROI, contact → support experience), vary roles to show a broad customer base.
+
+### FAQs (any page)
+
+Each FAQ requires `question` + `answer` (answers can include HTML like `<br><br>`). Use 3-5 per page, focused on the page's topic (pricing → billing/trials/refunds, contact → response times/channels), ordered by most commonly asked. `{{ site.brand.name }}` works in answers.
+
+## Dashboard Resource Pages (list/detail/edit)
+
+For dashboard resource pages (e.g., forms, users, orders), use separate pages — do NOT use a single page with show/hide toggling.
+
+**File structure:**
+
+```
+src/pages/dashboard/items/
+  index.html     ← list page
+  view.html      ← detail page
+  edit.html      ← edit page (optional)
+
+src/assets/js/pages/dashboard/items/
+  index.js
+  view.js
+  edit.js        ← (optional)
+```
+
+**URL pattern:** `/dashboard/items` (list) · `/dashboard/items/view?id={id}` (detail) · `/dashboard/items/edit?id={id}` (edit, optional).
+
+**Frontmatter:** the view page's breadcrumbs follow Home → Dashboard → Items (linked) → Details (active, no href):
+
+```yaml
+meta:
+  breadcrumbs:
+    - label: Home
+      href: /
+    - label: Dashboard
+      href: /dashboard
+    - label: Items
+      href: /dashboard/items
+    - label: Details
+      active: true
+```
+
+**JS conventions:**
+
+- `view.js` must redirect to the list page if no `?id=` param is present:
+
+  ```js
+  const id = new URLSearchParams(window.location.search).get('id');
+  if (!id) {
+    window.location.href = '/dashboard/items';
+    return;
+  }
+  ```
+
+- Links from the list page to detail use `/dashboard/items/view?id=${item.id}`
+- After creating an item, redirect to `/dashboard/items/view?id=${item.id}`
+- Delete on the view page redirects back to the list page
+
+## Creating Custom Pages (beyond blueprints)
+
+When a page needs custom HTML (no blueprint fits):
+
+1. Place it in `src/pages/` with `.html` extension
+2. Use `layout: themes/[ site.theme.id ]/frontend/core/base`
+3. **Include `meta.title` and `meta.description`** in frontmatter (see [seo.md](seo.md))
+4. Follow the HTML patterns from default pages: `{% uj_icon %}` for icons, theme-adaptive classes (`bg-body`, `bg-body-secondary`, `text-body`, `btn-adaptive` — see [css.md](css.md)), `data-lazy="@class animation-slide-up"` animations, `page.resolved.[section]` for frontmatter data, the superheadline/headline/headline_accent/subheadline pattern
+5. Use frontmatter for configuration data, keep actual content in the body
+6. Forms: always FormManager with `onsubmit="return false"` + `novalidate` — see [page-loading.md](page-loading.md) for the full form protection standards
+7. Create `src/assets/css/pages/[page-name]/index.scss` / `src/assets/js/pages/[page-name]/index.js` only if needed ([assets.md](assets.md))
+
+A good reference implementation to study: `src/defaults/dist/_layouts/themes/classy/frontend/pages/contact.html` (frontmatter structure, section organization, Bootstrap classes, `{% uj_icon %}`, `page.resolved`, form validation attributes, responsive grids, `data-lazy` animations).
+
+## See also
+
+- [assets.md](assets.md) — frontmatter customization mechanism, page module/CSS auto-loading, nav/footer/account JSON
+- [seo.md](seo.md) — content writing rules, services/solutions/alternatives page types, JSON-LD schema
+- [themes.md](themes.md) — theme layouts, the classy fallback, authoring new themes
+- [no-inline-scripts.md](no-inline-scripts.md) — where page JS goes (never inline)

package/docs/local-development.md

@@ -4,14 +4,7 @@ The local development server URL is stored in `.temp/_config_browsersync.yml` in
 
 ## Log Files
 
-UJM tees every line of stdout/stderr from the gulp pipeline into a log file in the consumer project root, so you can `tail -f` it or `grep` through it after a run:
-
-- `npm start` → `logs/dev.log`
-- `npm run build` (i.e. `UJ_BUILD_MODE=true`) → `logs/build.log`
-
-Both files **truncate fresh on each run** — the most recent session only. ANSI color codes are stripped from the file (so it's grep-friendly); the terminal continues to receive colored output unchanged. Captures everything that flows through stdout/stderr: `Manager.logger(...)` output, raw `console.log` calls, gulp task names, jekyll's child output, webpack output, the works.
-
-**Skipped on CI/cloud.** When `UJ_IS_SERVER=true` (set by GitHub Actions workflows and other server contexts), the tee is bypassed entirely — no `logs/` directory is written. Implementation: [src/utils/attach-log-file.js](../src/utils/attach-log-file.js), attached at the top of [src/gulp/main.js](../src/gulp/main.js).
+The gulp pipeline tees all output to `logs/dev.log` (`npm start`) / `logs/build.log` (`npm run build`), and `npx mgr test` tees to `logs/test.log`. Full reference — file table, capture behavior, CI skip via `UJ_IS_SERVER`: [logging.md](logging.md).
 
 ## Connecting to Local Firebase Emulators
 

package/docs/logging.md

@@ -0,0 +1,30 @@
+# Logging
+
+UJM tees every line of CLI/pipeline output to log files in the consumer project root, so you can `tail -f` or `grep` a run instead of scrolling terminal scrollback. Frontend runtime logs live in the browser console — this doc covers the file logs UJM itself writes.
+
+## Log files
+
+All in `<projectRoot>/logs/`:
+
+| File | Source | Lifetime |
+|---|---|---|
+| `dev.log` | Gulp pipeline output on `npm start` | Truncated each run |
+| `build.log` | Gulp pipeline output on `npm run build` (`UJ_BUILD_MODE=true`) | Truncated each run |
+| `test.log` | `npx mgr test` runner output (suite names, pass/fail states, timings) | Truncated each run |
+
+`dev.log` and `build.log` are the same gulp tee — which one it writes is chosen by `UJ_BUILD_MODE`, so they never both fill up in one run.
+
+## What gets captured
+
+Everything that flows through stdout/stderr: `Manager.logger(...)` output, raw `console.log` calls, gulp task names, jekyll's child output, webpack output, the works. ANSI color codes are stripped from the file (grep-friendly); the terminal continues to receive colored output unchanged.
+
+## Controls
+
+**Skipped on CI/cloud.** When `UJ_IS_SERVER=true` (set by GitHub Actions workflows and other server contexts), the tee is bypassed entirely — no `logs/` directory is written.
+
+Implementation: [src/utils/attach-log-file.js](../src/utils/attach-log-file.js), attached at the top of [src/gulp/main.js](../src/gulp/main.js) — same pattern as EM's `dev.log`/`build.log` and BXM's.
+
+## See also
+
+- [local-development.md](local-development.md) — dev server URL, emulator connection, PurgeCSS
+- [test-framework.md](test-framework.md) — the test runner that feeds `test.log`

package/docs/migration.md

@@ -0,0 +1,131 @@
+# Migration
+
+Procedures for moving projects between UJ/UJM format versions. Three modes: **full migration** (old UJ → latest UJM base), **quick fix** (normalize `_config.yml` section order), and **revert posts** (back to the OLD pre-migration format).
+
+## Full Migration (old UJ → new UJM)
+
+Three stages: repository migration to the latest UJM base (preserving content in `_legacy/`) → config YML re-mapping → cleanup.
+
+### Stage 1: Repository migration to the new UJM base
+
+1. **Sync latest changes:** `git fetch origin && git pull origin master`
+2. **Delete node_modules** before moving to legacy: `rm -rf node_modules`
+3. **Move everything to `_legacy/`** for a clean slate:
+   ```bash
+   mkdir -p _legacy
+   find . -maxdepth 1 ! -name '_legacy' ! -name '.' ! -name '.git' -exec mv {} _legacy/ \;
+   ```
+4. **Download the Ultimate Jekyll template** (https://github.com/itw-creative-works/ultimate-jekyll):
+   ```bash
+   git clone https://github.com/itw-creative-works/ultimate-jekyll.git /tmp/uj-fresh
+   rsync -av --exclude='.git' /tmp/uj-fresh/ ./
+   rm -rf /tmp/uj-fresh
+   ```
+5. **Setup and build:** `npm install && npx mgr setup && npm run build`
+6. **Migrate content from legacy.** **DO NOT copy default pages** — UJM provides standard pages through its template system (see `src/defaults/dist/pages` in the UJM package for the full list). Only migrate **content** (posts, images, collections):
+   ```bash
+   # Blog images
+   mkdir -p src/assets/images/blog
+   cp -r _legacy/assets/_src/images/blog/posts/* src/assets/images/blog/ 2>/dev/null || true
+   cp -r _legacy/assets/images/blog/posts/* src/assets/images/blog/ 2>/dev/null || true
+
+   # Blog posts
+   mkdir -p src/_posts
+   cp -r _legacy/_posts/* src/_posts/ 2>/dev/null || true
+
+   # Custom collections / images (if any)
+   cp -r _legacy/_themes src/_themes 2>/dev/null || true
+   cp -r _legacy/assets/images/themes src/assets/images/ 2>/dev/null || true
+   cp -r _legacy/assets/images/resources src/assets/images/ 2>/dev/null || true
+   ```
+   **Custom pages — DO NOT COPY, RECREATE:** reference `_legacy/pages/` for content/text only; rebuild the HTML with the current theme structure ([layouts-and-pages.md](layouts-and-pages.md), [themes.md](themes.md)).
+7. **Verify:** `src/_posts/` populated, `src/assets/images/blog/` populated, `_legacy/_config.yml` exists (used in stage 2), NO legacy pages copied.
+8. **Rename master → main:**
+   ```bash
+   git branch -m master main
+   git push -u origin main
+   gh api repos/OWNER/REPO -X PATCH -f default_branch=main
+   git push origin --delete master
+   ```
+
+### Stage 2: Config YML re-mapping
+
+1. Read the NEW standard template (`src/defaults/src/_config.yml` in the UJM package) and the OLD config (`_legacy/_config.yml`).
+2. Create a migration TODO list.
+3. **Map old keys to new format** — use the NEW format as the template (preserve order, comments, structure); map old keys to new (e.g. `contact.email-support` → `brand.contact.email`). **DO NOT import keys that don't exist in the NEW format**; only import deprecated keys when the user explicitly requests them.
+4. After initial mapping, tell the user: "Base migration complete. If you need any deprecated keys from `_legacy/_config.yml` imported, let me know which ones."
+5. Write the new `src/_config.yml` — NEW structure/order/comments, values filled from the old config where mappings exist.
+6. **Required adjustments:** replace hardcoded brand names with `{{ site.brand.name }}` in `meta.title`/`meta.description`; rewrite `brand.description` to 5-8 words max; set default colors for cookieConsent and chatsy (`#237afc` / `#fff`).
+7. Verify.
+
+### Stage 3: Cleanup
+
+1. Run `npx mgr migrate`.
+2. Tell the user: the `_legacy/` folder holds the original files for reference and can be deleted (`rm -rf _legacy/`) once confirmed.
+
+## Quick Fix (normalize `_config.yml` section order)
+
+Ensure these keys exist in `src/_config.yml` in this order. Insert missing keys with these defaults — do NOT overwrite existing values:
+
+```yaml
+# Tracking
+tracking:
+  google-analytics: null
+  meta-pixel: null
+  tiktok-pixel: null
+
+# reCAPTCHA
+recaptcha:
+  site-key: null
+
+# Cloudflare
+cloudflare:
+  zone: null
+
+# Download
+download:
+  mac:
+    universal: ""
+  windows:
+    universal: ""
+  linux:
+    debian: ""
+    snap: ""
+  ios:
+    universal: ""
+  android:
+    universal: ""
+
+# Extension
+extension:
+  chrome: ""
+  firefox: ""
+  opera: ""
+  safari: ""
+  edge: ""
+  brave: ""
+
+# Favicon
+favicon:
+  path: "https://cdn.itwcreativeworks.com/assets/itw-creative-works/images/favicon"
+  safari-pinned-tab: "#5bbad5"
+  msapp-tile-color: "#da532c"
+  theme-color: "#ffffff"
+```
+
+## Revert Posts (back to the OLD format)
+
+For sites that have NOT yet migrated to the new UJ structure. Verify `./src/_posts` exists before starting.
+
+1. **Move posts:** `./src/_posts` → `./_posts` (preserve folder structure)
+2. **Move blog images:** everything under `./src/assets/images/blog/` → `./assets/_src/images/blog/posts/` (create destination if needed)
+3. **Remove `./src`** after the moves complete
+4. **Update front matter** in every `./_posts/**/*.md`:
+   - `layout: blueprint/blog/post` → `layout: app/blog/post`
+   - rename key `post.description` → `post.excerpt`
+
+## See also
+
+- [directory-structure.md](directory-structure.md) — where everything lives in the new format
+- [layouts-and-pages.md](layouts-and-pages.md) — recreating custom pages with blueprints
+- [themes.md](themes.md) — the theme structure recreated pages must use

package/docs/no-inline-scripts.md

@@ -0,0 +1,304 @@
+# NO JavaScript in HTML Files — Hard Rule
+
+**THIS IS NON-NEGOTIABLE.** No `<script>` tag with an inline JS body is ever allowed in any file under `src/` — not pages, not components (`_includes/`), not layouts (`_layouts/`). If you find one, you move it. If you write one, you are wrong.
+
+## Why this rule exists
+
+1. **UJM auto-loads page modules.** The framework already provides a first-class mechanism: `src/assets/js/pages/<pagePath>/index.js` runs automatically for each page based on `data-page-path`. Inline scripts bypass this system, fragment the codebase, and make code impossible to lint/test/bundle properly.
+2. **Inline scripts break module boundaries.** They can't `import` anything, can't be code-split, can't be tree-shaken, and have to re-declare every helper.
+3. **Inline scripts hide bugs.** They often reference globals (`Manager`, `firebase`, `webManager.uj`) that aren't exposed, breaking silently at runtime.
+4. **Inline scripts duplicate logic.** The same drop-down/demo/filter logic gets copy-pasted into many files instead of being shared from a single module.
+5. **Inline scripts are a historical accident.** Old UJM (pre-2.0) exposed `Manager` globally and encouraged inline scripts. That's gone. Any inline script you see in a repo is migration debt that must be paid.
+
+## The rule, stated precisely
+
+For every `<script>` tag in `src/**/*.html` under a UJM project:
+
+| Tag shape | Allowed? | Why |
+|-----------|----------|-----|
+| `<script>...body...</script>` with JS body | ❌ **NEVER** | Move the body to a JS module (see below) |
+| `<script src="https://..."></script>` | ✅ OK | External loader, no inline code |
+| `<script type="application/ld+json">...</script>` | ✅ OK | Structured data, not JS |
+| `<script type="module" src="..."></script>` | ✅ OK | External ES module, no inline code |
+| `<script>` with ≤10 lines of trivial first-paint display | ✅ OK with comment | Small helpers that must run before the bundle |
+
+**The "small helper" exception must meet ALL of these:**
+
+- Under ~10 lines of code
+- Does a single cosmetic first-paint task (e.g. replacing a `--:--:--` placeholder with the current time)
+- Would cause visible flash/flicker if deferred to the bundle
+- Has an inline comment explaining why it's intentionally inline
+
+If in doubt, move it. The exception is for ≤10-line display polyfills, NOT for 20-line "quick" handlers.
+
+## Where to move the script
+
+### Case 1: The script is inside a **page** file (`src/pages/<something>.html` or `.md`)
+
+Move it to `src/assets/js/pages/<pagePath>/index.js` — the path is derived from the page's frontmatter `permalink:`.
+
+| Page frontmatter | Page module path |
+|------------------|------------------|
+| `permalink: /` | `src/assets/js/pages/index.js` |
+| `permalink: /contact` | `src/assets/js/pages/contact/index.js` |
+| `permalink: /dashboard/history` | `src/assets/js/pages/dashboard/history/index.js` |
+| `permalink: /tools/form-builder` | `src/assets/js/pages/tools/form-builder/index.js` |
+
+**Always check if the target file already exists.** If it does, MERGE your logic into the existing `export default` function. DO NOT overwrite.
+
+Module template:
+
+```javascript
+/**
+ * <Page Name> Page JavaScript
+ */
+
+import webManager from 'web-manager';
+
+export default async () => {
+  await webManager.dom().ready();
+
+  // ... moved logic ...
+};
+```
+
+### Case 2: The script is inside a **component** (`src/_includes/**/*.html`)
+
+Components are Jekyll partials — they don't have a single "page path" because they can be included in many pages. Two strategies:
+
+**Option A — Used by exactly one page:** Move the script to that one page's `src/assets/js/pages/<path>/index.js`. Simpler, more scoped.
+
+**Option B — Used by multiple pages (or you can't tell):** Move the script to `src/assets/js/main.js` as an `init<ComponentName>()` function with an **element-existence guard** so it's a no-op on pages without the component.
+
+```javascript
+// src/assets/js/main.js
+import Manager from 'ultimate-jekyll-manager';
+import webManager from 'web-manager';
+
+const manager = new Manager();
+
+manager.initialize().then(() => {
+  // Each component gets its own init function with a guard
+  initHeroDemo();
+  initChatDemo();
+  initScheduler();
+});
+
+function initHeroDemo() {
+  // Element-existence guard — MUST be the first thing in the function
+  const $toggle = document.getElementById('hero-demo-toggle');
+  if (!$toggle) return;
+
+  // ... moved logic ...
+}
+```
+
+**How to pick the guard element:** use the first `getElementById` / `querySelector` the original script called. If that element isn't on the page, the original script would have crashed anyway, so returning early is safe.
+
+### Case 3: The script is inside a **layout** (`src/_layouts/**/*.html`)
+
+Same as components: grep for `layout: <layout-path>` across pages. If one page uses it, move to that page's module. If multiple, move to `main.js` with a guard.
+
+## Handling Liquid templating inside a script
+
+This is the trickiest case, and the one that trips most people up. **Jekyll Liquid (`{{ ... }}`, `{% ... %}`) runs at BUILD TIME on HTML files. Webpack-bundled JS modules under `src/assets/js/` are NOT processed by Jekyll** — any Liquid you leave inside a `.js` file will appear as literal text in the output.
+
+### Strategy A: `data-*` attribute bridge (for Liquid values)
+
+Use this when the script reads values from Liquid, e.g. `{{ site.url }}`, `{{ include.action1 | default: "..." }}`, `{{ page.items | jsonify }}`.
+
+**Before (broken inline script):**
+
+```html
+<!-- src/_includes/frontend/components/hero-demo.html -->
+<script>
+  var platform = '{{ include.platform }}';
+  var actions = [
+    '{{ include.action1 | default: "Like" }}',
+    '{{ include.action2 | default: "Share" }}',
+  ];
+  var items = {{ page.items | jsonify }};
+</script>
+```
+
+**After:**
+
+```html
+<!-- src/_includes/frontend/components/hero-demo.html -->
+<!-- Hidden config element — Jekyll fills data attributes at build time -->
+<div id="hero-demo-config"
+     data-platform="{{ include.platform }}"
+     data-action-1="{{ include.action1 | default: 'Like' }}"
+     data-action-2="{{ include.action2 | default: 'Share' }}"
+     data-items='{{ page.items | jsonify }}'
+     hidden></div>
+
+<!-- ... rest of component markup ... -->
+
+<!-- Logic moved to src/assets/js/main.js (initHeroDemo) -->
+```
+
+```javascript
+// src/assets/js/main.js
+function initHeroDemo() {
+  const $config = document.getElementById('hero-demo-config');
+  if (!$config) return;
+
+  const platform = $config.dataset.platform;
+  const actions = [
+    $config.dataset.action1,
+    $config.dataset.action2,
+  ];
+  const items = JSON.parse($config.dataset.items);
+
+  // ... moved logic ...
+}
+```
+
+**Notes on data attributes:**
+
+- Use kebab-case in HTML (`data-action-1`), which maps to camelCase in JS (`.dataset.action1`).
+- For `| jsonify` output, wrap the attribute value in single quotes: `data-items='{{ x | jsonify }}'` (jsonify emits double-quoted JSON).
+- For complex objects, use `| jsonify` → `data-json='...'` → `JSON.parse($config.dataset.json)`.
+
+### Strategy B: `<template>` element cloning (for Liquid render tags)
+
+Use this when the script interpolates Liquid render tags like `{% uj_icon "name" %}` or `{% include partials/x.html %}` into HTML strings it builds.
+
+**Before (broken inline script):**
+
+```html
+<!-- Inline script tries to build HTML string with Liquid render tag -->
+<script>
+  el.innerHTML = '<span class="icon">{% uj_icon "arrow-pointer", "smaller" %}</span>';
+</script>
+```
+
+**After:**
+
+```html
+<!-- Hidden templates — Jekyll renders the icon markup inside at build time -->
+<template id="hero-demo-icon-arrow-pointer">{% uj_icon "arrow-pointer", "smaller" %}</template>
+<template id="hero-demo-icon-eye">{% uj_icon "eye", "smaller" %}</template>
+
+<!-- ... rest of component markup ... -->
+
+<!-- Logic moved to src/assets/js/main.js (initHeroDemo) -->
+```
+
+```javascript
+// src/assets/js/main.js
+function getIcon(name) {
+  const $template = document.getElementById('hero-demo-icon-' + name);
+  return $template ? $template.content.cloneNode(true) : document.createTextNode('');
+}
+
+function initHeroDemo() {
+  const $container = document.getElementById('hero-demo');
+  if (!$container) return;
+
+  // Build DOM nodes programmatically — NO innerHTML string building
+  const $span = document.createElement('span');
+  $span.className = 'icon';
+  $span.appendChild(getIcon('arrow-pointer'));
+  $container.appendChild($span);
+}
+```
+
+**Why template cloning instead of innerHTML string concat:** Liquid render tags produce complex nested HTML (SVG with classes, etc.) that can't be easily stringified. Templates let Jekyll render the full HTML once, then JS clones it as needed. This also avoids XSS risk and the need for `escapeHTML()`.
+
+### Strategy C: Liquid conditional branching (`{% if %}` in scripts)
+
+Rewrite as JS conditionals using data-attribute values.
+
+**Before:**
+
+```html
+<script>
+  {% if include.mode == "turbo" %}
+    setInterval(tick, 100);
+  {% else %}
+    setInterval(tick, 1000);
+  {% endif %}
+</script>
+```
+
+**After:**
+
+```html
+<div id="demo-config" data-mode="{{ include.mode }}" hidden></div>
+<!-- Logic moved to main.js (initDemo) -->
+```
+
+```javascript
+function initDemo() {
+  const $config = document.getElementById('demo-config');
+  if (!$config) return;
+
+  const mode = $config.dataset.mode;
+  const intervalMs = mode === 'turbo' ? 100 : 1000;
+  setInterval(tick, intervalMs);
+}
+```
+
+## Handling globals from inline scripts
+
+Old inline scripts often defined functions that other code expected to find on `window` (hCaptcha callbacks, YouTube IFrame API callbacks, inline `onclick="..."` handlers, etc.). When moving to a module:
+
+```javascript
+// In the page module / init function
+function hCaptchaLoadCallback() { /* ... */ }
+function hCaptchaCompleteCallback() { /* ... */ }
+
+// Expose on window — required by external script that calls it globally
+window.hCaptchaLoadCallback = hCaptchaLoadCallback;
+window.hCaptchaCompleteCallback = hCaptchaCompleteCallback;
+```
+
+Same applies to `onYouTubeIframeAPIReady`, inline `onclick="handleFoo(this)"`, and similar global-callback patterns. Leave the external `<script src="...">` loader in place (it's allowed), but put its callbacks in a module and explicitly assign them to `window`.
+
+## Playbook: moving an inline script step by step
+
+1. **Read the full HTML file** (not just the script block) — frontmatter, surrounding markup, all `<script>` tags.
+2. **Classify each `<script>` tag**:
+   - `type="application/ld+json"` → leave alone (structured data)
+   - `src="..."` → leave alone (external loader)
+   - Trivial ≤10-line first-paint helper → leave alone with a comment
+   - Everything else → **MOVE**
+3. **Grep the script body** for `{{` and `{%` to find Liquid references. Plan your data-attribute and template element bridges.
+4. **Determine the destination**:
+   - Page → `src/assets/js/pages/<pagePath>/index.js` (check if it exists; merge if so)
+   - Component/layout used by one page → that page's module
+   - Component/layout used by many pages → `src/assets/js/main.js` with `init<Name>()` guard
+5. **Add bridge elements to the HTML** (`<div data-*>` config, `<template>` icons) **before** removing the script. This way Jekyll still processes the Liquid.
+6. **Move the script body** to the destination. Unwrap any `(function() { ... })()` IIFE. Preserve `var`/`const`/`let` exactly. Add the element-existence guard as the first statement.
+7. **Rewrite Liquid references** in the moved JS to read from data attributes or clone templates.
+8. **Replace the `<script>...</script>` block** in HTML with `<!-- Logic moved to <destination path> -->`.
+9. **Verify with `git diff`** — confirm the HTML change is only the script removal + any bridge elements you added.
+10. **Do NOT refactor the script logic** while moving it. Move verbatim with only the changes required to work outside the HTML file. Refactoring and moving in the same pass is how bugs get introduced.
+
+## What NOT to do
+
+- ❌ Don't leave `Manager.something()` — `Manager` is not globally exposed. Use `import webManager from 'web-manager'`.
+- ❌ Don't leave `firebase.firestore()` — Firebase is not globally exposed either. Use `webManager.firestore()`.
+- ❌ Don't build HTML strings with Liquid interpolation inside a JS module — it won't be processed.
+- ❌ Don't use `window.showExitPopup = () => webManager.uj().showExitPopup()` shims as a way to avoid moving the rest of the logic. Move the whole script.
+- ❌ Don't split one inline script across multiple modules "for organization" — keep it as one function in the destination file.
+- ❌ Don't add the script to `main.js` without an element-existence guard. `main.js` runs on every page.
+- ❌ Don't forget that `src/assets/js/pages/index.js` is the module for the root `permalink: /` — the file lives at `pages/index.js`, NOT `pages//index.js` or `pages/home/index.js`.
+
+## Verification
+
+After moving an inline script, run this grep to confirm the file is clean:
+
+```bash
+# Should find zero matches (excluding ld+json and external src)
+rg -U '<script>[\s\S]*?</script>' src/**/*.html
+```
+
+## See also
+
+- [assets.md](assets.md) — page module structure, webpack aliases, where each JS file lives
+- [common-mistakes.md](common-mistakes.md) — inline scripts are mistake #1
+- [xss-prevention.md](xss-prevention.md) — escaping rules for any HTML the moved JS builds
+- [templating.md](templating.md) — what Liquid processes (and what it doesn't)