Jekyll Blog System - Comprehensive Design Document

Table of Contents

1. System Overview
2. Architecture Diagrams
3. GitHub Integration
4. Jekyll Processing Flow
5. Folder Structure
6. Content Management
7. Build and Deployment
8. User Journey
9. Technical Specifications

System Overview

This Jekyll-based blog system is a static site generator that transforms Markdown content into a responsive, SEO-optimized website. The system leverages GitHub Pages for hosting and automatic deployment, creating a seamless content management workflow.

Key Components

graph TB
    subgraph "Content Layer"
        MD[Markdown Files]
        POSTS[Blog Posts<br/>_posts/]
        ARTICLES[Technical Articles<br/>_articles/]
        HOWTOS[How-to Guides<br/>_howtos/]
    end
    
    subgraph "Processing Layer"
        JEKYLL[Jekyll Engine]
        LIQUID[Liquid Templating]
        LAYOUTS[Layout Templates]
    end
    
    subgraph "Output Layer"
        HTML[Static HTML]
        CSS[Compiled CSS]
        ASSETS[Static Assets]
    end
    
    subgraph "Deployment Layer"
        GITHUB[GitHub Repository]
        PAGES[GitHub Pages]
        DOMAIN[Custom Domain<br/>teamworx365.com]
    end
    
    MD --> JEKYLL
    POSTS --> JEKYLL
    ARTICLES --> JEKYLL
    HOWTOS --> JEKYLL
    
    JEKYLL --> LIQUID
    LIQUID --> LAYOUTS
    LAYOUTS --> HTML
    
    HTML --> GITHUB
    CSS --> GITHUB
    ASSETS --> GITHUB
    
    GITHUB --> PAGES
    PAGES --> DOMAIN

Architecture Diagrams

System Architecture Overview

C4Context
    title System Context Diagram - Jekyll Blog System

    Person(user, "Content Creator", "Creates and manages blog content")
    Person(visitor, "Website Visitor", "Reads blog content")
    
    System(blog, "Jekyll Blog System", "Static site generator with automated content discovery")
    
    System_Ext(github, "GitHub", "Version control and hosting platform")
    System_Ext(pages, "GitHub Pages", "Static site hosting service")
    System_Ext(dns, "DNS Provider", "Domain name resolution")
    
    Rel(user, blog, "Creates content")
    Rel(user, github, "Commits changes")
    Rel(blog, github, "Stores code")
    Rel(github, pages, "Auto-deploys")
    Rel(visitor, pages, "Views website")
    Rel(pages, dns, "Resolves domain")

Container Diagram

C4Container
    title Container Diagram - Jekyll Blog System

    Person(user, "Content Creator")
    Person(visitor, "Website Visitor")

    Container_Boundary(blog, "Jekyll Blog System") {
        Container(content, "Content Files", "Markdown", "Blog posts, articles, guides")
        Container(templates, "Templates", "Liquid/HTML", "Layout templates and includes")
        Container(assets, "Assets", "CSS/JS/Images", "Static resources")
        Container(config, "Configuration", "YAML", "Jekyll and build settings")
        Container(generator, "Jekyll Generator", "Ruby", "Static site generator engine")
    }

    System_Ext(github, "GitHub Repository")
    System_Ext(pages, "GitHub Pages")

    Rel(user, content, "Creates/edits")
    Rel(content, generator, "Processes")
    Rel(templates, generator, "Uses")
    Rel(assets, generator, "Includes")
    Rel(config, generator, "Configures")
    Rel(generator, github, "Generates to")
    Rel(github, pages, "Deploys")
    Rel(visitor, pages, "Views")

Component Diagram - Jekyll Processing

