Skip to content
This repository was archived by the owner on Jan 12, 2026. It is now read-only.

MODERN-FEATURES.md

Latest commit

 

History

History
526 lines (386 loc) · 11.7 KB

MODERN-FEATURES.md

File metadata and controls

526 lines (386 loc) · 11.7 KB

Modern JavaScript Features in Jekyll.js

This document describes the modern JavaScript packages and features added to Jekyll.js to enhance functionality while maintaining backward compatibility with Jekyll (Ruby).

Overview

Jekyll.js leverages modern JavaScript packages to provide enhanced functionality:

  1. Syntax Highlighting with Shiki - Modern, fast, VSCode-powered syntax highlighting
  2. Image Optimization with Sharp - High-performance image processing and optimization
  3. Configuration Validation with Zod - Runtime type validation with TypeScript-first schemas
  4. HTML Minification - Reduce HTML file sizes for faster page loads
  5. Resource Hints - Preload/prefetch for optimized resource loading

All features are opt-in and do not affect existing Jekyll sites unless explicitly enabled in configuration.

Syntax Highlighting with Shiki

Shiki is a modern syntax highlighter powered by the same engine as VS Code (TextMate grammars).

Features

  • Accurate, beautiful syntax highlighting
  • 100+ languages supported out of the box
  • Multiple themes available
  • Zero runtime dependencies (pre-generated HTML)
  • Perfect color accuracy

Usage

import { highlightCode, initHighlighter } from 'jekyll-ts/plugins/syntax-highlighting';

// Initialize once (optional - will auto-initialize on first use)
await initHighlighter({
  theme: 'github-light',
});

// Highlight code
const html = await highlightCode(
  'const x = 1;',
  'javascript'
);

Configuration

Enable in _config.yml:

modern:
  syntaxHighlighting:
    enabled: true
    theme: github-light
    showLineNumbers: true

Available Themes

  • github-light (default)
  • github-dark
  • monokai
  • nord
  • one-dark-pro
  • solarized-light
  • solarized-dark
  • dracula
  • material-theme
  • vitesse-light
  • vitesse-dark

Supported Languages

Over 100 languages including:

  • JavaScript, TypeScript
  • Python, Ruby, Go, Rust
  • Java, C, C++, C#
  • HTML, CSS, SCSS
  • JSON, YAML, Markdown
  • Bash, Shell, SQL
  • And many more...

Image Optimization with Sharp

Sharp is a high-performance Node.js image processing library.

Features

  • Resize, crop, and transform images
  • Convert between formats (JPEG, PNG, WebP, AVIF)
  • Optimize file sizes
  • Generate responsive images
  • Extract metadata

Usage

import { optimizeImage } from 'jekyll-ts/plugins/image-optimization';

// Optimize an image
const result = await optimizeImage('input.jpg', 'output.jpg', {
  quality: 80,
  width: 1200,
  generateWebP: true,
  generateAVIF: true,
  responsiveSizes: [400, 800, 1200],
});

console.log(`Reduced size by ${result.reduction}%`);

Configuration

Enable in _config.yml:

modern:
  imageOptimization:
    enabled: true
    quality: 80
    generateWebP: true
    generateAVIF: true
    responsiveSizes:
      - 400
      - 800
      - 1200

Supported Formats

  • JPEG (input and output)
  • PNG (input and output)
  • WebP (input and output)
  • AVIF (input and output)
  • GIF (input and output)
  • TIFF (input and output)

Benefits

  • Smaller files: Reduce image sizes by 30-70%
  • Modern formats: Automatic WebP/AVIF generation
  • Responsive images: Generate multiple sizes automatically
  • Fast processing: Uses native libraries for speed

Configuration Validation with Zod

Zod provides TypeScript-first schema validation for runtime type checking.

Features

  • Runtime type validation
  • Type inference from schemas
  • Detailed error messages
  • Composable schemas

Usage

