Skip to content

Profile Viewer

The Profile Viewer is a web application that visualizes GitHub contribution statistics generated by the gogithub profile command.

Features

Feature Description
Stats Card Embeddable SVG showing commits, PRs, issues, reviews, code changes
Contribution Calendar GitHub-style green heatmap with daily tooltips
Monthly Charts Bar and line charts for activity trends
Top Repositories Sortable table by commits or code changes
Dark Mode Automatic theme switching with manual toggle
Export Download stats card as SVG or PNG

Usage Options

There are two ways to use the Profile Viewer:

Option 1: Interactive Mode

Visit the hosted viewer, drag and drop your JSON file, and view your stats instantly.

  1. Generate your profile data:

    gogithub profile --user YOUR_USERNAME --output-raw profile.json

  2. Open the Profile Viewer in your browser

  3. Drag and drop profile.json (or click to select)

  4. View your visualizations

No data is uploaded

The viewer runs entirely in your browser. Your data never leaves your machine.

Option 2: Personal Static Site

Host your own profile page at https://YOUR_USERNAME.github.io/profile with automatic weekly updates.

See Deploying Your Own Profile Site below.

Visualizations

Stats Card

The stats card displays key metrics in an embeddable SVG format:

  • Total commits (GitHub official count)
  • Pull requests opened
  • Issues opened
  • Code reviews completed
  • Lines added / deleted
  • Longest contribution streak

Download as SVG for embedding in documentation or PNG for sharing.

Contribution Calendar

A GitHub-style heatmap showing daily contribution intensity:

Level Contributions Color
0 0 Gray
1 1-3 Light green
2 4-6 Medium green
3 7-9 Dark green
4 10+ Darkest green

Hover over any day to see the exact count and date.

Monthly Activity Charts

Two chart views are available:

Activity Chart (stacked bar):

  • Commits per month
  • Pull requests per month
  • Issues per month
  • Reviews per month

Code Changes Chart (line):

  • Lines added over time
  • Lines deleted over time

Top Repositories

A sortable table showing your most active repositories:

Column Description
Repository Full name (owner/repo)
Commits Number of commits
Additions Lines added (green)
Deletions Lines removed (red)

Click any column header to sort.

Deploying Your Own Profile Site

Create a personal profile page that automatically updates weekly.

Quick Start

# 1. Create repository from template
gh repo create profile \
    --template grokify/gogithub-profile-template \
    --public \
    --clone
cd profile

# 2. Generate your profile data
export GITHUB_TOKEN=your_token
gogithub profile --user YOUR_USERNAME --output-raw data.json

# 3. Commit and push
git add data.json
git commit -m "Add profile data"
git push

# 4. Enable GitHub Pages
# Go to Settings → Pages → Source: GitHub Actions

Your profile will be live at https://YOUR_USERNAME.github.io/profile

Automatic Updates

The template includes a GitHub Action that updates your profile weekly:

  • Runs every Sunday at midnight UTC
  • Fetches fresh data using gogithub profile
  • Commits and pushes if data changed
  • Triggers a new deployment

To customize the schedule, edit .github/workflows/update-profile.yml:

schedule:
  # Weekly (default)
  - cron: '0 0 * * 0'

  # Daily
  # - cron: '0 0 * * *'

  # Monthly
  # - cron: '0 0 1 * *'

Manual Updates

Trigger an update anytime:

  1. Go to Actions → Update Profile Data
  2. Click Run workflow

Or update locally:

gogithub profile --user YOUR_USERNAME --output-raw data.json
git add data.json
git commit -m "Update profile data"
git push

Token Permissions

The default GITHUB_TOKEN has read access to public data only.

For private repository statistics:

  1. Create a Personal Access Token with repo scope
  2. Add it as a repository secret named PAT_TOKEN

  3. Update the workflow to use the new secret:

    env:
  GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }}

Customization

Styling

Edit src/styles/main.css to customize:

  • Colors via CSS variables
  • Layout and spacing
  • Typography
  • Chart appearance

Key CSS variables:

:root {
  --bg-primary: #ffffff;
  --text-primary: #24292f;
  --accent-color: #0969da;
  --contrib-4: #216e39;  /* Darkest contribution green */
}

[data-theme="dark"] {
  --bg-primary: #0d1117;
  --text-primary: #c9d1d9;
  --accent-color: #58a6ff;
  --contrib-4: #39d353;
}

Repository Name

The default template suggests profile for a clean URL. Alternatives:

Repo Name URL
profile username.github.io/profile
github-stats username.github.io/github-stats
USERNAME.github.io username.github.io (root)

Local Development

The viewer source code lives in two places:

Location Purpose
gogithub/web/ Development source (in main repo)
gogithub-profile-template User-facing template repo

To modify the viewer locally:

# From gogithub repo
cd web/

# Install dependencies
npm install

# Start dev server
npm run dev

# Build for production
npm run build

The dev server runs at http://localhost:5173 with hot reload.

Tech Stack

Component Technology
Build Vite
Language TypeScript
Charts Chart.js
Stats Card Pure SVG
Calendar Pure SVG
Styling CSS Variables

Data Format

The viewer accepts JSON from gogithub profile --output-raw:

{
  "username": "grokify",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-12-31T23:59:59Z",
  "total_commits": 847,
  "total_prs": 128,
  "total_issues": 52,
  "total_reviews": 215,
  "total_additions": 156482,
  "total_deletions": 78241,
  "repos": [...],
  "monthly": [...],
  "calendar": {
    "total_contributions": 1242,
    "weeks": [...]
  }
}

See CLI: profile for complete output format documentation.