diff --git a/README.md b/README.md index 1ad0741..0023088 100644 --- a/README.md +++ b/README.md @@ -2,191 +2,505 @@ # 🌌 github-constellation -**Turn your GitHub contribution history into a living night sky.** +### Turn your GitHub contributions into a living night sky. -Every day you code becomes a star. Streaks become glowing constellation -lines. Your biggest days pulse like they know it. +**Stars for your coding days. Β· Glow for your streaks. Β· Color for your journey.** -github-constellation hero example +github-constellation preview -↑ Replace this with your own generated SVG β€” see Quick Start below. +
-

+[![Marketplace](https://img.shields.io/badge/GitHub%20Action-github--constellation-181717?logo=github\&logoColor=white)](https://github.com/marketplace/actions/github-constellation) +[![GitHub stars](https://img.shields.io/github/stars/m3hrab/github-constellation?style=flat\&logo=github\&color=gold)](https://github.com/m3hrab/github-constellation/stargazers) +[![Latest release](https://img.shields.io/github/v/release/m3hrab/github-constellation?style=flat)](https://github.com/m3hrab/github-constellation/releases) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -[![Marketplace](https://img.shields.io/badge/Marketplace-github--constellation-blue?logo=github)](https://github.com/marketplace/actions/github-constellation) -[![GitHub stars](https://img.shields.io/github/stars/your-username/github-constellation?style=flat&logo=github&color=gold)](https://github.com/your-username/github-constellation/stargazers) -[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) -[![Latest release](https://img.shields.io/github/v/release/your-username/github-constellation)](https://github.com/your-username/github-constellation/releases) +
+ +**A beautiful, zero-runtime-dependency GitHub Action that transforms your contribution calendar into a generative constellation.** --- -## Why - -GitHub's contribution graph is a grid of green squares. It's information β€” -but it isn't _beautiful_, and it doesn't tell you anything a spreadsheet -couldn't. **github-constellation** renders the exact same data as a -generative sky: stars for days, size for effort, color for time, and soft -glowing threads for the streaks that held your year together. Drop it in -your profile README and it becomes the thing people actually look at. - -## ✨ Features - -- **⭐ Stars = days.** Every contribution day is a star; empty days stay - dim background dust. -- **πŸ“ Size = commit count.** Bigger day, bigger star β€” scaled and capped so - one huge day never flattens the rest of the sky. -- **🎨 Color = recency.** A gradient sweeps across your _entire year_, oldest - to newest, so the color alone tells you when things happened. -- **〰️ Streaks = glowing curves.** Consecutive contribution days are - connected with soft, blurred, smoothly-curved constellation lines β€” not - spreadsheet connectors. -- **πŸ’« Pulse on big days.** Days above a commit threshold twinkle and - breathe with a slow independent glow halo. -- **πŸŒ— Dark + light variants,** generated together, both fully recolorable. -- **🧡 Zero runtime dependencies.** The generator is one Node script using - only `fs`, `path`, and `https` β€” no `npm install`, no supply chain to - audit. -- **βš™οΈ Fully tunable** via action inputs: commit cap, twinkle threshold, all - four gradient colors, output directory, layout. +## ✨ What is this? + +Your GitHub contribution graph tells a story β€” but it looks like a spreadsheet. + +**github-constellation** turns that same contribution history into a visual night sky. + +Every contribution day becomes a star. +More commits make the star brighter and larger. +Streaks become glowing constellation lines. +Recent activity shifts the color toward the newest end of the gradient. +Big coding days gently pulse like they're still alive. + +The result is a **self-updating SVG** you can embed directly into your GitHub profile README. + +> **Your contribution history, visualized as a constellation.** + +--- + +## 🌌 How it works + +```text +GitHub Contributions + β”‚ + β–Ό + GraphQL API + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ github-constellationβ”‚ +β”‚ generator β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”œβ”€β”€ ⭐ Contribution days β†’ Stars + β”œβ”€β”€ πŸ“ Commit count β†’ Size + β”œβ”€β”€ 🎨 Date β†’ Color + β”œβ”€β”€ 〰️ Streaks β†’ Connections + └── πŸ’« Big days β†’ Pulse + β”‚ + β–Ό + Static SVG files + β”‚ β”‚ + β–Ό β–Ό + Dark Light + β”‚ β”‚ + β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ + β–Ό + GitHub README +``` + +Everything is generated ahead of time. + +**No client-side API calls. No JavaScript on your profile. No runtime server.** + +--- + +## ⭐ Features + +### Contribution β†’ Visual mapping + +| GitHub data | Constellation | +| ----------------- | --------------------- | +| Contribution day | ⭐ Star | +| Commit count | πŸ“ Star size | +| Contribution date | 🎨 Color | +| Consecutive days | 〰️ Constellation line | +| High-activity day | πŸ’« Pulse / twinkle | +| No contributions | Β· Background dust | + +### Built for GitHub + +* πŸŒ— **Dark + light SVGs** generated automatically +* 🎨 **Fully customizable gradients** +* πŸ’« **Animated twinkle effects** for high-activity days +* 〰️ **Smooth constellation curves** connecting streaks +* πŸ“Š **Commit-aware star sizing** +* βš™οΈ **Configurable through GitHub Action inputs** +* πŸ”„ **Automatically regenerates every day** +* 🧡 **Zero runtime dependencies** +* πŸš€ **Works directly from a GitHub repository** +* πŸ“¦ **Produces static SVG output** +* πŸ” **No external database or hosted service required** + +--- ## πŸš€ Quick Start -Three steps: add a workflow file, add a token secret, push. +### 1. Create a GitHub token + +Create a **classic Personal Access Token** with no scopes: -**1. Create a [classic Personal Access Token](https://github.com/settings/tokens/new)** β€” -no scopes needed, since it's only reading public contribution data β€” and add -it to your profile repository as a secret named `CONSTELLATION_TOKEN` -(_Settings β†’ Secrets and variables β†’ Actions β†’ New repository secret_). +[Create a GitHub Personal Access Token](https://github.com/settings/tokens/new?utm_source=chatgpt.com) -> Why not the default `GITHUB_TOKEN`? It's scoped to the current repo and -> isn't reliably able to query another user's GraphQL contribution data -> across all GitHub setups. A plain PAT avoids that entirely β€” see the -> [FAQ](#-faq). +Then add it to your repository: -**2. Add this workflow** at `.github/workflows/constellation.yml`: +**Settings β†’ Secrets and variables β†’ Actions β†’ New repository secret** + +Use: + +```text +Name: CONSTELLATION_TOKEN +Value: +``` + +> **Why a PAT?** +> +> The workflow needs to query GitHub's GraphQL API for contribution data. +> The repository-scoped `GITHUB_TOKEN` can be restrictive when querying +> contribution information outside the current repository. + +--- + +### 2. Add the workflow + +Create: + +```text +.github/ +└── workflows/ + └── constellation.yml +``` + +Then add: ```yaml name: Update Constellation on: schedule: - - cron: "0 0 * * *" # once a day; tweak to taste - workflow_dispatch: {} + - cron: "0 0 * * *" + workflow_dispatch: permissions: contents: write jobs: generate: + name: Generate constellation runs-on: ubuntu-latest + steps: - - uses: actions/checkout@v4 + - name: Checkout repository + uses: actions/checkout@v4 - - uses: your-username/github-constellation@v1 + - name: Generate constellation + uses: m3hrab/github-constellation@v1 with: github_user: ${{ github.repository_owner }} github_token: ${{ secrets.CONSTELLATION_TOKEN }} - - name: Commit and push if changed + - name: Commit generated SVGs run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" + git add dist/ - git diff --staged --quiet || git commit -m "chore: update constellation" - git push + + if git diff --staged --quiet; then + echo "No constellation changes." + else + git commit -m "chore: update constellation" + git push + fi ``` -**3. Embed it in your profile README:** +--- + +### 3. Add it to your profile README ```markdown - - - My GitHub constellation + + + My GitHub contribution constellation ``` -Run the workflow once via **Actions β†’ Update Constellation β†’ Run workflow**, -and you're done. It'll keep itself up to date on the schedule from here on. +Then run: + +**Actions β†’ Update Constellation β†’ Run workflow** + +That's it. + +Your contribution constellation will regenerate automatically. + +--- + +## 🎨 Customize your sky + +You don't have to use the defaults. + +For example: + +```yaml +- name: Generate constellation + uses: m3hrab/github-constellation@v1 + with: + github_user: ${{ github.repository_owner }} + github_token: ${{ secrets.CONSTELLATION_TOKEN }} + + commit_cap: 25 + twinkle_min_commits: 12 + + recent_color_dark: "#ffd166" + old_color_dark: "#6c63ff" + + recent_color_light: "#b86b00" + old_color_light: "#4338ca" + + layout: "full" +``` + +### Available inputs + +| Input | Required | Default | Description | +| --------------------- | :------: | --------: | ------------------------------------------- | +| `github_user` | βœ… | β€” | GitHub username to visualize | +| `github_token` | βœ… | β€” | GitHub GraphQL API token | +| `commit_cap` | ❌ | `20` | Maximum commit count used for star scaling | +| `twinkle_min_commits` | ❌ | `10` | Minimum commits required for a pulsing star | +| `recent_color_dark` | ❌ | `#ffcf5c` | Recent-date gradient color for dark mode | +| `old_color_dark` | ❌ | `#7c6fe0` | Old-date gradient color for dark mode | +| `recent_color_light` | ❌ | `#c9820a` | Recent-date gradient color for light mode | +| `old_color_light` | ❌ | `#463c94` | Old-date gradient color for light mode | +| `output_dir` | ❌ | `dist` | Generated SVG output directory | +| `layout` | ❌ | `full` | `full` or `minimal` | + +### Layouts + +**`full`** -## πŸ”§ Inputs +Includes labels and the statistics caption. -| Input | Required | Default | Description | -| --------------------- | :------: | --------- | ------------------------------------------------------------------------- | -| `github_user` | βœ… | β€” | GitHub username whose contribution calendar to render. | -| `github_token` | βœ… | β€” | Token with read access to the GitHub GraphQL API. See Quick Start above. | -| `commit_cap` | ❌ | `20` | Commit count at which star size/opacity growth is capped. | -| `twinkle_min_commits` | ❌ | `10` | Minimum commits/day required for that day's star to twinkle and pulse. | -| `recent_color_dark` | ❌ | `#ffcf5c` | Hex color for the most-recent end of the gradient, dark theme. | -| `old_color_dark` | ❌ | `#7c6fe0` | Hex color for the oldest end of the gradient, dark theme. | -| `recent_color_light` | ❌ | `#c9820a` | Hex color for the most-recent end of the gradient, light theme. | -| `old_color_light` | ❌ | `#463c94` | Hex color for the oldest end of the gradient, light theme. | -| `output_dir` | ❌ | `dist` | Directory the generated SVGs are written to. | -| `layout` | ❌ | `full` | `full` (labels + stats caption) or `minimal` (bare star grid, no chrome). | +**`minimal`** -**Outputs:** `dark_svg_path`, `light_svg_path` β€” absolute paths to the two -generated files, in case a later step in your workflow needs them. +Just the constellation β€” ideal for compact profile layouts. + +--- ## πŸ–ΌοΈ Gallery -> Using github-constellation on your profile? Open a PR adding your -> screenshot here β€” real skies are the best advertisement. +### Dark sky + +Dark github-constellation example + +### Light sky + +Light github-constellation example + +> Have a particularly beautiful constellation? +> Open a PR and add it to the gallery. + +--- + +## 🧠 Design philosophy + +github-constellation intentionally keeps the visualization simple. + +It doesn't try to turn your GitHub history into a dashboard full of charts. + +Instead, it answers one question: + +> **What would my coding year look like if it were a night sky?** + +That means every visual element has a purpose: + +**Stars** represent consistency. +**Size** represents effort. +**Color** represents time. +**Lines** represent momentum. +**Glow** represents exceptional days. + +The goal isn't more data. + +**It's a more memorable way to see the data you already have.** -| | | | -| --------------- | --------------- | --------------- | -| _your sky here_ | _your sky here_ | _your sky here_ | +--- + +## ⚑ Performance & architecture + +github-constellation is deliberately lightweight. + +The generator uses only Node.js built-ins: + +```text +fs +path +https +``` + +There are: + +* ❌ No npm dependencies +* ❌ No database +* ❌ No hosted backend +* ❌ No client-side API requests +* ❌ No external runtime service + +The workflow generates static SVG files and commits them to your repository. + +Your profile simply displays those files. + +```text +GitHub Actions + β”‚ + β–Ό +Generate SVG + β”‚ + β–Ό +Commit to repo + β”‚ + β–Ό +GitHub README + β”‚ + β–Ό + ⭐ +``` + +--- + +## πŸ” Security + +The action only needs access to GitHub's GraphQL API to retrieve contribution information. + +Your token should be stored as a **GitHub Actions secret**: + +```text +CONSTELLATION_TOKEN +``` + +Never hard-code your token into: + +* workflow files +* source code +* README files +* commits +* issues +* pull requests + +For public contribution data, use the minimum permissions necessary. + +--- ## ❓ FAQ -**Does this work for private contributions?** -Yes β€” the GraphQL `contributionsCollection` query returns the same data -shown on your public profile, including the "private contributions" count if -you've enabled _Include private contributions_ in your GitHub profile -settings, using whatever token you supply. - -**Can I use this on someone else's profile, or an org?** -The action will render whatever `github_user` you give it, but you should -only render a sky for accounts you have permission to represent β€” this is -meant for your own profile README. - -**Why does it need a Personal Access Token instead of the built-in -`GITHUB_TOKEN`?** -The built-in token is scoped narrowly to the repo running the workflow. A -classic PAT with no scopes reliably authenticates the GraphQL query for any -public contribution calendar and avoids permission edge cases across -personal, org, and Enterprise setups. - -**Can I change the colors?** -Yes β€” all four gradient endpoints (`recent_color_dark`, `old_color_dark`, -`recent_color_light`, `old_color_light`) are inputs. See the table above. - -**Will this slow down my profile page?** -No β€” the SVG is generated once per scheduled run and committed as a static -file. Your README just references a file in your repo; nothing runs -client-side except the CSS twinkle animation already baked into the SVG. - -**Can I run this outside GitHub Actions?** -Yes β€” `src/generate-constellation.js` is a plain Node script. See -[CONTRIBUTING.md](CONTRIBUTING.md#testing-locally) for local usage. +### Does it support private contributions? + +Yes, subject to what GitHub exposes through your authenticated contribution +data and your profile's private-contribution settings. + +### Can I generate a constellation for another GitHub user? + +The action accepts any `github_user` value for which the supplied token can +retrieve the required contribution data. + +However, the project is primarily designed for representing **your own +GitHub profile**. + +### Why not use `GITHUB_TOKEN`? + +The built-in token is scoped to the repository running the workflow and may +not provide the access needed for contribution queries in every setup. + +A classic PAT provides a more predictable authentication path for the +GraphQL request. + +### Does the SVG require a server? + +No. + +The SVG is generated once and stored in your repository as a static file. + +### Does the animation work on GitHub? + +The generated SVG contains the animation itself, so the README only needs +to reference the resulting SVG. + +### Can I run the generator locally? + +Yes. + +The generator is a regular Node.js script: + +```bash +node src/generate-constellation.js +``` + +See [CONTRIBUTING.md](CONTRIBUTING.md#testing-locally) for development and +testing instructions. + +--- + +## πŸ› οΈ Development + +Clone the repository: + +```bash +git clone https://github.com/m3hrab/github-constellation.git +cd github-constellation +``` + +Run the generator: + +```bash +node src/generate-constellation.js +``` + +Generated files will appear in: + +```text +dist/ +β”œβ”€β”€ constellation-dark.svg +└── constellation-light.svg +``` + +--- ## 🀝 Contributing -Bug reports, feature ideas, and gallery submissions are all welcome β€” see -[CONTRIBUTING.md](CONTRIBUTING.md). Please be excellent to each other; see -the [Code of Conduct](CODE_OF_CONDUCT.md). +Ideas, bug reports, improvements, visual experiments, and gallery +submissions are welcome. + +Before opening a pull request, please read: + +* [CONTRIBUTING.md](CONTRIBUTING.md) +* [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) + +If you build something interesting with github-constellation, I'd love to +see it. + +--- ## πŸ“„ License -[MIT](LICENSE) β€” do whatever you want with it. +Released under the **MIT License**. + +See [LICENSE](LICENSE) for details. + +--- ## ⭐ Star History - + - - - Star History Chart + + + Star History Chart + +--- + +
+ +### 🌌 Your commits are more than green squares. + +**They're a story. Turn it into a constellation.** + +
+ +Made with ⭐ by [m3hrab](https://github.com/m3hrab) + +