import { validateJekyllConfig, mergeAndValidateConfig } from 'jekyll-ts/config/validation';

// Validate a configuration
const result = validateJekyllConfig(config);

if (result.success) {
  // result.data is typed and validated
  console.log(result.data.title);
} else {
  // result.errors contains detailed validation errors
  console.error(result.errorMessage);
}

Benefits

  • Type safety: Catch configuration errors at runtime
  • Better errors: Clear, actionable error messages
  • IntelliSense: Full TypeScript autocomplete support
  • Validation: Ensure config values are valid (e.g., port numbers in range)

HTML Minification

HTML minification reduces file sizes by removing unnecessary whitespace, comments, and optimizing markup.

Features

  • Remove HTML comments
  • Collapse whitespace
  • Minify inline CSS and JavaScript
  • Collapse boolean attributes
  • Remove empty attributes
  • Preserve whitespace in pre/textarea elements

Usage

import { minifyHtml } from 'jekyll-ts/plugins/html-minifier';

const result = await minifyHtml(html, {
  enabled: true,
  removeComments: true,
  collapseWhitespace: true,
  minifyCSS: true,
  minifyJS: true,
});

console.log(`Reduced by ${result.reduction.toFixed(1)}%`);

Configuration

Enable in _config.yml:

modern:
  htmlMinification:
    enabled: true
    removeComments: true
    collapseWhitespace: true
    minifyCSS: true
    minifyJS: true
    collapseBooleanAttributes: true
    removeEmptyAttributes: true

Benefits

  • Smaller files: Typically 10-30% size reduction
  • Faster loads: Less data to transfer
  • Cache efficiency: Smaller files improve caching
  • Zero configuration: Sensible defaults

Resource Hints (Preload/Prefetch)

Resource hints tell browsers to fetch critical resources earlier, improving perceived page load performance.

Features

  • Preload: Load critical resources (CSS, fonts, hero images)
  • Prefetch: Load likely next-page resources
  • Preconnect: Establish early connections to important origins
  • DNS Prefetch: Resolve DNS for external domains early

Usage

import { injectResourceHints } from 'jekyll-ts/plugins/resource-hints';

const html = injectResourceHints(originalHtml, {
  enabled: true,
  preloadStyles: true,
  preloadFonts: true,
  preconnectOrigins: ['https://fonts.googleapis.com'],
});

Configuration

Enable in _config.yml:

modern:
  resourceHints:
    enabled: true
    preloadStyles: true
    preloadFonts: true
    preloadHeroImages: false
    preconnectOrigins:
      - https://fonts.googleapis.com
      - https://fonts.gstatic.com
    prefetchUrls:
      - /about/
      - /contact/
    dnsPrefetchDomains:
      - https://analytics.example.com

Benefits

  • Faster page loads: Critical resources load earlier
  • Better Core Web Vitals: Improved LCP and FID scores
  • Automatic detection: Extracts stylesheets and fonts from HTML
  • Common CDNs: Auto-detects popular CDN origins

Backward Compatibility

All modern features:

  • ✅ Are opt-in via configuration
  • ✅ Do not affect existing Jekyll sites
  • ✅ Maintain default behavior matching Jekyll (Ruby)
  • ✅ Work alongside existing features
  • ✅ Are fully tested and documented

Existing Jekyll sites continue to work without modification.

Performance

Modern packages are chosen for both functionality and performance:

  • Shiki: Pre-generates HTML, zero runtime overhead
  • Sharp: Native libraries, 4-5x faster than JavaScript alternatives
  • Zod: Minimal runtime overhead, tree-shakeable
  • HTML Minifier: Async processing, preserves content integrity
  • Resource Hints: Zero runtime cost (static HTML injection)

Dependencies

The following modern packages are included:

{
  "shiki": "^3.19.0",             // Syntax highlighting
  "sharp": "^0.34.5",             // Image optimization
  "zod": "^3.25.76",              // Schema validation
  "html-minifier-terser": "^7.2.0" // HTML minification
}

