shield.pug – Developer shields

View source code on Github

---

Shields by urls

mixin shield-urls(image_url, target_url)
  a(href=target_url target="__blank")&attributes(attributes)
    img(src=image_url)

+shield-urls(image_url, target_url)

Insert a shield passing the image url and link href.

Arguments:

• image_url (string) – Image url of the shield.
• target_url (string) – Target url of the shield.

Usage

Input

+shield-urls("https://travis-ci.org/mondeja/pymarketcap.svg?branch=master", "https://cnhv.co/1xgw5")

Output

<a href="https://cnhv.co/1xgw5" target="__blank">
  <img src="https://travis-ci.org/mondeja/pymarketcap.svg?branch=master">
</a>

Render

---

Shields by services

mixin shield(service, project_id)
  - if (attributes)
    - if ("branch" in attributes)
      - branch = attributes.branch;
      - delete attributes.branch;
    - else
      - branch = "master";
    - if ("version" in attributes)
      - version = attributes.version;
      - delete attributes.version;
    - else
      - version = "latest";
    - if ("url" in attributes)
      - url = attributes.url;
      - delete attributes.url;
    - else
      - url = null;
  - else
    - attributes = {};
  - if (service == "travis")
    - url = url || `https://travis-ci.org/${project_id}`;
    +shield-urls(
      `https://travis-ci.org/${project_id}.svg?branch=${branch}`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "pypi-version")
    - url = url || `https://pypi.org/project/${project_id}`;
    +shield-urls(
      `https://img.shields.io/pypi/v/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "pypi-py-versions")
    - url = url || `https://pypi.org/project/${project_id}`;
    +shield-urls(
      `https://img.shields.io/pypi/pyversions/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "pypi-status")
    - url = url || `https://pypi.org/project/${project_id}`;
    +shield-urls(
      `https://img.shields.io/pypi/status/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "pypi-license")
    - url = url || `https://pypi.org/project/${project_id}`;
    +shield-urls(
      `https://img.shields.io/pypi/l/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "binder")
    - url = url || `https://mybinder.org/v2/gh/${project_id}/${branch}`;
    +shield-urls(
      `https://mybinder.org/badge.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "readthedocs" || service == "rtd")
    - url = url || `http://${project_id}.readthedocs.io/`;
    +shield-urls(
      `https://readthedocs.org/projects/${project_id}/badge/?version=${version}`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "ask-me-anything")
    - url = url || project_id;
    +shield-urls(
      `https://camo.githubusercontent.com/d52b9239d76d77ebff4fc954745ee8ba555338ee/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f41736b2532306d652d616e797468696e672d3161626339632e737667`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "github-issues")
    - url = url || `https://github.com/${project_id}/issues`;
    +shield-urls(
      `https://img.shields.io/github/issues/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "github-issues-closed")
    - url = url || `https://github.com/${project_id}/issues?q=is%3Aissue+is%3Aclosed`;
    +shield-urls(
      `https://img.shields.io/github/issues-closed/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "github-issues-closed-in")
    - url = url || `https://github.com/${project_id}/issues`;
    +shield-urls(
      `https://img.shields.io/issuestats/i/long/github/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "github-last-commit")
    - url = url || `https://github.com/${project_id}/commits`;
    +shield-urls(
      `https://img.shields.io/github/last-commit/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "github-contributors")
    - url = url || `https://github.com/${project_id}/graphs/contributors`;
    +shield-urls(
      `https://img.shields.io/github/contributors/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "isitmaintained-issues-open-perc")
    - url = url || `http://isitmaintained.com/project/${project_id}`;
    +shield-urls(
      `http://isitmaintained.com/badge/open/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)
  - else if (service == "isitmaintained-issues-closed-in")
    - url = url || `http://isitmaintained.com/project/${project_id}`;
    +shield-urls(
      `http://isitmaintained.com/badge/resolution/${project_id}.svg`,
      `${url}`
    )&attributes(attributes)

+shield(service, project_id, url=null, branch=null, version=null)

Include shields passing, as minimum, their service and project id.

Arguments:

• service (string) –

  Shield service. Valid services are:

  • "travis": Insert a travis shield. Pass the parameter branch with a valid project branch or the branch used will be "master".
  • "pypi-version": Shield that shows version of a project hosted at Pypi defined by project_id parameter.
  • "pypi-py-version": Shows versions defined by a python project setup’s classifiers param hosted at Pypi.
  • "pypi-status": Shows a shield with status information of a project hosted at Pypi.
  • "pypi-license": Shows a shield with the license of a project hosted at Pypi.
  • "binder": Inserts a Binderhub shield that links to an IPython console for a repository. Pass the parameter branch with a valid project branch or the branch used will be "master". Only works for Github projects.
  • "readthedocs"/"rtd": Insert a Readthedocs shield. You need to pass the optional argument version, by default "latest" will be used.
  • "ask-me-anything": Insert an “Ask me anything” shield. You need to pass the url link target in the optional parameter url.
  • "github-issues": Shows number of issues opened in a Github project.
  • "github-issues-closed": Shows number of issues closed in a Github project.
  • "github-issues-closed-in": Shows mean time spended closing a issue in a Github project.
  • "github-last-commit": Shows a shield with how many time has elapsed since last commit in a project.
  • "github-contributors": Shows number of contributors that have been participated in a project.
  • "isitmaintained-issues-open-perc": Shows the percentage of issues open against total issues. This data is provided by Isitmaintained and is useful to know if a project are currently been maintained.
  • "isitmaintained-issues-closed-in": Shows mean time spended closing a issue in a Github project provided by Isitmaintained.
• project_id (string) – Identificator of the project. Depends of service, some needs only a project name like the Pypi shields, but others like Github shields need a string including the repository author like "mondeja/pug-mixins". Only ask yourself, this service works identificating their hosted projects by an author and project name or only needs the project name?
• url (string, optional) – Target url of a shield. Can be used to replace manually default shields link targets. As default null.
• branch (string, optional) – Branch of a project. As default "master".
• version (string, optional) – Version of the project. Is used only by "readthedocs" service for now. As default latest.

Usage

Input

+shield("readthedocs", "pymarketcap")(version="latest")

Output

<a href="http://pymarketcap.readthedocs.io/" target="__blank">
  <img src="https://readthedocs.org/projects/pymarketcap/badge/?version=latest">
</a>

Render