Kirchner.io
Back to Compendium

Making GitHub Repos Nice

Shields.io

Shields from GitHub

last commit badge is underrated, it's a great way to see if a project is still maintained or not. others include release, stars, forks, watchers, license, etc.

for repo utkarshkukreti/markup.rs, the badges are:

Build Version Documentation Downloads License

Static Badges

It is possible to use shields.io to make a wide variety of badges displaying static text and/or logos. For example:

  • any text you like
  • just the message
  • 'for the badge' style
  • with a logo

For more info, see:

Logos

SimpleIcons

We support a wide range of logos via SimpleIcons. All simple-icons are referenced using icon slugs. e.g:

You can click the icon title on simple-icons to copy the slug or they can be found in the slugs.md file in the simple-icons repository. NB - the Simple Icons site and slugs.md page may at times contain new icons that haven't yet been pulled into Shields.io yet. More information on how and when we incorporate icon updates can be found here.

Shields logos

We also maintain a small number of custom logos for a handful of services: They can also be referenced by name and take preference to SimpleIcons e.g:

Custom Logos

Any custom logo can be passed in a URL parameter by base64 encoding it. e.g:

logoColor parameter

The logoColor param can be used to set the color of the logo. Hex, rgb, rgba, hsl, hsla and css named colors can all be used. For SimpleIcons named logos (which are monochrome), the color will be applied to the SimpleIcons logo.

In the case where Shields hosts a custom multi-colored logo, if the logoColor param is passed, the corresponding SimpleIcons logo will be substituted and colored.

Spec

Static Badge

The static badge accepts a single required path parameter which encodes either:

  • Label, message and color separated by a dash -. For example:
    • any text: you like
  • Message and color only, separated by a dash -. For example:
    • just the message
URL inputBadge output
Underscore _ or %20Space ``
Double underscore __Underscore _
Double dash --Dash -

Hex, rgb, rgba, hsl, hsla and css named colors may be used.

Path Parameters

badgeContent string — REQUIRED Label, (optional) message, and color. Separated by dashes

Example: build-passing-brightgreen

Query Parameters

  • style string

    • One of: flat (default), flat-square, plastic, for-the-badge, social
    • Example: flat

  • logo string

    • One of the named logos (bitcoin, dependabot, gitlab, npm, paypal, serverfault, stackexchange, superuser, telegram, travis) or simple-icons. All simple-icons are referenced using icon slugs. You can click the icon title on simple-icons to copy the slug or they can be found in the slugs.md file in the simple-icons repository. Further info.
    • Example: appveyor

  • logoColor string

    • The color of the logo (hex, rgb, rgba, hsl, hsla and css named colors supported). Supported for named logos and Shields logos but not for custom logos. For multicolor Shields logos, the corresponding named logo will be used and colored.
    • Example: violet

  • label string

  • Override the default left-hand-side text (URL-Encoding needed for spaces or special characters!)

  • Example: healthiness

  • labelColor string

    • Background color of the left part (hex, rgb, rgba, hsl, hsla and css named colors supported).
    • Example: abcdef

  • color string

    • Background color of the right part (hex, rgb, rgba, hsl, hsla and css named colors supported).
    • Example: fedcba

  • cacheSeconds string

    • HTTP cache lifetime (rules are applied to infer a default value on a per-badge basis, any values specified below the default will be ignored).
    • Example: 3600

  • link string[]

    • Specify what clicking on the left/right of a badge should do. Note that this only works when integrating your badge in an <object> HTML tag, but not an <img> tag or a markup language