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=1756830188"></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
- Links not working: Check for
data-no-swup
attribute or external URLs - JavaScript errors: Ensure all dependencies are loaded before swup-modern.js
- 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
- Preload critical pages by adding
data-swup-preload
to important links - Optimize images in your content for faster loading
- Minimize JavaScript in components that reinitialize frequently
- 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.