ultimate-jekyll-manager 1.7.2 → 1.8.0

package/docs/purgecss.md

@@ -0,0 +1,164 @@
+# PurgeCSS Safelist
+
+PurgeCSS removes unused CSS in production builds. Classes added dynamically via JavaScript (e.g., `classList.add()`, `innerHTML` templates) won't be found in static HTML, so they get purged.
+
+## IMPORTANT: Update Safelist When Writing Dynamic JS
+
+**When writing JavaScript that dynamically adds CSS classes** (via `classList.add()`, `classList.toggle()`, `className =`, or `innerHTML` with class attributes), you MUST check if the class is already safelisted. If not, add it to the appropriate safelist:
+
+- **UJM-internal classes** → `src/gulp/tasks/sass.js` safelist
+- **Consuming project classes** → `config/ultimate-jekyll-manager.json` → `sass.purgecss.safelist`
+
+**NEVER edit `dist/` or `node_modules/`.** Those are build outputs. Edit `src/` only.
+
+## Two Safelist Locations
+
+### 1. UJM Internal Safelist (sass.js)
+
+**File:** `src/gulp/tasks/sass.js`
+
+This is where UJM's own safelist lives — patterns for Bootstrap utilities, UJM core classes, and third-party injected elements. Uses native RegExp objects.
+
+**Changes to sass.js require a dev server restart** — gulp tasks are loaded once at startup.
+
+### 2. Consuming Project Safelist (JSON config)
+
+**File:** `config/ultimate-jekyll-manager.json` → `sass.purgecss.safelist`
+
+For consuming project-specific classes. Uses regex strings (converted to `new RegExp(s)` by UJM).
+
+```json5
+{
+  sass: {
+    purgecss: {
+      safelist: {
+        standard: [],  // Class names (converted to RegExp)
+        deep: [],      // Pseudo-selector patterns
+        greedy: [],    // Broader patterns (matches substrings)
+        keyframes: [], // @keyframes animation names
+      },
+    },
+  },
+}
+```
+
+## PurgeCSS Gotchas
+
+### `!` Negation patterns DON'T work in the content array
+
+PurgeCSS passes each content pattern to `fast-glob` **individually** (not as a batch), so `!path/**` returns 0 files instead of excluding anything. Use `skippedContentGlobs` for exclusions instead.
+
+### Option naming is counterintuitive
+
+`true` = "yes, **purge** this category", `false` = "leave it alone":
+
+| Option | `true` | `false` |
+|--------|--------|---------|
+| `variables` | Remove unused CSS variables | Don't touch variables |
+| `keyframes` | Remove unused @keyframes | Don't touch keyframes |
+| `fontFace` | Remove unused @font-face | Don't touch font-face |
+
+### `variables` must stay `false`
+
+PurgeCSS processes each CSS file independently. Page-specific CSS sets CSS custom properties (e.g., `--bs-btn-bg` in `.btn-paypal`) that are consumed by the base `.btn` class in the main bundle. With `variables: true`, these cross-file variable references are falsely flagged as unused and removed.
+
+### PurgeCSS processes per-file, not per-bundle
+
+Each CSS file is processed against the content files independently. A class defined in a page CSS file must be found in the content files on its own — it can't rely on being "seen" in the context of the main bundle.
+
+## All Entries Are RegExp
+
+Every entry in the consuming project safelist arrays is wrapped in `new RegExp(s)`. This means:
+
+- `'dot'` becomes `/dot/` — matches ANY class containing "dot" (e.g., `dotted`, `polkadot`)
+- **Always anchor exact class names** with `^...$`
+
+### Correct Usage
+
+```json5
+{
+  standard: ['^fw-semibold$'],             // Top-level exact matches
+  deep: ['^dot$'],                         // Nested selectors (.chat-typing .dot)
+  greedy: ['^chat-'],                      // Prefix match (all chat-* classes)
+  keyframes: ['chat-typing-bounce'],       // Specific enough, no anchor needed
+}
+```
+
+## Current UJM Safelist (sass.js)
+
+Before adding classes, check what UJM already safelists in `src/gulp/tasks/sass.js`:
+
+### Bootstrap Utilities
+- `/^btn-/` — button variants
+- `/^d-/` — display utilities
+- `/^text-/` — text utilities
+- `/^bg-/` — background utilities
+- `/^flex-/` — flex utilities
+- `/^justify-/`, `/^align-/` — alignment
+- `/^position-/` — positioning
+- `/^[mp][trblxy]?-[0-9]+$/` — margin/padding
+- `/^w-/`, `/^h-/`, `/^mw-/`, `/^mh-/`, `/^min-/`, `/^max-/` — sizing
+- `/^border-/`, `/^rounded-/`, `/^shadow-/` — borders/shadows
+- `/^overflow-/`, `/^order-/` — overflow/order
+- `/^fw-/` — font weight
+- `/^ratio-/`, `/^object-/` — aspect ratio/object-fit
+- `/^filter-/` — filter utilities
+
+### Bootstrap Components
+- `/^modal-/`, `/^carousel-/`, `/^dropdown-/`, `/^offcanvas-/`
+- `/^tooltip-/`, `/^popover-/`, `/^toast-/`
+- `/^accordion/`, `/^collapse/`, `/^collapsed$/`, `/^collapsing$/`
+- `/^show$/`, `/^showing$/`, `/^hide$/`, `/^fade$/`, `/^active$/`, `/^disabled$/`
+- `/^bs-/`, `/^data-bs-/`
+
+### State & Dynamic Classes
+- `/^is-/`, `/^has-/`, `/^was-/` — state classes
+- `/^animation-/` — all animation-* classes
+
+### Form & Validation
+- `/^invalid-feedback$/` — form validation messages
+- `/^spinner-/` — loading spinners
+- `/^file-drop-/` — file drop zone states
+
+### Libraries & Third-Party
+- `/^fa-/` — Font Awesome
+- `/^lazy-/` — lazy loading
+- `/^cookie-consent-/` — cookie consent
+- `/^social-share-/` — social sharing
+- `/^grecaptcha/` — Google reCAPTCHA
+- `/^adsbygoogle$/` — Google AdSense
+- `/^uj-vert-unit$/` — UJM ad units
+- `/^uptime-tooltip$/` — status page tooltip
+
+### Also Safe: Classes in Static HTML
+
+Classes that appear in any HTML file (includes, layouts, pages) are automatically found by PurgeCSS and won't be purged. Only classes created exclusively in JavaScript need safelisting.
+
+## When to Use Each Category
+
+| Category | Use For | Example |
+|----------|---------|---------|
+| `standard` | Top-level class selectors only in JS | `'^fw-semibold$'` or `/^fw-/` |
+| `deep` | Classes used as **nested/descendant** selectors | `'^dot$'` (for `.chat-typing .dot`) |
+| `greedy` | Prefix-based families of classes | `'^chat-'` (matches chat-row, chat-bubble, etc.) |
+| `keyframes` | Custom @keyframes animation names | `'chat-typing-bounce'` |
+
+### standard vs deep
+
+- **standard**: Only preserves top-level selectors. If a class is ONLY used as a descendant (e.g., `.chat-typing .dot`), `standard` won't preserve the rule.
+- **deep**: Preserves the entire rule tree when any part of the selector matches.
+
+## Workflow
+
+1. **Find dynamic classes**: Search JS files for `classList.add()`, `classList.toggle()`, `className =`, `innerHTML` with `class=`, template literals with classes
+2. **Check safelist**: Cross-reference against the patterns above — don't add what's already covered
+3. **Check static HTML**: If a class appears in any HTML file, it doesn't need safelisting
+4. **Add to correct location**: UJM core classes → `sass.js`, consuming project classes → `config/ultimate-jekyll-manager.json`
+5. **Group by prefix**: If multiple classes share a prefix, use a prefix pattern like `/^chat-/`
+6. **Restart required**: Changes to `sass.js` require a dev server restart (gulp tasks load once at startup)
+
+## See also
+
+- [css.md](css.md) — CSS guidelines, theme-adaptive classes
+- [build-system.md](build-system.md) — where the sass/purge task runs in the pipeline
+- [themes.md](themes.md) — theme SCSS structure (theme classes ship in static CSS, not JS)

