Skip to content

customization.md

Latest commit

 

History

History
555 lines (372 loc) · 55.6 KB

customization.md

File metadata and controls

555 lines (372 loc) · 55.6 KB
Raw

🎨 Customization Guide & Parameter Reference

CommitPulse is designed to be fully customizable. Every visual attribute is controllable via a URL parameter, following a clear priority chain:

URL Parameter > Theme Default > System Fallback

📋 Parameter Reference

Parameter Type Required Default Description
user string ✅ Yes — GitHub username to render
theme string No dark Preset theme name (see below)
bg hex No Theme default Background color — without #
accent hex No Theme default Tower & glow color — without #
text hex No Theme default Label & stat text color — without #
radius number No 8 Border corner radius in pixels
border string No — Custom stroke color around the main SVG container — without #
speed string No 8s Radar scan duration (2s–20s, default 8s)
scale string No linear Tower height scaling: linear, log (logarithmic), or sqrt (square root)
size string No medium Badge dimensions: small (400×280), medium (600×420), large (800×560)
font string No CommitPulse default typography Any Google Font name (e.g. Orbitron, Inter)
refresh boolean No false Bypass cache for real-time data
year string No — Calendar year to render (e.g. 2023, 2024)
days number No — Number of days of contribution history to fetch and render. Accepts a positive integer up to 365 (e.g. days=90).
from string No — Start date for the contribution query in ISO 8601 format (e.g. 2023-01-01). Must be less than or equal to to date.
to string No — End date for the contribution query in ISO 8601 format (e.g. 2023-12-31). Must be greater than or equal to from date.
hide_title boolean No false Hide GitHub username/title from the SVG badge
custom_title string No — Render a custom title instead of username/title
custom_subtitle string No — Render a custom subtitle right below the title
hide_background boolean No false Remove the background rect, letting the monolith float on the page
hide_stats boolean No false Hides the bottom row displaying Current Streak, Annual Sync Total, and Peak Streak stats when set to true or 1.
tz string No Omitted = UTC IANA timezone (e.g. Asia/Kolkata, America/New_York) — aligns "today" with the user local midnight. Note: ?tz=UTC is valid but cached separately from omitting tz.
lang string No en Language code for labels (en, es, hi, fr, pt, ko, ja, de, zh)
view string No default Rendering mode: default (3D Monolith), monthly (Compact monthly stats), heatmap (flat 2D heatmap), pulse (heartbeat pulse), skyline (city skyline), languages (top languages skyline), constellation (celestial star-map), weekday (contribution totals grouped by day of week), radar (5-axis skill radar chart), doughnut (weekday vs weekend doughnut chart), pie (weekday vs weekend pie chart), activity_graph (30-day activity sparkline), or commit_clock (24-hour polar chart of peak coding hours)
entrance string No rise Entrance animation for towers: rise (default), fade, slide, or none.
disable_particles boolean No false Disable floating heat particle animations on the monolith towers when set to true or 1.
glow boolean No true Enable neon-style glow/blur effects for the towers. Accepts true/1 (enable) or false/0 (disable).
delta_format string No percent Format for month-over-month delta in monthly view: percent (e.g. +12%), absolute (e.g. +15 commits), or both
width number No 300 Custom width for the SVG canvas (applies to view=monthly, pulse, skyline)
height number No 120 Custom height for the SVG canvas (applies to view=monthly, pulse, skyline)
grace number No 1 Grace period in days before a streak resets (0–7). grace=0 = strict mode (no missed days), grace=2 = lenient (forgives up to 2 missed days). Default is 1.
mode string No commits Rendering mode: commits (default) or loc (Lines of Code landscape)
repo string No — Render the monolith for a specific repository (e.g. owner/repo) instead of the whole profile
org string No — Organization name to generate a Mega-City for
labels boolean No false Render optional 3D isometric month headers and weekday labels
labelColor hex No — Custom text color for the isometric labels — without #
versus string No — GitHub username of an opponent to compare against in side-by-side versus mode
shading boolean No false Apply intensity-based opacity shading to tower faces so lower intensity levels appear slightly dimmer
dim_weekends boolean No false Dim towers representing weekend commits (Saturdays and Sundays) to opacity: 0.3 to highlight weekday schedules
opacity number No 1.0 Global opacity scalar for all tower fill-opacity values (0.1–1.0). opacity=0.5 = semi-transparent ghost look. opacity=0.8 = faded, great on light backgrounds.
gradient boolean No false Opt-in to show volumetric gradients on the monolith floor
gradient_stops string No — Comma-separated list of hex colors (e.g. ff6b35,ff007f) for custom floor gradient. Requires gradient=true and at least two valid colors. Hex prefix # is optional.
gradient_dir string No vertical Direction of the volumetric floor gradient: vertical (default), horizontal, or diagonal.
minify boolean No true Enable lightweight SVG minification to reduce payload size by 15–30%. Accepts true/1 (enable) or false/0 (disable).

