Readme Contribs

Simple embeddable contributor and sponsor widgets for your GitHub README

🌐 readme-contribs.as93.net

Contents

• About
  • Motivation
• Usage
  • Embedding
  • Base Domain
  • Embed Contributors
  • Embed Sponsors
  • Embed Stargazers
  • Embed Forkers
  • Image Options
• Deploying your Own
• Developing
• Examples
• Web Interface
• Attributions
  • Contributors
  • Sponsors
• License

---

About

Motivation

It's nice to give credit to contributors and supporters who've helped your project 💞

But using GitHub Actions to generate these causes your commit history to become unnecessarily cluttered. And existing services to embed contributor widgets aren't very customizable and don't support sponsors or stargazers.

My aim with this project, is to provide an easy way for you to embed your projects contributors, sponsors, stargazers, etc, and to let you configure the look and feel. You can also easily deploy this project to Vercel, so you'll never need to worry about the managed instance becoming unavailable. ↳ See Examples

---

Usage

Embedding

To embed the image in your markdown, simply use the endpoint as the image URL.
For example:

![Sponsors](https://readme-contribs.as93.net/sponsors/lissy93)

Base Domain

The following API routes are to be made from the base domain.
For the public instance, use https://readme-contribs.as93.net.
If you're hosting your own instance, update this to your domain.

Embed Contributors

/contributors/[user]/[repo]

Embed Sponsors

/sponsors/[user]

Embed Stargazers

/stargazers/[user]/[repo]

Embed Forkers

/sponsors/[user]/[repo]

Image Options

You can customize the outputed image, it's appearence and functionality with the following options.
Specify these as query string parameters, appended to the end of your GET request. All values are optional.

Parameter	Description	Type	Default Value
title	The title to be displayed above the widget	String	'' (Empty string = no title)
avatarSize	Minimum size of avatars	Integer	50
perRow	Maximum number of avatars per row	Integer	8
shape	Shape of the avatar images (square, circle, squircle)	Enum	square
hideLabel	If set to true, name labels will not be displayed	Boolean	false
fontSize	Font size for label text	Integer	12
fontFamily	Font family for the text	String	'Mona Sans', Verdana, sans-serif
textColor	Color of the text (as hex code excluding # or color name)	String	333333 (exclude the #)
backgroundColor	Background color of the widget	String	transparent
limit	Maximum number of items to display	Integer	100
outerBorderWidth	Width of the outer border	Integer	0
outerBorderColor	Color of the outer border	String	'' (Empty string = no border)
outerBorderRadius	Radius of the outer border corners	Integer	0
margin	Margin around each avatar	Integer	20
textOffset	Offset for text alignment below avatars	Integer	20
svgWidth	Width of the entire SVG widget	Integer	500
svgHeight	Height of the entire SVG widget	Integer	500
dynamic	If true, won't base64 encode images, faster (iframe usage only)	Boolean	false
isResponsive	If true, makes the widget responsive	Boolean	false

View the Swagger Docs for more details.

---

Deploying your Own

If you plan to use this at any kind of scale, it is highly reccomended to deploy your own instance.

Don't worry, it's super quick, easy and free!

1. Fork this repository (by clicking here)
2. Login / Sign up to Vercel
3. Create a new app, and select your newly forked repo
4. Create a GitHub API token here
5. Add the GITHUB_TOKEN environmental variable into Vercel
6. Hit deploy!

---

Developing

You can run readme-contribs locally, to make and preview any changes

1. Get the code: git clone git@github.com:Lissy93/readme-contribs.git
2. Navigate into the directory: cd readme-contribs
3. Install dependencies: yarn (or npn install)
4. Start the development server: yarn start
5. Then open the running app at localhost:3000

Don't forget to add your token in the GITHUB_TOKEN environmental variable (or put it in .env)

---

Examples

Example 1

Example 2

Example 3

Example 4

Example 5

Example 6

---

Web Interface

If you're finding constructing the URL, and previewing the different options tricky, you can use our web interface to build your embedable card.

Visit readme-contribs.as93.net to get started.

---

Attributions

Contributors

Sponsors

---

License

Lissy93/README-Contribs is licensed under MIT © Alicia Sykes 2024.
^{For information, see TLDR Legal > MIT}

Expand License

The MIT License (MIT)
Copyright (c) Alicia Sykes <alicia@omg.com> 

Permission is hereby granted, free of charge, to any person obtaining a copy 
of this software and associated documentation files (the "Software"), to deal 
in the Software without restriction, including without limitation the rights 
to use, copy, modify, merge, publish, distribute, sub-license, and/or sell 
copies of the Software, and to permit persons to whom the Software is furnished 
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included install 
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANT ABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

© Alicia Sykes 2024
Licensed under MIT

^{Thanks for visiting :)}