package/docs/seo.md

@@ -1,9 +1,125 @@
-# SEO — Alternatives Pages & Structured Data
+# SEO & Content
 
-This doc covers two SEO-focused subsystems:
+This doc covers UJM's SEO and content subsystems:
 
-1. **Alternatives Collection** — competitor comparison landing pages.
-2. **Schema / Structured Data (JSON-LD)** — `SoftwareApplication` and `FAQPage` JSON-LD blocks.
+1. **Content writing rules** — headlines, sentence case, keywords (applies to ALL pages).
+2. **Content page types** — Services (main offerings), Solutions (SEO landing pages), Alternatives (competitor comparisons).
+3. **Schema / Structured Data (JSON-LD)** — `SoftwareApplication` and `FAQPage` JSON-LD blocks.
+
+## Content Writing Rules (applies to ALL pages)
+
+### H1 Headlines
+
+- **Start with an action verb** — tell the user what they're getting immediately
+- "Grow your business with social media ads" NOT "Social Media Advertising Services"
+- "Automate your workflow in minutes" NOT "Workflow Automation Platform"
+
+### Sentence Case (ALL headings)
+
+- First word capitalized, rest lowercase
+- "Grow your business with social media ads" NOT "Grow Your Business With Social Media Ads"
+
+### Keywords
+
+- Use primary keywords naturally throughout the page — in headings, subheadings, and body text
+- Keep content readable and natural — don't keyword stuff but still use primary and secondary keywords where relevant
+
+### Headline Structure (headline / headline_accent)
+
+**Section headlines (non-hero):**
+
+- Maximum 5-6 words total
+- ONLY the LAST word should be accented (placed in `headline_accent`)
+
+```yaml
+# CORRECT — Last word only
+headline: "Compare all"
+headline_accent: "plans"
+
+headline: "Frequently asked"
+headline_accent: "questions"
+
+# WRONG — Multiple words accented or wrong position
+headline: "Compare"
+headline_accent: "all plans"  # Too many words accented
+```
+
+**Hero section headlines (exception):**
+
+- Hero sections may accent MORE than just the last word — up to half of the phrase for emphasis
+
+```yaml
+hero:
+  headline: "The right plans for"
+  headline_accent: "your business"  # Multiple words OK in hero
+```
+
+**Homepage hero (special case):** more flexible — longer phrases with creative accent placement; focus on impact and brand messaging.
+
+### Frontmatter SEO Rules
+
+- **Default pages** (blueprint layouts): Do NOT include `meta.title` or `meta.description` — these are already set in the layout
+- **Custom pages**: MUST include `meta.title` and `meta.description` in frontmatter
+
+### Superheadline Rules
+
+- Homepage: Do NOT change (keep default icon AND text)
+- Other pages: Can customize `text` but keep default `icon`
+
+### General Content Guidelines
+
+- Keep copy concise and scannable; use active voice
+- Focus on benefits, not features
+- Match the brand tone from `_config.yml`
+- Maintain consistency across all pages
+
+## Services Pages (Main Offerings)
+
+Services (or Features) pages represent the MAIN OFFERINGS of the business — the core products, services, or capabilities the business publicly promotes (e.g. an agency's "Social Media Advertising", "SEO Services", "Web Design").
+
+**Structure:**
+
+```
+src/pages/services/
+├── index.md              # Lists all services
+├── [service-1].md        # layout: blueprint/index
+├── [service-2].md
+└── [service-3].md
+```
+
+**Page strategy — exactly 3 service pages** based on the business's core offerings:
+
+- Featured prominently in nav dropdown AND the services index page
+- Linked throughout the site (footer, CTAs, internal links)
+- Fully customized with tailored features, testimonials, case studies, etc.
+
+Each service page uses `layout: blueprint/index` with a hero like:
+
+```yaml
+hero:
+  tagline: "{{ site.brand.name }}"
+  headline: "Professional"
+  headline_accent: "[Service Name]"
+  subheadline: "[Value proposition for this service]"
+```
+
+**Navigation:** add a `Services` dropdown to `src/_includes/frontend/sections/nav.json` (3 services + divider + "All Services" link) and a `Services` column to `footer.json` — see [assets.md](assets.md) for the JSON section system.
+
+## Solutions Pages (SEO Landing Pages)
+
+Solutions pages are SEO-focused landing pages that target SPECIFIC keywords, niches, or audience segments. They are NOT publicly linked on the site — they LINK BACK to the main Services pages (e.g. for a "Social Media Advertising" service: "TikTok Ads Agency", "Facebook Ads for E-commerce").
+
+**Purpose:** drive organic traffic via long-tail keywords; target specific industries/platforms/use cases; funnel visitors to main service pages via CTAs and internal links.
+
+**Structure:** individual pages only (`src/pages/solutions/*.md`, `layout: blueprint/index`) — **NO index page**; solutions are discovered via search engines, not site navigation.
+
+**Guidelines:**
+
+- **NOT linked in nav, footer, or services index** — search-engine discovery only
+- **Always link back** to the related main service page (CTAs, body content, related-services section)
+- Can be lighter customizations (hero + key sections) since they're keyword-focused
+- Focus on specific search intent (e.g., "[Platform] + [Service] + [Location/Industry]")
+- Any number of pages — use keyword research to identify opportunities
 
 ## Alternatives Collection (SEO Competitor Comparison Pages)
 
@@ -96,6 +212,17 @@ Which renders as "Can I import my data from ExampleApp?" for an ExampleApp compe
 | CSS | `src/assets/css/pages/alternatives/alternative/index.scss` |
 | JS | `src/assets/js/pages/alternatives/alternative/index.js` |
 
+### Content Guidelines (alternatives)
+
+- **Comparison features:** include 8-12 features for a thorough comparison
+- **Values:** use `true`/`false` for binary features, strings for nuanced values ("Unlimited", "Limited", "Basic")
+- **Tone:** confident but not aggressive — focus on our strengths, not bashing competitors
+- **Shared sections:** do NOT repeat testimonials, stats, FAQs, CTA, or why_switch per page — they're inherited from the layout; override only when a specific competitor needs unique content
+- **Video:** optional — set `video.youtube_id` only if a comparison video exists for that competitor
+- **Up to 20 pages**
+- The `/alternatives` index page is auto-generated — do NOT create it manually
+- Do NOT add alternatives to the main nav or footer — discovered via search engines, like Solutions pages
+
 ## Schema / Structured Data (JSON-LD)
 
 UJ automatically generates JSON-LD structured data in `foot.html`. The SoftwareApplication schema with AggregateRating is opt-in via frontmatter.

package/docs/templating.md

@@ -0,0 +1,23 @@
+# Templating
+
+UJM uses node-powertools' `template()` for build-time token replacement, alongside (and deliberately distinct from) Jekyll's own Liquid templating.
+
+## How it works
+
+Two bracket conventions, chosen per call site so node-powertools tokens never collide with Liquid:
+
+| Brackets | Used by | Files |
+|---|---|---|
+| `{ x }` (node-powertools default) | Any `template()` call without a `brackets:` option — e.g. `defaults.js` Gemfile templating | Gemfile, scaffolded defaults |
+| `[ x ]` | `distribute.js` theme fallback + [template-transform.js](../src/gulp/tasks/utils/template-transform.js) | `.html` / `.md` / `.liquid` / `.json` |
+
+## Liquid coexistence
+
+Jekyll's Liquid `{{ }}` / `{% %}` is processed by **Jekyll itself**, NOT by node-powertools — those placeholders pass through node-powertools untouched. The square-bracket convention exists precisely so the two engines can template the same file without fighting.
+
+Corollary for consumer JS: Jekyll does NOT process `src/assets/js/**/*.js` — never leave Liquid tokens inside JS modules; bridge values via `data-*` attributes or `<template>` elements instead. See [common-mistakes.md](common-mistakes.md).
+
+## See also
+
+- [build-system.md](build-system.md) — where the templating passes run in the pipeline
+- [layouts-and-pages.md](layouts-and-pages.md) — Liquid-side layout/frontmatter reference

package/docs/test-boot-layer.md

@@ -1,4 +1,4 @@
-# Boot Layer
+# Test Framework — Boot Layer
 
 The boot layer runs Puppeteer against a real built `_site/` served by a tiny embedded HTTP server. It's the integration smoke that catches "did my actually-shipped site boot?" regressions — things plain-Node build tests can't see.
 

package/docs/test-framework.md

@@ -22,7 +22,19 @@ Mock **nothing** by default. There are exactly two cases where the real dependen
 
 If you can run it for real, you must. These exceptions are not a license to unit-test in isolation when a real-harness layer would work.
 
-**External APIs are skipped in-source, NOT mocked.** UJM build/gulp code that would hit the network (e.g. fetching Firebase auth files) short-circuits in its own source when `Manager.isTesting()` is true — it returns early, it does not return canned/mocked data. See [environment-detection.md](environment-detection.md). If a suite has slower live-integration tests, gate them behind the `--integration` flag (`UJ_TEST_INTEGRATION=1`) and run the real path; anything such a test creates externally MUST be cleaned up by the test (`cleanup`/`inspect` teardown) — the runner does not clean external systems.
+**External APIs are skipped in-source, NOT mocked.** UJM build/gulp code that would hit the network (e.g. fetching Firebase auth files) short-circuits in its own source when `Manager.isTesting()` is true — it returns early, it does not return canned/mocked data. See [environment-detection.md](environment-detection.md). If a suite has slower live-integration tests, gate them behind [extended mode](#extended-mode-test_extended_mode) (`--extended` / `TEST_EXTENDED_MODE=true`) and run the real path; anything such a test creates externally MUST be cleaned up by the test (`cleanup`/`inspect` teardown) — the runner does not clean external systems.
+
+## Test coverage — every surface gets a test (HARD RULE)
+
+A feature is not done when it works — it's done when every surface it exposes is covered in the layer that owns that surface:
+
+| Coverage | Layer | Proves |
+|---|---|---|
+| **Logic** | `build` / `page` | The feature's functions do the right thing when called directly (real build Manager, real frontend Manager surface) |
+| **UI** | `page` | The feature's interface is WIRED — a real event on the real DOM triggers the behavior and the visible result appears |
+| **End-to-end** | `boot` | The feature survives in the consumer's actual built `_site/` (extend the boot suite's `inspect` assertions) |
+
+**Skipping a layer is the exception, not the default.** A layer may be skipped ONLY when the feature genuinely has no surface there — a pure build-time utility has no UI; a CSS-only tweak has no logic to call. Convenience is never a reason: "the logic test already covers it" does NOT excuse the UI test — logic tests prove the logic, UI tests prove the wiring (a button can come unhooked while every logic test stays green), boot tests prove the built site. When in doubt, write the test.
 
 ## Quick start
 
@@ -37,25 +49,46 @@ npx mgr test --reporter json   # machine-readable __UJM_TEST__ events
 
 `npm test` works too — added to consumer `package.json#scripts.test` on `npx mgr setup`.
 
+All test output is also teed (ANSI-stripped) to `<projectRoot>/logs/test.log`, truncated fresh on each run — same pattern as `dev.log`/`build.log` and EM's/BEM's `test.log`. Skipped on CI (`isServer()`). Grep it after a run instead of scrolling terminal output.
+
 ### Filtering tests
 
-Pass a path (relative to `test/`) as a positional argument to run specific tests:
+Pass a path (relative to `test/`) as a positional **target** to select which test FILES run:
 
 ```bash
-# Run a single test file
+# Run a single test file (matches both framework + project)
 npx mgr test pages/home
 
-# Run only UJM framework tests
-npx mgr test ujm:pages/home
+# Run ONLY consumer project tests (no framework suites at all)
+npx mgr test project:
 
-# Run only consumer project tests
+# Run a single project test file
 npx mgr test project:custom-test
 
+# Run ONLY framework tests (universal cross-framework alias)
+npx mgr test mgr:
+
+# Run ONLY UJM framework tests (UJM-specific aliases, equivalent to mgr:)
+npx mgr test ujm:
+npx mgr test framework:
+
+# Run framework tests matching a path
+npx mgr test mgr:pages/home
+npx mgr test ujm:pages/home
+
 # Combine with extended mode
 TEST_EXTENDED_MODE=true npx mgr test pages/boot-test
 ```
 
-The filter matches against the test file path. `ujm:` and `project:` prefixes scope the filter to framework-only or project-only tests respectively. Without a prefix, both are searched.
+The target matches against the test file path. The source prefix scopes selection to framework-only or project-only tests — a prefixed target excludes the other source entirely:
+
+- `mgr:` — the **universal cross-framework alias** for "the manager's own tests" (framework-only). Works identically in UJM, EM, BXM, and BEM.
+- `ujm:` / `framework:` — UJM-specific aliases for framework-only tests, equivalent to `mgr:`.
+- `project:` — consumer project tests only.
+
+A bare prefix (`mgr:` / `ujm:` / `project:` with no path) runs every test in that source. A bare path (no prefix) searches both sources by path.
+
+> **Target vs `--filter`.** The positional target selects test FILES (by path + source). The `--filter=<substring>` flag is orthogonal: it matches test NAMES/descriptions within the selected files. They compose, e.g. `npx mgr test project: --filter=foo`. The `--layer=build|page|boot` flag further narrows to a single layer.
 
 ## Layers
 
@@ -227,12 +260,27 @@ module.exports = ({ projectRoot }) => ({
 });
 ```
 
+## Extended mode (`TEST_EXTENDED_MODE`)
+
+By default `npx mgr test` is fast and offline-safe: tests that would hit real external services are **skipped** (the code short-circuits in-source — it does NOT mock). Extended mode opts those tests in to run against the real path.
+
+- **Turn it on:** `npx mgr test --extended` or `TEST_EXTENDED_MODE=true npx mgr test`.
+- **Shared, unprefixed name.** `TEST_EXTENDED_MODE` is the SAME env var across BEM, BXM, UJM, and EM — cross-framework parity. Setting it in CI (or your shell) flips every framework's extended suites on.
+- **Propagates to spawned environments.** Once the test command sets `process.env.TEST_EXTENDED_MODE`, it reaches every child it spawns — the Jekyll build (via inherited `process.env`) and the boot HTTP server / Puppeteer browsers — automatically.
+- **A warning prints** when extended mode is on (also teed to `logs/test.log`), since it makes real network calls against live backends.
+- **Tests gate on `process.env.TEST_EXTENDED_MODE`.** Skip the live path unless it's set, e.g. `if (process.env.TEST_EXTENDED_MODE !== 'true') return ctx.skip('extended mode only');`. Anything an extended test creates in a real external system MUST be cleaned up by the test (`cleanup`/`inspect` teardown) — the runner never resets external systems.
+
+```bash
+TEST_EXTENDED_MODE=true npx mgr test            # all extended suites, all layers
+npx mgr test --extended mgr:build               # extended + a specific target
+```
+
 ## Env vars
 
 | Env | Set by | Purpose |
 |---|---|---|
 | `UJ_TEST_MODE=true`         | `npx mgr test` always | Canonical test signal. `Manager.isTesting()` reads this. Use it to short-circuit network calls / prompts / long timers in code that runs during tests. |
-| `UJ_TEST_INTEGRATION=1`     | `--integration` flag | Opt-in flag for slower live-integration tests if your suite has them. These run the **real** external path (NOT mocked); anything they create externally MUST be cleaned up by the test. |
+| `TEST_EXTENDED_MODE=true`   | `--extended` flag, or set in the env | Opt into tests that hit **real** external services (network fetches, Firebase via web-manager, live APIs). Off by default. Unprefixed + shared across BEM/BXM/UJM/EM. Propagates to every spawned child (Jekyll build, boot HTTP server / Puppeteer). Gate such tests on `process.env.TEST_EXTENDED_MODE`; anything they create externally MUST be cleaned up by the test. See [Extended mode](#extended-mode-test_extended_mode). |
 | `UJ_TEST_BOOT_PROJECT`      | Auto-set when UJM tests itself; else manual | Project root the boot runner uses (its `_site/` is the boot target) |
 | `UJ_TEST_BOOT_DIR`          | Manual | Absolute override for the `_site/` directory. Wins over `UJ_TEST_BOOT_PROJECT/_site` and `<cwd>/_site` |
 | `UJ_TEST_DEBUG=1`           | Manual | Verbose Puppeteer console output piped to the parent stdout |