Skip to content

Latest commit

 

History

History
259 lines (183 loc) · 10.7 KB

README.md

File metadata and controls

259 lines (183 loc) · 10.7 KB
Raw

Readme Contribs

Simple embeddable contributor and sponsor widgets for your GitHub README

🌐 readme-contribs.as93.net

Contents

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

Rust Lang Contributors

Example 2

Dashy Contributors

Example 3

AdGuardian Forkers

Example 4

Lissy93 Sponsors

Example 5

Web Check Stargazers

Example 6

Hot Dog Stand lolz

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

Contributors

Sponsors

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 :)