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
dark, dark-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

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.

Reference Button text

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.

`button-link` and `button-ref` options¶

ref-type (button-ref only): Type of reference to use; any (default), ref, doc, or myst
color: Set the color of the button (background and font). One of the semantic color names: primary, secondary, success, danger, warning, info, light, dark, muted.
outline: Outline color variant
align: Align the button on the page; left, right, center or justify
expand: Expand to fit parent width
click-parent: Make parent container also clickable
tooltip: Add tooltip on hover
shadow: Add shadow CSS
class: Additional CSS classes

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.

MARKDOWN

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

RST

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.

MARKDOWN

- 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.

RST

- 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

MARKDOWN

- 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.

RST

- 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

Badges, Buttons & Icons ¶

Badges¶

Buttons¶

button-link and button-ref options¶

Inline Icons¶

Octicon Icons¶

Material Design Icons¶

FontAwesome Icons¶

`button-link` and `button-ref` options¶