All parameters below are optional except user. Append them to the base URL as query string key-value pairs (e.g. ?user=YOUR_USERNAME&theme=neon&size=large). Boolean parameters accept true or false. Hex color values are provided without the # prefix.

Parameter Description Default Allowed Values / Constraints Example
user GitHub username to render (Required) — Any valid GitHub username ?user=jhasourav07
theme Preset theme name dark auto, dark, neon, dracula, github, light, gruvbox, random, etc. ?theme=dracula
bg Background color Theme default Hex color code (without #) ?bg=0d1117
accent Tower & glow color Theme default Hex color code (without #) ?accent=58a6ff
text Label & stat text color Theme default Hex color code (without #) ?text=c9d1d9
radius Border corner radius in pixels 8 Numeric value ?radius=16
border Custom stroke color around the SVG container — Hex color code (without #) ?border=ff0000
speed Radar scan duration 8s 2s–20s ?speed=4s
scale Tower height scaling linear linear, log, sqrt ?scale=sqrt
size Badge dimensions medium small, medium, large ?size=large
font Custom font for text Default typography Any valid Google Font name ?font=Orbitron
refresh Bypass cache for real-time data false true, false ?refresh=true
year Calendar year to render Current year 2023, 2024, etc. ?year=2023
hide_title Hide GitHub username/title false true, false ?hide_title=true
custom_title Custom header title text — Any text string (XML-escaped) ?custom_title=My%20Pulse
custom_subtitle Custom subtitle text right below title — Any text string (XML-escaped) ?custom_subtitle=Dev
hide_background Remove the background rect false true, false ?hide_background=true
hide_stats Hide bottom row displaying stats false true, false ?hide_stats=true
tz IANA timezone UTC Valid IANA timezone ?tz=Asia/Kolkata
lang Language code for labels en en, es, hi, fr, pt, ko, ja, de, zh ?lang=hi
view Rendering mode default default, monthly, heatmap, pulse, skyline, languages, constellation, weekday, radar, doughnut, pie, activity_graph, commit_clock ?view=commit_clock
entrance Entrance animation for towers rise rise, fade, slide, none ?entrance=fade
delta_format Month-over-month delta format (view=monthly) percent percent, absolute, both ?delta_format=absolute
width Custom width for SVG canvas (view=monthly, pulse, skyline) 300 Numeric value ?width=400
height Custom height for SVG canvas (view=monthly, pulse, skyline) 120 Numeric value ?height=150
grace Grace period in days before streak resets (see Grace Period Examples) 1 0–7 ?grace=2
mode Base data rendering mode commits commits, loc ?mode=loc
repo Render monolith for a specific repository — owner/repo ?repo=vercel/next.js
org Organization name to generate a Mega-City for — Valid GitHub organization name ?org=vercel
labels Render optional isometric month/weekday labels false true, false ?labels=true
labelColor Custom text color for isometric labels — Hex color code (without #) ?labelColor=ffffff
versus Compare against an opponent side-by-side — Any valid GitHub username ?versus=octocat
shading Apply intensity-based opacity shading to tower faces false true, false ?shading=true
dim_weekends Dim weekend towers (Saturdays and Sundays) false true, false ?dim_weekends=true
opacity Global opacity scalar for tower fill 1.0 0.1–1.0 ?opacity=0.8
gradient Show volumetric gradients on the floor false true, false ?gradient=true
minify Enable SVG minification and payload optimization true true, false ?minify=false

⚡ Grace Period Examples

<!-- Strict mode — streak resets on any single missed day -->

![CommitPulse](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&grace=0)

<!-- Default — one day grace period (current behavior) -->

![CommitPulse](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&grace=1)

<!-- Lenient — forgives up to 2 consecutive missed days -->

![CommitPulse](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&grace=2)

🎨 Theme Presets

Theme Preview bg accent text
auto System light / dark adapts adapts adapts
dark (default) GitHub dark 0d1117 58a6ff c9d1d9
neon Cyberpunk 000000 ff00ff 00ffcc
dracula Dracula Pro 282a36 bd93f9 f8f8f2
github GitHub green 0d1117 39d353 ffffff
light Clean & minimal ffffff 0969da 24292f
gruvbox Retro warm dark 282828 fe8019 ebdbb2
random Surprise theme on reload varies varies varies
highcontrast Accessibility high contrast 0a0a0a ff4500 ffffff
cyber-pulse AMOLED true-black & cyan 000000 00ffee ffffff
retro-terminal Classic CRT terminal 000000 00ff41 00ff41
obsidian Deep charcoal & amber gold 1a1a2e f59e0b e2e8f0
glacier Icy sky blue & cyan e0f2fe 06b6d4 0369a1
lumos Void black & mint gold 0a0a0a fbbf24 a7f3d0

auto uses CSS @media (prefers-color-scheme) inside the SVG so the badge switches between the light and dark palettes based on the viewer's OS setting — no JavaScript required. This is ideal for GitHub profile READMEs where visitors may use either mode.

🎨 Theme Preview Gallery

Explore some of the built-in CommitPulse themes and quickly copy the style you like.

Theme Usage Example
Dark ?theme=dark
Neon ?theme=neon
Dracula ?theme=dracula
Gruvbox ?theme=gruvbox
GitHub ?theme=github

Examples

<!-- Auto theme — adapts to the viewer's light/dark system preference -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=auto)

<!-- The Dracula aesthetic -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=dracula)

<!-- Space-age typography with Orbitron -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&font=Orbitron)

<!-- Fully custom — hot orange on void black -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&bg=080808&accent=ff4500&text=eeeeee&radius=16)

<!-- Force bypass cache for latest data -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&refresh=true)

<!-- Fast scan + logarithmic scaling for power users -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&speed=4s&scale=log)

