Theme Migration Documentation

Theme Migration Documentation

Date: January 24, 2026 From: Minima Theme To: Menca Theme by Artem Sheludko

Overview

Successfully migrated neerajhirani.github.io from the default Minima theme to the modern Menca theme, maintaining all existing content while adding new features and improving visual design.

Changes Summary

1. Theme Migration

  • Removed: Minima theme files (_sass/minima/, assets/main.scss)
  • Added: Complete Menca theme structure
    • Modern layouts (default, page, post)
    • Enhanced includes (hero, article, pagination, related-posts, search, section-tags)
    • New CSS framework with responsive design
    • JavaScript enhancements (lazy loading, lightbox, search)

2. Configuration Updates

_config.yml

  • Updated title and description
  • Added jekyll-paginate plugin for blog pagination
  • Set pagination to 9 posts per page
  • Maintained existing SEO and feed plugins

_data/settings.yml (New)

  • Site configuration and branding
  • Navigation menu structure
  • Hero section settings
  • Author profile configuration
  • Social media links (Twitter, LinkedIn)
  • Gallery configuration (49 images)
  • Disabled: MailChimp newsletter, contact form
  • Enabled: Disqus comments (awaiting shortname configuration)

3. Content Migration

Posts (5 total)

All posts migrated with updated front matter:

  • 2020-11-24-now-person-or-when-person.markdown
  • 2020-11-24-problem-focused-versus-solution-focused.markdown
  • 2021-11-23-atomic-habits.markdown
  • 2021-12-31-reflections-from-2021.markdown
  • 2022-09-21-operationalising-meetings.markdown

Front matter additions:

  • description: field for SEO and article previews
  • image: field (currently using /images/default-post.jpg)
  • tags: preserved and enhanced

Pages

  • About page: Converted from about.markdown to _pages/about.md
  • Books page: New page at _pages/books.md
  • Tags page: New page at _pages/tags.md with visual tag cloud
  • Gallery page: New page at _pages/gallery.md with lightbox functionality

4. Images & Media

  • Location: /images/gallery/
  • Count: 49 images (001_IMG.jpg through 049_IMG.jpg)
  • Display: 3-column grid layout with Lightense lightbox
  • Footer preview: Shows 9 random images with link to full gallery

Site Images

  • Kept:
    • logo.png - Site logo
    • default-post.jpg - Fallback image for posts
  • Removed: All demo images from Menca theme (0.jpg, 1.jpg - ~8.5MB)

Future Image Additions

Posts are configured to accept custom images:

image: '/images/posts/your-image-name.jpg'

5. Customizations

Social Sharing

Modified _layouts/post.html to show only 3 sharing options:

  • Twitter (X)
  • LinkedIn
  • Email (mailto link)

Removed: Facebook, Pinterest

  • Footer Gallery:
    • Limited to 9 images (from 49 total)
    • Title links to full gallery page
    • 3-column grid layout
  • Gallery Page:
    • All 49 images in 3-column responsive grid
    • Lightense lightbox on click
    • Zoom cursor on hover

6. Navigation Structure

Home (/)
├── Blog posts (homepage)
├── Books (/books/)
├── Tags (/tags/)
├── Gallery (/gallery/)
└── About (/about/)

7. Features Added

  • Lazy loading for images (performance optimization)
  • Search functionality with JSON-based search
  • Related posts section on blog posts
  • Tag filtering with visual tag pages
  • Responsive design for mobile, tablet, desktop
  • Dark mode support (auto, light, dark options)
  • Lightbox for gallery images (Lightense library)
  • Pagination for blog posts (9 per page)

8. Files Deleted

  • about.markdown → moved to _pages/about.md
  • index.markdown → replaced with index.html
  • notes.md → removed (not needed)
  • All Minima SASS files
  • All Menca demo images

9. Dependencies

Gemfile additions:

  • jekyll-paginate (for blog pagination)
  • webrick (for local development on Ruby 3.0+)

10. Build & Deployment

  • Build status: ✅ Successfully builds with no errors
  • Local testing: ✅ Verified all pages and features
  • Production ready: ✅ Ready for GitHub Pages deployment

Technical Details

Jekyll Plugins

  • jekyll-paginate
  • jekyll-sitemap
  • jekyll-seo-tag
  • jekyll-feed

Browser Support

  • Modern browsers (Chrome, Firefox, Safari, Edge)
  • Responsive design for mobile devices
  • Progressive enhancement approach

Performance Optimizations

  • Lazy loading for images
  • Minified CSS (SASS compressed)
  • Optimized image sizes
  • Efficient JavaScript loading

Post-Deployment Tasks

Immediate

  • Verify live site at https://neerajhirani.github.io
  • Test all navigation links
  • Verify gallery functionality
  • Check mobile responsiveness

Optional/Future

  • Add custom images to blog posts (currently using default image)
  • Configure Disqus comments (add shortname to settings.yml)
  • Set up Google Analytics (add tracking ID to settings.yml)
  • Add MailChimp newsletter integration (if desired)
  • Create more blog posts
  • Add more gallery images

Image Guidelines for Future Posts

Location

  • Post featured images: /images/posts/
  • In-content images: /images/posts/
  • Gallery images: /images/gallery/

Specifications

  • Format: JPG or PNG
  • Size: 100-300 KB (max 500 KB)
  • Dimensions: 1200x600px for featured images (2:1 ratio)
  • Naming: lowercase-with-hyphens.jpg

Usage in Posts

---
title: "Your Post Title"
image: '/images/posts/your-image.jpg'
tags: [tag1, tag2]
---

Maintenance Notes

Adding New Posts

  1. Create file in _posts/ with format: YYYY-MM-DD-title.markdown
  2. Include front matter with title, description, image, tags
  3. Write content in Markdown
  4. Images are optional but recommended
  1. Add images to /images/gallery/
  2. Update _data/settings.yml gallery_images array
  3. Follow existing format: {url: "/images/gallery/filename.jpg", alt: "Description"}

Updating Navigation

Edit _data/settings.yml → menu_settings → menu_items

Support & Credits

Migration Completed By

Claude Code (Sonnet 4.5) - January 24, 2026