# GitHub README Profile Generator — Day 28 of 365

A free, self-hostable Astro template that is both a beautiful landing page and a pure client-side GitHub profile README generator. Fill the form, pick your tech stack, copy the markdown, paste into GitHub. No backend, no account, no tracking.

![Preview](./preview.png)

**Live demo:** [templates.allanninal.dev/github-readme-profile/](https://templates.allanninal.dev/github-readme-profile/)

---

## Features

- Split-pane generator: live form on the left, rendered preview + raw markdown on the right
- 30 tech-stack chips with shields.io badges (React, TypeScript, Rust, Go, Docker, and more)
- 4 one-click preset personas: Full-Stack Dev, OSS Maintainer, Design Engineer, Indie Maker
- Copy to clipboard (with "Copied!" flash) + Download as README.md
- Advanced options: stats card, top languages, streak stats, visitor counter, alignment
- 100% client-side — your inputs never leave your browser
- Dark-only GitHub-echo palette (`#0D1117` bg, cyan `#00D4FF` accent)
- Space Grotesk display font + JetBrains Mono for the code output panel (self-hosted)
- Schema.org WebApplication + FAQPage JSON-LD for SEO
- 6-question FAQ with accessible disclosure widgets
- Trust strip: client-side privacy, no account needed, MIT licensed
- GitHub Pages deploy workflow included

---

## Stack

- **Framework:** Astro 4 (static output)
- **Styling:** Tailwind CSS 3 + CSS custom properties
- **Fonts:** `@fontsource/space-grotesk` + `@fontsource/jetbrains-mono` (self-hosted)
- **Generator:** Vanilla JS string interpolation (no React, no backend)
- **Testing:** Playwright + axe-core + Lighthouse CI + linkinator
- **Hosting:** GitHub Pages (primary); Vercel / Netlify / Cloudflare Pages as alternates

---

## Quick start

```bash
# 1. Download the source ZIP from the live demo:
#    templates.allanninal.dev/github-readme-profile/ → "Source (Astro)"

# 2. Unzip into a new folder and init a repo:
unzip github-readme-profile-source.zip -d my-readme-gen && cd my-readme-gen
git init && git add . && git commit -m "init from github-readme-profile template"

# 3. Install dependencies:
npm install

# 4. Start the dev server:
npm run dev
# → http://localhost:4321/

# 5. Build for production:
npm run build
# → dist/

# 6. Preview the build locally:
npm run preview
```

---

## Deploy to GitHub Pages (3 steps)

1. Push the source to a new GitHub repository (your own account).
2. In the repo: **Settings → Pages → Source: GitHub Actions**.
3. Push any commit to `main` — the included `pages.yml` workflow builds and deploys automatically.

The workflow resolves the base path from `${GITHUB_REPOSITORY}` automatically — no code edits needed.

**Custom domain:** set `PUBLIC_BASE_PATH=/` and `PUBLIC_SITE_URL=https://your-domain.com` as repository variables (Settings → Secrets and variables → Actions → Variables).

---

## Alternate deploys

**Vercel:** Import the repo, set `npm run build` as the build command and `dist` as the output directory. Add env vars from `.env.example`.

**Netlify:** Drag-drop the `dist/` folder, or connect the repo and set build command to `npm run build`, publish directory to `dist`.

**Cloudflare Pages:** Connect the repo, framework preset "Astro", build command `npm run build`, output `dist`.

---

## Customize

### Copy (placeholder content)

- Persona presets: `src/data/personas.ts` — edit the 4 persona objects with your own demo values.
- FAQ: `src/data/faq.ts` — add, edit, or remove FAQ items.
- Footer: `src/pages/index.astro` — update the author name, LinkedIn, and email in the `<footer>` block.

### Tech stack chips

`src/data/techStack.ts` exports `TECH_STACK` — add or remove entries. Each entry needs: `id`, `name`, `logo` (simple-icons name), `color` (hex), `logoColor` (hex or "white").

### Colors / theme

All colors are CSS custom properties in `src/styles/global.css` under `:root`. The palette uses the GitHub dark echo — change `--color-accent` to shift the entire theme. No dark/light toggle needed (dark-only by design).

### Fonts

Font imports are at the top of `src/styles/global.css`. Swap out `@fontsource/space-grotesk` for any other `@fontsource/*` package — install it first with `npm install @fontsource/<name>`.

### Generator output format

The markdown generator logic lives in the `<script is:inline>` block at the bottom of `src/pages/index.astro`. The `buildMarkdown()` function assembles the markdown string — edit it to change section order, add sections, or change the badge style.

### OG image

Replace `public/og-image.png` (1200×630). The source SVG is at `public/og-image.svg` — edit and regenerate: `rsvg-convert -w 1200 -h 630 public/og-image.svg -o public/og-image.png`.

---

## Environment variables

Copy `.env.example` to `.env` and edit:

| Variable | Default | Purpose |
|---|---|---|
| `PUBLIC_SITE_URL` | `https://templates.allanninal.dev` | Canonical URL for OG images and sitemap |
| `PUBLIC_BASE_PATH` | `/github-readme-profile/` | URL base path; set to `/` for custom domain |
| `PUBLIC_TEMPLATE_HUB_URL` | _(blank)_ | When set, shows the "Download / All 365" bar. Leave blank on your fork. |
| `PUBLIC_AUTHOR_DONATE_URL` | `https://ko-fi.com/allanninal` | Small Ko-fi attribution in footer. Set blank to hide. |
| `PUBLIC_USER_DONATE_URL` | _(blank)_ | Your own donate URL. Set if you want a prominent donate CTA. |

---

## Donations

This template is free and MIT-licensed.

- The repo's GitHub "Sponsor" button is driven by `.github/FUNDING.yml` — edit it to point at your Ko-fi handle, or delete it to hide the button.
- The footer Ko-fi attribution renders when `PUBLIC_AUTHOR_DONATE_URL` is set. To remove or repoint it, edit that env var (blank = hidden).
- To show a prominent donate button on your own deploy, set `PUBLIC_USER_DONATE_URL`.
- The donate link lives in `src/pages/index.astro` inside the `<footer>` block.

---

## Testing

```bash
# Full suite (build + Playwright + links + Lighthouse):
npm run test:all

# Playwright only (interactive + a11y + responsive):
npm run test

# A11y only:
npm run test:a11y

# Broken-link check (runs against dist/):
npm run test:links

# Lighthouse CI (≥95 on all 4 categories):
npm run test:lighthouse

# Interactive UI test runner:
npm run test:ui
```

### What each suite covers

| Suite | File | Coverage |
|---|---|---|
| Pages | `tests/pages.spec.ts` | Every route renders, has h1/nav/footer, no console errors |
| Interactions | `tests/interactions.spec.ts` | Form inputs, tech chips, tab switching, copy/download, persona presets, FAQ accordion, toggles |
| Responsive | `tests/responsive.spec.ts` | 375 / 768 / 1280 / 1920 px — no horizontal overflow |
| Theme | `tests/theme.spec.ts` | Dark palette holds under both light and dark color-scheme emulation |
| A11y | `tests/a11y.spec.ts` | axe-core WCAG 2.1 AA on every route × both color schemes |
| Links | `tests/links.spec.ts` | No broken internal links; external `target="_blank"` links have `rel="noopener noreferrer"` |
| TemplateInfo | `tests/template-info.spec.ts` | Download bar renders, all 4 hrefs correct, zero github.com links inside the bar |

### Adding tests when you add features

- New page: add the route to `tests/helpers.ts` `ROUTES` array, and add a row to `tests/pages.spec.ts`.
- New interaction (button, toggle, form field): add a `test(...)` block in `tests/interactions.spec.ts`.
- New tech chip: no test change needed — chip toggle behavior is covered by the existing tech chip test.

---

## License

MIT — use for personal, commercial, or client work. No attribution required (though appreciated).

---

Built by [Allan Ninal](https://www.linkedin.com/in/allanninal/) · Part of the [365 free static templates](https://templates.allanninal.dev) series.