<!-- View contributions for a specific past year -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&year=2023)

<!-- Compact Monthly Stats View -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&view=monthly)

<!-- Monthly View with Absolute Delta and Custom Dimensions -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&view=monthly&delta_format=absolute&width=400&height=150)

<!-- Hide GitHub username/title -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&hide_title=true)

<!-- Hide bottom statistics row -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&hide_stats=true)

<!-- Use local timezone instead of UTC -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&tz=Asia/Kolkata)

<!-- Strict streak — resets on any single missed day -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&grace=0)

<!-- Lenient streak — forgives up to 2 missed days -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&grace=2)

<!-- Render labels in Hindi -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&lang=hi)

<!-- Render labels in Simplified Chinese -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&lang=zh)

<!-- Large badge size -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&size=large)

<!-- Side-by-side versus comparison -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&versus=octocat)

<!-- Lines of Code landscape mode -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&mode=loc)

<!-- Gradient + shading for extra depth -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&gradient=true&shading=true)

<!-- Semi-transparent ghost city look -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&opacity=0.5)

<!-- Slightly faded — perfect for light background embeds -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&opacity=0.8)

<!-- GitHub-style Heatmap View -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&view=heatmap)

<!-- Heatmap with Neon theme -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&view=heatmap&theme=neon)

<!-- Weekday breakdown — contributions grouped by day of week -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&view=weekday)

<!-- Weekday breakdown with Dracula theme -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&view=weekday&theme=dracula)

🚀 Advanced Usage Examples

