Badges, Buttons & Icons

Badges

Inline badges can be used as a labelling component. Badges are available in each semantic color, with filled and outline variants:

  • plain badge

  • primary, primary-line

  • secondary, secondary-line

  • success, success-line

  • info, info-line

  • warning, warning-line

  • danger, danger-line

  • light, light-line

  • muted, muted-line

  • dark, dark-line

  • white, white-line

  • black, black-line

Syntax
{bdg}`plain badge`

{bdg-primary}`primary`, {bdg-primary-line}`primary-line`

{bdg-secondary}`secondary`, {bdg-secondary-line}`secondary-line`

{bdg-success}`success`, {bdg-success-line}`success-line`

{bdg-info}`info`, {bdg-info-line}`info-line`

{bdg-warning}`warning`, {bdg-warning-line}`warning-line`

{bdg-danger}`danger`, {bdg-danger-line}`danger-line`

{bdg-light}`light`, {bdg-light-line}`light-line`

{bdg-muted}`muted`, {bdg-muted-line}`muted-line`

{bdg-dark}`dark`, {bdg-dark-line}`dark-line`

{bdg-white}`white`, {bdg-white-line}`white-line`

{bdg-black}`black`, {bdg-black-line}`black-line`

:bdg:`plain badge`

:bdg-primary:`primary`, :bdg-primary-line:`primary-line`

:bdg-secondary:`secondary`, :bdg-secondary-line:`secondary-line`

:bdg-success:`success`, :bdg-success-line:`success-line`

:bdg-info:`info`, :bdg-info-line:`info-line`

:bdg-warning:`warning`, :bdg-warning-line:`warning-line`

:bdg-danger:`danger`, :bdg-danger-line:`danger-line`

:bdg-light:`light`, :bdg-light-line:`light-line`

:bdg-muted:`muted`, :bdg-muted-line:`muted-line`

:bdg-dark:`dark`, :bdg-dark-line:`dark-line`

:bdg-white:`white`, :bdg-white-line:`white-line`

:bdg-black:`black`, :bdg-black-line:`black-line`

bdg-link- and bdg-ref- variants are also available for use with links and references. The syntax is the same as for the ref role.

https://example.com

explicit title

Badges

Syntax
{bdg-link-primary}`https://example.com`

{bdg-link-primary-line}`explicit title <https://example.com>`

:bdg-link-primary:`https://example.com`

:bdg-link-primary-line:`explicit title <https://example.com>`

See Bootstrap badges for more information, and related Material Design chips.

Buttons

Buttons allow users to navigate to external (button-link) / internal (button-ref) links with a single tap.

https://example.com

Button text

https://example.com

https://example.com

https://example.com

Buttons

Reference Button text

Syntax
```{button-link} https://example.com
```

```{button-link} https://example.com
Button text
```

```{button-link} https://example.com
:color: primary
:shadow:
```

```{button-link} https://example.com
:color: primary
:outline:
```

```{button-link} https://example.com
:color: secondary
:expand:
```

.. button-link:: https://example.com

.. button-link:: https://example.com

    Button text

.. button-link:: https://example.com
    :color: primary
    :shadow:

.. button-link:: https://example.com
    :color: primary
    :outline:

.. button-link:: https://example.com
    :color: secondary
    :expand:

Note that by default sphinx converts the content of references to raw text. For example **Bold text** with ref-type set to ref will be rendered without bold:

Bold text

However, if using myst-parser, you can set the ref-type to myst, and the content will be properly rendered:

Bold text

Use the click-parent option to make the button’s parent container also clickable.

Card with an expanded button

https://example.com

See the Material Design and Bootstrap descriptions for further details.

Inline Icons

Inline icon roles are available for the GitHub octicon, Google Material Design Icons, or FontAwesome libraries.

Octicon icons and Material icons are added as SVG’s directly into the page with the octicon and material-<flavor> roles. See below for the different flavors of Material Design Icons.

