Ultimate Jekyll Manager Development

You are an expert developer working with Ultimate Jekyll Manager, a template framework that consuming projects install as an NPM module to build Jekyll sites quickly and efficiently.

Critical Understanding

**This is NOT a standalone project.** You cannot run `npm start` or `npm run build` directly in this repository. It provides best-practice configurations, default components, themes, and build tools for consuming projects.

Project Structure

Directory Organization

Consuming Project Structure

Local Development

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 Rules

Ultimate Jekyll Manager Files (THIS project)

**CSS Structure:**

**JavaScript Structure:**

**Default Pages & Layouts:**

**IMPORTANT:** Consuming projects CAN override UJ defaults by creating files with the same paths in their own `src/` directory, but this should ONLY be done when absolutely necessary. Prefer using `src/pages/` and `src/_layouts/` for custom pages.

Section Configuration Files (JSON)

UJ provides JSON5 configuration files for common sections:

HTML templates in `src/defaults/dist/_includes/themes/[theme-id]/frontend/sections/` read and render this data.

**Customizing Navigation/Footer:**

Consuming projects should create their own JSON files in `src/_includes/frontend/sections/`:

Customizing Default Pages via Frontmatter

**BEST PRACTICE:** UJ default pages are designed to be customized through frontmatter WITHOUT writing any HTML.

**Process:**

1. Read the UJ default page in `src/defaults/dist/_layouts/` to understand available frontmatter options

2. Consuming projects create a page in `src/pages/` with custom frontmatter

3. The page uses a UJ layout (e.g., `blueprint/pricing`)

4. Frontmatter overrides default values without any HTML

**Example - Customizing Pricing Page:**

```yaml

---

layout: blueprint/pricing

permalink: /pricing

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"

---

```

Consuming Project Files

**CSS:**

**JavaScript:**

**Pages & Layouts:**

**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

/**

* [Page Name] Page JavaScript

*/

// Libraries

let webManager = null;

// Module

export default (Manager) => {

return new Promise(async function (resolve) {

// Shortcuts

webManager = Manager.webManager;

// Initialize when DOM is ready

await webManager.dom().ready();

// Page initialization logic

helper1();

// Resolve after initialization

return resolve();

});

};

// Helper functions

function helper1() {

// Helper implementation

}

```

**Key Points:**

Layouts and Pages

Page Types

Layout Requirements

All layouts and pages must eventually require a theme entry point:

```yaml

layout: themes/[ site.theme.id ]/frontend/core/base

```

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

---

```

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

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:**

#### `page.resolved`

A deeply merged object containing all site, layout, and page variables. Precedence: page > layout > site. Enables 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")

**Available Icon Sizes:**

`fa-2xs`, `fa-xs`, `fa-sm`, `fa-md`, `fa-lg`, `fa-xl`, `fa-2xl`, `fa-3xl`, `fa-4xl`, `fa-5xl`

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.

When to Use `{% uj_icon %}` vs Prerendered Icons

#### Use `{% uj_icon %}` in HTML/Liquid Templates

When icons are part of the static HTML template:

```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>

```

#### Use Prerendered Icons in JavaScript

When icons need to be dynamically inserted via JavaScript:

**1. Add icons to page frontmatter:**

```yaml

---

prerender_icons:

- name: "mobile"

class: "fa-sm me-1"

- name: "envelope"

class: "fa-sm me-1"

---

```

**2. Import the library:**

```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`;

```

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`;

```

CSS Guidelines

Theme-Adaptive Classes

**DO NOT USE:** `bg-light`, `bg-dark`, `text-light`, `text-dark`

Ultimate Jekyll supports both light and dark modes. Use adaptive classes instead:

**Backgrounds:**

**Text:**

**Borders:**

Development Workflow

1. **Read the UJ default files** to understand available features and frontmatter options

2. **Prefer frontmatter customization** over HTML overrides when possible

3. **Follow the page module structure** for consistent JavaScript organization

4. **Use adaptive CSS classes** for theme compatibility

5. **Pre-render icons in frontmatter** when using them in JavaScript

6. **Use `asset_path` frontmatter** when multiple pages share assets

7. **Check the powertools README** before implementing custom functionality

Important Notes