C4Component
    title Component Diagram - Jekyll Processing Engine

    Container_Boundary(generator, "Jekyll Generator") {
        Component(reader, "File Reader", "Ruby", "Reads markdown and config files")
        Component(converter, "Markdown Converter", "Kramdown", "Converts MD to HTML")
        Component(liquid, "Liquid Processor", "Liquid", "Processes templates and variables")
        Component(layout, "Layout Engine", "Ruby", "Applies layouts to content")
        Component(collections, "Collections Manager", "Ruby", "Manages content collections")
        Component(writer, "File Writer", "Ruby", "Outputs final HTML files")
    }

    Container_Ext(content, "Content Files")
    Container_Ext(templates, "Templates")
    Container_Ext(output, "Generated Site")

    Rel(content, reader, "Reads")
    Rel(reader, collections, "Organizes")
    Rel(collections, converter, "Converts")
    Rel(converter, liquid, "Processes")
    Rel(liquid, layout, "Applies")
    Rel(templates, layout, "Uses")
    Rel(layout, writer, "Outputs")
    Rel(writer, output, "Generates")

GitHub Integration

Repository Structure and Git Flow

gitgraph
    commit id: "Initial Jekyll setup"
    commit id: "Add content collections"
    commit id: "Implement responsive design"
    branch feature/blog-enhancement
    commit id: "Add blog functionality"
    commit id: "Create navigation menu"
    checkout main
    merge feature/blog-enhancement
    commit id: "Fix index.html generation"
    commit id: "Add blog link to navigation"
    commit id: "Clean up unused files"
    commit id: "Add comprehensive documentation"

GitHub Pages Deployment Flow

sequenceDiagram
    participant Dev as Developer
    participant Git as Git Repository
    participant GH as GitHub
    participant Pages as GitHub Pages
    participant CDN as GitHub CDN
    participant User as End User

    Dev->>Git: git push origin main
    Git->>GH: Push commits to remote
    GH->>GH: Trigger Pages build
    GH->>Pages: Jekyll build process
    Pages->>Pages: Generate static files
    Pages->>CDN: Deploy to CDN
    CDN->>User: Serve website
    
    Note over GH,Pages: Automatic deployment<br/>on every push to main

File Change Detection

flowchart TD
    A[File Changed] --> B{File Type?}
    
    B -->|Markdown Content| C[Collection Detection]
    B -->|Layout/Template| D[Full Site Rebuild]
    B -->|Config File| D
    B -->|CSS/Assets| E[Asset Pipeline]
    
    C --> F{Collection Type?}
    F -->|_posts/| G[Blog Posts Collection]
    F -->|_articles/| H[Articles Collection]
    F -->|_howtos/| I[How-tos Collection]
    
    G --> J[Update Blog Index]
    H --> K[Update Articles Index]
    I --> L[Update How-tos Index]
    
    J --> M[Regenerate Homepage]
    K --> M
    L --> M
    
    D --> N[Complete Rebuild]
    E --> O[Update Assets]
    M --> P[Deploy to GitHub Pages]
    N --> P
    O --> P

Jekyll Processing Flow

Build Process Overview

flowchart TD
    A[Start Jekyll Build] --> B[Read _config.yml]
    B --> C[Scan Directory Structure]
    C --> D[Load Plugins]
    D --> E[Process Collections]
    
    E --> F[Read Markdown Files]
    F --> G[Extract Front Matter]
    G --> H[Convert Markdown to HTML]
    H --> I[Apply Liquid Templates]
    I --> J[Apply Layouts]
    J --> K[Generate Permalinks]
    K --> L[Create Navigation]
    L --> M[Process Assets]
    M --> N[Generate Feeds/Sitemaps]
    N --> O[Write Output Files]
    O --> P[Build Complete]
    
    style A fill:#e1f5fe
    style P fill:#c8e6c9

Content Processing Pipeline

graph LR
    subgraph "Input Stage"
        MD[Markdown Files]
        FM[Front Matter]
        META[Metadata]
    end
    
    subgraph "Processing Stage"
        PARSE[YAML Parser]
        KRAMDOWN[Kramdown Converter]
        LIQUID[Liquid Engine]
        LAYOUT[Layout Engine]
    end
    
    subgraph "Output Stage"
        HTML[HTML Files]
        INDEX[Index Pages]
        FEED[RSS Feed]
        SITEMAP[XML Sitemap]
    end
    
    MD --> KRAMDOWN
    FM --> PARSE
    META --> PARSE
    
    PARSE --> LIQUID
    KRAMDOWN --> LIQUID
    LIQUID --> LAYOUT
    
    LAYOUT --> HTML
    LAYOUT --> INDEX
    LAYOUT --> FEED
    LAYOUT --> SITEMAP