By default the icon will be of height 1em (i.e. the height of the font). A specific height can be set after a semi-colon (;) with units of either px, em or rem. Additional CSS classes can also be added to the SVG after a second semi-colon (;) delimiter.

Octicon Icons

A coloured icon: , some more text.

A coloured icon: {octicon}`report;1em;sd-text-info`, some more text.

A coloured icon: :octicon:`report;1em;sd-text-info`, some more text.
All Octicons
accessibility
accessibility-inset
alert
alert-fill
apps
archive
arrow-both
arrow-down
arrow-down-left
arrow-down-right
arrow-left
arrow-right
arrow-switch
arrow-up
arrow-up-left
arrow-up-right
beaker
bell
bell-fill
bell-slash
blocked
bold
book
bookmark
bookmark-fill
bookmark-slash
bookmark-slash-fill
briefcase
broadcast
browser
bug
cache
calendar
check
check-circle
check-circle-fill
checkbox
checklist
chevron-down
chevron-left
chevron-right
chevron-up
circle
circle-slash
clock
clock-fill
cloud
cloud-offline
code
code-of-conduct
code-review
code-square
codescan
codescan-checkmark
codespaces
columns
command-palette
comment
comment-discussion
commit
container
copilot
copilot-error
copilot-warning
copy
cpu
credit-card
cross-reference
dash
database
dependabot
desktop-download
device-camera
device-camera-video
device-desktop
device-mobile
devices
diamond
diff
diff-added
diff-ignored
diff-modified
diff-removed
diff-renamed
discussion-closed
discussion-duplicate
discussion-outdated
dot
dot-fill
download
duplicate
ellipsis
eye
eye-closed
feed-discussion
feed-forked
feed-heart
feed-issue-closed
feed-issue-draft
feed-issue-open
feed-issue-reopen
feed-merged
feed-person
feed-plus
feed-public
feed-pull-request-closed
feed-pull-request-draft
feed-pull-request-open
feed-repo
feed-rocket
feed-star
feed-tag
feed-trophy
file
file-added
file-badge
file-binary
file-code
file-diff
file-directory
file-directory-fill
file-directory-open-fill
file-directory-symlink
file-media
file-moved
file-removed
file-submodule
file-symlink-file
file-zip
filter
filter-remove
fiscal-host
flame
fold
fold-down
fold-up
gear
gift
git-branch
git-commit
git-compare
git-merge
git-merge-queue
git-pull-request
git-pull-request-closed
git-pull-request-draft
globe
goal
grabber
graph
hash
heading
heart
heart-fill
history
home
home-fill
horizontal-rule
hourglass
hubot
id-badge
image
inbox
infinity
info
issue-closed
issue-draft
issue-opened
issue-reopened
issue-tracked-by
issue-tracks
italic
iterations
kebab-horizontal
key
key-asterisk
law
light-bulb
link
link-external
list-ordered
list-unordered
location
lock
log
logo-gist
logo-github
mail
mark-github
markdown
megaphone
mention
meter
milestone
mirror
moon
mortar-board
move-to-bottom
move-to-end
move-to-start
move-to-top
multi-select
mute
no-entry
no-entry-fill
north-star
note
number
organization
package
package-dependencies
package-dependents
paintbrush
paper-airplane
paperclip
passkey-fill
paste
pencil
people
person
person-add
person-fill
pin
pin-slash
pivot-column
play
plug
plus
plus-circle
project
project-roadmap
project-symlink
project-template
pulse
question
quote
read
redo
rel-file-path
reply
repo
repo-clone
repo-deleted
repo-forked
repo-locked
repo-pull
repo-push
repo-template
report
rocket
rows
rss
ruby
screen-full
screen-normal
search
server
share
share-android
shield
shield-check
shield-lock
shield-slash
shield-x
sidebar-collapse
sidebar-expand
sign-in
sign-out
single-select
skip
skip-fill
sliders
smiley
sort-asc
sort-desc
sparkle-fill
sponsor-tiers
square
square-fill
squirrel
stack
star
star-fill
stop
stopwatch
strikethrough
sun
sync
tab
tab-external
table
tag
tasklist
telescope
telescope-fill
terminal
three-bars
thumbsdown
thumbsup
tools
tracked-by-closed-completed
tracked-by-closed-not-planned
trash
triangle-down
triangle-left
triangle-right
triangle-up
trophy
typography
undo
unfold
unlink
unlock
unmute
unread
unverified
upload
verified
versions
video
webhook
workflow
x
x-circle
x-circle-fill
zap
zoom-in
zoom-out

