McGarrah Technical Blog

Merging Two Jekyll Websites: Architectural Analysis and Integration Strategies

By · 8 min read

Following my previous article on managing multiple Jekyll sites under one domain, I’ve been exploring whether it makes sense to merge my two Jekyll websites into a single repository. This is the analysis phase — not an implementation article. I’m laying out the architectural differences and weighing the options before committing to a direction. A large part of my day job as a Solutions Architect involves exactly this kind of trade-off analysis, so I figured I’d write it up.

Current Architecture Overview

Main Blog Site (mcgarrah.github.io)

Resume Site (resume)

Architectural Differences Analysis

1. Content Management Approaches

Blog Site: File-based content management

# Traditional Jekyll structure
_posts/2025-01-02-article-title.md
_pages/about.md
categories.html
tags.html

Resume Site: Data-driven content management

# Centralized data structure
_data/data.yml  # All content in structured YAML
_includes/      # Modular HTML components
_layouts/       # Specialized resume layouts

2. Theme Architecture Incompatibility

Blog Theme Structure:

Resume Theme Structure:

3. Configuration Conflicts

Blog Configuration (_config.yml):

title: "McGarrah Technical Blog"
permalink: /:title/
paginate: 4
show_excerpts: true
plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-paginate
  - jekyll-seo-tag
  - jekyll-redirect-from

Resume Configuration (_config.yml):

title: McGarrah Resume
baseurl: "/resume"
theme_skin: ceramic
compress-site: yes
plugins:
  - jekyll-sitemap
  - jekyll-seo-tag
  - jekyll-pandoc-exports

Integration Strategies

Strategy 1: Resume as Jekyll Collection

Approach: Convert resume content to a Jekyll collection within the main site.

Implementation:

# _config.yml additions
collections:
  resume:
    output: true
    permalink: /resume/:name/

# Directory structure
_resume/
  index.md
  print.md
_data/
  resume.yml  # Migrated from resume site

Pros:

Cons:

Strategy 2: Subdirectory Integration

Approach: Move resume content into a subdirectory of the main site.

Implementation:

mcgarrah.github.io/
├── _posts/           # Blog content
├── _layouts/
│   ├── default.html  # Blog layouts
│   ├── resume.html   # Resume-specific layout
│   └── print.html    # Print layout
├── resume/
│   ├── index.html
│   ├── print.html
│   └── assets/       # Resume-specific assets
└── _data/
    └── resume.yml

Pros:

Cons:

Strategy 3: Hybrid Layout System

Approach: Create a unified theme that supports both blog and resume layouts.

Implementation:

# Front matter switching
---
layout: blog-post     # For articles
layout: resume-page   # For resume sections
layout: hybrid-home   # Unified homepage
---

Pros:

Cons:

Technical Challenges

1. Asset Management Conflicts

Blog Assets:

Resume Assets:

Resolution Approach:

// Unified SASS structure
_sass/
├── base/           # Shared styles
├── blog/           # Blog-specific styles
├── resume/         # Resume-specific styles
└── components/     # Reusable components

2. Navigation Integration

Current Blog Navigation:

navigation:
  - {file: "index.html", icon: blog}
  - {file: "archive.html", icon: list}
  - {file: "tags.html", title: Tags, icon: tags}
  - {file: "categories.html", title: Categories, icon: th-list}
  - {file: "search.html", title: Search, icon: search}
  - {url: "/about/", title: About, icon: user}
  - {url: "/contact/", title: Contact, icon: envelope}
  - {url: "/privacy/", title: Privacy, icon: lock}

Proposed Unified Navigation:

navigation:
  - {file: "index.html", title: "Blog", icon: blog}
  - {file: "resume/index.html", title: "Resume", icon: user}
  - {file: "archive.html", title: "Archive", icon: list}
  - {file: "search.html", title: "Search", icon: search}

3. Data Structure Harmonization

Challenge: Resume site uses extensive YAML data structures that don’t align with blog post front matter.

Current Resume Data Structure:

experiences:
  - role: Lead Principal Engineer
    time: Oct 2021 - Present
    company: Envestnet, Inc.
    details: |
      Building large scale cloud platforms...

Proposed Integration:

# _data/site.yml
blog:
  title: "McGarrah Technical Blog"
  description: "Technical content..."
  
resume:
  personal:
    name: "Michael McGarrah"
    tagline: "Data Scientist / Cloud Architect"
  experiences: [...]
  education: [...]

Complexity Assessment

Low Complexity Options

  1. Keep Separate Sites: Maintain current architecture with improved sitemap coordination
  2. Simple Subdirectory: Move resume as static subdirectory with minimal integration

Medium Complexity Options

  1. Collection-Based Integration: Convert resume to Jekyll collection with custom layouts
  2. Shared Navigation: Integrate navigation while maintaining separate themes

High Complexity Options

  1. Full Theme Merger: Create unified theme supporting both content types
  2. Dynamic Layout Switching: Context-aware layouts based on content type

What I’d Actually Recommend

If I were going to do this, I’d take a phased approach:

Phase 2: Asset Consolidation

Phase 3: Navigation Unification

The Case for Staying Separate

Honestly, maintaining separate sites may be the most pragmatic answer given the architectural gap:

Benefits of Separation:

Improved Coordination:

Conclusion

Merging these two sites is technically feasible but would require substantial work. The two sites have fundamentally different architectures:

The collection-based integration (Strategy 1) is the cleanest path, but it’s a real project — not a weekend task. For now, I’ve been improving coordination between the two sites instead: unified sitemaps, consistent SEO plugins, and shared tooling like jekyll-pandoc-exports for document generation.

The SEO benefits of a single repository are real (one sitemap, one robots.txt, consistent structured data), but they need to be weighed against the development effort and the risk of breaking a resume site that works well as-is.

Next Steps

If I decide to proceed:

  1. Prototype the collection-based integration on a branch
  2. Audit all asset dependencies and potential conflicts
  3. Design unified layouts that support both content types
  4. Plan the migration step by step
  5. Test across devices and use cases before switching over
Tags: jekyll, github-pages, architecture, website-migration, multi-site, integration
Categories: web-development, technical, jekyll
About the Author: Michael McGarrah is a Cloud Architect with 25+ years in enterprise infrastructure, machine learning, and system administration. He holds an M.S. in Computer Science (AI/ML) from Georgia Tech and a B.S. in Computer Science from NC State University, and is currently pursuing an Executive MBA at UNC Wilmington. LinkedIn · GitHub · ORCID · Google Scholar · Resume