# Day 28 — GitHub README Profile Generator — Research Brief

## Concept

A free, self-hostable Astro template that is **both** a beautiful landing page and a pure client-side GitHub profile README generator. Users fill in a form, get real-time markdown output, and copy or download a `.md` file. No backend, no account, no tracking. Distinct from every hosted SaaS generator: this is a template you own.

---

## Audience & Primary CTA

- **Who visits:** Junior-to-mid developers, OSS contributors, bootcamp grads, indie hackers — anyone who just discovered the GitHub profile README feature and wants a polished one fast.
- **Primary CTA:** "Copy Markdown" (or "Download .md") — the moment the user has filled the form and sees the preview, the generator has delivered. The CTA is the copy/download button inside the output panel.
- **Secondary CTAs:** "Load preset" (one-click sample personas), "Star on GitHub" (social proof for the template itself), TemplateInfo download bar.

---

## Reference Sites / Prior Art (real tools, verified)

- **https://gprm.itsvg.in/** — GPRM: 300+ tech options, streak stats, trophies, visitor counter. Strengths: comprehensive widget set. Weaknesses: no live preview, cluttered UI, no visual design of the output README itself, hosted SaaS with ads.
- **https://rahuldkjain.github.io/gh-profile-readme-generator/** — Rahul's generator: large form with tech-stack icon selection by category, social links, add-ons. Strengths: widely known, many tech icons. Weaknesses: information-dense, no live split-pane preview, last major update 2022, form overwhelms first-time users.
- **https://profilinator.rishav.dev/** — Profilinator: section-based builder (intro, skills, connect, stats). Strengths: modular, Spotify integration, pre-built templates. Weaknesses: tech focus is MERN-heavy, placeholder blog section, no preview pane.
- **https://profile-readme-generator.com/** — Mauro's generator: drag-and-drop section builder, live preview. Strengths: visual block system, best-in-class UX among generators. Weaknesses: hosted SaaS, cannot self-host, no landing-page demo of output.
- **https://github.com/abhisheknaiidu/awesome-github-profile-readme** — Curated gallery of real profiles. Key insight: the most-starred profiles use minimal section counts (3-5 sections), not kitchen-sink outputs. Quality beats quantity.
- **https://github.com/DenverCoder1/github-readme-streak-stats** — Streak stats widget (img embed). Canonical URL: `https://streak-stats.demolab.com?user={username}`. Used in the generated markdown output.
- **https://github.com/anuraghazra/github-readme-stats** — The dominant stats card. Canonical embed: `https://github-readme-stats.vercel.app/api?username={username}`. Top-langs card also from same project.
- **https://github.com/Platane/snk** — Contribution snake animation via GitHub Actions. Popular but requires GitHub Actions workflow — excluded from our generated markdown (adds complexity; we note it in FAQ).
- **https://shields.io/** — Standard for static tech-stack badges. URL pattern: `https://img.shields.io/badge/{label}-{color}?style=flat&logo={logo}&logoColor=white`. We use `simple-icons` logos via shields.io for the ~30 curated tech chips.

---

## Existing Templates Surveyed

- **https://rahuldkjain.github.io/gh-profile-readme-generator/** — Strength: battle-tested, huge tech library. Weakness: no live preview, dated UX, not self-hostable as an Astro template, no beautiful landing page demo.
- **https://profilinator.rishav.dev/** — Strength: pre-built template starters. Weakness: MERN-centric, hosted SaaS.
- **https://profile-readme-generator.com/** — Strength: drag-and-drop, live preview. Weakness: React SPA, no static-site landing demo, no downloadable self-host version.
- **https://git-readme-generator.vercel.app/** (AGRG) — Strength: deployed on Vercel. Weakness: minimal design, no preset personas.
- **GitHub topic `profile-readme-generator`** — Dozens of repos; none ship as a polished Astro static-site template with a showcase landing page. Gap confirmed.
- **Themeforest / Astro themes directory** — No profile README generator template found. Category does not exist on either marketplace.

**Gap:** No existing tool is: (a) a beautiful static landing-page demo + (b) a pure-client-side generator + (c) an MIT-licensed, self-hostable Astro template with preset personas. We own that intersection.