Collection Processing Detail

sequenceDiagram
    participant Jekyll as Jekyll Engine
    participant Config as Configuration
    participant Scanner as File Scanner
    participant Processor as Content Processor
    participant Generator as Site Generator
    
    Jekyll->>Config: Load collections config
    Config->>Scanner: Scan collection directories
    Scanner->>Scanner: Find .md files
    Scanner->>Processor: Send file list
    
    loop For each content file
        Processor->>Processor: Parse front matter
        Processor->>Processor: Convert markdown
        Processor->>Processor: Apply layout
        Processor->>Generator: Add to collection
    end
    
    Generator->>Generator: Sort by date
    Generator->>Generator: Generate index pages
    Generator->>Generator: Create navigation
    Generator->>Jekyll: Return processed content

Folder Structure

Complete Directory Tree

graph TD
    ROOT["/"] --> CONFIG["_config.yml"]
    ROOT --> GEMFILE["Gemfile"]
    ROOT --> INDEX["index.html"]
    ROOT --> ABOUT["about.md"]
    ROOT --> BLOG["blog.md"]
    ROOT --> ARTICLES["articles.md"]
    ROOT --> HOWTOS["howtos.md"]
    ROOT --> CNAME["CNAME"]
    
    ROOT --> LAYOUTS["_layouts/"]
    LAYOUTS --> DEFAULT["default.html"]
    LAYOUTS --> POST["post.html"]
    
    ROOT --> POSTS["_posts/"]
    POSTS --> POST1["2025-07-20-sample-post.md"]
    POSTS --> POST2["2025-01-20-test-markdown.md"]
    POSTS --> POST3["2025-07-20-testing-auto-discovery.md"]
    
    ROOT --> ARTICLESCOL["_articles/"]
    ARTICLESCOL --> ART1["sample-article.md"]
    ARTICLESCOL --> ART2["setup-docker-development.md"]
    ARTICLESCOL --> ART3["jekyll-collections-vs-posts.md"]
    ARTICLESCOL --> ARTINDEX["index.html"]
    
    ROOT --> HOWTOSCOL["_howtos/"]
    HOWTOSCOL --> HOW1["sample-howto.md"]
    HOWTOSCOL --> HOW2["deploy-github-pages.md"]
    HOWTOSCOL --> HOW3["quick-reference-adding-content.md"]
    HOWTOSCOL --> HOWINDEX["index.html"]
    
    ROOT --> ASSETS["assets/"]
    ASSETS --> CSS["css/"]
    CSS --> MAIN["main.css"]
    
    ROOT --> SITE["_site/"]
    SITE --> GENERATED["Generated HTML files"]
    
    style ROOT fill:#e3f2fd
    style LAYOUTS fill:#fff3e0
    style POSTS fill:#f3e5f5
    style ARTICLESCOL fill:#e8f5e8
    style HOWTOSCOL fill:#fff8e1
    style ASSETS fill:#fce4ec
    style SITE fill:#f1f8e9

File Organization Strategy