All packages are:

  • Well-maintained with active development
  • Used by thousands of projects
  • Battle-tested in production
  • TypeScript-first with excellent type definitions

Examples

Example 1: Syntax Highlighting in a Plugin

import { highlightCode } from 'jekyll-ts/plugins/syntax-highlighting';

async function renderCodeBlock(code: string, language: string) {
  return await highlightCode(code, language, {
    theme: 'github-dark',
  });
}

Example 2: Image Optimization in Build Process

import { optimizeImage } from 'jekyll-ts/plugins/image-optimization';
import { glob } from 'glob';

async function optimizeAllImages() {
  const images = await glob('assets/images/*.{jpg,png}');
  
  for (const imagePath of images) {
    await optimizeImage(imagePath, imagePath, {
      quality: 85,
      generateWebP: true,
    });
  }
}

Example 3: Config Validation

import { validateJekyllConfig } from 'jekyll-ts/config/validation';

const config = {
  title: 'My Site',
  port: 4000,
  modern: {
    syntaxHighlighting: {
      enabled: true,
    },
  },
};

const result = validateJekyllConfig(config);
if (!result.success) {
  console.error('Invalid config:', result.errorMessage);
  process.exit(1);
}

Modern Liquid Filters

Jekyll.js includes several modern Liquid filters that enhance content processing while maintaining backwards compatibility:

Reading Time Filter

Calculate estimated reading time for content:

{{ content | reading_time }}

Returns the number of minutes to read the content (based on 200 words per minute by default):

Reading time: {{ page.content | reading_time }} min

Custom words-per-minute:

{{ content | reading_time: 250 }}

Table of Contents Filter

Generate a table of contents from HTML content:

{% assign toc = content | toc %}
<nav class="table-of-contents">
  <ul>
    {% for item in toc %}
      <li class="toc-level-{{ item.level }}">
        <a href="#{{ item.id }}">{{ item.text }}</a>
      </li>
    {% endfor %}
  </ul>
</nav>

Each TOC entry has:

  • level: Heading level (2-4)
  • id: The heading's ID attribute (generated from text if not present)
  • text: The heading text

Heading Anchors Filter

Add anchor links to headings for easy linking:

{{ content | heading_anchors }}

Transforms:

<h2>Getting Started</h2>

Into:

<h2 id="getting-started">Getting Started <a href="#getting-started" class="anchor" aria-hidden="true">#</a></h2>

External Links Filter

Automatically add target="_blank" and rel="noopener noreferrer" to external links for security and UX:

{{ content | external_links }}

Internal links (same domain) are left unchanged. External links get security attributes added.

Specify your site domain explicitly:

{{ content | external_links: "mysite.com" }}

Truncate Words Filter

Truncate text to a specified number of words:

{{ content | truncate_words: 50 }}

Custom ellipsis:

{{ content | truncate_words: 50, "..." }}

Auto Excerpt Filter

Generate excerpts automatically:

{{ content | auto_excerpt }}

This returns the first paragraph. For word-based excerpts:

{{ content | auto_excerpt: 100 }}

Future Enhancements

Potential future additions:

  • PDF generation with modern libraries
  • Advanced markdown features (math, diagrams)
  • Asset bundling and minification
  • Modern image formats (JXL)
  • Service worker generation
  • Progressive web app features

Resources

Contributing

To add new modern features:

  1. Choose well-maintained, popular packages
  2. Ensure TypeScript support
  3. Make features opt-in via configuration
  4. Maintain backward compatibility
  5. Add comprehensive tests
  6. Document usage and benefits

Support

For questions or issues related to modern features:

  • Open an issue on GitHub
  • Include your configuration
  • Provide reproduction steps
  • Check documentation first

License

All modern features are part of Jekyll.js and follow the same MIT license.