---

## Visual Differentiation from Days 1–27

### Chosen palette — **cyan-phosphor on deep navy** ("terminal phosphor" register)

None of the 27 prior days use deep navy as a background. None use cyan as a primary accent. The closest are: Day 6 cobalt (blue, light background), Day 10 teal (dark but teal-green), Day 20 emerald (dark, green-shifted). Cyan phosphor on near-navy is the "CRT monitor" register — unmistakably developer-coded, nostalgic without being retro-cheesy.

```css
--color-bg:          #0D1117   /* GitHub's own dark bg — intentional echo */
--color-surface:     #161B22   /* GitHub dark surface — card backgrounds */
--color-surface-alt: #1C2330   /* alternating sections, input panels */
--color-accent:      #00D4FF   /* cyan-phosphor — neon but not garish */
--color-accent-dim:  #00A8CC   /* hover/active states */
--color-accent-glow: rgba(0, 212, 255, 0.12) /* subtle glow on cards */
--color-text:        #E6EDF3   /* GitHub's text-primary */
--color-text-muted:  #848D97   /* GitHub's text-secondary */
--color-border:      #30363D   /* GitHub's border-default */
--color-code-bg:     #161B22   /* output panel background */
--color-green:       #3FB950   /* contribution green — used for "copy success" flash */
```

**Why untaken and appropriate:**
- Background `#0D1117` is literally GitHub's dark background — users land on a tool that feels native to the GitHub ecosystem, not a generic landing page.
- Cyan `#00D4FF` has never appeared in Days 1–27. It reads as "terminal phosphor" — the historical monitor color for developer tools. Completely distinct from Day 6 cobalt (blue), Day 10 teal (green-shifted dark), Day 20 emerald (vivid green).
- The "GitHub color echo" is a deliberate design signal: this tool belongs in the GitHub universe.

**WCAG contrast checks:**
- Cyan `#00D4FF` on `#0D1117`: ~11.2:1 — AAA ✓
- Text `#E6EDF3` on `#0D1117`: ~14.1:1 — AAA ✓
- Muted `#848D97` on `#0D1117`: ~5.3:1 — AA ✓
- White `#FFFFFF` on accent `#00D4FF`: ~1.4:1 — FAIL. Use `#0D1117` as text color on cyan buttons: ~11.2:1 ✓
- `#3FB950` green on `#0D1117`: ~7.2:1 — AA ✓

**Mode:** Dark-only. GitHub's own interface is dark-first. A GitHub README tool that ships light-first would be tone-deaf to the audience.

### Chosen typography — **Space Grotesk** (display) + **JetBrains Mono** (code output panel)

- **Space Grotesk** (Google Fonts, OFL): A geometric sans-serif with quirky character shapes (`R`, `G`, `&`) that feel technical without being sterile. Untaken across all 27 prior days. Weights 400, 500, 600, 700. At display sizes it reads "maker tool" — not corporate, not playful, just sharp.
- **JetBrains Mono** (Google Fonts, OFL): The canonical developer monospace. Used exclusively in the output `<pre><code>` panel and any inline code. Gives the generated markdown a "real IDE" feel. Untaken in the roadmap.
- Body prose uses Space Grotesk 400/16px.

**Pairing rationale:** Space Grotesk (geometric display) + JetBrains Mono (code panel) = the visual language of a developer tool, not a marketing site. No other template in the 27-day roadmap uses either font.

---

## Must-Have Sections (landing page order)

1. **Hero** — Headline: "Generate your GitHub profile README in seconds." Sub: "Fill the form. Copy the markdown. Paste into GitHub." Two CTAs: "Try the generator ↓" + "See examples ↓". Dark background, cyan accent, Space Grotesk display.
2. **Generator** — Two-pane layout: left = form inputs, right = live markdown preview (rendered as styled output + raw `<pre><code>` tab). This is the core product; it sits at `#generator` anchor.
3. **Preset Personas** — 4 clickable cards: "Full-Stack Dev", "OSS Maintainer", "Design Engineer", "Indie Maker". One-click loads that persona's values into the form. Provides immediate value for users who don't know where to start.
4. **Why use this** — 3-column trust strip: "100% client-side — your data never leaves your browser" / "No account required — open and use" / "MIT licensed — fork it, self-host it, own it"
5. **What goes in a great README** — Brief editorial: the 5 elements that make a profile README stand out vs. a generic one. Positions us as knowledgeable, not just a form.
6. **FAQ** — 6 questions (see FAQ section below).
7. **Footer + TemplateInfo bar**