graph TB
    subgraph "Content Organization"
        direction TB
        CONTENT[Content Strategy]
        
        CONTENT --> TEMPORAL[Temporal Content<br/>_posts/]
        CONTENT --> REFERENCE[Reference Content<br/>_articles/]
        CONTENT --> PROCEDURAL[Procedural Content<br/>_howtos/]
        
        TEMPORAL --> BLOG_POSTS[Blog Posts<br/>Date-based<br/>Personal thoughts]
        REFERENCE --> TECH_ARTICLES[Technical Articles<br/>Comprehensive guides<br/>In-depth tutorials]
        PROCEDURAL --> HOW_TO_GUIDES[How-to Guides<br/>Step-by-step<br/>Quick solutions]
    end
    
    subgraph "File Naming Conventions"
        direction TB
        NAMING[Naming Strategy]
        
        NAMING --> POST_NAME[Posts: YYYY-MM-DD-title.md]
        NAMING --> ARTICLE_NAME[Articles: descriptive-title.md]
        NAMING --> HOWTO_NAME[How-tos: action-based-title.md]
    end
    
    subgraph "URL Structure"
        direction TB
        URLS[URL Strategy]
        
        URLS --> POST_URL[Posts: /category/year/month/day/title/]
        URLS --> ARTICLE_URL[Articles: /articles/title/]
        URLS --> HOWTO_URL[How-tos: /howtos/title/]
    end

Content Management

Content Lifecycle

stateDiagram-v2
    [*] --> Draft: Create .md file
    Draft --> Review: Add front matter
    Review --> Published: Commit to main
    Published --> Updated: Edit content
    Updated --> Published: Commit changes
    Published --> Archived: Move to archive
    Archived --> [*]: Delete file
    
    Review --> Draft: Need changes
    
    note right of Draft
        Front matter required:
        - title
        - date (for posts)
        - layout
        - categories/tags
    end note
    
    note right of Published
        Automatically appears on:
        - Homepage (recent items)
        - Collection index pages
        - RSS feed
        - XML sitemap
    end note

Content Discovery Flow

flowchart TD
    A[New .md File Added] --> B{File Location?}
    
    B -->|_posts/| C[Blog Posts Collection]
    B -->|_articles/| D[Articles Collection]
    B -->|_howtos/| E[How-tos Collection]
    B -->|Root directory| F[Static Page]
    
    C --> G[Parse Front Matter]
    D --> G
    E --> G
    F --> H[Generate Page]
    
    G --> I{Valid Front Matter?}
    I -->|Yes| J[Add to Collection]
    I -->|No| K[Skip Processing]
    
    J --> L[Update Collection Index]
    L --> M[Update Homepage]
    M --> N[Regenerate Navigation]
    N --> O[Update RSS Feed]
    O --> P[Update Sitemap]
    P --> Q[Content Live]
    
    H --> Q
    K --> R[Error in Build Log]

Metadata Schema

classDiagram
    class ContentBase {
        +String title
        +String layout
        +Date date
        +String[] tags
        +String excerpt
        +String permalink
    }
    
    class BlogPost {
        +String[] categories
        +String author
        +Boolean published
        +String featured_image
    }
    
    class TechnicalArticle {
        +String category
        +String difficulty
        +Integer estimated_time
        +String[] prerequisites
        +String code_language
    }
    
    class HowToGuide {
        +String difficulty
        +String estimated_time
        +String[] tools_required
        +Integer step_count
        +String complexity
    }
    
    ContentBase <|-- BlogPost
    ContentBase <|-- TechnicalArticle
    ContentBase <|-- HowToGuide

Build and Deployment

CI/CD Pipeline

graph TD
    A[Developer commits code] --> B[GitHub receives push]
    B --> C[GitHub Pages triggered]
    C --> D[Checkout repository]
    D --> E[Setup Ruby environment]
    E --> F[Install dependencies<br/>bundle install]
    F --> G[Run Jekyll build<br/>bundle exec jekyll build]
    G --> H{Build successful?}
    
    H -->|Yes| I[Deploy to CDN]
    H -->|No| J[Send failure notification]
    
    I --> K[Update DNS]
    K --> L[Clear cache]
    L --> M[Site live]
    
    J --> N[Check build logs]
    N --> O[Fix issues]
    O --> A
    
    style A fill:#e1f5fe
    style M fill:#c8e6c9
    style J fill:#ffcdd2

Build Environment

