Monkeytype Stats in Github Readme

Table of Contents

Show / hide

• Monkeytype Stats in Github Readme
  • Table of Contents
  • Changelog
  • Demo
  • Preparation
    • Static Usage
    • Dynamic Github Readme Update
      • 1. Readme Resource Declaration
      • 2. Monkeytype API Key
  • Github Action Workflow
    • Edge Cases
  • Endpoint Documentation
  • Contributing

Changelog

Demo

(Sometimes it takes a bit of time or some browser refresh for the badges below to all appear. If someone knows why let me know ^_^)

Style variants: show / hide

style	demo
flat
flat-square
plastic
for-the-badge

Icon variants: show / hide

icon	demo
one
two

Preparation

Static Usage

Show / hide

This project's strategy relies on shields.io endpoint api. For one time & static badge, follow the steps below.

1. Edit this endpoint to your liking:

   https://monkeytype-badge-vhd5lan7mmhz.runkit.sh?message=...&label=...&logoVariant=...
   

   See Endpoint Documentation for more details about the query params.

2. Parse (1) and use shields.io endpoint helper to further customize your badge.

   

Dynamic Github Readme Update

Show / hide

1. Readme Resource Declaration

Put the following at the bottom of your README. This is a default badge that will get updated by the github action...

[monkeytype.badge]: https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fmonkeytype-badge-vhd5lan7mmhz.runkit.sh

You can display this badge somewhere in your readme as below

<!-- For just the image -->
![!monkeytype.badge]

<!-- For clickable image that links to monkeytype website -->
[![monkeytype.badge]](https://monkeytype.com/)

2. Monkeytype API Key

Go to monkeytype.settings, search for the ape key section, then generate and save an API Key somewhere for the next step. Remember to activate your key at the end to (might be a little checkbox at the left).

Add this key as a Action secret in your repo's settings.

Now follow the next section to set up a github workflow.

Github Action Workflow

See action.yaml for description about the inputs.

I recommend keeping the workflow_dispatch trigger so you can run the action manually whenever you want.

Since personal bests don't change that often, in the example I leave it to run once every week. But you can use the crontab-guru site to adjust as needed.

Example: show / hide

# .github/workflow/monkeytype.yaml
name: Monkeytype Readme

on:
  # Runs if triggered manually through github action console
  workflow_dispatch:
  schedule:
    # Runs at 00:00 each sunday
    - cron: '0 0 * * 0'

jobs:
  update-readme:
    name: Update README
    runs-on: ubuntu-latest
    # it shouldn't take longer than a few minutes
    # but leave a timeout here in case request hangs
    timeout-minutes: 10
    steps:
      - uses: vnphanquang/monkeytype-readme@main
        with:
          # required:
          monkeytype_api_key: ${{ secrets.MONKEYTYPE_API_KEY }}
          mode: 'time'
          mode2: '30'
          # not required with default:
          style: 'flat' # option from shields.io
          logoVariant: 'one'
          label: 'monkeytype'
  # outputs badge_url should you need to use that in later steps

Edge Cases

Some edge cases to expect:

• If your personal best stays the same at the time the action runs, no update should be made to README (the action still succeeds but it should have skipped that step).
• If an invalid mode / mode2 is passed, the action should fail with a MonkeytypePersonalBestNotFoundError error.
• In case monkeytype server is down, the action should also fail.
• In case runkit server is down, a generic error badge from shields.io should be displayed.
• If any of the above server hangs, the action should timeout (provided you include a timeout-minutes input in the action).

If you encounter other edge cases not covered above, please open an issue to let me know. Thanks a lot!

Endpoint Documentation

See the code on runkit. The endpoint is:

https://monkeytype-badge-vhd5lan7mmhz.runkit.sh

Query params: show / hide

name	required	default	description
message	no	calculating	message to display on the badge, usually something like '120wpm'
logoVariant	no	one	the logo variant to use, see Demo. Accepts only the string one or two
label	no	monkeytype	the text next to the icon

Contributing

Read Contribution Guide