Ultimate Jekyll is a template that helps you jumpstart your Jekyll sites and is fueled by an intuitive incorporation of npm, gulp, and is fully SEO optimized and blazingly fast.
## ๐ฆ Features
* **SEO Optimized**: Ultimate Jekyll is fully SEO optimized.
* **Blazingly Fast**: Ultimate Jekyll is blazingly fast.
* **NPM & Gulp**: Ultimate Jekyll is fueled by an intuitive incorporation of npm and gulp.
* **Built-in test framework**: three layers (`build` / `page` / `boot`) โ plain Node, headless Chromium tab, headless Chromium against real `_site/` with SW registration verification.
## ๐ Getting started
1. [Create a repo](https://github.com/itw-creative-works/ultimate-jekyll/generate) from the **Ultimate Jekyll** template.
2. Clone the repo to your local machine.
3. Run these commands to get everything setup and sync'd!
```bash
npm start
```
## ๐งช Testing
UJM ships a built-in three-layer test harness. Write tests under `test//*.test.js` and run with:
```bash
npx mgr test # all layers
npx mgr test --layer build # plain Node, fast
npx mgr test --layer page # headless Chromium tab against harness HTML
npx mgr test --layer boot # headless Chromium against built _site/
```
Test files use Jest-compatible matchers:
```js
// test/build/config.test.js
const Manager = require('ultimate-jekyll-manager/build');
module.exports = {
layer: 'build',
description: 'config has brand.id',
run: async (ctx) => {
const cfg = Manager.getConfig('project');
ctx.expect(cfg.brand.id).toBeTruthy();
},
};
```
Boot tests run against your actually-built `_site/` after `npm run build`:
```js
// test/boot/site.test.js
module.exports = {
layer: 'boot',
description: 'home renders + SW registers',
inspect: async ({ site, page, expect }) => {
await page.goto(site.baseUrl + '/');
expect((await page.title()).length).toBeGreaterThan(0);
},
};
```
Full guide: [docs/test-framework.md](docs/test-framework.md). Boot layer deep-dive: [docs/test-boot-layer.md](docs/test-boot-layer.md).
## ๐ฆ How to sync with the template
1. Simply run `npm start` in Terminal to get all the latest updates from the **Ultimate Jekyll template** and launch your website in the browser.
## ๐ Publishing your website
1. Change the `url` in `_config.yml` to your domain.
2. Push your changes to GitHub using `npm run dist` in Terminal.
## โณ๏ธ Flags
* `--browser=false` - Disables the browser from opening when running `npm start`.
```bash
npm start -- --browser=false
```
* `--debug=true` - Enables logging of extra information when running `npm start`.
```bash
npm start -- --debug=true
```
* `--ujPluginDevMode=true` - Enables the development mode for the [Ultimate Jekyll Ruby plugin](https://github.com/itw-creative-works/jekyll-uj-powertools).
```bash
npm start -- --ujPluginDevMode=true
```
* `--profile` - Enables Jekyll build profiling to see how long each phase takes.
```bash
npm start -- --profile
```
* `--all-posts` - Disables the development post limit (15 posts) and builds with all posts. Useful when you need to test with full blog content.
```bash
npm start -- --all-posts
```
### Other ENV variables
```bash
UJ_PURGECSS=true # Enables PurgeCSS to remove unused CSS (normally only happens in production builds)
UJ_IMAGEMIN_CACHE=false # Disables the GitHub-backed imagemin cache (forces local processing)
UJ_IMAGEMIN_REWRITE_SOURCES=true # One-off cleanup: shrinks oversized source images (>4096px) in place. See docs/images.md
```
## Running Specific Tasks
You can run specific tasks using the `npm run gulp` command with the appropriate task name.
Some of these require environment variables to be set and other tasks to be run first.
Here are some examples:
### Run the `audit` task:
```bash
# Run the audit task
npx mgr audit
# Run with a Lighthouse URL (defaults to "/" if not provided)
npx mgr audit -- --lighthouseUrl="/contact"
# Add autoExit to continue developing and testing AFTER the audit
npx mgr audit -- --lighthouseUrl="/contact" --autoExit=false
```
### Run the `translation` task:
```bash
# Test translation with GitHub cache (requires GH_TOKEN and GITHUB_REPOSITORY)
GH_TOKEN=XXX \
GITHUB_REPOSITORY=XXX \
UJ_TRANSLATION_CACHE=true \
npx mgr translation
# Test with only 1 file
UJ_TRANSLATION_ONLY="index.html" \
GH_TOKEN=XXX \
GITHUB_REPOSITORY=XXX \
UJ_TRANSLATION_CACHE=true \
npx mgr translation
```
### Run the `imagemin` task:
Test image optimization with GitHub cache in development mode:
```bash
# Test with GitHub cache (requires GH_TOKEN and GITHUB_REPOSITORY)
GH_TOKEN=XXX \
GITHUB_REPOSITORY=XXX \
UJ_IMAGEMIN_CACHE=true \
npx mgr imagemin
# Or run locally without cache
npx mgr imagemin
```
The imagemin task will:
- Process images from `src/assets/images/**/*.{jpg,jpeg,png}`
- Generate multiple sizes (1024px, 425px) and WebP formats
- Cache processed images in `cache-imagemin` branch (when using GitHub cache)
- Skip already processed images on subsequent runs
**Keep sources reasonably sized.** Source images larger than ~4096px on the longest side can stall `sharp`/`gulp-responsive-modern` in a way gulp can't detect, causing them to silently fail to land in `_site/`. Cap images at the upload step where possible. For one-off cleanup of an existing repo, run with `UJ_IMAGEMIN_REWRITE_SOURCES=true npm run build` โ see [docs/images.md](docs/images.md#cleanup-for-existing-oversized-sources-uj_imagemin_rewrite_sources) for details.
## ๐ Developing
1. Clone the repo to your local machine.
2. Run these commands
```bash
npm install
npm run prepare:watch
```
### Run the `blogify` task:
Create 12 test blog posts in the `_posts` directory with the `blogify` task. This is useful for testing and development purposes.
```bash
npx mgr blogify
```
## Page Frontmatter
You can add the following frontmatter to your pages to customize their behavior:
### All pages
```yaml
---
# Layout and Internals
layout: themes/[ site.theme.id ]/frontend/core/minimal # The layout to use for the page, usually 'default' or 'page'
permalink: /path/to/page # The URL path for the page, can be relative
# Control the page's meta tags
meta:
index: true # Set to false to disable indexing by search engines
title: 'Page Title' # Custom meta title for the page
description: 'Page description goes here.' # Custom meta description for the page
breadcrumb: '' # Custom breadcrumb for the page
# Control the page's theme and layout
theme:
nav:
enabled: true # Enable theme's nav on the page
footer:
enabled: true # Enable theme's footer on the page
body:
class: '' # Add custom classes to the body tag
main:
class: '' # Add custom classes to the main tag
head:
content: '' # Injected at the end of the head tag
foot:
content: '' # Injected at the end of the foot tag (inside )
---
```
### Post pages
```yaml
---
# Post pages
post:
title: "Post Title" # Custom post title for the page
description: "Post description goes here." # Custom post description for the page
author: "author-id" # ID of the author from _data/authors.yml
id: 1689484669 # Unique ID for the post, used for permalink
---
```
### Team Member pages
```yaml
---
# Team Member pages
member:
id: "member-id" # ID of the team member from _data/team.yml
name: "Member Name" # Name of the team member
---
```
### Special Class
`uj-signin-btn`: Automatically handles signin (just add `data-provider="google.com"` to the button)
`uj-signup-btn`: Automatically handles signup (just add `data-provider="google.com"` to the button)
`uj-language-dropdown`:
`uj-language-dropdown-item`
### Utility Classes
#### Max-Width Utilities
Ultimate Jekyll includes max-width utility classes based on Bootstrap's breakpoint sizes. These classes constrain an element's maximum width to match Bootstrap's standard responsive breakpoints:
- `.mw-sm` - Sets max-width to 576px
- `.mw-md` - Sets max-width to 768px
- `.mw-lg` - Sets max-width to 992px
- `.mw-xl` - Sets max-width to 1200px
- `.mw-xxl` - Sets max-width to 1400px
**Usage Examples:**
```html
```
These utilities are particularly useful for:
- Improving readability by preventing text from spanning too wide
- Creating consistent content widths across different sections
- Constraining forms, cards, and modals to reasonable sizes
- Maintaining design consistency with Bootstrap's grid system
### HTML Element Attributes
The `` element has data attributes for JavaScript/CSS targeting:
| Attribute | Values |
|-----------|--------|
| `data-theme-id` | Theme ID (e.g., `classy`) |
| `data-theme-target` | `frontend`, `backend`, `docs` |
| `data-bs-theme` | `light`, `dark` |
| `data-page-path` | Page permalink (e.g., `/about`) |
| `data-asset-path` | Custom asset path or empty |
| `data-environment` | `development`, `production` |
| `data-platform` | `windows`, `mac`, `linux`, `ios`, `android`, `chromeos`, `unknown` |
| `data-device` | `mobile` (<768px), `tablet` (768-1199px), `desktop` (>=1200px) |
| `data-runtime` | `web`, `extension`, `electron`, `node` |
| `aria-busy` | `true` (loading), `false` (ready) |
### Appearance Switching
Ultimate Jekyll supports dark/light/system theme switching with user preference persistence.
**JavaScript API:**
```javascript
webManager.uj().appearance.get(); // Returns 'dark', 'light', 'system', or null
webManager.uj().appearance.set('dark'); // Save and apply preference
webManager.uj().appearance.toggle(); // Toggle dark/light
webManager.uj().appearance.cycle(); // Cycle: dark โ light โ system
```
**HTML Dropdown Example:**
```html
```
### Page Loading Protection System
Ultimate Jekyll includes an automatic protection system that prevents users from clicking buttons before JavaScript is fully loaded, eliminating race conditions and errors.
#### How It Works
1. Pages start with `data-page-loading="true"` on the HTML element
2. Certain buttons are automatically protected from clicks during this state
3. When JavaScript finishes loading, the attribute is removed and buttons become clickable
#### Protected Elements
During page load, these elements are automatically protected:
- All form buttons (`
