Shield¶

About¶

A component to render badges through Shields.io, with or without links, and optional parameterization. It implements the Sphinx directive shield.

Options¶

The shield directive supports the options provided by Shields.io Static Badges.

message:: The text on the right hand side of the shield. When no label is defined, the shield will only include the message text.

label:: The optional text on the left hand side of the shield.

logo:: One of the named logos (bitcoin, dependabot, gitlab, npm, paypal, serverfault, stackexchange, superuser, telegram, travis), or one of Simple Icons. All simple icons are referenced using icon slugs. For general documentation, see also Shields.io Logos.

Style

style:: The style of the shield, flat by default. Possible values: flat, flat-square, plastic, for-the-badge, social.

Colors

For the colors, hex, rgb, rgba, hsl, hsla and css named colors supported. Formats: rgb(r,g,b) / rgba(r,g,b,a) and hsl(h,s,l) / hsla(h,s,l,a).

message-color:: Background color of the right part. When no label is defined, the shield will be single-colored. When not defining a color, the default is blue.
label-color:: Background color of the left part.
logo-color:: The background color of the logo. Supported for named logos and Shields logos, but not for custom logos.
color:: An alias for message-color.

Synopsis¶

A static shield badge linking to a URL, defined using the markup outlined below.

Usage¶

MARKDOWN

:::{shield}
:label: Example
:message: Shield
:color: darkcyan
:logo: Markdown
:link: https://example.org/
:link-type: url
:link-title: An example using the shield directive
:::

RST

.. shield::
    :label: Example
    :message: Shield
    :color: darkcyan
    :logo: Markdown
    :link: https://example.org/
    :link-type: url
    :link-title: An example using the shield directive

Variants¶

A few more variants how to change the visual appearance.

The following examples just enumerate variants in MyST syntax. Modulo some specific features, it should work roughly the same way when using rST.

Basics

Fundamental features of the shield directive, about basic text and layout options, and configuration styles.

Item

Description

Syntax

A basic shield without any options.

:::{shield} Read More
:::

The message can also be defined using the message option.

:::{shield}
:message: Read More
:::

Left vs. right texts can be defined by using the label vs. message options.

:::{shield}
:label: Read
:message: More
:::

When using MyST, options can also be defined in YAML syntax, which also allows to use multi-line values.

YAML

:::{shield}
---
message: "Read More"
:::

Multi-line

:::{shield}
---
message: |
    Read
    More
:::

Text input also accepts Unicode glyphs.

:::{shield}
:message: 🌻 Read More 🍀
:::

By default, shield directives render as block-level elements. To place multiple items side by side, in order to display them inline, wrap them into a ::::{div} inline colon fence.

::::{div} inline

:::{shield} S 1
:::

:::{shield} S 2
:::

::::

Styling

About defining colors, an icon, and the style/shape of the shield.

The color option determines the background color.

:::{shield}
:message: Read More
:color: darkgreen
:::

Left vs. right background colors can be defined by using the label-color vs. message-color options, see Colors. For single-colored shields, the color option can be used as an alias for message-color.

:::{shield}
:label: Read
:message: More
:label-color: darkgreen
:message-color: orange
:::

:::{shield}
:label: Read
:message: More
:label-color: hsl(270,60%,70%)
:message-color: rgb(255,0,153)
:::

:::{shield} Read More
:color: #123456
:::

Select an image from a collection of brand depictions, using the logo option.

:::{shield}
:message: CrateDB
:logo: CrateDB
:color: gray
:::

Use a custom logo image by base64 encoding it.

:::{shield}
:message: Play Station
:logo: data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEiIHdpZHRoPSI2MDAiIGhlaWdodD0iNjAwIj48cGF0aCBkPSJNMTI5IDExMWMtNTUgNC05MyA2Ni05MyA3OEwwIDM5OGMtMiA3MCAzNiA5MiA2OSA5MWgxYzc5IDAgODctNTcgMTMwLTEyOGgyMDFjNDMgNzEgNTAgMTI4IDEyOSAxMjhoMWMzMyAxIDcxLTIxIDY5LTkxbC0zNi0yMDljMC0xMi00MC03OC05OC03OGgtMTBjLTYzIDAtOTIgMzUtOTIgNDJIMjM2YzAtNy0yOS00Mi05Mi00MmgtMTV6IiBmaWxsPSIjZmZmIi8+PC9zdmc+
:::

The style option determines the style / shape of the shield.

:::{shield}
:message: Read More
:style: flat
:::

:::{shield}
:message: Read More
:style: flat-square
:::

:::{shield}
:message: Read More
:style: plastic
:::

:::{shield}
:message: Read More
:style: for-the-badge
:::

:::{shield}
:message: Read More
:style: social
:::

Linking

How to use the shield as a hypertext reference to link to other resources. See also complete linking options.

Link to a Sphinx document using the link-type=doc option. In this case, link refers to a document name.

:::{shield}
:message: Sandbox
:link: sandbox
:link-type: doc
:::

Link to a Sphinx reference using the link-type=ref option. In this case, link refers to any local Sphinx reference.

:::{shield}
:message: Linking
:link: shield-linking
:link-type: ref
:::

Link to another project using the link-type=ref option. In this case, link refers to an intersphinx reference.

Note: This only works in MyST.

intersphinx_mapping = {
  "sd": ("https://sphinx-design.readthedocs.io/en/latest/", None),
}

:::{shield}
:message: sphinx{design}
:link: sd:index
:link-type: ref
:::

Link to any URL using url for the link-type option.

:::{shield}
:message: example.org
:link: https://example.org/
:link-type: url
:::

:::{shield}
:message: test@example.org
:link: mailto:test@example.org
:link-type: url
:::

Indirect references are defined out-of-band from the link definition, for example at the end of the page.

In MyST, indirect references are defined by, for example:

[label]: inv:<project>#<label>
[label]: <url>

Note: This only works in MyST.

:::{shield}
:message: Indirect Reference
:link: "inv:sd#index"
:link-type: ref
:::

:::{shield}
:message: Indirect URL
:link: "[example-org]"
:link-type: url
:::

[example-org]: https://example.org/

Backlog¶

Todo

Provide style presets, like the shortcut hyper roles, or how markdown-badges define them.

Todo

Local shield badges? It’s SVG anyway, right?

Needs a server? https://github.com/badges/shields/blob/master/doc/self-hosting.md
Is templating sufficient? Would need a Python implementation?
- https://github.com/badges/shields/blob/master/badge-maker/lib/badge-renderers.js
- https://github.com/dbrgn/coverage-badge
- Use pybadges or pybadges-trend?
Just scrape the SVG from img.shields.io once, at build time?

Todo

Alternatives