---

## Generator Form Fields

Group fields logically — collapse advanced options behind an "Advanced" disclosure:

**Identity (always visible)**
- Display name
- Role / headline (e.g., "Full-Stack Engineer · Open Source Enthusiast")
- Location (city, country — optional)
- Current focus (one line: "Building X", "Learning Y")
- Fun fact (optional)

**Links (always visible)**
- GitHub username (required — drives stats card URLs)
- Twitter/X handle
- LinkedIn URL
- Portfolio / personal site URL
- Dev.to / Hashnode handle (optional)

**Tech stack chips (always visible)**
- Pre-curated chip grid of ~30 techs: React, Vue, Angular, Next.js, Svelte, TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, Swift, C++, Node.js, Deno, PostgreSQL, MySQL, MongoDB, Redis, Docker, Kubernetes, AWS, GCP, Azure, Linux, Git, Figma, TailwindCSS, GraphQL.
- Multi-select; renders as shields.io `flat` style badges in output.

**GitHub Stats options (Advanced)**
- Include stats card? (toggle) — theme selector: dark / tokyonight / radical / gruvbox / onedark
- Include top languages card? (toggle)
- Include streak stats? (toggle)
- Show visitor counter? (toggle — uses komarev.com)

**README style (Advanced)**
- Include greeting GIF? (toggle — uses a canned tenor/giphy embed from a curated allowlist of 3 options)
- Alignment: centered (default) vs left-aligned

---

## Generated Markdown Shape (canonical output)

```markdown
<h1 align="center">Hi, I'm {name} 👋</h1>
<p align="center">{role} · {location}</p>

---

**About me**
- Currently working on: {focus}
- Fun fact: {fun_fact}

---

**Tech Stack**
![React](https://img.shields.io/badge/React-20232A?style=flat&logo=react&logoColor=61DAFB)
<!-- ...per selected chips -->

---

**GitHub Stats**
<p align="center">
  <img src="https://github-readme-stats.vercel.app/api?username={username}&show_icons=true&theme={theme}" />
  <img src="https://streak-stats.demolab.com?user={username}&theme={theme}" />
</p>

---

**Connect**
[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat&logo=linkedin&logoColor=white)]({linkedin_url})
<!-- ...per selected socials -->
```

---

## What Good Profile READMEs Include (curated, not kitchen-sink)

Based on the `abhisheknaiidu/awesome-github-profile-readme` gallery, top-performing profiles share:
1. Concise greeting header (name + role, centered)
2. 3-5 bullet "about" points — not an essay
3. Tech stack badges (shields.io, flat style, grouped)
4. Stats card + streak card (anuraghazra + DenverCoder1)
5. Social links as icon badges
6. Optional: typing SVG animation for the header (readme-typing-svg by DenverCoder1)

**Excluded from our template** (too gimmicky, fragile, or require GitHub Actions):
- Contribution snake animation (requires Actions workflow — FAQ addresses this)
- Spotify Now Playing (requires OAuth server)
- Wakatime stats (requires account + setup)
- Random joke / quote widgets (low-signal)
- Full blog post feed via Actions (fragile, separate tutorial)

---

## Trust Signals to Include

- "100% client-side — zero server calls. Your inputs never touch a server."
- MIT licensed — shown in footer and TemplateInfo bar
- "Works in any browser — no install, no login"
- Stats cards powered by anuraghazra/github-readme-stats (link to repo for transparency)
- Streak stats powered by DenverCoder1/github-readme-streak-stats (link to repo)
- "Used by 1,200+ developers" (placeholder stat — update once real traffic exists)
- TemplateInfo bar: canonical 3-button bar per project pattern

---

## FAQ (6 questions)

