# github/personal-website architecture

> Architecture diagram of the GitHub repository github/personal-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/github/personal-website
- Repository: https://github.com/github/personal-website

## Overview

##### Project Type and Purpose
- This is a static site generator project built with Jekyll to serve as a personal developer portfolio and blog.
- It leverages GitHub Pages for hosting and the GitHub Metadata plugin (GitHub’s API) to auto-populate dynamic content (profile info, repositories, blog posts).

##### File Structure Analysis
- Root files
- _config.yml: Jekyll configuration (site metadata, theme settings, plugin config)
- index.html: Home page entry point (uses the “home” layout)
- Gemfile: Ruby + Jekyll dependencies
- Directories
- _includes/: Reusable HTML snippets (header, footer, repo-card, post-card, interests, social links)
- _layouts/: Page templates (“default”, “home”, “post”)
- _posts/: Blog posts in Markdown with front matter
- _sass/ + assets/: SCSS/CSS (Primer import & custom styles)
- Hidden/config files
- .gitignore, .gitattributes, LICENSE.txt – standard repo config

##### Architectural Insights from README
- Build pipeline: Local (or GitHub Pages) Jekyll build → transforms Markdown + layouts/includes + data → static HTML/CSS/JS
- Data integration: github-metadata plugin calls GitHub’s REST API to fetch user profile & repo data at build time
- Hosting: GitHub Pages automatically runs Jekyll on pushes to master/main (or special branch)

##### Main Components
a. Developer Environment
- Local machine (Ruby + Bundler + Jekyll)
- Source code: markdown, templates, SCSS, config
b. Jekyll Build Engine
- Core Jekyll conversion (Liquid templating, front matter parsing)
- Plugins: github-metadata
c. External Service
- GitHub API (metadata endpoints for user info, repos)
d. Output Artifact
- Generated static site (_site) with HTML, CSS, assets
e. Hosting Layer
- GitHub Pages (build hook, CDN)
- Custom domain (optional)

##### Component Interactions and Data Flow
1. Developer edits source files → commits to GitHub
2. On push, GitHub Pages triggers Jekyll build
3. Jekyll build reads:
– _config.yml + front matter (site settings, layout declarations)
– _includes/ + _layouts/ (templates)
– _posts/ (Markdown content)
– _data/ (static JSON/YAML)
– assets/ (SCSS → CSS)
4. github-metadata plugin sends requests to GitHub API → retrieves user profile & repository data
5. Jekyll merges templates + content + API data → produces static site in _site/
6. GitHub Pages serves the resulting files via HTTPS on username.github.io (or custom domain)

##### Architectural Patterns and Principles
- Static site generator (SSG) pattern
- Component-based templates (DRY includes, layouts)
- Data-driven rendering (YAML/JSON + external API)
- Separation of concerns: content (_posts), presentation (_layouts, _includes), style (SCSS)

##### Technologies & Frameworks
- Ruby, Jekyll, Liquid templating
- GitHub Pages (host & CI for build)
- GitHub Metadata plugin (API integration)
- Primer CSS via SCSS import
- Front matter (YAML) and data files (_data)

- Component names and roles
- Layer separation: Content layer, Template layer, Data layer, Build layer, Delivery layer

## Diagram (Mermaid)

