gitbreathing

1# GitBreathing
2 
3A configurable GitHub profile composition engine. It turns public GitHub profile data, contribution history, repository metrics and original animated ASCII motifs into one embeddable SVG, plus standalone breathing art.
4 
5## Profile README output
6 
7After GitHub Actions runs, embed the complete generated profile with one ordinary Markdown image:
8 
9```md
10![GitBreathing profile](https://gitlab.com/bitzzdev/gitbreathing/-/raw/main/dist/profile.svg)
11```
12 
13No JavaScript, iframe, external widget or custom HTML script is required in the README. GitHub displays the generated SVG as an image. For platforms that block SVG, use the individual PNG/GIF assets.
14 
15## What can be displayed
16 
17Configure `readme.show` in `gitbreathing.json` to select any combination of:
18 
19- Display name, username, bio, location, company and website
20- GitHub social accounts and manually configured links
21- ORCID, including a manually supplied ORCID URL
22- Followers, following, public repositories, received stars, starred repositories, gists and organizations
23- Commit, pull request, issue and code-review contribution totals
24- Top repository languages and pinned repositories
25- Total contributions and the daily contribution calendar
26 
27The workflow fetches public profile fields and the contribution calendar through GitHub GraphQL. Missing or private fields are omitted. Social accounts not exposed by GitHub can be added under `socials`, and ORCID can be set under `orcid`.
28 
29## Composition and anime-inspired corner art
30 
31The generated profile uses an editorial, paper-like dark layout with restrained typography, thin separators, metric columns, contribution heatmap, repository panels and configurable corner decorations.
32 
33Each corner can be configured independently in `readme.corners`:
34 
35- `fire`: animated breathing flame
36- `titan`: original freedom-wing geometry
37- `demon`: original sword-form geometry
38- `cursed`, `chakra`, `pirate`, `spirit`, `hunter`, `dragon`
39- `none`: no decoration
40 
41The anime presets are original motifs inspired by broad genre visual language. They are not official anime artwork, character illustrations, studio logos or copied screenshots. This avoids bundling unlicensed show assets. For freely reusable animated ASCII scenes and effects, the renderer uses [ascii.rest](https://ascii.rest/), an MIT-licensed library.
42 
43## Quick start
44 
45Requires Node.js 22 or newer.
46 
47```sh
48npm install
49cp config.example.json gitbreathing.json
50# Edit username, selected profile fields and corner motifs.
51npm run build
52CONTRIBUTIONS=1200 npm run render
53npm run render:profile
54```
55 
56## Generated files
57 
58| File | Purpose |
59| --- | --- |
60| `dist/profile.svg` | Complete GitHub profile composition, embed this in README |
61| `dist/slash.svg` | Animated breathing artwork |
62| `dist/slash.gif` | Animated raster fallback |
63| `dist/slash.png` | Static first frame |
64| `dist/slash.txt` | Plain-text frame |
65| `dist/profile-data.json` | Public GitHub data fetched by the workflow |
66| `dist/metadata.json` | Rendering metadata |
67 
68## GitHub Actions
69 
70The included workflow fetches the configured GitHub user's public profile, contribution calendar, repository metadata, pinned repositories and social accounts. It then renders both the breathing artwork and the complete profile SVG and commits the outputs.
71 
72Enable **Settings → Actions → General → Workflow permissions → Read and write permissions** if the workflow cannot push. GitHub's contribution total includes qualifying commits, pull requests, issues and code reviews.
73 
74## Configuration
75 
76The `readme.show` array controls visibility. The `readme.corners` object controls each corner independently. Manual social links and ORCID are supported separately:
77 
78```json
79{
80  "socials": {
81    "Instagram": "https://instagram.com/your-handle",
82    "LinkedIn": "https://linkedin.com/in/your-handle"
83  },
84  "orcid": "https://orcid.org/0000-0000-0000-0000"
85}
86```
87 
88## Privacy and cost
89 
90GitBreathing has no hosted backend, telemetry or central token storage. GitHub data is fetched in the user's own GitHub Actions runner. The generated profile SVG contains only fields selected in the configuration. Keep private tokens in repository secrets, never in `gitbreathing.json`.
91 
92## Attribution
93 
94Created by [Dev Borah](https://bitz.is-a.dev/).
95 
96- [ascii.rest](https://ascii.rest/), MIT-licensed animated ASCII renderer.
97- GitBreathing's original SVG corner motifs and profile layout are part of this repository under MIT.
98 
99GitBreathing is an independent fan-made project. Anime-inspired presets are original visual motifs and are not affiliated with or endorsed by any anime publisher or studio.
100 
101## License
102 
103MIT.
104