1. Do my inputs leave the browser? — No. All markdown assembly is pure JavaScript string interpolation in the browser. No network requests are made with your data.
2. Can I edit the generated markdown afterward? — Yes. It's just markdown. Paste it into any editor, add or remove sections freely.
3. What are github-readme-stats and streak-stats? — They're free, open-source services that render SVG stat cards from your public GitHub data. The images are fetched by GitHub's servers when someone views your profile.
4. What is my GitHub username vs my display name? — Your GitHub username is in your profile URL (github.com/username). Your display name is what appears on your profile page. Both can differ.
5. Why does the stats card say "Loading…" in the preview? — The preview renders the markdown with real img tags. Stats cards require GitHub to make a live fetch; they appear correctly once you paste the README into GitHub.
6. Can I add the contribution snake animation? — The snake requires a GitHub Actions workflow in your `<username>/<username>` repo. We include a link to Platane/snk docs in the generated README's comment block but don't generate the workflow file (it's outside the scope of a static generator).

---

## Schema.org

- **Primary type:** `WebApplication` (applicationCategory: "DeveloperApplication", operatingSystem: "All", offers: free)
- **Secondary type:** `SoftwareApplication` — same properties, broader indexing
- **Tertiary type:** `FAQPage` — separate JSON-LD block for the 6 FAQ entries
- **Required properties (WebApplication):** `name`, `url`, `description`, `applicationCategory`, `operatingSystem`, `offers` (price: 0), `browserRequirements`
- **Suggested OG image:** Dark terminal-style screenshot of the split-pane generator — form on left, rendered README preview on right. Cyan accent visible. 1200×630px. Conveys "tool" instantly.

---

## Static-Only Fit

**No SSR concerns.** The entire generator is client-side string assembly. The only dynamic data in the output README (stats cards, streak stats) are fetched by GitHub's own servers at render time, not by our template. Static substitutes:

- Stats card preview: Show a static placeholder `<img>` in the preview pane with `alt="Your GitHub stats will appear here"` — no live fetch during preview.
- Streak stats: Same — static placeholder.
- Visitor counter (komarev.com): Generated as a static markdown badge string; user pastes it; counter runs on komarev's servers.

**No concerns.** Everything deploys to GitHub Pages as-is.

---

## Differentiation — What We Do Better

| Aspect | Our template | GPRM / Rahul's generator / Profilinator |
|--------|-------------|----------------------------------------|
| Self-hostable | MIT Astro template, clone and own | Hosted SaaS — dependent on their uptime |
| Landing page demo | Beautiful showcase at templates.allanninal.dev | Plain form page, no marketing context |
| Preset personas | 4 one-click presets (dev, OSS, designer, indie) | None — blank form only |
| Split-pane live preview | Left form → right rendered output, live | None (Rahul's) or separate step (GPRM) |
| Design quality | Dark GitHub-echo palette, Space Grotesk, polished | Functional but minimal/dated UI |
| Privacy story | Explicit "zero server calls" trust signal | Not prominently stated |
| Opinionated output | Curated 5-section output — quality over quantity | Kitchen-sink 20+ section option |
| Ads | None | GPRM and others show ads |
| Accessibility | WCAG AA throughout | Not audited |
| GitHub Pages | One-click deploy workflow | N/A |

---

## Technical Notes for Builder

- The generator lives in a single Astro page (`src/pages/index.astro`) with a client-side `<script>` island (`client:load`). No React needed — vanilla JS for form → markdown assembly.
- Tech-stack chips: `src/data/techStack.ts` — array of `{name, logo, color, labelColor}` objects for shields.io URL generation.
- Preset personas: `src/data/personas.ts` — 4 objects with pre-filled form values.
- Output panel: `<pre><code>` block with a "Copy to clipboard" button (Clipboard API) + a "Download README.md" button (Blob + anchor download).
- The preview pane renders the markdown-as-HTML for visual feedback; a `<textarea>` below shows raw markdown for copying. Consider using a simple markdown renderer (marked.js, ~3KB) or just rendering key elements manually to avoid bloat.
- `@fontsource/space-grotesk` + `@fontsource/jetbrains-mono` — self-hosted.
- No Tailwind opacity modifiers on text. All colors fully opaque per a11y pitfalls doc.