```mermaid
graph TD
    %% Developer & Source
    subgraph "Developer & Source" 
        direction TB
        Gemfile["Gemfile"]:::dev
        ConfigYml["_config.yml"]:::dev
        Readme["README.md"]:::dev
        Index["index.html"]:::dev
        Gitignore[".gitignore"]:::dev
        Gitattributes[".gitattributes"]:::dev
        License["LICENSE.txt"]:::dev
        PostMD["_posts/2019-01-29-hello-world.md"]:::dev
        DefaultLayout["_layouts/default.html"]:::dev
        HomeLayout["_layouts/home.html"]:::dev
        PostLayout["_layouts/post.html"]:::dev
        HeaderInc["_includes/header.html"]:::dev
        FooterInc["_includes/footer.html"]:::dev
        MastheadInc["_includes/masthead.html"]:::dev
        InterestsInc["_includes/interests.html"]:::dev
        ProjectsInc["_includes/projects.html"]:::dev
        RepoCardInc["_includes/repo-card.html"]:::dev
        PostCardInc["_includes/post-card.html"]:::dev
        TopicCardInc["_includes/topic-card.html"]:::dev
        ThoughtsInc["_includes/thoughts.html"]:::dev
        ColorsData["_data/colors.json"]:::dev
        SocialData["_data/social_media.yml"]:::dev
        HighlightSCSS["_sass/_highlight-syntax.scss"]:::dev
        StylesSCSS["assets/styles.scss"]:::dev
    end

    %% Build Engine & Plugins
    subgraph "Jekyll Build Engine" 
        direction TB
        JekyllCore["Jekyll Core\n(Liquid & Front Matter)"]:::build
        Plugin["github-metadata Plugin"]:::build
    end

    %% External API
    subgraph "External Service" 
        direction TB
        GitHubAPI["GitHub API"]:::external
    end

    %% Output Artifact
    subgraph "Static Site Output" 
        direction TB
        StaticSite["_site/"]:::build
    end

    %% Hosting Layer
    subgraph "Hosting & Delivery" 
        direction TB
        GitHubPages["GitHub Pages\nHost & CDN"]:::hosting
    end

    %% Connections
    Gemfile -->|reads config| JekyllCore
    ConfigYml -->|reads config| JekyllCore
    Readme -->|includes in site| JekyllCore
    Index -->|uses layout| JekyllCore
    Gitignore -->|ignored during build| JekyllCore
    Gitattributes -->|repo config| JekyllCore
    License -->|license info| JekyllCore
    PostMD -->|content| JekyllCore
    DefaultLayout -->|template| JekyllCore
    HomeLayout -->|template| JekyllCore
    PostLayout -->|template| JekyllCore
    HeaderInc -->|include| JekyllCore
    FooterInc -->|include| JekyllCore
    MastheadInc -->|include| JekyllCore
    InterestsInc -->|include| JekyllCore
    ProjectsInc -->|include| JekyllCore
    RepoCardInc -->|include| JekyllCore
    PostCardInc -->|include| JekyllCore
    TopicCardInc -->|include| JekyllCore
    ThoughtsInc -->|include| JekyllCore
    ColorsData -->|data| JekyllCore
    SocialData -->|data| JekyllCore
    HighlightSCSS -->|styles| JekyllCore
    StylesSCSS -->|styles| JekyllCore

    JekyllCore -->|invokes| Plugin
    Plugin -->|fetch profile & repos| GitHubAPI
    JekyllCore -->|builds site| StaticSite
    StaticSite -->|deploy| GitHubPages

    %% Click Events
    click Gemfile "https://github.com/github/personal-website/tree/master/Gemfile"
    click ConfigYml "https://github.com/github/personal-website/blob/master/_config.yml"
    click Readme "https://github.com/github/personal-website/blob/master/README.md"
    click Index "https://github.com/github/personal-website/blob/master/index.html"
    click Gitignore "https://github.com/github/personal-website/blob/master/.gitignore"
    click Gitattributes "https://github.com/github/personal-website/blob/master/.gitattributes"
    click License "https://github.com/github/personal-website/blob/master/LICENSE.txt"
    click PostMD "https://github.com/github/personal-website/blob/master/_posts/2019-01-29-hello-world.md"
    click DefaultLayout "https://github.com/github/personal-website/blob/master/_layouts/default.html"
    click HomeLayout "https://github.com/github/personal-website/blob/master/_layouts/home.html"
    click PostLayout "https://github.com/github/personal-website/blob/master/_layouts/post.html"
    click HeaderInc "https://github.com/github/personal-website/blob/master/_includes/header.html"
    click FooterInc "https://github.com/github/personal-website/blob/master/_includes/footer.html"
    click MastheadInc "https://github.com/github/personal-website/blob/master/_includes/masthead.html"
    click InterestsInc "https://github.com/github/personal-website/blob/master/_includes/interests.html"
    click ProjectsInc "https://github.com/github/personal-website/blob/master/_includes/projects.html"
    click RepoCardInc "https://github.com/github/personal-website/blob/master/_includes/repo-card.html"
    click PostCardInc "https://github.com/github/personal-website/blob/master/_includes/post-card.html"
    click TopicCardInc "https://github.com/github/personal-website/blob/master/_includes/topic-card.html"
    click ThoughtsInc "https://github.com/github/personal-website/blob/master/_includes/thoughts.html"
    click ColorsData "https://github.com/github/personal-website/blob/master/_data/colors.json"
    click SocialData "https://github.com/github/personal-website/blob/master/_data/social_media.yml"
    click HighlightSCSS "https://github.com/github/personal-website/blob/master/_sass/_highlight-syntax.scss"
    click StylesSCSS "https://github.com/github/personal-website/blob/master/assets/styles.scss"
    click StaticSite "https://github.com/github/personal-website/tree/master/_site/"

    %% Styles
    classDef dev fill:#D6EAF8,stroke:#21618C,stroke-width:1px;
    classDef build fill:#D5F5E3,stroke:#196F3D,stroke-width:1px;
    classDef external fill:#FDEBD0,stroke:#B9770E,stroke-width:1px;
    classDef hosting fill:#E8DAEF,stroke:#6C3483,stroke-width:1px;
```
