Modern Swup for Jekyll - Integration Guide

Modern Swup for Jekyll - Integration Guide

This is a streamlined, reliable Swup implementation designed specifically for Jekyll sites. It creates smooth page transitions while maintaining simplicity and performance.

Quick Setup

1. Add Required Files

Copy these files to your Jekyll project:

assets/
├── js/
│   └── swup-modern.js
└── css/
    └── components/
        └── swup-transitions.css

2. Include Swup Libraries

Add to your _includes/head.html or scripts section:

<!-- Swup Core & Plugins -->
<script src="/assets/js/swup/swup.min.js"></script>
<script src="/assets/js/swup/head-plugin.min.js"></script>
<script src="/assets/js/swup/progress-plugin.min.js"></script>
<script src="/assets/js/swup/preload-plugin.min.js"></script>
<script src="/assets/js/swup/fragment-plugin.min.js"></script>

3. Add CSS

Include in your _includes/styles.html:

<link rel="stylesheet" href="/assets/css/components/swup-transitions.css">

4. Add JavaScript

Include in your _includes/scripts.html:

<script src="/assets/js/swup-modern.js?v=1758821224"></script>

5. Update Your Layout

Wrap your main content in the swup container:

<main id="swup" class="transition-smooth">
  <!-- Your page content here -->
</main>

Configuration

Basic Options

The system works out of the box with sensible defaults:

• Container: #swup (main content area)
• Animation: Smooth fade with subtle slide
• Duration: 0.4s (0.25s on mobile)
• Plugins: Head, Progress, Preload, Fragment (if available)

Custom Transitions

Add classes to your main container:

<!-- Fade only -->
<main id="swup" class="transition-fade">

<!-- Slide up effect -->
<main id="swup" class="transition-slide">

<!-- Smooth (default) -->
<main id="swup" class="transition-smooth">

Hero Coordination

Elements outside the swup container (like heroes) are automatically coordinated:

<!-- This will animate smoothly during page transitions -->
<section class="hero-section">
  <!-- Hero content -->
</section>

<main id="swup" class="transition-smooth">
  <!-- Page content -->
</main>

Features

✅ What Works

• Smooth page transitions with automatic fallback
• Hero coordination outside swup container
• Progress indicator during page loads
• Link preloading for faster navigation
• History management with browser back/forward
• Error handling with graceful fallback
• Mobile optimization with faster transitions
• Accessibility support with reduced motion

🎯 Component Integration

The system automatically reinitializes:

• Lucide icons
• Lazy loading (lazySizes)
• Theme management
• Custom modules (if they expose reinit methods)

📱 Mobile Optimized

• Faster transition duration (0.25s)
• Touch-friendly progress bar
• Reduced motion support

Extending the System

Adding Custom Reinitalization

// In your component files
window.YourModule = {
  init() {
    // Initial setup
  },
  
  reinit() {
    // Called after each page transition
    this.init();
  }
};

Custom Transition Hooks

// Access the swup instance
if (window.modernSwup && window.modernSwup.swup) {
  window.modernSwup.swup.hooks.on('animation:out:start', () => {
    // Your custom logic before transition
  });
  
  window.modernSwup.swup.hooks.on('animation:in:end', () => {
    // Your custom logic after transition
  });
}

Troubleshooting

Common Issues

1. Links not working: Check for data-no-swup attribute or external URLs
2. JavaScript errors: Ensure all dependencies are loaded before swup-modern.js
3. Slow transitions: Check for console errors or missing CSS files

Debug Mode

Enable debug logging:

// In browser console
window.modernSwup.swup.options.debugMode = true;

Fallback Behavior

The system automatically falls back to normal navigation if:

• Swup fails to load
• Fetch errors occur
• JavaScript is disabled

Performance Tips

1. Preload critical pages by adding data-swup-preload to important links
2. Optimize images in your content for faster loading
3. Minimize JavaScript in components that reinitialize frequently
4. Use CSS transitions instead of JavaScript animations when possible

Browser Support

• ✅ Chrome 60+
• ✅ Firefox 55+
• ✅ Safari 12+
• ✅ Edge 79+
• ⚠️ IE11 (limited support with polyfills)

Single Page App Features

This setup transforms your Jekyll site into a modern SPA:

• No page reloads between internal navigation
• Persistent elements outside swup container
• Smooth transitions with loading states
• Browser history fully supported
• SEO friendly with proper meta tag updates
• Progressive enhancement - works without JavaScript

Perfect for portfolios, blogs, and content sites that want modern UX without the complexity of a full SPA framework.