🎨 Custom Gradient Backgrounds

Create stunning visual effects with custom gradient backgrounds using the gradient, gradient_stops, and gradient_dir parameters.

<!-- Vertical gradient with sunset colors -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&gradient=true&gradient_stops=ff6b35,ff007f,7b2cbf&gradient_dir=vertical)

<!-- Horizontal gradient with ocean tones -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&gradient=true&gradient_stops=0077b6,00b4d8,90e0ef&gradient_dir=horizontal)

<!-- Diagonal gradient with neon cyberpunk colors -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&gradient=true&gradient_stops=ff00ff,00ffff,ff0080&gradient_dir=diagonal)

<!-- Custom gradient with specific theme -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=dark&gradient=true&gradient_stops=1a1a2e,16213e,0f3460&gradient_dir=vertical)

Parameters:

  • gradient=true - Enable volumetric gradients on the monolith floor
  • gradient_stops - Comma-separated hex colors (without #) for the gradient
  • gradient_dir - Direction: vertical, horizontal, or diagonal

👥 Multi-User Comparison

Compare contribution patterns between multiple users or team members using comma-separated usernames.

<!-- Compare two users side-by-side -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07,octocat)

<!-- Team comparison with custom theme -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07,octocat&theme=neon)

<!-- Small team comparison (up to 7 users) -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07,octocat,torvalds,gaearon&size=large)

<!-- Multi-user with skyline view -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07,octocat&view=skyline)

<!-- Versus mode for direct comparison -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&versus=octocat)

<!-- Versus comparison with custom styling -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&versus=octocat&theme=dracula&size=large)

Parameters:

  • user=user1,user2 - Comma-separated usernames for multi-user views
  • versus=username - Direct side-by-side comparison mode
  • view=skyline - City skyline visualization for multiple users

🏢 Organization Dashboards

Generate comprehensive organization-wide contribution dashboards using the org parameter.

<!-- Organization mega-city dashboard -->

![](https://commitpulse.vercel.app/api/streak?org=vercel)

<!-- Organization with custom theme -->

![](https://commitpulse.vercel.app/api/streak?org=vercel&theme=github)

<!-- Organization dashboard with labels -->

![](https://commitpulse.vercel.app/api/streak?org=vercel&labels=true&labelColor=ffffff)

<!-- Large organization view -->

![](https://commitpulse.vercel.app/api/streak?org=vercel&size=large&hide_title=false)

<!-- Organization with custom dimensions -->

![](https://commitpulse.vercel.app/api/streak?org=vercel&width=800&height=600)

<!-- Organization monthly stats -->

![](https://commitpulse.vercel.app/api/streak?org=vercel&view=monthly)

Parameters:

  • org=organization-name - Generate mega-city dashboard for an organization
  • labels=true - Show isometric month and weekday labels
  • labelColor - Custom color for labels (hex without #)

📅 Custom Date Ranges

Analyze contributions for specific time periods using from, to, start_date, end_date, or year parameters.

<!-- Specific year analysis -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&year=2023)

<!-- Custom date range (ISO 8601 format) -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&from=2023-01-01&to=2023-12-31)

<!-- First quarter of 2024 -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&from=2024-01-01&to=2024-03-31)

<!-- Recent 90 days using days parameter -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&days=90)

<!-- Last 30 days with custom styling -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&days=30&theme=neon)

<!-- Historical comparison: same period last year -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&from=2023-06-01&to=2023-08-31)

<!-- Custom date range with monthly view -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&from=2024-01-01&to=2024-06-30&view=monthly)

<!-- Date range with custom subtitle -->

![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&start_date=2024-01-01&end_date=2024-06-30&custom_subtitle=Q1%20%26%20Q2%202024)

Parameters:

  • year=YYYY - Full calendar year
  • from=YYYY-MM-DD - Start date (ISO 8601 format)
  • to=YYYY-MM-DD - End date (ISO 8601 format)
  • start_date=YYYY-MM-DD - Alternative start date parameter
  • end_date=YYYY-MM-DD - Alternative end date parameter
  • days=N - Last N days of contributions (1-365)

