Clpsplug/README.md

## README.md

      
    Raw
  

              README.md
            
          
    The shields_to Custom Jekyll Liquid Tag

What

Shields.IO is a web service to create a 'badge' you may find in a README in many GitHub repositories.

All you need to craft is a URL, and the service will interpret your request.
Example shield by URL

https://img.shields.io/static/v1?label=Find%20me%20on&message=GitHub&color=181717&style=flat&logo=github


There is one issue with this approach; the URL is too long to handle for human.

I wrote these files to create a Liquid tag for Jekyll that makes it easier to create those shields.
How to use

Copy custom-tags.rb into $SOURCE_DIR/_plugins directory, where $SOURCE_DIR is . (your Jekyll project root) by default
and may change if you have source key in your _config.yml.
A restart of bundle exec jekyll serve is required should you be running one already.
The syntax is:
{% shields_io <JSON here> %}
The idea is to pass a JSON object consisting of query parameters.
{
  "href": "https://www.github.com/clpsplug",
  "label": "Find me on",
  "message": "GitHub",
  "color": "181717",
  "style": "flat",
  "logo": "github",
  "alt": "GitHub"
}


key
required?
content


href
NO
A URL. Specifying this key will turn the shield into a clickable link


label
NO
The leftside text of the shield. If left, it will be "static"


message
YES
The rightside text of the shield.


color
NO
The color of the right side (some styles may ignore this value.) This can be color name (see Shields.io for supported names) or hex color code. Hex color codes must not contain #. If left, 'inactive' is used.


style
NO
The shield style, see Shields.io for valid values. If left, 'plastic' is used.


logo
NO
Service name or Simple Icons icon name; display on the left of the leftside text.


alt
NO, but strongly recommended
The alternative text for the image. This should be specified for accessibility reasons and when the service fails for any reason.


Notes


JSON payload should be passed without being surrounded by quotes; quotes will break them.
Liquid tags can span across multiple lines, so it is safe to prettify your JSON.

License

MIT

  
## custom-tags.rb
require 'json'

module Jekyll
  class ShieldsIOTag < Liquid::Tag
    def initialize(tag_name, input, parse_context)
      super
      # @type [Hash]
      @config = JSON.parse input.strip, { symbolize_names: true }
    end

    def render(_context)
      href = @config[:href]
      alt = @config[:alt]
      @config.delete(:href)
      @config.delete(:alt)
      shield_tag = <<HTML
      <img src="https://img.shields.io/static/v1?#{config_to_query}"
HTML
      if alt != nil
        shield_tag += " alt=\"#{alt}\" />"
      else
        shield_tag += " />"
      end
      if href != nil
        <<HTML
<a href="#{href}">
#{shield_tag}
</a>
HTML
      else
        shield_tag
      end
    end

    private
    def config_to_query
      @config.to_a.map { |k, v|
        "#{k}=#{v}"
      }.join '&'
    end
  end
end

Liquid::Template.register_tag('shields_io', Jekyll::ShieldsIOTag)

## example.liquid
---
layout: your_layout
---

<p>
    {% shields_io {
        "href": "https://www.github.com/clpsplug",
        "label": "Find me on",
        "message": "GitHub",
        "color": "181717",
        "style": "flat",
        "logo": "github",
        "alt": "GitHub"
        } %}
</p>
key	required?	content
href	NO	A URL. Specifying this key will turn the shield into a clickable link
label	NO	The leftside text of the shield. If left, it will be "static"
message	YES	The rightside text of the shield.
color	NO	The color of the right side (some styles may ignore this value.) This can be color name (see Shields.io for supported names) or hex color code. Hex color codes must not contain `#`. If left, 'inactive' is used.
style	NO	The shield style, see Shields.io for valid values. If left, 'plastic' is used.
logo	NO	Service name or Simple Icons icon name; display on the left of the leftside text.
alt	NO, but strongly recommended	The alternative text for the image. This should be specified for accessibility reasons and when the service fails for any reason.
	require 'json'

	module Jekyll
	class ShieldsIOTag < Liquid::Tag
	def initialize(tag_name, input, parse_context)
	super
	# @type [Hash]
	@config = JSON.parse input.strip, { symbolize_names: true }
	end

	def render(_context)
	href = @config[:href]
	alt = @config[:alt]
	@config.delete(:href)
	@config.delete(:alt)
	shield_tag = <<HTML
	<img src="https://img.shields.io/static/v1?#{config_to_query}"
	HTML
	if alt != nil
	shield_tag += " alt=\"#{alt}\" />"
	else
	shield_tag += " />"
	end
	if href != nil
	<<HTML
	<a href="#{href}">
	#{shield_tag}
	</a>
	HTML
	else
	shield_tag
	end
	end

	private
	def config_to_query
	@config.to_a.map { \|k, v\|
	"#{k}=#{v}"
	}.join '&'
	end
	end
	end

	Liquid::Template.register_tag('shields_io', Jekyll::ShieldsIOTag)
	---
	layout: your_layout
	---

	<p>
	{% shields_io {
	"href": "https://www.github.com/clpsplug",
	"label": "Find me on",
	"message": "GitHub",
	"color": "181717",
	"style": "flat",
	"logo": "github",
	"alt": "GitHub"
	} %}
	</p>