GitHub City Skyline

Transform your GitHub contribution graph into a stunning 3D isometric city skyline! This project generates an SVG illustration based on your commit history, with support for multiple dynamic themes.

Features

• 3D Isometric Projection: Turns flat 2D contribution squares into volumetric 3D buildings.
• Dynamic Themes: - github: The classic green block style with a clean, bright look.
  • cityNight: A dark cyberpunk aesthetic with randomly lit, breathing neon windows.
• Fully Automated: Designed to run seamlessly via GitHub Actions, updating your skyline daily without manual intervention.

Demo

Default

White

CityNight

Cyberpunk

Quick Start (Automated via GitHub Actions)

Want to show this on your GitHub Profile? You don't need to fork this repository or configure any complex environments. Just add a workflow file to your own repository (such as your personal Profile README repository) to call this action.

1. In your repository, create a new file at .github/workflows/generate-city.yml.
2. Copy and paste the following code into the file:

name: Generate 3D City

on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Generate City Skyline
        uses: Haruko386-UnOffical/github-city@main
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          theme: github 

      - name: Commit and Push
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -f city.svg
          git commit -m "chore: update 3D city skyline" || exit 0
          git push

3. Commit and push the file to your repository.
4. Go to your repository's Settings -> Actions -> General.
5. Scroll down to Workflow permissions, select Read and write permissions, and save.
6. Go to the Actions tab, select the Generate 3D City workflow, and click Run workflow to generate your first image.

A city.svg file will be generated in the root of your repository. You can now link this image in your README.md using:

![City Skyline](./github.svg)

Note: The GitHub Action is scheduled to run automatically every day at 00:00 UTC.

Local Development

If you want to create your own themes or modify the rendering logic, you can run this project locally.

Prerequisites

• Node.js (v18 or higher recommended)
• A GitHub Personal Access Token (PAT) with read:user access.

Installation

1. Clone the repository:

   git clone https://github.com/Haruko386-UnOffical/github-city.git
   cd github-city

2. Install dependencies:

   npm install

3. Configure Environment Variables: Rename .env.example to .env and fill in your details:

   GITHUB_TOKEN=your_personal_access_token_here
   GITHUB_USERNAME=your_github_username

4. Run the generator:

   # Generate with the default classic theme
   node index.js
   
   # Or specify a theme via environment variables
   # Windows PowerShell:
   $env:THEME="github"; node index.js
   
   # Linux/macOS:
   THEME=github node index.js

Themes Configuration

Themes are located in src/themes/. You can easily create a new theme by exporting an object with the following structure:

export default {
    name: "myCustomTheme",
    defs: "", // Optional SVG definitions (like gradients)
    backgroundFill: "#ffffff", // Background color or gradient reference
    
    // Functions determining face colors based on daily contribution count
    top: (contribution) => { ... },
    left: (contribution) => { ... },
    right: (contribution) => { ... },
    
    // Optional: Enables 3D mapped windows on buildings
    windowColor: (contribution) => { ... } 
}

License

MIT License. Feel free to use and modify!