Material Design Icons

Material Design icons come as several flavors. Each flavor represents a different role used in sphinx-design. These flavors are:

  • material-regular

  • material-outlined

  • material-round

  • material-sharp

  • material-twotone

Not all icons are available for each flavor, but most are. Instead of displaying the 10660+ icons here, you are encouraged to browse the available icons from the Material Design Icons’ showcase hosted by Google.

  • A regular icon: , some more text

  • A coloured regular icon: , some more text.

  • A coloured outline icon: , some more text.

  • A coloured sharp icon: , some more text.

  • A coloured round icon: , some more text.

  • A coloured two-tone icon: , some more text.

- A regular icon: {material-regular}`data_exploration;2em`, some more text
- A coloured regular icon: {material-regular}`settings;3em;sd-text-success`, some more text.
- A coloured outline icon: {material-outlined}`settings;3em;sd-text-success`, some more text.
- A coloured sharp icon: {material-sharp}`settings;3em;sd-text-success`, some more text.
- A coloured round icon: {material-round}`settings;3em;sd-text-success`, some more text.
- A coloured two-tone icon: {material-twotone}`settings;3em;sd-text-success`, some more text.
- A fixed size icon: {material-regular}`data_exploration;24px`, some more text.

- A regular icon: :material-regular:`data_exploration;2em`, some more text
- A coloured regular icon: :material-regular:`settings;3em;sd-text-success`, some more text.
- A coloured outline icon: :material-outlined:`settings;3em;sd-text-success`, some more text.
- A coloured sharp icon: :material-sharp:`settings;3em;sd-text-success`, some more text.
- A coloured round icon: :material-round:`settings;3em;sd-text-success`, some more text.
- A coloured two-tone icon: :material-twotone:`settings;3em;sd-text-success`, some more text.
- A fixed size icon: :material-regular:`data_exploration;24px`, some more text.

FontAwesome Icons

FontAwesome icons are added via the Fontawesome CSS classes. If the theme you are using does not already include the FontAwesome CSS, it should be loaded in your configuration from a font-awesome CDN, with the html_css_files option, e.g.:

html_css_files = [
    "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"
]

Use either fa (deprecated in font-awesome v5), fas, fab or far for the role name. Note that not all regular style icons are free, far role only works with free ones.

Warning

Since the FontAwesome icons are fetched directly from their distributed CSS, specifying a height/size to the fa* roles is not supported. However, you can always add your custom CSS class that controls the font-size property.

If a height/size is supplied to a fa* role, then it will be interpreted as a CSS class. There can only be a maximum of 1 ; in the fa* roles’ arguments

- An icon {fas}`spinner;sd-text-primary`, some more text.
- An icon {fab}`github`, some more text.
- An icon {fab}`gitkraken;sd-text-success fa-xl`, some more text.
- An icon {fas}`skull;sd-text-danger`, some more text.

- An icon :fas:`spinner;sd-text-primary`, some more text.
- An icon :fab:`github`, some more text.
- An icon :fab:`gitkraken;sd-text-success fa-xl`, some more text.
- An icon :fas:`skull;sd-text-danger`, some more text.

  • An icon , some more text.

  • An icon , some more text.

  • An icon , some more text.

  • An icon , some more text.

By default, icons will only be output in HTML formats. But if you want FontAwesome icons to be output on LaTeX, using the fontawesome package, you can add to your configuration:

sd_fontawesome_latex = True