Important Notes:

  • Date ranges must be in ISO 8601 format (YYYY-MM-DD)
  • from date must be less than or equal to to date
  • days parameter takes precedence over date ranges when both are specified
  • Historical data is limited to GitHub's availability (founded in 2008)

💡 Pro Tips for Advanced Usage

  1. Combine Parameters: Mix and match parameters for unique effects

    ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=neon&gradient=true&gradient_stops=ff00ff,00ffff&from=2024-01-01&to=2024-06-30)

  2. Performance Optimization: Use refresh=true sparingly as it bypasses cache

    ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&refresh=true)

  3. Accessibility: Use high-contrast themes for better readability

    ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=highcontrast)

  4. Embedding: Adjust opacity for seamless integration with different backgrounds

    ![](https://commitpulse.vercel.app/api/streak?user=jhasourav07&opacity=0.8)

❓ Troubleshooting & FAQ

Below are solutions to common issues and questions when embedding CommitPulse SVGs into GitHub Profile READMEs or web pages.

🔄 GitHub Camo Proxy & Caching Issues

Why are my latest contributions or updated stats not showing on my GitHub Profile README?

GitHub routes all external images in profile READMEs through an anonymizing proxy called Camo (camo.githubusercontent.com). GitHub Camo aggressively caches image assets to ensure fast page loads and user privacy.

  • Cache TTL: GitHub's Camo proxy caches images for several hours (typically up to 24 hours).
  • Bypassing the Proxy Cache:
    • CommitPulse Cache Invalidation: Add &refresh=true to your URL parameter list to bypass CommitPulse's internal cache: 
      ![](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&refresh=true)
    • GitHub Camo Invalidation: If GitHub Camo continues to serve a cached image after using refresh=true, append a version or cache-buster query parameter to force Camo to treat it as a new URL: 
      ![](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&v=2)
  • Daily Invalidation: CommitPulse automatically invalidates stored data at UTC midnight to align with GitHub's daily contribution cycles.

📐 Layout, Alignment & Responsiveness

How do I center the CommitPulse SVG badge in my profile README?

Standard Markdown image syntax ![]() does not support alignment attributes. Use HTML alignment elements like <p align="center"> or <div align="center">:

<p align="center">
  <img
    src="https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=neon"
    alt="CommitPulse Monolith"
  />
</p>

How can I prevent the SVG badge from overflowing on smaller or mobile screens?

Set explicit percentage widths and CSS responsive styling using an HTML <img> tag inside your Markdown:

<p align="center">
  <img
    src="https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=dracula"
    alt="CommitPulse Stats"
    width="100%"
    max-width="600"
  />
</p>

How do I place CommitPulse side-by-side with other profile stats badges?

Use an HTML <table> layout or place image tags within the same paragraph block:

<p align="center">
  <img
    src="https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=dark&size=small"
    width="48%"
  />
  <img
    src="https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&theme=dark"
    width="48%"
  />
</p>

🔍 Parameter Syntax & Troubleshooting Checklist

If your monolith falls back to default dark styling or displays missing parameters, run through this quick verification checklist:

  1. Hex Colors (No # Prefix):

    • ❌ ?bg=#0d1117&accent=#58a6ff (The # symbol acts as an anchor fragment in URLs and breaks query parameters)
    • ✅ ?bg=0d1117&accent=58a6ff

  2. Mandatory user Parameter:

    • ❌ https://commitpulse.vercel.app/api/streak?theme=neon
    • ✅ https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME&theme=neon

  3. Boolean Values:

    • Boolean parameters accept true / false or 1 / 0.
    • ✅ hide_stats=true, gradient=1, labels=true, shading=true

  4. URL-Encoding Special Characters & Custom Fonts:

    • Google Font names with spaces or special characters must be URL-encoded.
    • ❌ ?font=Press Start 2P&custom_title=My Stats
    • ✅ ?font=Press%20Start%202P&custom_subtitle=Dev%20Dashboard

  5. Parameter Spelling Check:

    • Ensure parameter names match exact keys listed in the Parameter Reference table (e.g. dim_weekends, hide_background, delta_format).