github-readme-zodiac

Your GitHub activity, written in the stars. A zodiac-themed profile card for your README — add it with a single URL.

Quick start

Paste this into your profile README and replace YOUR_USERNAME:

![Developer Zodiac](https://github-readme-zodiac.vercel.app/api/card?username=YOUR_USERNAME&birthdate=YYYY-MM-DD)

That's it — no fork, no token, no setup. Your sign comes from birthdate (or force one with sign=), and the stats come from your public GitHub activity.

Live demo: github-readme-zodiac.vercel.app

All 12 signs

Options

Param	Description
username	GitHub username (required)
birthdate	YYYY-MM-DD
sign	Force sign: aries … pisces
name	Override display name
role	Override role
width	Display width in px (240–900, default 360)

![Developer Zodiac](https://github-readme-zodiac.vercel.app/api/card?username=seuthootDev)

![Developer Zodiac](https://github-readme-zodiac.vercel.app/api/card?username=seuthootDev&width=480)

Sister project (Asian zodiac): github-readme-chinese-zodiac

---

Bonus: pin it as a Gist

Prefer your profile Pins over the README? A fork-based GitHub Action (like productive-box) can keep a text version of the card in a pinned Gist.

Mode	Where it appears	Setup
SVG card	Profile README	One URL (above)
Pinned Gist	Profile Pins	Fork + token + Action (below)

What a Pin looks like

GitHub only shows about 5 lines of a pinned Gist. Below is the full 12-sign gallery (pin + full gist) from the local preview:

Gist pin preview — 12 signs (PDF)

Also available as HTML (download / open locally): docs/gist-pin-preview.html

Example pin body (Taurus):

♉ TAURUS · Builder                        ✦
✨ seuthootDev · JUNG SEUNGHOON              \
⭐   4  📦  36  👥   0                  ✦-----✦
Consistency ███████████░  95%             \
Builder     █████████░░░  75%              ✦--✦

Open the Gist itself to see the full card (description + tagline under the pin fold).

Pin quality (help wanted). Pins work, but the constellation ASCII is still a rough sketch vs real sky maps. SVG cards are the polished path today — see CONTRIBUTING.md if you want to improve src/gist/constellations.js.

How to put this on your profile Pins

Same pattern as productive-box: fork → Action fills your Gist → pin that Gist. No Vercel for Pins.

1. Fork this repo
2. Create a public Gist and copy its ID
   (https://gist.github.com/YOU/GIST_ID — not the .js embed URL)
3. Create a PAT with gist scope → on your fork, add Secrets GH_TOKEN + GIST_ID
4. On your fork, add Variable BIRTHDATE = YYYY-MM-DD (optional but recommended)
5. Actions → Update Zodiac Gist → Run workflow
6. Pin the Gist on your profile

Details (secrets table, variables, schedule): Fork setup below.

Fork setup

Recommended: fork this repo and run the Action on your fork.

1. Fork

Fork seuthootDev/github-readme-zodiac.

2. Create a public Gist

1. https://gist.github.com/
2. Filename e.g. zodiac.md, any placeholder text
3. Create public gist
4. Copy only the Gist ID (not the .js embed URL):
   https://gist.github.com/YOU/GIST_ID

3. Create a token (once)

https://github.com/settings/tokens → Tokens (classic) → enable gist only.
The token string is shown once — save it. The same PAT can be reused on the Asian sister project.

4. Secrets and Variables on your fork

Settings → Secrets and variables → Actions

Secrets tab:

Secret	Value
GH_TOKEN	PAT with gist scope
GIST_ID	Gist ID only (see above)

Variables tab (optional but recommended):

Variable	Value	Notes
BIRTHDATE	YYYY-MM-DD	e.g. 1995-04-24 → zodiac sign
USERNAME	your GitHub login	default: token owner
SIGN	scorpio	force a sign
NAME	display name	optional override
ROLE	Backend Dev	optional override

Birthdate is a Variable (BIRTHDATE), not a Secret.
Path: Settings → Secrets and variables → Actions → Variables → New repository variable.

5. Run the Action

1. On your fork: Actions → enable workflows if prompted
2. Update Zodiac Gist → Run workflow
3. Pin the Gist on your profile

Also runs on every push to main and daily at 00:00 UTC.

Pin vs SVG

Feature	Your fork’s Action?	Uses github-readme-zodiac.vercel.app?
Pinned Gist	Yes	No
SVG in README	No	Yes (shared public instance), unless you deploy your own

---

Stats

Each card shows 3 of 5 traits. Which three appear depends on the sign’s statKeys. Values are weighted from public GitHub signals with no maximum. Bars are relative to the highest of the three shown.

Stat	Drawn from (roughly)
Consistency	Account age + repos per year
Explorer	Distinct languages + public repos
Builder	Public repos + stars + forks
Open Source	Stars + forks + followers
Debugger	Open issues + repos (+ a little stars)

Sister project (Asian zodiac) uses the same signals with different labels: Discipline / Ingenuity / Craft / Renown / Insight.

---

Daily forecast & streak

The speech bubble is a daily dev horoscope — a lucky language (picked from your own top languages) and one piece of advice. It changes every day (UTC) and stays the same all day.

The footer shows your current streak and contributions this year. This needs GITHUB_TOKEN on the server (GraphQL); without it the card shows the tagline instead.

How it works

Pinned Gist (fork)

Your fork → GitHub Action
  → GitHub API (your profile)
  → Zodiac + stats
  → PATCH your Gist
  → Pin on your profile

SVG (shared or self-hosted)

README image URL → Vercel /api/card → GitHub API → Zodiac + stats → SVG

Local development

npm start

Open http://localhost:3000

node scripts/preview-all-gists.js
# → scripts/out/all-signs-gist-preview.html

Project layout

action.yml
.github/workflows/update-gist.yml
assets/signs/                 # title glyphs
assets/signs-line/            # line-art accent
assets/constellations/        # card constellation art
docs/gist-pin-preview-12-signs.pdf
docs/gist-pin-preview.html
docs/license-*.pdf            # Magnific certificates
scripts/update-gist.js
scripts/preview-all-gists.js
scripts/extract-zodiac-signs.py
src/gist/
api/card.js
public/index.html

Contributing

New designs, card copy, sign-flavored roles, pin layouts — ideas are welcome anytime.
Highest-priority gap today: pinned Gist constellation ASCII (see help wanted).
See CONTRIBUTING.md.

Credits / attribution

Card sign artwork is derived from Magnific (Freepik) assets under a free license with attribution:

Used for	Asset	Designed by	Certificate
Title glyphs (assets/signs)	zodiac white signs set…	hannazasimova — Magnific.com	docs/license-zodiac-white-signs-set-67006418.pdf
Line-art accent (assets/signs-line)	flat zodiac sign collection	Freepik — Magnific.com	docs/license-flat-zodiac-sign-collection-15112717.pdf
Card constellations (assets/constellations)	various zodiac signs flat icon set	Freepik — Magnific.com	docs/license-various-zodiac-signs-flat-icon-set-9652101.pdf

License

MIT © seuthootDev

Third-party artwork remains under its Magnific license (see certificates above); the MIT license covers this repository’s code.

Roadmap

• Username → zodiac SVG
• Birthdate mapping + GitHub REST stats
• Editable name / role (auto by default)
• Pinned Gist Action (productive-box style)
• Fork-based pin setup guide
• Pin constellation ASCII closer to real figures (help wanted)
• Daily dev forecast + GraphQL contributions / streak
• Optional self-host docs for high SVG traffic

---

More from the same author

Want a terminal-style contribution graph too? Sister project:

github-readme-insight-terminal-ascii

GitHub stats as macOS / Windows / Ubuntu terminal SVGs — contribution graph, stats, top languages, neofetch.

![GitHub contribution graph](https://github-readme-insight-terminal-asci.vercel.app/svg?user=YOUR_USERNAME&theme=mac)