Create a gist now

Instantly share code, notes, and snippets.

@LPGhatguy /
Last active Aug 29, 2015

What would you like to do?
An API to generate badges and place them in markdown readme files automatically using


This file is to be used with the example.lua file.

Here, we use Markdown's ability to use shortlink images:

Testing results: ![shield_build] ![shield_tests]

Version information: ![shield_dev_version]

Some projects might link to their latest released versions using the GitHub API: ![shield_release_version] ![shield_prerelease_version]

These links (visible only in plaintext view) are automatically updated by badges.lua. [shield_build]: [shield_tests]: [shield_dev_version]:

These links are not automatically updated, but you can use them as a template with your own repository to have badges that fit in: [shield_release_version]: [shield_prerelease_version]:

A simple API to generate badges and place them in Markdown-driven readme files automatically.
local badges = {
readme_path = "",
shields = {
build = "[shield_build]:",
tests = "[shield_tests]:",
dev_version = "[shield_dev_version]:"
updaters = {
-- Unit test results
function(self, body, data)
local tests = data.tests or {}
local pass = tests.pass or 0
local fail = or 0
local pass_word = "unknown"
local pass_color = "lightgrey"
if (fail == 0 and pass > 0) then
pass_word = "passing"
pass_color = "green"
elseif (fail > 0) then
pass_word = "failing"
pass_color = "red"
local total = pass + fail
local ratio = pass / total
local tests_color =
ratio ~= ratio and "lightgrey" or -- NaN: zero tests
ratio == 1.0 and "brightgreen" or
ratio >= 0.5 and "yellow" or
return body
:gsub("%[shield_build%]:[^\n]*",, pass_color))
:gsub("%[shield_tests%]:[^\n]*", self.shields.tests:format(pass, total, tests_color))
-- Current dev version
function(self, body, data)
return body
:gsub("%[shield_dev_version%]:[^\n]*", self.shields.dev_version:format((data.version:gsub("%-", "--"))))
function badges:update_readme_body(body, data)
for i, updater in ipairs(self.updaters) do
body = updater(self, body, data)
return body
Updates readme with all results from testing and the likes.
status structure:
tests (table):
pass (number)
fail (number)
version (string)
function badges:update_readme(data)
local path = self.readme_path
local handle = assert(, "r"))
local body = handle:read("*a")
local updated = self:update_readme_body(body, data)
local handle = assert(, "w"))
return badges
badges.lua sample
See for how these badges can look on a real project.
local badges = require("badges")
badges.readme_path = "" -- Small configuration
local function main()
local MyLib = require("MyLib")
print("Test Suite for MyLib " .. MyLib._VERSION)
local pass, fail = 0, 0
-- Run your tests here and set the total number of passing tests as 'pass'
-- and the number of failing tests as 'fail'.
print("Tests complete!")
-- Small pretty way to report test results.
print(("Result:\n%-2d pass\n%-2d fail\noverall: %s"):format(
fail == 0 and "PASS" or "FAIL"
-- Call badges.update_readme with our result data
-- Badges will be updated automatically.
badges:update_readme {
tests = {
pass = pass,
fail = fail,
version = MyLib._VERSION
print("README updated successfully!")
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment