Badges

Automatically render project badges into readme and documentation files, with consistent styling.

Publishing Status

Development Status

Documentation/Help

There's a wealth of status badges available out there, but even using a service like https://shields.io still doesn't cover everything and what it covers can be missing functionality…

…how about handling differences in your published and development branches?

…and, of course, you want it all looking organised and consistent, as much as possible…

Doing it properly means too much faffing about, despite it being useful to have 'at-a-glance' status reporting. This module is my attempt to cover off all that badge work into something I can simply include in package.json and move on.

If there are badges you'd like to see included, add an issue above, or better still a PR and I'll add it.

Usage

Installation

npm install --save @thebespokepixel/badges

Example

With this source.markdown:

  Badges:
  ${badges}

Read it in as a template and merge the AST:

/* Import the module… */
import {readFileSync} from 'fs'
import _ from 'lodash'
import remark from 'remark'
import badges from 'badges'

/* …then read the 'badges.readme' stanza from package.json and send the AST into remark etc. */
const content = {
  badges: await badges('readme')
}

const template = _.template(readFileSync('./source.markdown'))
const page = await remark().process(template(content))

Supported badges

• Status (plus similar aux1 and aux2)
• Travis (.org and .com)
• Travis private repos (requires a travis private repo token)
• Libraries.io [New]
• Code Climate and Code Climate Coverage (requires a codeclimate repo token)
• Inch CI
• npm
• Rollup
• Snyk
• Gitter
• Twitter

David has been dropped as it seems the site is now dead.

Configuration

In package.json...

...
"badges": {
  "name": "badges", // Package name
  "github": "thebespokepixel", // github user
  "npm": "thebespokepixel", // npm user
  "libraries-io": "TheBespokePixel", // libraries-io github user (seems to use the name)
  "twitter": "thebespokepixel", // twitter user (optional, defaults to github user name)
  "devBranch": "develop", // Development branch name (optional, defaults to 'develop')
  "codeclimate": "a0a755b0fce22eb0b784", // codeclimate repo token (optional)
  "travis": "1a2b3c4d", // Travis 'Pro' private repo token (optional)
  "providers": { // Non-default badge provider configuration
    "status": {
      "text": "beta",
      "color": "blue"
    },
    "aux1": {
      "title": "github",
      "text": "source",
      "color": "4E73B6",
      "link": "https://github.com/MarkGriffiths/badges"
    }
  }
  "readme": { // Section with subtitles as map of arrays
    "Status": [
      [ "status", "npm", "travis-com", "libraries-io-npm" ],
    ],
    "Dev Status": [
      [ "travis-com-dev", "libraries-io-repo" ],
      [ "code-climate", "code-climate-coverage", "snyk" ]
    ],
    "Documentation/Help": [ "inch", "twitter" ]
  },
  "docs": [ // Lines as an array of arrays
    [ "aux1", "travis" ],
    [ "code-climate", "code-climate-coverage" ],
    [ "libraries-io-npm" ]
  ]
}

Full list

ID	Badge Description	Link
status	Generic status
aux-1	Generic aux 1
aux-2	Generic aux 2
gitter	Gitter chat badge	https://gitter.im
code-climate	Code Climate Maintainability	https://codeclimate.com
code-climate-coverage	Code Climate Coverage
libraries-io-npm	Libraries.io latest release dependency status badge	https://libraries.io
libraries-io-repo	Libraries.io repo deep dependency status badge (dev branch)
inch	Inch-CI doumentation coverage	https://inch-ci.org
inch-dev	Inch-CI doumentation coverage (dev branch)
npm	NPM published version	https://www.npmjs.com
rollup	Show Rollup/Treeshaking module/mjs support	https://rollupjs.org/guide/en/
snyk	Show Snyk Vulnerablilities	https://snyk.io
travis	Travis.org build status	https://travis.org
travis-dev	Travis.org build status (dev branch)
travis-com	Travis.com build status	https://travis.com
travis-com-dev	Travis.com build status (dev branch)
travis-pro	Travis.com build status with private token
travis-pro-dev	Travis.com build status with private token (dev branch)

Where possible, https://shields.io is used, or shields.io 'flat' styling is chosen where available from other providers.