graph TB
    subgraph "GitHub Pages Environment"
        RUBY[Ruby 3.1.x]
        JEKYLL[Jekyll 3.9.x<br/>GitHub Pages Compatible]
        GEMS[GitHub Pages Gem]
        PLUGINS[Whitelisted Plugins Only]
    end
    
    subgraph "Local Development Environment"
        LOCAL_RUBY[Ruby 3.4.0]
        LOCAL_JEKYLL[Jekyll 4.3.0]
        LOCAL_GEMS[All Gems Available]
        LOCAL_PLUGINS[Any Plugin Supported]
    end
    
    subgraph "Configuration Management"
        GEMFILE[Gemfile]
        CONFIG[_config.yml]
        GITHUB_PAGES_GEM[github-pages gem]
    end
    
    GEMFILE --> RUBY
    GEMFILE --> LOCAL_RUBY
    CONFIG --> JEKYLL
    CONFIG --> LOCAL_JEKYLL
    GITHUB_PAGES_GEM --> GEMS

Performance Optimization

flowchart TD
    A[Performance Optimization] --> B[Build Time]
    A --> C[Runtime Performance]
    A --> D[SEO Optimization]
    
    B --> B1[Incremental builds]
    B --> B2[Cached dependencies]
    B --> B3[Parallel processing]
    
    C --> C1[Static file optimization]
    C --> C2[CSS minification]
    C --> C3[Image optimization]
    C --> C4[CDN delivery]
    
    D --> D1[Meta tags]
    D --> D2[Structured data]
    D --> D3[XML sitemap]
    D --> D4[RSS feeds]
    D --> D5[Semantic HTML]
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#e8f5e8

User Journey

Visitor Experience Flow

journey
    title Website Visitor Journey
    section Discovery
      Search Engine: 8: Visitor
      Social Media: 7: Visitor
      Direct URL: 9: Visitor
    section First Visit
      Landing Page: 8: Visitor
      Navigation: 7: Visitor
      Content Browse: 9: Visitor
    section Content Consumption
      Read Blog Post: 9: Visitor
      Technical Article: 8: Visitor
      How-to Guide: 9: Visitor
    section Engagement
      Share Content: 6: Visitor
      Bookmark Site: 7: Visitor
      Return Visit: 8: Visitor

Content Creator Workflow

sequenceDiagram
    participant Creator as Content Creator
    participant Editor as Text Editor
    participant Git as Git Repository
    participant GitHub as GitHub
    participant Pages as GitHub Pages
    participant Site as Live Site
    
    Creator->>Editor: Write new content
    Editor->>Editor: Add front matter
    Editor->>Git: Save as .md file
    Creator->>Git: git add .
    Creator->>Git: git commit -m "New content"
    Creator->>GitHub: git push origin main
    GitHub->>Pages: Trigger build
    Pages->>Pages: Jekyll build process
    Pages->>Site: Deploy updated site
    Site->>Creator: Content live notification

Navigation Architecture

graph TD
    HOME[Homepage<br/>index.html] --> BLOG[Blog<br/>/blog/]
    HOME --> ARTICLES[Articles<br/>/articles/]
    HOME --> HOWTOS[How-tos<br/>/howtos/]
    HOME --> ABOUT[About<br/>/about/]
    
    BLOG --> BLOG_POST[Individual Post<br/>/category/year/month/day/title/]
    ARTICLES --> ARTICLE[Individual Article<br/>/articles/title/]
    HOWTOS --> HOWTO[Individual Guide<br/>/howtos/title/]
    
    BLOG_POST --> RELATED[Related Posts]
    ARTICLE --> RELATED_ARTICLES[Related Articles]
    HOWTO --> RELATED_GUIDES[Related Guides]
    
    RELATED --> HOME
    RELATED_ARTICLES --> HOME
    RELATED_GUIDES --> HOME
    
    style HOME fill:#e3f2fd
    style BLOG fill:#f3e5f5
    style ARTICLES fill:#e8f5e8
    style HOWTOS fill:#fff8e1
    style ABOUT fill:#fce4ec

Technical Specifications

Technology Stack Details

