Architecture Overview

This document describes the technical architecture and structure of the johnoct.github.io website.

Technology Stack

Core Framework

• Jekyll 4.4.1: Static site generator
• Minima 2.5: Base theme (customized)
• Ruby: Runtime environment
• Kramdown: Markdown processor
• Rouge: Syntax highlighter

Hosting & Deployment

• GitHub Pages: Free hosting and automatic deployment
• GitHub Actions: CI/CD pipeline for builds
• Custom Domain: johnoct.github.io

Dependencies

• jekyll-feed: RSS feed generation
• jekyll-sitemap: XML sitemap generation

Directory Structure

johnoct.github.io/
├── _config.yml              # Jekyll configuration
├── _layouts/                # Page templates
│   ├── default.html         # Base layout with navigation
│   └── post.html            # Blog post template
├── _posts/                  # Blog content (Markdown)
│   ├── 2024-12-06-*.md     # Technical blog posts
│   └── 2025-07-26-*.md     # GitHub stars posts
├── _site/                   # Generated static files (ignored)
├── scripts/                 # Automation utilities
│   ├── daily-stars.sh      # GitHub stars collection
│   └── quick-stars.sh      # Manual stars script
├── assets/                  # Static assets
├── docs/                    # Documentation
├── blog.md                  # Blog listing page
├── github-stars.md          # Stars collection page
├── github-activity.md       # Activity tracker page
├── index.html              # Homepage
├── styles.css              # Custom styling
├── Gemfile                 # Ruby dependencies
└── README.md               # Project documentation

Jekyll Configuration

Site Settings (_config.yml)

title: John - Senior Cloud Engineer
description: Cloud Engineering & Technical Leadership
url: "https://johnoct.github.io"
theme: minima

# Permalink structure
permalink: /blog/:year/:month/:day/:title/

# Post collections
collections:
  posts:
    output: true
    permalink: /blog/:title/

# Plugins
plugins:
  - jekyll-feed
  - jekyll-sitemap

Content Categories

Posts are organized using Jekyll’s category system:

1. Technical Blog (categories: blog)
   • Professional insights and experiences
   • Cloud engineering tutorials
   • DevOps best practices
2. GitHub Stars (categories: github-stars)
   • Daily automated collections
   • Weekly curated roundups
   • Repository discoveries

Page Templates

Default Layout (_layouts/default.html)

• Site header with navigation
• Main content area
• Footer with links
• Responsive design
• SEO meta tags

Post Layout (_layouts/post.html)

• Extends default layout
• Post title and date
• Content formatting
• Navigation between posts

Content Management

Front Matter Structure

Technical Blog Posts

---
title: "Post Title"
date: YYYY-MM-DD
layout: post
categories: blog
tags: [aws, cloud, devops]
---

GitHub Stars Posts

---
title: "Daily GitHub Stars: Month DD, YYYY"
date: YYYY-MM-DD
layout: post
categories: github-stars
tags: [automation, open-source, github]
---

Content Filtering

Pages use Jekyll’s Liquid templating to filter content:

# Blog page - shows only technical posts


# GitHub stars page - shows only repository posts

Styling Architecture

CSS Organization

• Base styles: Typography, layout, responsive design
• Component styles: Blog posts, navigation, forms
• Utility classes: Spacing, colors, alignment
• Mobile-first: Responsive breakpoints

Key Design Principles

• Minimalist aesthetic
• Fast loading times
• Mobile accessibility
• Clean typography
• Consistent spacing

Build Process

Local Development

1. Jekyll monitors file changes
2. Automatically regenerates _site/ directory
3. Serves content at localhost:4000
4. Live reload for immediate feedback

Production Deployment

1. Push commits to master branch
2. GitHub Actions triggers build
3. Jekyll generates static files
4. GitHub Pages serves content
5. Site updates within 1-2 minutes

Automation Architecture

GitHub Stars Collection

• Trigger: Manual execution or cron job
• Data Source: GitHub API via GitHub CLI
• Processing: Shell script with JSON parsing
• Output: Formatted Markdown blog posts
• Deduplication: Compares with previous posts

Content Generation Flow

1. Fetch starred repositories from GitHub API
2. Compare with existing posts to find new additions
3. Generate front matter and content structure
4. Create properly formatted blog post file
5. Include repository metadata and descriptions

Performance Considerations

Optimization Strategies

• Static file generation (no server-side processing)
• Minimal JavaScript dependencies
• Optimized images and assets
• Efficient CSS with minimal bloat
• CDN delivery via GitHub Pages

Loading Times

• Average page load: < 2 seconds
• First contentful paint: < 1 second
• Mobile-optimized performance
• Progressive enhancement

Security & Maintenance

Security Features

• Static site (no dynamic vulnerabilities)
• HTTPS by default via GitHub Pages
• No user input or database
• Regular dependency updates via Dependabot

Maintenance Tasks

• Monitor Jekyll and gem updates
• Review and update documentation
• Test automation scripts
• Validate markup and accessibility

Extension Points

Adding New Features

• Create new page templates in _layouts/
• Add new content types with front matter
• Extend automation with additional scripts
• Customize styling in styles.css

Integration Possibilities

• Analytics platforms (Google Analytics)
• Comment systems (Disqus, utterances)
• Search functionality (Algolia, Lunr)
• Newsletter integration (Mailchimp)

Technical Details: This architecture prioritizes simplicity, performance, and maintainability while providing flexibility for future enhancements.