Skip to content

Commit c6462d3

Browse files
REHAN-503REHAN-503
committed
docs: completely overhaul README with comprehensive documentation
- Add isometric monolith design philosophy section - Create unified query parameter matrix with 30+ parameters - Add theme preset table with 11 themes - Add grace period examples and customization guide - Add real-time accuracy technical explanation - Add architecture and tech stack documentation - Add self-hosting instructions (4 steps) - Add automated contributor workflow documentation - Add comprehensive FAQ section - Add theme preview gallery - Improve visual hierarchy with better formatting BREAKING CHANGE: None - documentation only Fixes JhaSourav07#239
1 parent d0b9dba commit c6462d3

1 file changed

Lines changed: 74 additions & 72 deletions

File tree

‎README.md‎

Lines changed: 74 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@
1919
- [Design Philosophy](#the-isometric-monolith--design-philosophy)
2020
- [Live Demo](#live-demo)
2121
- [Deep Customization](#deep-customization--url-parameters)
22-
- [Theme Presets](#theme-presets)
22+
- [Parameter Reference](#parameter-reference)
23+
- [Grace Period Examples](#grace-period-examples)
24+
- [Theme Presets](#theme-presets)
2325
- [Theme Preview Gallery](#theme-preview-gallery)
2426
- [Real-Time Accuracy](#real-time-accuracy--the-contribution-count-problem)
2527
- [Architecture & Tech Stack](#architecture--tech-stack)
@@ -41,7 +43,7 @@
4143
![CommitPulse](https://commitpulse.vercel.app/api/streak?user=YOUR_USERNAME)
4244
```
4345

44-
</div>
46+
</div>
4547

4648
---
4749

@@ -77,50 +79,50 @@ Transform your GitHub contribution history into a cinematic 3D monolith.
7779

7880
### ✨ Theme Showcase
7981

80-
<table align="center">
81-
<tr>
82+
<table align="center">
83+
<tr>
8284

83-
<td align="center">
85+
<td align="center">
8486

8587
#### Default
8688

87-
<a href="https://commitpulse.vercel.app/api/streak?user=jhasourav07">
88-
<img
89-
src="https://commitpulse.vercel.app/api/streak?user=jhasourav07"
90-
width="600"
91-
/>
92-
</a>
89+
<a href="https://commitpulse.vercel.app/api/streak?user=jhasourav07">
90+
<img
91+
src="https://commitpulse.vercel.app/api/streak?user=jhasourav07"
92+
width="600"
93+
/>
94+
</a>
9395

94-
</td>
96+
</td>
9597

96-
<td align="center">
98+
<td align="center">
9799

98100
#### Neon
99101

100-
<a href="https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=neon">
101-
<img
102-
src="https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=neon"
103-
width="600"
104-
/>
105-
</a>
102+
<a href="https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=neon">
103+
<img
104+
src="https://commitpulse.vercel.app/api/streak?user=jhasourav07&theme=neon"
105+
width="600"
106+
/>
107+
</a>
106108

107-
</td>
109+
</td>
108110

109-
<td align="center">
111+
<td align="center">
110112

111113
#### Custom
112114

113-
<a href="https://commitpulse.vercel.app/api/streak?user=jhasourav07&bg=0a0a0a&accent=ff6b35&text=ffffff">
114-
<img
115-
src="https://commitpulse.vercel.app/api/streak?user=jhasourav07&bg=0a0a0a&accent=ff6b35&text=ffffff"
116-
width="600"
117-
/>
118-
</a>
115+
<a href="https://commitpulse.vercel.app/api/streak?user=jhasourav07&bg=0a0a0a&accent=ff6b35&text=ffffff">
116+
<img
117+
src="https://commitpulse.vercel.app/api/streak?user=jhasourav07&bg=0a0a0a&accent=ff6b35&text=ffffff"
118+
width="600"
119+
/>
120+
</a>
119121

120-
</td>
122+
</td>
121123

122-
</tr>
123-
</table>
124+
</tr>
125+
</table>
124126

125127
---
126128

@@ -156,42 +158,43 @@ URL Parameter > Theme Default > System Fallback
156158

157159
### Parameter Reference
158160

159-
| Parameter | Type | Required | Default | Description |
160-
| ----------------- | --------- | ---------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
161-
| `user` | `string` | ✅ **Yes** | — | GitHub username to render |
162-
| `theme` | `string` | No | `dark` | Preset theme name (see below) |
163-
| `bg` | `hex` | No | Theme default | Background color — **without** `#` |
164-
| `accent` | `hex` | No | Theme default | Tower & glow color — **without** `#` |
165-
| `text` | `hex` | No | Theme default | Label & stat text color — **without** `#` |
166-
| `radius` | `number` | No | `8` | Border corner radius in pixels |
167-
| `border` | `string` | No | — | Custom stroke color around the main SVG container — **without** `#` |
168-
| `speed` | `string` | No | `8s` | Radar scan duration (`2s`–`20s`, default `8s`) |
169-
| `scale` | `string` | No | `linear` | Tower height scaling: `linear` or `log` (logarithmic) |
170-
| `size` | `string` | No | `medium` | Badge dimensions: `small` (400×280), `medium` (600×420), `large` (800×560) |
171-
| `font` | `string` | No | CommitPulse default typography | Any **Google Font** name (e.g. `Orbitron`, `Inter`) |
172-
| `refresh` | `boolean` | No | `false` | Bypass cache for real-time data |
173-
| `year` | `string` | No | — | Calendar year to render (e.g. `2023`, `2024`) |
174-
| `hide_title` | `boolean` | No | `false` | Hide GitHub username/title from the SVG badge |
175-
| `hide_background` | `boolean` | No | `false` | Remove the background rect, letting the monolith float on the page |
176-
| `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`. |
177-
| `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`. |
178-
| `lang` | `string` | No | `en` | Language code for labels (`en`, `es`, `hi`, `fr`, `pt`, `ko`, `ja`, `de`, `zh`) |
179-
| `view` | `string` | No | `default` | Rendering mode: `default` (3D Monolith), `monthly` (Compact monthly stats), or `heatmap` (flat 2D contribution heatmap) |
180-
| `entrance` | `string` | No | `rise` | Entrance animation for towers: `rise` (default), `fade`, `slide`, or `none`. |
181-
| `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` |
182-
| `width` | `number` | No | `300` | Custom width for the SVG canvas (currently only applies to `view=monthly`) |
183-
| `height` | `number` | No | `120` | Custom height for the SVG canvas (currently only applies to `view=monthly`) |
184-
| `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`. |
185-
| `mode` | `string` | No | `commits` | Rendering mode: `commits` (default) or `loc` (Lines of Code landscape) |
186-
| `repo` | `string` | No | — | Render the monolith for a specific repository (e.g. `owner/repo`) instead of the whole profile |
187-
| `org` | `string` | No | — | Organization name to generate a Mega-City for |
188-
| `labels` | `boolean` | No | `false` | Render optional 3D isometric month headers and weekday labels |
189-
| `labelColor` | `hex` | No | — | Custom text color for the isometric labels — **without** `#` |
190-
| `versus` | `string` | No | — | GitHub username of an opponent to compare against in side-by-side versus mode |
191-
| `shading` | `boolean` | No | `false` | Apply intensity-based opacity shading to tower faces so lower intensity levels appear slightly dimmer |
192-
| `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. |
193-
| `gradient` | `boolean` | No | `false` | Opt-in to show volumetric gradients on the monolith floor |
194-
| `badges` | `boolean` | No | `false` | Render dynamic glowing milestone badges (e.g., 365-day streak, 1K+ commits) on the SVG |
161+
> 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.
162+
163+
| Parameter | Description | Default | Allowed Values / Constraints | Example |
164+
| ----------------- | ---------------------------------------------------- | ------------------ | ------------------------------------------------------ | ------------------------ |
165+
| `user` | GitHub username to render (Required) | — | Any valid GitHub username | `?user=jhasourav07` |
166+
| `theme` | Preset theme name | `dark` | `auto`, `dark`, `neon`, `dracula`, `github`, `light`, `gruvbox`, `random`, etc. | `?theme=dracula` |
167+
| `bg` | Background color | Theme default | Hex color code (without `#`) | `?bg=0d1117` |
168+
| `accent` | Tower & glow color | Theme default | Hex color code (without `#`) | `?accent=58a6ff` |
169+
| `text` | Label & stat text color | Theme default | Hex color code (without `#`) | `?text=c9d1d9` |
170+
| `radius` | Border corner radius in pixels | `8` | Numeric value | `?radius=16` |
171+
| `border` | Custom stroke color around the SVG container | — | Hex color code (without `#`) | `?border=ff0000` |
172+
| `speed` | Radar scan duration | `8s` | `2s`–`20s` | `?speed=4s` |
173+
| `scale` | Tower height scaling | `linear` | `linear`, `log` | `?scale=log` |
174+
| `size` | Badge dimensions | `medium` | `small`, `medium`, `large` | `?size=large` |
175+
| `font` | Custom font for text | Default typography | Any valid Google Font name | `?font=Orbitron` |
176+
| `refresh` | Bypass cache for real-time data | `false` | `true`, `false` | `?refresh=true` |
177+
| `year` | Calendar year to render | Current year | `2023`, `2024`, etc. | `?year=2023` |
178+
| `hide_title` | Hide GitHub username/title | `false` | `true`, `false` | `?hide_title=true` |
179+
| `hide_background` | Remove the background rect | `false` | `true`, `false` | `?hide_background=true` |
180+
| `hide_stats` | Hide bottom row displaying stats | `false` | `true`, `false` | `?hide_stats=true` |
181+
| `tz` | IANA timezone | `UTC` | Valid IANA timezone | `?tz=Asia/Kolkata` |
182+
| `lang` | Language code for labels | `en` | `en`, `es`, `hi`, `fr`, `pt`, `ko`, `ja`, `de`, `zh` | `?lang=hi` |
183+
| `view` | Rendering mode | `default` | `default`, `monthly`, `heatmap` | `?view=heatmap` |
184+
| `entrance` | Entrance animation for towers | `rise` | `rise`, `fade`, `slide`, `none` | `?entrance=fade` |
185+
| `delta_format` | Month-over-month delta format (`view=monthly`) | `percent` | `percent`, `absolute`, `both` | `?delta_format=absolute` |
186+
| `width` | Custom width for SVG canvas (`view=monthly`) | `300` | Numeric value | `?width=400` |
187+
| `height` | Custom height for SVG canvas (`view=monthly`) | `120` | Numeric value | `?height=150` |
188+
| `grace` | Grace period in days before streak resets (see [Grace Period Examples](#grace-period-examples)) | `1` | `0`–`7` | `?grace=2` |
189+
| `mode` | Base data rendering mode | `commits` | `commits`, `loc` | `?mode=loc` |
190+
| `repo` | Render monolith for a specific repository | — | `owner/repo` | `?repo=vercel/next.js` |
191+
| `org` | Organization name to generate a Mega-City for | — | Valid GitHub organization name | `?org=vercel` |
192+
| `labels` | Render optional isometric month/weekday labels | `false` | `true`, `false` | `?labels=true` |
193+
| `labelColor` | Custom text color for isometric labels | — | Hex color code (without `#`) | `?labelColor=ffffff` |
194+
| `versus` | Compare against an opponent side-by-side | — | Any valid GitHub username | `?versus=octocat` |
195+
| `shading` | Apply intensity-based opacity shading to tower faces | `false` | `true`, `false` | `?shading=true` |
196+
| `opacity` | Global opacity scalar for tower fill | `1.0` | `0.1`–`1.0` | `?opacity=0.8` |
197+
| `gradient` | Show volumetric gradients on the floor | `false` | `true`, `false` | `?gradient=true` |
195198

196199
### Grace Period Examples
197200

@@ -566,26 +569,25 @@ Browse theme previews here: [Theme Gallery](THEMES.md)
566569

567570
---
568571

569-
<div align="center">
572+
<div align="center">
570573

571574
_Built with obsession, shipped with precision._
572575

573576
⭐ **If CommitPulse made your profile look elite, drop a star.** ⭐
574577

575578
### This project is an official participant in GSSoC 2026.
576579

577-
</div>
580+
</div>
578581

579582
---
580583

581584
## 💖 Contributors
582585

583586
Thanks to all contributors who have helped make CommitPulse better!
584587

585-
<a href="https://github.com/JhaSourav07/commitpulse/graphs/contributors">
586-
<img src="https://contrib.rocks/image?repo=JhaSourav07/commitpulse&max=300&columns=14" alt="Contributors" />
587-
</a>
588+
<a href="https://github.com/JhaSourav07/commitpulse/graphs/contributors">
589+
<img src="https://contrib.rocks/image?repo=JhaSourav07/commitpulse&max=300&columns=14" alt="Contributors" />
590+
</a>
588591

589592
<sub>View the [full contributor list →](https://github.com/JhaSourav07/commitpulse/graphs/contributors)</sub>
590593

591-
test commit for PR creation

0 commit comments

Comments
 (0)