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
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 ✦
✨ JUNG SEUNGHOON · Full-Stack Dev \
⭐ 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.
Same pattern as productive-box: fork → Action fills your Gist → pin that Gist. No Vercel for Pins.
- Fork this repo
- Create a public Gist and copy its ID
(https://gist.github.com/YOU/GIST_ID— not the.jsembed URL) - Create a PAT with
gistscope → on your fork, add SecretsGH_TOKEN+GIST_ID - On your fork, add Variable
BIRTHDATE=YYYY-MM-DD(optional but recommended) - Actions → Update Zodiac Gist → Run workflow
- Pin the Gist on your profile
Details (secrets table, variables, schedule): § Pin a Zodiac Gist — fork setup below.
Recommended: fork this repo and run the Action on your fork.
Fork seuthootDev/github-readme-zodiac.
- https://gist.github.com/
- Filename e.g.
zodiac.md, any placeholder text - Create public gist
- Copy only the Gist ID (not the
.jsembed URL):
https://gist.github.com/YOU/GIST_ID
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.
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.
- On your fork: Actions → enable workflows if prompted
- Update Zodiac Gist → Run workflow
- Pin the Gist on your profile
Also runs on every push to main and daily at 00:00 UTC.
| 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 |
| 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) |
Each card shows 3 of 5 traits. Which three appear depends on the sign’s statKeys. Values are scaled from public GitHub signals (0–100).
| 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.
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
npm startnode scripts/preview-all-gists.js
# → scripts/out/all-signs-gist-preview.htmlaction.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
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.
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 |
MIT © seuthootDev
Third-party artwork remains under its Magnific license (see certificates above); the MIT license covers this repository’s code.
- 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