Custom Cards

[Zo-Bro-23]

Custom Cards

This PR adds an option to generate custom cards in addition to the GitHub Stats cards! Right now only stats and top languages can be generated, but options will be soon added for wakatime and repo cards!

API Usage

Main endpoint is https://{VERCEL_URL}/api/wild.

Stats Card

Endpoint is /. The following options aren't used:

• username
• exclude_repo
• locale
• count_private
• include_all_commits
• custom_title
• cache_seconds

In addition, the following new options are added (through query params):

• total_stars
• total_commits
• total_prs
• total_issues
• total_contribs
• level (for rank level)
• score (for rank score)
• stars_title
• commits_title
• issues_title
• prs_title
• contribs_title
• title (main title)

Note
total_stars, total_commits, total_prs, total_issues, and total_contribs can be text or numbers. If number, it will be auto-formatted.

Top Languages Card

Endpoint is /top-langs. The following options aren't used:

• username
• langs_count
• exclude_repo
• locale
• custom_title
• cache_seconds

In addition, the following new options are added (through query params):

• title (main title)
• langs - Format is as follows:

{
  "name": "Rap",
  "size": 50,
  "color": "#4287f5",
  "text": "50 Hours"
};
{
  "name": "Pop",
  "size": 20,
  "color": "#eb4034",
  "text": "20 Hours"
}

It's essentially JSON with ; separating the different objects. The object attributes are as follows (same as used internally):

• name - Name of category
• size - An arbitrary size to calculate what percent of the bar to fill
• color - HEX code for the color of the category
• text - Text to add next to the category

name defaults to No Name, size defaults to 0, text defaults to a percentage value of that category (calculated from size), and color defaults to the selected theme's default color.

Repo Card

Endpoint is /pin. The following options aren't used:

• username
• repo
• show_owner
• locale
• cache_seconds

In addition, the following new options are added (through query params):

• title (instead of repo name)
• description (instead of repo description)
• footer (instead of repo language)
• badge - Circular badge color next to repo language or footer
• highlight - Highlight text (usually Template or Archive)
• stars - Star count (can be text or number - number will be auto-formatted)
• forks - Fork count (can be text or number - number will be auto-formatted)

Note
All added options are optional (default to normal titles and random values), and all other options are required as was previously.

Warning
You may use the https://github-readme-stats.zohan.tech deployment to test this PR, but it will constantly be updated as I make changes (so may have errors at some point).

Changelog

• ./vercel.json - Changed maxDuration; ignore for now (used for testing), will revert before PR is published.
• ./src/cards/stats-card.js
  • Restructured kFormatter to allow NaN values too (checks if it's text or number)
  • Replaced i18n titles with generic ones and added titles as parameters for the renderStatsCard() function
  • Replaced specific logic for commits (line 295 old 311 new) with generic logic that is used for all other lines (didn't understand why this was needed - see Don't understand this code #2407)
• ./src/cards/top-languages-card.js
  • Replace i18n titles with generic ones and added title as parameter for the renderTopLanguages() function
  • Restructured kFormatter (stars and forks) to allow NaN values too (checks if it's text or number)
• ./src/cards/repo-card.js
  • Added option for custom highlight text (instead of Template or Archive) through a function param
• Added ./api/wild/index.js - Adds an API endpoint for custom cards like shown above
• Added ./api/wild/top-langs.js - Adds an API endpoint for custom top language cards
• Added ./api/wild/pin.js - Adds an API endpoint for custom repo cards

To Do

• Add other card types
  • Top Languages
  • [x] Wakatime (not needed because Top Languages added support for custom text)
  • Repo
• Add updates to README
• Add tests (probably not needed as renderStatsCard() still works the same, and the new APIs don't add much to the existing ones)
• Ensure that changing renderStatsCard() doesn't affect anything else (other tests, etc)

[vercel]

@Zo-Bro-23 is attempting to deploy a commit to the github readme stats Team on Vercel.

A member of the Team first needs to authorize it.

[Zo-Bro-23]

@anuraghazra @rickstaa thoughts?

[rickstaa]

@Zo-Bro-23 Thanks for your pull request. I like the idea. I, however, have some very busy months ahead due to my graduation, so I can not promise I can review this PR in time. Maybe @anuraghazra can take a look at it.

[Zo-Bro-23]

@anuraghazra ready for review! If possible, I'd like feedback on three things please:

• Parameter names. If you can think of more intuitive variable or parameter names, please let me know. As for that, I think even the API endpoints can be named better, since top-langs doesn't actually list languages anymore!
• API integrations. Can you think of any platforms (besides GitHub) that we can integrate with? Now that we have custom cards, it would be really easy to make stat cards for other platforms like GitHub (I can only think of YouTube at the moment).
• README. I've placed this at the bottom of the README, mostly because I don't want this to be obstructive to the proper documentation near the top. Please let me know where you think this should be placed though, since some people might find this useful (even if they don't scroll all the way down to see it), and others might just find it annoying when they're trying to read the documentation for the actual GitHub Stats. Also, let me know if you have any suggestions for the documentation I've written, since I can always try to make it clearer and better!

Looking forward to reading your reviews; cheers!

[rickstaa]

I don't think giving users the ability to construct their stats and language cards is wise. The idea of having an endpoint where people can create custom cards (i.e. wild) is very cool. I would, however, make the stats and language card items reserved and throw an error if people try to use those.