Open Source Contributions Card Generator

A modern web application that generates beautiful, shareable cards showcasing your open source contributions on GitHub. Perfect for adding to your README files, portfolios, or social media.

🎯 Features

• 🎨 Beautiful Card Generation - Creates stunning, dynamic contribution cards
• ⚡ Real-time Preview - See your card instantly as you type
• 🏢 Organization Filtering - Remove specific organizations from your contributions
• 📋 Multiple Export Formats - Copy as Markdown or direct URL
• ✨ Zero Configuration - Just enter your GitHub username
• 🚀 Fast & Responsive - Built with Next.js for optimal performance
• 🌙 Dark Theme - Modern, eye-catching GitHub-inspired design

🛠️ Tech Stack

• Framework: Next.js 14+ - React framework with App Router
• Language: TypeScript - Type-safe development
• Styling: Tailwind CSS - Utility-first CSS framework
• Icons & Effects: Custom CSS gradients and animations
• API: GitHub API integration for fetching user data

⚙️ Prerequisites

• Node.js 18+
• npm
• GitHub API access (for card generation)

📦 Installation

1. Clone the repository

   git clone git@github.com:anurag2787/OSS-Markdown.git
   cd OSS-Markdown

2. Install dependencies

   npm install

3. Set up environment variables (if needed for GitHub API)

   cp .env.example .env
   # Edit .env with your GitHub token

4. Start the development server

   npm run dev

5. Open in browser Navigate to http://localhost:3000 to see the application

🚀 Usage

Basic Usage

1. Enter your GitHub username in the input field
2. (Optional) Add organizations you want to exclude from the card
3. Click "Generate" or press Enter
4. See the real-time preview of your card
5. Choose between Markdown or Direct URL format
6. Copy the content to your clipboard
7. Paste it in your README.md or anywhere you want to showcase your contributions

Examples

Markdown Format (Perfect for README files):

![Open Source Contributions](https://ossmarkdown.vercel.app/api/card/[your-github-username])

Direct URL (For sharing or embedding):

https://ossmarkdown.vercel.app/api/card/[your-github-username]

With Organization Filtering (Remove specific orgs):

![Open Source Contributions](https://ossmarkdown.vercel.app/api/card/[your-github-username]?remove=org1,org2)

📁 Project Structure

OSS-Markdown/
├── app/
│   ├── api/
│   │   ├── card/
│   │   │   └── [username]/
│   │   │       └── route.tsx          # Card generation endpoint
│   │   └── github/
│   │       └── [username]/
│   │           └── route.ts           # GitHub data fetching
│   ├── fonts/                         # Custom font files
│   ├── page.tsx                       # Main UI component
│   ├── layout.tsx                     # Root layout
│   └── globals.css                    # Global styles
├── lib/
│   └── github.ts                      # GitHub API utilities
├── package.json                       # Project dependencies
├── tsconfig.json                      # TypeScript configuration
├── tailwind.config.ts                 # Tailwind CSS configuration
└── next.config.mjs                    # Next.js configuration

🔌 API Endpoints

Card Generation Endpoint

GET /api/card/[username]?remove=[organizations]

Parameters:

• username (required): GitHub username
• remove (optional): Comma-separated list of organizations to exclude

Response: SVG or HTML card image

GitHub Data Endpoint

GET /api/github/[username]

Parameters:

• username (required): GitHub username

Response: User contribution data in JSON format

🎨 Customization

Styling

• Colors and themes can be modified in app/page.tsx
• Tailwind configuration in tailwind.config.ts

Card Design

• Edit the card generation logic in app/api/card/[username]/route.tsx

📊 How It Works

1. User Input: User enters their GitHub username and optional organization filters
2. API Call: Frontend calls /api/github/[username] to fetch contribution data
3. Card Generation: Backend processes the data and calls /api/card/[username] to generate the card
4. Display: Card is rendered as an image in the preview
5. Export: Users can copy the markdown or direct URL to use anywhere

🔐 Security Considerations

• GitHub API calls are rate-limited
• No personal data is stored on the server
• All user data is fetched from GitHub's public API
• HTTPS recommended for production deployment

🤝 Contributing

Contributions are welcome! Here's how to contribute:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 License

This project is open source and available under the MIT License.

🐛 Troubleshooting

Card not loading

• Check if the GitHub username is correct
• Ensure you're not hitting GitHub API rate limits
• Verify network connectivity

Copy not working

• Check browser permissions for clipboard access
• Try a different browser
• Ensure JavaScript is enabled

Build errors

• Clear .next folder: rm -rf .next
• Reinstall dependencies: rm -rf node_modules && npm install
• Check Node.js version compatibility

📞 Support

For issues, feature requests, or questions:

• Open an Issue
• Check existing issues for solutions
• Provide detailed information about your problem

🎓 Learn More

• Next.js Documentation
• Tailwind CSS Documentation
• GitHub API Documentation
• TypeScript Handbook

⭐ Show Your Support

If you find this project helpful, please give it a star! Your support means a lot.

---

Built with ❤️ for the open source community