github-readme-zodiac

Zodiac-themed profile cards from your GitHub activity.

Your coding personality written in the stars

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

Two ways to show it on your profile:

Mode	Where it appears	Style
Pinned Gist (like productive-box)	Profile Pins	ASCII / text card
SVG card	Profile README	Full-color image (default 360×192)

Live SVG demo: https://github-readme-zodiac.vercel.app

---

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): § Pin a Zodiac Gist — fork setup below.

---

1) Pin a Zodiac Gist — 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

---

2) SVG card (README embed)

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

Demo

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

All 12 signs (SVG)

SVG 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)

---

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.

---

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/readme-banner.jpg
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
README banner (docs/readme-banner.jpg)	hand drawn colorful zodiac pattern	Freepik — Magnific.com	docs/license-hand-drawn-colorful-zodiac-pattern-4635124.pdf
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)
• 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)