graph TB
    subgraph "Frontend Technologies"
        HTML5[HTML5<br/>Semantic markup]
        CSS3[CSS3<br/>Grid + Flexbox]
        JS[Vanilla JavaScript<br/>Progressive enhancement]
    end
    
    subgraph "Build Tools"
        JEKYLL[Jekyll 4.3.0<br/>Static site generator]
        LIQUID[Liquid<br/>Templating engine]
        KRAMDOWN[Kramdown<br/>Markdown processor]
        ROUGE[Rouge<br/>Syntax highlighter]
    end
    
    subgraph "Development Environment"
        RUBY[Ruby 3.4.0<br/>Runtime environment]
        BUNDLER[Bundler<br/>Dependency management]
        GIT[Git<br/>Version control]
    end
    
    subgraph "Hosting & Deployment"
        GITHUB[GitHub<br/>Code repository]
        PAGES[GitHub Pages<br/>Static hosting]
        CDN[GitHub CDN<br/>Global distribution]
        DNS[Custom DNS<br/>teamworx365.com]
    end
    
    subgraph "SEO & Analytics"
        SEO_TAG[Jekyll SEO Tag<br/>Meta optimization]
        SITEMAP[XML Sitemap<br/>Search indexing]
        FEED[RSS Feed<br/>Content syndication]
        SCHEMA[Schema.org<br/>Structured data]
    end

Database Schema (Jekyll Collections)

erDiagram
    SITE ||--o{ POSTS : contains
    SITE ||--o{ ARTICLES : contains
    SITE ||--o{ HOWTOS : contains
    SITE ||--o{ PAGES : contains
    
    POSTS {
        string title
        date date
        string[] categories
        string[] tags
        string author
        string layout
        text content
        string permalink
    }
    
    ARTICLES {
        string title
        date date
        string category
        string difficulty
        string[] tags
        string layout
        text content
        string permalink
        int estimated_time
    }
    
    HOWTOS {
        string title
        date date
        string difficulty
        string estimated_time
        string[] tools_required
        string[] tags
        string layout
        text content
        string permalink
    }
    
    PAGES {
        string title
        string layout
        string permalink
        text content
        boolean published
    }

Security Considerations

graph TD
    A[Security Measures] --> B[Static Site Benefits]
    A --> C[GitHub Security]
    A --> D[Content Security]
    
    B --> B1[No database vulnerabilities]
    B --> B2[No server-side processing]
    B --> B3[Reduced attack surface]
    
    C --> C1[Two-factor authentication]
    C --> C2[Branch protection rules]
    C --> C3[Dependency scanning]
    C --> C4[Secret scanning]
    
    D --> D1[Content sanitization]
    D --> D2[Safe markdown processing]
    D --> D3[XSS prevention]
    D --> D4[HTTPS enforcement]
    
    style A fill:#e3f2fd
    style B fill:#e8f5e8
    style C fill:#fff3e0
    style D fill:#f3e5f5

Performance Metrics

graph LR
    subgraph "Core Web Vitals"
        LCP[Largest Contentful Paint<br/>< 2.5s]
        FID[First Input Delay<br/>< 100ms]
        CLS[Cumulative Layout Shift<br/>< 0.1]
    end
    
    subgraph "Additional Metrics"
        FCP[First Contentful Paint<br/>< 1.8s]
        TTI[Time to Interactive<br/>< 3.8s]
        TBT[Total Blocking Time<br/>< 200ms]
    end
    
    subgraph "Network Performance"
        SIZE[Total Page Size<br/>< 500KB]
        REQUESTS[HTTP Requests<br/>< 20]
        CACHE[Cache Hit Rate<br/>> 90%]
    end
    
    style LCP fill:#c8e6c9
    style FID fill:#c8e6c9
    style CLS fill:#c8e6c9

Conclusion

This comprehensive design document outlines the complete architecture and implementation of the Jekyll blog system. The system provides:

• Scalable Content Management: Through Jekyll collections and automated discovery
• Modern Development Workflow: Git-based content management with automatic deployment
• Performance Optimization: Static site generation with CDN delivery
• SEO Excellence: Built-in optimization features and structured data
• Maintainability: Clean separation of content, presentation, and configuration

The system is designed to grow with content needs while maintaining simplicity and performance.