[Guide] Adding badges to a mod's github readme

[pfg]

Some github projects have badges that give you information about the project like number of open issues or number of users. The factorio mods page has an API where you can get some of this info. Using https://shields.io you can get badges from your mod page.

To use, replace YOUR-MOD with your mod

Download Count:

Code: Select all

![https://mods.factorio.com/mod/YOUR-MOD](https://img.shields.io/badge/dynamic/json.svg?label=downloads&url=https%3A%2F%2Fmods.factorio.com%2Fapi%2Fmods%2FYOUR-MOD&query=%24.downloads_count&colorB=%23a87723)

Latest version of factorio released for:

Code: Select all

![https://mods.factorio.com/mod/YOUR-MOD](https://img.shields.io/badge/dynamic/json.svg?label=factorio%20version&url=https%3A%2F%2Fmods.factorio.com%2Fapi%2Fmods%2Fliquid-science&query=%24.releases%5B-1%3A%5D.info_json.factorio_version&colorB=%23a87723)

Version of the mod:

Code: Select all

![https://mods.factorio.com/mod/YOUR-MOD](https://img.shields.io/badge/dynamic/json.svg?label=version&url=https%3A%2F%2Fmods.factorio.com%2Fapi%2Fmods%2FYOUR-MOD&query=%24.releases%5B-1%3A%5D.version&colorB=%23a87723)

These badges will link to your mod page and sometimes update to show up to date statistics about your mod

To generate other ones you can scroll to the Dynamic section on https://shields.io and enter these values:

Data Type: JSON
Name: This is the text before the number, like "downloads" 510
URL: https://mods.factorio.com/api/mods/YOUR-MOD
Query: One of these

Code: Select all

$.downloads_count - The number of downloads
$.name - The name of the project
$.owner - The owner of the project
$.title - The title of the project

$.releases[0].version - The version of the first release
$.releases[0].info_json.factorio_version - The factorio version of the first release
$.releases[-1:].version - The version of the latest release
$.releases[-1:].info_json.factorio_version - The factorio version of the latest release

If there's something else you want to get, look at the json at https://mods.factorio.com/api/mods/YOUR-MOD and use a path from https://www.npmjs.com/package/jsonpath



Hex Color: Choose a color from https://www.google.com/search?q=color+picker and copy the value starting with a #

[slindenau]

Great guide, i've applied it to the github page of my mod. Works like a charm!

Some comments and remarks:
- The API of the mod portal page has been made public recently, see for more details: https://wiki.factorio.com/Mod_portal_API
- With this update the "downloads" number has also been changed from "total downloads" to "unique downloads", so it will be a lot lower. I suggest reflecting this change in the name of the badge
- In the example markdown code for the "factorio version" badge the SVG still links to your own mod (liquid-science) instead of YOUR-MOD
- On GitHub the images become hyperlinks to the pictures instead of what i assume should be the mod-portal page? I didn't investigate this further as it didn't really bother me.
- The images on GitHub are cached by their own proxy ("Camo"), this proxy respects any cache related headers. The shields io badges have all the required headers, so new values will indeed update "sometimes". See https://docs.github.com/en/authenticati ... mized-urls

[Sharparam]

- On GitHub the images become hyperlinks to the pictures instead of what i assume should be the mod-portal page? I didn't investigate this further as it didn't really bother me.

This is just due to GitHub turning pure image tags into links to the image if not wrapped within an explicit link. In regular markdown the snippets in OP's post would just turn into images without a link.

So you'd have to wrap them in a link to the mod page:

Code: Select all

[![image alt text](image-url)](https://mods.factorio.com/mod/YOUR-MOD)