| name | github-pages-generator |
| description | Transform GitHub repositories into production-ready portfolio websites. Auto-detects project type, guides interactive customization, generates multi-page responsive sites with GitHub Actions deployment. Triggers on any GitHub URL + portfolio/website/showcase intent. Generates complete HTML/CSS/JS, deployment guides, and customization instructions—no partial deliverables. |
GitHub Pages Site Generator
A specialized skill for transforming GitHub repositories into polished, interactive portfolio showcase websites with interactive customization, intelligent repo-type detection, and multiple design aesthetics.
Core Purpose
Turn a GitHub repo URL into a production-ready, deployable GitHub Pages site in an interactive workflow. Auto-detect project type, guide customization via targeted questions, then generate complete site files ready to deploy.
When to Use This Skill
Use this skill when the user:
- Provides a GitHub repository URL and wants a portfolio/showcase website
- Requests "create a Pages site for my repo"
- Wants to showcase a project with a professional website
- Needs GitHub Pages files + deployment structure
- Mentions generating a portfolio site, project showcase, or documentation site from a GitHub repo
Triggers: "portfolio site", "GitHub Pages", "showcase website", "create a site for my repo", "generate Pages", "make a website from my GitHub project"
Workflow Overview
User provides repo URL
↓
Auto-detect repo type
↓
Ask design preference (modern/portfolio/docs)
↓
Interactive customization (sections, content, focus areas)
↓
Generate complete site structure
↓
Deliver deployment-ready files + guide
Step 1: Repository Analysis & Type Detection
When the user provides a GitHub repo URL:
Auto-Detection Logic
Analyze the repository to determine type:
**Primary Project Types** (auto-detected):
├── TypeScript/Node.js Projects
│ ├── Files: package.json, tsconfig.json, .ts files
│ ├── Frameworks: Express, Next.js, NestJS, React
│ └── Highlight: API design, performance, scalability
│
├── .NET/C# Projects
│ ├── Files: *.csproj, *.sln, appsettings.json
│ ├── Frameworks: .NET Core, ASP.NET, Entity Framework
│ └── Highlight: Architecture patterns (DDD, CQRS), enterprise patterns
│
├── Python/ML/Computer Vision
│ ├── Files: requirements.txt, setup.py, *.ipynb, Dockerfile
│ ├── Frameworks: PyTorch, TensorFlow, scikit-learn, OpenCV
│ └── Highlight: Model architecture, training pipeline, metrics
│
└── Full-Stack Web Apps
├── Indicators: Frontend + Backend + Database
├── Files: package.json + *.csproj OR requirements.txt + node modules
└── Highlight: Architecture, feature walkthrough, deployment
Detection Process
find {repo} -maxdepth 2 -type f \( -name "*.csproj" -o -name "package.json" \
-o -name "requirements.txt" -o -name "Cargo.toml" -o -name "go.mod" \)
find {repo} -name "*.md" | grep -i "readme\|architecture\|design\|docs"
cat {repo}/package.json | jq .dependencies
cat {repo}/*.csproj 2>/dev/null | grep -o "TargetFramework.*"
Step 2: Design Style Selection
Present the user with three design options:
Option 1: Modern Minimal
- Aesthetic: Clean, typography-focused, high whitespace
- Color: Neutral palette (grays, one accent color)
- Layout: Single-column or two-column, prose-heavy
- Best for: Libraries, APIs, documentation-heavy projects
- Tech: Plain HTML/CSS, fast loading, accessible
- Example vibe: HubSpot docs, Stripe documentation
Option 2: Portfolio Heavy
- Aesthetic: Visually rich, showcase-focused, metrics-prominent
- Color: Brand-forward, dynamic gradients
- Layout: Multi-section, image galleries, stat cards
- Best for: Full-stack apps, ML projects, anything you're proud of
- Tech: CSS animations, image assets, modern design patterns
- Example vibe: Vercel product pages, Figma's case studies
Option 3: Documentation Style
- Aesthetic: Official docs vibe, navigation-focused, scannable
- Color: Professional (blue/dark theme options)
- Layout: Sidebar navigation, multi-page, code-centric
- Best for: Tools, CLIs, frameworks, data engineering
- Tech: Code syntax highlighting, table of contents, search-ready
- Example vibe: Official React/Next.js docs, GitHub documentation
Defaults by Project Type:
- ML/Data Engineering → Portfolio Heavy (showcase results, metrics)
- Libraries/SDKs → Documentation Style (API-focused)
- Full-Stack Web → Portfolio Heavy (feature showcase)
- Systems (Go/Rust) → Modern Minimal (performance-focused)
- .NET/Enterprise → Documentation Style or Portfolio Heavy (your choice)
Step 2b: Hybrid Content Gathering
The skill uses a hybrid approach:
-
Auto-extract from repository (first pass)
- Project description, README
- Tech stack from dependency files
- Architecture docs if present
- Code examples and quick-start guides
- Existing metrics or benchmarks
-
Ask refinement questions (second pass)
- Clarify/enhance what was auto-detected
- Fill gaps not found in repo
- Prioritize what to emphasize
- Provide qualitative context (problems solved, decisions made)
This minimizes user input while capturing rich context from existing repo content.
Step 3: Interactive Customization Questions
Based on detected project type, ask targeted questions:
For ML/Computer Vision Projects
1. What's the primary use case? (e.g., image classification, NLP, object detection)
2. Do you have:
- [ ] Performance metrics (accuracy, F1, inference time)?
- [ ] Training data samples or visualizations?
- [ ] Model architecture diagrams?
- [ ] Demo/inference examples?
3. Should we include:
- [ ] Live model demo (iframe to Hugging Face Space, etc.)?
- [ ] Training pipeline visualization?
- [ ] Results gallery/comparison charts?
4. Key achievements to highlight?
5. Want a "Quick Start" section for running inference?
For .NET/C# Projects
1. Project type: [ ] Web API [ ] Web App [ ] Library [ ] Enterprise Service [ ] Other?
2. Architectural patterns used?
- [ ] DDD [ ] CQRS [ ] Microservices [ ] Clean Architecture [ ] Event-Driven
3. Most interesting technical aspect to showcase?
4. Do you have:
- [ ] Architecture diagrams?
- [ ] Performance benchmarks?
- [ ] Security/compliance highlights?
5. Target audience: [ ] Recruiters [ ] Architects [ ] Engineering Teams [ ] Other?
6. Include deployment details (Azure, Docker, etc.)?
For TypeScript/Node.js Projects
1. Project category: [ ] API [ ] Web Framework [ ] CLI [ ] SDK [ ] Full-Stack App [ ] Other?
2. Key technical achievements:
- [ ] Performance optimization [ ] Scalability [ ] DX improvement [ ] Novel architecture
3. Do you have:
- [ ] Benchmark numbers?
- [ ] Architecture diagrams?
- [ ] Example usage code?
- [ ] Performance comparisons?
4. Should we include:
- [ ] Installation/setup guide?
- [ ] API reference?
- [ ] Example projects?
5. Does it integrate with other services? Which ones?
For Full-Stack Web Apps
1. Frontend stack: __________ (React, Vue, Svelte, etc.)
2. Backend stack: __________ (.NET, Node, Python, Go, etc.)
3. Database(s): __________
4. Most impressive feature/achievement?
5. Do you have:
- [ ] Screenshot/video walkthrough?
- [ ] Architecture diagram (frontend/backend/DB)?
- [ ] Performance metrics?
- [ ] User/usage statistics?
6. Include live demo link or screenshots?
Universal Questions
Always ask:
1. Primary goal for this site:
- [ ] Get hired/showcase skills
- [ ] Attract contributors
- [ ] Document the project
- [ ] Demonstrate impact
2. Include sections:
- [ ] Quick Start / Installation
- [ ] Architecture/Technical Deep-Dive
- [ ] Features showcase
- [ ] Live demo / Examples
- [ ] Contributing guide
- [ ] Metrics / Impact
3. Call-to-action: What do you want visitors to do?
(Star the repo / Use the project / Contact you / Other?)
Step 4: Content Gathering
Auto-Extraction from Repository
For content already in the repo, automatically extract:
✓ Project description (from README)
✓ Tech stack (from package.json, *.csproj, requirements.txt)
✓ Installation/quick-start (from README or CONTRIBUTING)
✓ Architecture docs (from docs/, architecture/, or ADR files)
✓ Examples (from examples/ or demo/)
✓ Contributing guidelines (from CONTRIBUTING.md)
✓ License (from LICENSE file)
User-Provided Content
For content not in repo, ask user to provide:
- Key achievements / metrics
- Project motivation / problem statement
- Architecture diagrams (if not in repo)
- Screenshots / demo links
- Performance/metrics data
- Target audience focus
Step 5: Site Generation
Complete GitHub Pages Repository Package
The skill generates a complete, ready-to-deploy GitHub Pages repository with multi-page structure and sidebar navigation:
{project}-portfolio/
├── index.html # Homepage with hero + sidebar nav
├── architecture.html # Architecture & tech stack
├── features.html # Feature showcase with images & diagrams
├── quick-start.html # Installation & getting started guide
├── demo.html # Live demo/examples (if applicable)
├── css/
│ ├── style.css # Main stylesheet (design-specific)
│ ├── variables.css # Design system (colors, fonts, spacing)
│ └── responsive.css # Mobile & breakpoint optimizations
├── js/
│ ├── main.js # Navigation, sidebar toggle, smooth scroll
│ ├── diagrams.js # Mermaid diagram initialization
│ └── syntax-highlight.js # Code snippet syntax highlighting
├── images/
│ ├── screenshots/ # Feature/demo screenshots with annotations
│ ├── diagrams/ # Exported architecture diagrams (PNG/SVG)
│ └── assets/ # Icons, logos, project assets
├── assets/
│ └── sample-metrics.json # Sample metrics dashboard data
├── _config.yml # Jekyll/GitHub Pages configuration
├── .github/
│ └── workflows/
│ └── deploy.yml # GitHub Actions auto-deploy workflow
├── .gitignore # Standard git ignore
├── README.md # **Deployment & setup instructions**
├── STYLE_GUIDE.md # **Design system documentation**
└── CUSTOMIZATION_GUIDE.md # **Post-generation modification guide**
Multi-Page Navigation Structure
All generated sites use a sidebar navigation layout for easy browsing:
┌─────────────────────────────────┐
│ Header / Logo │
├──────────────┬──────────────────┤
│ │ │
│ SIDEBAR NAV │ MAIN CONTENT │
│ │ │
│ • Home │ │
│ • Arch │ Current Page │
│ • Features │ (HTML Content) │
│ • Quick Start│ │
│ • Demo │ │
│ │ │
└──────────────┴──────────────────┘
Mobile: Sidebar collapses to hamburger menu
Page Templates by Design Style
Note: All designs use the same multi-page sidebar navigation structure. The difference is in colors, spacing, animations, and visual hierarchy. The sidebar markup is shared; design changes come through CSS variables.
Modern Minimal - Example Structure
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{Project Name}</title>
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/style.css">
</head>
<body>
<div class="page-wrapper">
<aside class="sidebar">
<div class="sidebar-header">
<a href="index.html" class="logo">{Project Name}</a>
</div>
< =>
Home
Architecture
Features
Quick Start
Demo
GitHub →
☰
{Page Title}
{Section Title}
{Content}
Key Features
{Feature 1}
{Feature 2}
{Feature 3}
Architecture
{Architecture overview}
{Mermaid diagram}
Getting Started
{Installation steps}
Impact Metrics
{Metric 1}
{Label 1}
{Year}. View on GitHub
Portfolio Heavy - Example Structure
<section id="hero" class="hero-gradient">
<div class="hero-content">
<h1 class="hero-title">{Project Name}</h1>
<p class="hero-subtitle">{Compelling tagline}</p>
<div class="hero-cta">
<a href="#features" class="btn btn-primary">Explore</a>
<a href="https://github.com/{repo}" class="btn btn-secondary">GitHub</a>
</div>
</div>
<div class="hero-visual">
{Screenshot or demo video}
</div>
</section>
<section id="impact" class=>
Impact
{Number}
{Achievement}
Features
Feature Name
Description
Architecture
{Mermaid diagrams}
{Technical explanation}
Documentation Style - Example Structure
<div class="doc-container">
<aside class="sidebar">
<nav class="doc-nav">
<h3>Navigation</h3>
<ul>
<li><a href="#overview">Overview</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#usage">Usage</a>
<ul>
<li><a href="#api">API Reference</a></li>
<li><a href="#examples">Examples</>
Architecture
Contributing
{Project Name}
{Overview paragraph}
Installation
{Installation command}
Usage
Architecture
{Diagrams and explanations}
Content Sections Generated
Based on user preferences and detected project type, generate:
Standard for All
- Homepage: Project intro, value proposition, quick stats, CTA
- Architecture: Tech stack, design decisions, system diagram
- Quick Start: Installation, first example, "hello world"
Conditional by Type
Python/ML/Computer Vision:
- Model Architecture section
- Results/Metrics gallery
- Demo/Inference guide
- Training pipeline overview
.NET/C#:
- Design Patterns Used (DDD, CQRS, etc.)
- Enterprise Features (security, scalability, monitoring)
- Deployment Guide (Azure, Docker, etc.)
- Performance Benchmarks
TypeScript/Node.js:
- API Reference (auto-generated from docs)
- Performance Metrics and benchmarks
- Integration Guide
- Example Projects or code samples
Full-Stack Web Apps:
- Feature Walkthrough with screenshots
- Architecture Diagram (frontend/backend/DB)
- Demo or Screenshots gallery
- Deployment Instructions
Styling by Design Choice
Modern Minimal CSS Variables
:root {
--color-bg: #ffffff;
--color-text: #1a1a1a;
--color-border: #e0e0e0;
--color-accent: #0066cc;
--color-accent-light: #f0f7ff;
--font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
--font-mono: "Courier New", monospace;
--spacing-xs: 0.5rem;
--spacing-sm: 1rem;
--spacing-md: 1.5rem;
--spacing-lg: 2rem;
--spacing-xl: 3rem;
--max-width: 900px;
--border-radius: 4px;
--transition: 0.2s ease;
}
body {
font-family: var(--font-sans);
line-height: 1.6;
color: var(--color-text);
background: var(--color-bg);
margin: 0;
padding: 0;
}
.page-wrapper {
display: grid;
grid-template-columns: 250px fr;
: ;
: ;
}
{
: (--color-bg);
: solid (--color-border);
: (--spacing-lg);
: sticky;
: ;
: ;
: auto;
}
{
: (--spacing-lg);
}
{
: block;
: ;
: ;
: none;
: (--color-text);
}
{
: flex;
: column;
: (--spacing-sm);
}
{
: block;
: (--spacing-sm) (--spacing-md);
: none;
: (--color-text);
: (--border-radius);
: (--transition);
}
{
: (--color-accent-light);
: (--color-accent);
}
{
: (--spacing-lg);
: auto;
}
{
: (--spacing-xl);
: flex;
: center;
: (--spacing-md);
}
{
: none;
: none;
: none;
: ;
: pointer;
}
{
: ;
: auto;
}
{
: (--spacing-xl);
: (--spacing-xl);
: solid (--color-border);
}
, , {
: ;
: (--spacing-lg);
: (--spacing-md);
}
{
: (--color-accent-light);
: ;
: (--border-radius);
: (--font-mono);
: ;
}
pre {
: (--color-accent-light);
: (--spacing-md);
: (--border-radius);
: auto;
: (--font-mono);
}
{
: inline-block;
: (--spacing-sm) (--spacing-md);
: none;
: (--border-radius);
: (--transition);
}
{
: (--color-accent);
: white;
}
{
: ;
}
(: ) {
{
: fr;
}
{
: fixed;
: ;
: ;
: ;
: ;
: ;
: (-);
: transform (--transition);
}
{
: ();
}
{
: block;
}
{
: (--spacing-md);
}
}
Portfolio Heavy CSS
:root {
--gradient-primary: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
--shadow-sm: 0 2px 4px rgba(0,0,0,0.1);
--shadow-lg: 0 10px 30px rgba(0,0,0,0.2);
}
.hero-gradient {
background: var(--gradient-primary);
color: white;
padding: 6rem 2rem;
text-align: center;
animation: fadeInDown 0.6s ease;
}
.cards-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 2rem;
}
.card {
background: white;
padding: 2rem;
border-radius: 8px;
box-shadow: var(--shadow-lg);
: transform ease;
}
{
: (-);
: (,,,);
}
fadeInDown {
{
: ;
: (-);
}
{
: ;
: ();
}
}
Documentation Style CSS
.doc-container {
display: grid;
grid-template-columns: 250px 1fr;
gap: 2rem;
max-width: 1400px;
margin: 0 auto;
}
.sidebar {
position: sticky;
top: 20px;
height: fit-content;
border-right: 1px solid #e0e0e0;
padding-right: 2rem;
}
.doc-nav ul {
list-style: none;
padding: 0;
}
.doc-nav a {
display: block;
padding: 0.5rem 0;
color: #666;
text-decoration: none;
border-left: 3px solid transparent;
padding-left: 1rem;
transition: 0.2s;
}
.doc-nav a:hover,
.doc-nav a.active {
color: #0066cc;
border-left-color: #0066cc;
}
{
: ;
}
(: ) {
{
: fr;
}
{
: static;
: none;
: solid ;
: ;
: ;
: ;
}
}
Step 6: Deliverables
Generated Files Structure
Complete deployment package includes:
1. HTML Pages (styled, ready to render)
├── index.html
├── architecture.html
├── features.html (if applicable)
├── quick-start.html
└── demo.html (if applicable)
2. Styling
├── css/variables.css (design system)
├── css/style.css (main styles - 500-1500 lines depending on design)
└── css/responsive.css (mobile optimizations)
3. JavaScript
├── js/main.js (navigation, interactivity)
├── js/diagrams.js (Mermaid initialization)
└── js/theme.js (optional: dark mode)
4. Assets
├── images/screenshots/ (user-provided or extracted)
├── images/diagrams/ (exported architecture diagrams as PNG/SVG)
└── images/assets/ (icons, logos, etc.)
5. Configuration
├── _config.yml (Jekyll config for GitHub Pages)
├── .github/workflows/deploy.yml (auto-deploy workflow)
└── .gitignore
6. Documentation
├── README.md (Deployment instructions)
└── STYLE_GUIDE.md (Design system documentation)
Package Contents
When delivering, provide:
- Complete Site Files - All HTML, CSS, JS, images organized and ready to deploy
- GitHub Pages Repository Structure - Ready to push to GitHub (no additional setup needed)
- GitHub Actions Workflow - Automatic deployment on push to main branch
- Deployment Instructions - Step-by-step guide for enabling GitHub Pages
- Customization Guide - Post-generation modification instructions
- Design System Documentation - Colors, fonts, spacing, variables used
- Asset Inventory - List of images/diagrams needing screenshots or additional content
Included Visual & Interactive Elements
All generated sites include:
- ✅ Embedded Mermaid Diagrams - Architecture, dataflow, system diagrams
- ✅ Screenshot Gallery with Annotations - Feature walkthroughs with labeled images
- ✅ Live Code Snippets with Syntax Highlighting - Installation, usage, examples
- ✅ Embedded Live Demo - Links to working demos, Hugging Face Spaces, or interactive sections
- ✅ Metrics Dashboard - Performance stats, benchmarks, usage metrics (styled cards/grid)
- ✅ Link to Original GitHub Repository - Prominent "View on GitHub" link throughout
- ✅ Installation/Quick-Start Section - Installation methods, first example, common usage patterns
Quality Checklist
Before delivery:
Responsive Design Guidelines
All generated sites must be mobile-responsive:
@media (max-width: 768px) {
main { max-width: 100%; }
nav { display: block; }
.grid { grid-template-columns: 1fr; }
h1 { font-size: 1.5rem; }
}
@media (max-width: 480px) {
padding: 1rem;
font-size: 0.95rem;
}
Diagram Generation
For architecture diagrams, generate Mermaid code and provide:
- Embedded Mermaid - Direct in HTML with CDN
- PNG Export - For offline viewing or embedding
- Source Code - User can edit/regenerate later
Example embedded:
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({ startOnLoad: true, theme: 'default' });
</script>
<div class="mermaid">
graph TB
Client[Client] --> API[API Gateway]
API --> Service[Service]
Service --> DB[(Database)]
</div>
Deployment Instructions
Generate clear deployment guide:
# Deployment Guide
## Option 1: GitHub Pages (Recommended)
1. Create a new repository: `{username}.github.io` or `{project}-portfolio`
2. Copy all files from `dist/` to repository root
3. Commit and push: `git push origin main`
4. Site will be live at: `https://{username}.github.io`
## Option 2: Custom Domain
1. Add `CNAME` file with your domain
2. Configure DNS records to point to GitHub Pages
3. Update repository settings → Pages → Custom domain
## Option 3: Deploy with GitHub Actions
1. Workflow file included in `.github/workflows/deploy.yml`
2. Push to trigger automatic deployment
3. Check Actions tab for build status
Examples & Templates
For each design style, keep 1-2 quick reference examples:
Modern Minimal: Simple, fast, scannable. Good for: libraries, CLIs, technical projects
Portfolio Heavy: Rich visuals, showcase-focused. Good for: apps you built, full-stack projects
Documentation: Official docs vibe. Good for: tools, frameworks, complex systems
Tips for Best Results
- Provide repo access: Cloning allows extraction of more context
- Include metrics: Performance numbers, download stats, adoption metrics
- Supply screenshots: Visual assets make huge difference (5-10 good screenshots)
- Describe the "why": Problem statement resonates more than just feature list
- Clarify target audience: Different people care about different aspects
- Mention what's hard: Challenges overcome often more interesting than easy parts
Common Customizations
After generation, users may want to:
- Change colors: Edit
css/variables.css color values
- Add/remove sections: Modify HTML, keep CSS structure
- Add more pages: Duplicate page template, update nav
- Optimize images: Compress and replace files in
images/
- Update content: Edit text directly in HTML
- Change font: Update
--font-sans in CSS variables
Include guidance for each in the customization guide.