{"id":15288519,"url":"https://github.com/clpsplug/jekyll-shields_io","last_synced_at":"2026-01-31T23:39:20.163Z","repository":{"id":65936234,"uuid":"602137711","full_name":"Clpsplug/jekyll-shields_io","owner":"Clpsplug","description":"Placing shields.io badges in your Jekyll blog, made more readable","archived":false,"fork":false,"pushed_at":"2023-03-14T12:58:00.000Z","size":68,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"base","last_synced_at":"2025-06-09T02:25:46.316Z","etag":null,"topics":["jekyll","plugin","shieldsio"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/jekyll-shields_io","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Clpsplug.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-15T15:19:07.000Z","updated_at":"2024-04-17T20:26:41.000Z","dependencies_parsed_at":"2025-02-12T08:45:07.309Z","dependency_job_id":"53d5c804-b784-4bd8-9e93-4e009e30c899","html_url":"https://github.com/Clpsplug/jekyll-shields_io","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Clpsplug/jekyll-shields_io","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fjekyll-shields_io","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fjekyll-shields_io/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fjekyll-shields_io/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fjekyll-shields_io/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Clpsplug","download_url":"https://codeload.github.com/Clpsplug/jekyll-shields_io/tar.gz/refs/heads/base","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Clpsplug%2Fjekyll-shields_io/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259606977,"owners_count":22883559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["jekyll","plugin","shieldsio"],"created_at":"2024-09-30T15:49:52.789Z","updated_at":"2026-01-31T23:39:20.121Z","avatar_url":"https://github.com/Clpsplug.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jekyll-shields_io\n\n\u003e **Adding shields (badges) to your Jekyll blog, made more readable**\n\n![Ruby 2.7 and 3.1 supported](https://img.shields.io/badge/Ruby-2.7%20%7C%203.1-%23CC342D?logo=ruby)\n![Jekyll 3.5 through 4.3 supported](https://img.shields.io/badge/Jekyll-3.5%20~%204.x-%23CC0000?logo=jekyll)\n![Test status](https://github.com/clpsplug/jekyll-shields_io/actions/workflows/test.yml/badge.svg)\n\nThis is a Jekyll plugin to generate a [Shields.io](https://shields.io) badge in your Jekyll blog\nwith a more readable way.\n\nShields.io takes the properties of the badges you want to make in forms of GET parameters like so:\n\nhttps://img.shields.io/static/v1?label=Find%20me%20on\u0026message=GitHub\u0026color=181717\u0026style=flat\u0026logo=github\n\nThis URL would become this:\n![A badge that says Find me on GitHub](https://img.shields.io/static/v1?label=Find%20me%20on\u0026message=GitHub\u0026color=181717\u0026style=flat\u0026logo=github)\n\nThis plugin exists because this URL was too long for me to debug.\n\nInstead, this plugin accepts parameters structured as a JSON:\n\n```liquid\n\u003c!-- When using in Markdown, you need to use `{%- tag -%}` syntax - see \"Usage\" section --\u003e\n{% shields_io {\n  \"label\": \"Find me on\",\n  \"message\": \"GitHub\",\n  \"color\": \"181717\",\n  \"style\": \"flat\",\n  \"logo\": \"github\",\n}\n%}\n```\n\n## Installation\n\n1. Introduce this gem in your Gemfile\n    ```ruby\n    group :jekyll_plugins do\n      # Latest release\n      gem \"jekyll-shields_io\"\n      # \"HEAD\" version\n      gem \"jekyll-shields_io\", git: \"https://github.com/clpsplug/jekyll-shields_io\", branch: \"base\"\n    end\n    ```\n2. `bundle install`\n3. Add the plugin to your `_config.yml`\n    ```yaml\n    plugins:\n      - jekyll-shields_io\n    ```\n\n## Usage\n\nThe tag name is `shields_io`.\nThe JSON payload for your shield follows the tag name.\nYou can put newlines in your JSON for readability.\n\nDepending on where you use the tag, you need to use one of the following tag syntaxes:\n\n### Using the tag in Liquid template / HTML\n(i.e., the file name is either `*.html` or `*.liquid`)\n```liquid\n{% shields_io {\n  \"label\": \"Find me on\",\n  \"message\": \"GitHub\",\n  \"color\": \"181717\",\n  \"style\": \"flat\",\n  \"logo\": \"github\",\n}\n%}\n```\n\n### Using the tag in Markdown\n(i.e., the file name is `*.md`)  \nFor markdown files, this syntax is required because the other one causes the shields `\u003cimg\u003e` tags to be escaped.\n```liquid\n\u003c!-- Note the \"hyphen\" (-) after the percentage sign (%) --\u003e\n{%- shields_io {\n  \"label\": \"Find me on\",\n  \"message\": \"GitHub\",\n  \"color\": \"181717\",\n  \"style\": \"flat\",\n  \"logo\": \"github\",\n}\n-%}\n```\n\n## Supported parameters\n\n| key     | content                                                                                                                                                                                                                                     | required?                    |\n|:--------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------|\n| message | The right-side text of the shield.                                                                                                                                                                                                          | YES                          |\n| alt     | The alternative text for the image. This _should_ be specified for accessibility reasons and when the service fails for any reason.                                                                                                         | NO, but strongly recommended |\n| label   | The left-side text of the shield. If left, it will be \"static\"                                                                                                                                                                              | NO                           |\n| color   | The color of the right side (some styles may ignore this value.) This can be color name (see [Shields.io](https://shields.io/) for supported names) or hex color code. Hex color codes _must not_ contain `#`. If left, 'inactive' is used. | NO                           |\n| style   | The shield style, see [Shields.io](https://shields.io) for valid values. If left, 'plastic' is used.                                                                                                                                        | NO                           |\n| logo    | Service name or Simple Icons icon name; display on the left of the leftside text.                                                                                                                                                           | NO                           |\n| href    | A URL. Specifying this key will turn the shield into a clickable link                                                                                                                                                                       | NO                           |\n\n## Features\n\n### Debuggable shield parameters\n\nYou can specify the parameters passed to Shields.io using JSON,\nwhich prevents accidental and hard-to-spot mistakes.\n\n### Automatic caching\n\nThe shields are only fetched at the first time it is rendered during site builds.  \n\nThis plugin creates a `_cache` directory in the blog's source directory\n(which is the project root by default, can be configured with `source` config value)\nand stores fetched shields, and then deploys them into the blog's `asset/img/shields` folder\nto prevent unnecessary external HTML requests.\n\nDeployment is done build-time, so it does not mess with your blog source\n(other than creating `_cache` dir).\n\n### Extra parameters for your convenience\n\n#### Make it a link\n\nWith the extended parameter `href`, you can instantly turn the shield\ninto a clickable link.\n\n```liquid\n{% shields_io {\n  \"label\": \"Find me on\",\n  \"message\": \"GitHub\",\n  \"color\": \"181717\",\n  \"style\": \"flat\",\n  \"logo\": \"github\",\n  \"href\": \"https://github.com/clpsplug/jekyll-shields_io\"\n}\n%}\n```\n\n#### Alternative Texts\n\nSupplying the image with an alternative text is almost mandatory these days;\nthis plugin has an extended parameter `alt` for that purpose.\n\n```liquid\n{% shields_io {\n  \"label\": \"Find me on\",\n  \"message\": \"GitHub\",\n  \"color\": \"181717\",\n  \"style\": \"flat\",\n  \"logo\": \"github\",\n  \"alt\": \"Write your alternative text here\"\n}\n%}\n```\n\n## NOTE: i18n plugin compatibility\n\nThis plugin tries to detect i18n plugin [Polyglot](https://github.com/untra/polyglot) when deploying shields to the assets folder;\nthis is done so that we don't accidentally deploy the shields for each language version of your site\n(because usually you would have one `asset` folder that all the language versions would access.)  \n\nIf you use other i18n plugins, the plugin may fail to spot that such i18n plugin is generating non-main language version of the site\nand incorrectly deploy cached shields to those versions.  \nIf you happen to see this behavior, please report it or send me a PR so that we can make this plugin compatible with that one!\n\n## Contributing\n\nBug reports \u0026 pull requests are welcome on [GitHub repo](https://github.com/clpsplug/jekyll-shields_io).\n\n### Development setup\n\nTo set up the plugin development env only:\n```sh\ngit clone https://github.com/Clpsplug/jekyll-shields_io.git\n# OR\ngit clone git@github.com:Clpsplug/jekyll-shields_io.git\n# OR \ngh repo clone Clpsplug/jekyll-shields_io\n\n# Get dependencies\nbundle install\n# Run checks that are run on Github Actions\nrake\n# Run test for latest Jekyll available in your environment\nrake spec\n# Check code style using \"standard\" gem\nrake standard\n\n# To test every supported Jekyll \u0026 Ruby combination:\nbundle exec appraisal install\nbundle exec appraisal rake spec\n```\n\nWhen contributing, please at least run `rake` and check that \nno issues are raised from \"standard\" gem and that specs passes!  \n(If you're having trouble passing the specs, don't hesitate note so in the PR.)\n\nTo test the plugin with real Jekyll environment, \nfollow the [Installation](#installation) guide except for adding a line to Gemfile.  \nYou will need to add this line to your Gemfile instead:\n```ruby\ngem \"jekyll-shields_io\", path: \"\u003cWherever you have this repository, can be relative path\u003e\"\n# for example\ngem \"jekyll-shields_io\", path: \"../jekyll-shields_io\"\n```\n\n## License\n\n[MIT License](https://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclpsplug%2Fjekyll-shields_io","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclpsplug%2Fjekyll-shields_io","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclpsplug%2Fjekyll-shields_io/lists"}