How github/personal-website works
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