HF_README.md

# GitHub Readme Stats on Hugging Face Spaces

Dynamically generate GitHub statistics cards for your profile README. This is a Hugging Face Spaces deployment of [github-readme-stats](https://github.com/anuraghazra/github-readme-stats).

## Quick Start (Docker SDK)

1. **Create a new Space**:
   - Go to https://huggingface.co/spaces
   - Click "Create new Space"
   - Choose **Docker** as the SDK
   - Choose **Blank** as the template

2. **Upload the files**:
   - Clone this repo or upload files via git:
   ```bash
   git clone https://github.com/anuraghazra/github-readme-stats.git
   cd github-readme-stats
   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
   git push hf main
   ```

3. **Add a GitHub Personal Access Token** as a secret:
   - Go to Settings > Variables and Secrets
   - Create a new secret named `PAT_1` with your GitHub token
   - [Create a GitHub token here](https://github.com/settings/tokens) (needs `public_repo` scope)

3. **(Optional) Add your username to the whitelist**:
   - Create a secret named `WHITELIST` with your GitHub username
   - Example: `yourusername`

4. **Wait for the Space to start** - it may take a minute to build

## Usage

Once your Space is running, use the API endpoints in your README:

### Stats Card
```markdown
![Stats](https://your-space-name.hf.space/api?username=yourusername)
```

### Top Languages
```markdown
![Top Languages](https://your-space-name.hf.space/api/top-langs?username=yourusername)
```

### Pinned Repositories
```markdown
![Pinned Repos](https://your-space-name.hf.space/api/pin?username=yourusername&repo=your-repo)
```

## Configuration Secrets

| Secret | Description | Default |
|--------|-------------|---------|
| `PAT_1` | GitHub Personal Access Token | Required |
| `WHITELIST` | Comma-separated allowed usernames | `*` (all) |
| `CACHE_SECONDS` | Cache duration in seconds | `14400` (4 hours) |

## All Available Endpoints

| Endpoint | Description |
|----------|-------------|
| `/api` | Generate stats card |
| `/api/pin` | Generate pinned repo card |
| `/api/top-langs` | Generate top languages card |
| `/api/gist` | Generate gist card |
| `/api/wakatime` | Generate WakaTime stats card |

See the [original documentation](https://github.com/anuraghazra/github-readme-stats) for all available parameters and themes.

## Technical Details

- **SDK**: Docker (Blank template)
- **Runtime**: Node.js 22+
- **Framework**: Express.js
- **Default Port**: 7860 (Hugging Face Spaces standard)