Author
Affiliation

Alex Taylor

University of Evansville

Jekyll to Quarto Migration Summary

Overview

Your website has been successfully migrated from Jekyll to Quarto! Here’s what has changed and what you need to know.

Major Changes

1. Build System

  • Before: Jekyll with Ruby gems and bundler
  • After: Quarto with modern web technologies
  • Benefit: Faster builds, better integration with R/Python, modern features

2. Configuration

  • Before: _config.yml (now backed up as _config.yml.backup)
  • After: _quarto.yml
  • Migration: All your site settings, navigation, author info, and Google Analytics have been transferred

3. Page Files

  • Before: .md files in _pages/ directory
  • After: .qmd files in the root directory
  • Converted Pages:
    • index.html → index.qmd (home page)
    • _pages/research.md → research.qmd
    • _pages/teaching.md → teaching.qmd
    • _pages/r-links.md → r-links.qmd
    • _pages/resources.md → resources.qmd

4. Styling

  • Preserved: All your custom styling and branding
  • Enhanced: Added modern Quarto theming with custom.scss
  • Maintained: Your existing styles.css with improvements

5. Deployment

  • Before: Jekyll GitHub Pages automatic build
  • After: GitHub Actions workflow for Quarto
  • File: .github/workflows/publish.yml
  • Trigger: Pushes to gh-pages branch

What Still Works

✅ All your content: Research papers, teaching info, CV links, etc.
✅ Navigation: Same menu structure and links
✅ Styling: Your site looks and feels the same
✅ Google Analytics: Still tracking with your existing ID
✅ Assets: All images, PDFs, and documents in assets/ folder
✅ URLs: Same permalink structure for SEO

What’s New and Better

🎉 Faster builds: Quarto is significantly faster than Jekyll
🎉 Modern features: Better responsive design, search, dark mode support
🎉 R integration: Easy to add R code, plots, and analysis
🎉 Better accordion: Improved research paper expandable sections
🎉 Maintenance: Simpler dependency management

Development Workflow

Local Development

# Start preview server
quarto preview

# Build site
quarto render

# Clean build files
rm -rf _site .quarto

Using the Management Script

# Start preview server
./site-management.sh preview

# Build the site
./site-management.sh build

# Clean build artifacts
./site-management.sh clean

# Build and deploy
./site-management.sh deploy

Files Moved to Backup

These Jekyll-specific files have been moved to _jekyll_backup/ folder to prevent conflicts:

  • Gemfile and Gemfile.lock (Ruby dependencies)
  • _layouts/, _includes/, _sass/, _data/ directories (Jekyll templates)
  • _config.yml.backup (backed up configuration)
  • index.html.backup (backed up home page)
  • .travis.yml, Rakefile, staticman.yml (old CI and config files)

These files are preserved for reference but won’t interfere with Quarto builds.

Important Notes

  1. GitHub Pages Settings: Make sure GitHub Pages is set to deploy from GitHub Actions in your repository settings
  2. Branch: The workflow deploys from gh-pages branch
  3. Domain: Your custom domain settings should remain the same
  4. Analytics: Google Analytics is configured and working

Troubleshooting

If something doesn’t work:

  1. Check that Quarto is installed: quarto --version
  2. Try rebuilding: quarto render
  3. Check the GitHub Actions logs in your repository
  4. Verify GitHub Pages is set to “GitHub Actions” as the source

Common Issues Fixed

Issue: GitHub Actions using deprecated artifacts - ✅ Fixed: Updated to actions/upload-pages-artifact@v3 and actions/deploy-pages@v4

Issue: Jekyll trying to process Quarto site - ✅ Fixed: Added .nojekyll file to disable Jekyll processing - ✅ Fixed: Moved Jekyll files to _jekyll_backup/ folder - ✅ Fixed: Updated workflow to only trigger on gh-pages branch

Issue: Conflicting configuration files - ✅ Fixed: Moved Gemfile, _layouts, _includes, _sass, _data to backup folder - ✅ Fixed: These files are preserved but won’t interfere with Quarto

Next Steps

  1. Test the site: Browse through all pages to ensure everything works
  2. Update repository settings: Ensure GitHub Pages uses GitHub Actions
  3. Commit changes: Push all changes to deploy the new site
  4. Remove old files: Optionally clean up Jekyll-specific files

Your site is now powered by Quarto and ready for the future! 🚀