github-readme-chinese-zodiac
Your GitHub activity as one of the 12 Asian zodiac animals (生肖). A profile card for your README — add it with a single URL.
Quick start
Paste this into your profile README and replace YOUR_USERNAME:
That's it — no fork, no token, no setup. Your animal comes from your birth year (or force one with sign=), and the stats come from your public GitHub activity.
Live demo: github-readme-chinese-zodiac.vercel.app
🎀 New default design (v0.2). Cards now use a pastel sticker look. Prefer the original vermilion & gold brush style? Add &theme=classic to your URL.
All 12 animals
Themes & variants
With birthdate (animal year):
Classic theme (the original vermilion & gold brush design):
Options
| Param | Description |
|---|
username | GitHub username (required) |
birthdate | YYYY-MM-DD → animal year |
sign | Force animal: rat … pig |
name / role | Overrides (auto by default) |
width | 240–900, default 360 |
theme | cute (default) — pastel sticker card · classic — original vermilion & gold brush card |
glow | 1 / true — cute: sparkles twinkle around the character · classic: soft halo + twinkle on the large hanzi (default off; best when opening the SVG URL directly — GitHub Camo is a still frame) |
Animals (sign= param)
sign= | Animal |
|---|
rat | 🐀 Rat |
ox | 🐂 Ox |
tiger | 🐅 Tiger |
rabbit | 🐇 Rabbit |
dragon | 🐉 Dragon |
snake | 🐍 Snake |
horse | 🐴 Horse |
goat | 🐐 Goat |
monkey | 🐒 Monkey |
rooster | 🐓 Rooster |
dog | 🐕 Dog |
pig | 🐷 Pig |
Birthdate → animal uses the birth year (simple pre–Feb 4 → previous year approximation). No birthdate → deterministic animal from username hash.
Sister project (Western zodiac): github-readme-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. Full 12-animal gallery (pin + full gist):
Gist pin preview — 12 animals (PDF)
Also: docs/gist-pin-preview.html
Example pin body (Pig / 亥 — birthdate=1995-04-24):
🐷 PIG · Generous Collaborator ╭────╮
✨ seuthootDev · JUNG SEUNGHOON │ 亥 │
🌟 4 📦 37 👥 0 │ 猪 │
Renown █░░░░░░░░░░░ 7% ╰────╯
Craft █████████░░░ 76% 生肖
Pin quality (help wanted). Pins work, but the hanzi seal often misaligns in monospace (wide CJK vs box-drawing). SVG cards are the polished path today — see CONTRIBUTING.md if you want to improve src/gist/emblem.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.
- Fork this repo
- Create a public Gist and copy its ID
(https://gist.github.com/YOU/GIST_ID — not the .js embed URL)
- Create a PAT with
gist scope → on your fork, add Secrets GH_TOKEN + GIST_ID
- On your fork, add Variable
BIRTHDATE = YYYY-MM-DD (optional but recommended)
- Actions → Update Asian Zodiac Gist → Run workflow
- Pin the Gist on your profile
Details (secrets table, variables, schedule): Fork setup below.
Fork setup
Recommended for everyone: fork this repo and run the Action on your fork.
(That keeps your token/Gist on your account and matches how most README pin projects work.)
1. Fork
Fork seuthootDev/github-readme-chinese-zodiac.
2. Create a public Gist
- https://gist.github.com/
- Filename e.g.
chinese_zodiac.md, any placeholder text
- Create public gist
- 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 Western 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 → animal year |
USERNAME | your GitHub login | default: token owner |
SIGN | pig | force an animal |
NAME / ROLE | display overrides | optional |
Birthdate is a Variable (BIRTHDATE), not a Secret.
Path: Settings → Secrets and variables → Actions → Variables → New repository variable.
5. Run the Action
- On your fork: Actions → enable workflows if prompted
- Update Asian Zodiac Gist → Run workflow
- 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? | Vercel? |
|---|
| Pinned Gist | Yes | No |
| SVG in README | No | Yes (github-readme-chinese-zodiac.vercel.app) |
Stats
Each card shows 3 of 5 traits. Which three appear depends on the animal’s statKeys. Values are weighted from public GitHub signals with no maximum — same math as the Western sister project, Asian-flavored names. Bars are relative to the highest of the three shown.
| Stat | Western twin | Drawn from (roughly) |
|---|
| Discipline | Consistency | Account age + repos per year |
| Ingenuity | Explorer | Distinct languages + public repos |
| Craft | Builder | Public repos + stars + forks |
| Renown | Open Source | Stars + forks + followers |
| Insight | Debugger | Open issues + repos (+ a little stars) |
Daily forecast & streak
On the default (cute) card, the line under the title 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. theme=classic keeps its original blurb and tagline.
Local development
npm start
# http://localhost:3000
npm run preview:gists
Contributing
Designs, copy, animal-flavored roles, better New Year tables — welcome anytime.
Highest-priority gap today: pinned Gist hanzi seal alignment (see help wanted).
See CONTRIBUTING.md.
Credits / attribution
Animal artwork is derived from a Magnific (Freepik) asset under a free license with attribution:
License
MIT © seuthootDev
Third-party artwork remains under its Magnific license (see certificate above); the MIT license covers this repository’s code.
More from the same author
Want a terminal-style contribution graph too? Sister project:
GitHub stats as macOS / Windows / Ubuntu terminal SVGs — contribution graph, stats, top languages, neofetch.
