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

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

Badge tooltips¶

Any badge can be given a tooltip (shown on hover, via the HTML title attribute) by appending a ; tooltip suffix to its text. This works for every badge family:

stable docs badges

MARKDOWN

{bdg-primary}`stable ; A released, supported version`
{bdg-link-info}`docs <https://example.com> ; Opens the documentation`
{bdg-ref-primary}`badges <badges> ; Jump to the badges section`

RST

:bdg-primary:`stable ; A released, supported version`
:bdg-link-info:`docs <https://example.com> ; Opens the documentation`
:bdg-ref-primary:`badges <badges> ; Jump to the badges section`

The tooltip is the text after the last unescaped semicolon; both the badge text and the tooltip are stripped of surrounding whitespace. To include a literal semicolon in the badge text, escape it as \; (for example {bdg}`step 1\; step 2`); a trailing bare ; (with nothing after it) is not treated as a tooltip and is kept in the badge text.

Because semicolons are valid in URLs and reference targets, the link and reference badges (bdg-link-*, bdg-ref-*) only recognise the tooltip suffix after the explicit text <target> form – a bare target such as {bdg-link-primary}`https://example.com/a;b` is never split. To add a tooltip to a link/ref badge, use the explicit form: {bdg-link-primary}`docs <https://example.com> ; Opens the docs`. A bdg-ref tooltip overrides the reference’s automatic title.

Warning

title tooltips are not accessible to keyboard or touch users, and are not surfaced by all screen readers. Do not put essential information in a tooltip alone – keep it in the visible badge text (or nearby prose) as well.

Buttons¶

Buttons in Sphinx Design are actually links:

Links that can be styled to look like Bootstrap buttons
Links that are either external (button-link) or internal (button-ref)

Most of the time, you should create links using the link syntax for the language you’ve chosen:

Sometimes, though, you may want to call attention to a particular link or set of links, or set them apart visually from other links on the site.

Note on accessibility

Despite the name, button-link and button-ref do not convert to <button> tags in HTML. They are output as <a> tags and use CSS to achieve the button look. This has important accessibility implications. For example, assistive tech will include Sphinx Design “buttons” when asked to present a list of all the links on the page.

Reference Button text

The content of a button-ref supports rich inline formatting (such as emphasis and icons), which is rendered in the button, just as it is for button-link:

Bold text

To break the text of a button over several lines, write it as a line block in reStructuredText (one | per line), or end each line but the last with a backslash (\, a hard line break) in MyST Markdown. The MyST hard line break only breaks the line in HTML and LaTeX output: other builders join the lines (text) or print the raw break markup (texinfo), and the gettext message contains that markup too, so translated projects should use the reStructuredText line block (in MyST, inside an eval-rst block):

Multi-line
button text

MARKDOWN

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

Multi-line\
button text
:::

RST

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

    | Multi-line
    | button text

In reStructuredText, a one-line label that starts with | (or is a bare |) is read as a one-line line block, whose leading bar is not shown, so write a literal leading bar as \|.

Reference targets may also contain spaces, for example the labels that sphinx.ext.autosectionlabel generates from section titles.

When using myst-parser, you can also set ref-type to myst to resolve Markdown-style references.

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

Card with an expanded button

https://example.com

Use the new-tab option to open the button’s link in a new browser tab. Since this changes what the reader expects a link to do, say so in the button text:

example.com (opens in a new tab)

MARKDOWN

:::{button-link} https://example.com
:color: primary
:new-tab:

example.com (opens in a new tab)
:::

RST

.. button-link:: https://example.com
    :color: primary
    :new-tab:

    example.com (opens in a new tab)

`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
new-tab: Open the link in a new browser tab (target="_blank", rel="noreferrer noopener"). Works for both button-link and button-ref. Sphinx renders the rel attribute only from version 7.4; browsers already treat target="_blank" links as noopener. It affects only HTML-based output (HTML, EPUB); other formats ignore it.
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.

Icon roles can be used within section titles, and the icon is preserved when the title is referenced from a toctree (whilst no longer leaking its SVG markup into plain-text contexts such as the search index).

Note

Icon roles cannot be used inside a toctree entry title (the Title <target> form written directly in the toctree directive), because Sphinx parses those titles as plain text, so roles are never processed. To show an icon next to a page’s toctree entry, place the icon role in that page’s own top-level heading instead, and reference the page without an explicit title.

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`
`agent`
`ai-model`
`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`
`book-locked`
`bookmark`
`bookmark-fill`
`bookmark-filled`
`bookmark-slash`
`bookmark-slash-fill`
`boolean-off`
`boolean-on`
`briefcase`
`broadcast`
`browser`
`bug`
`cache`
`calendar`
`chat`
`chat-add`
`chat-locked`
`chat-question`
`check`
`check-agent`
`check-circle`
`check-circle-fill`
`checkbox`
`checkbox-fill`
`checklist`
`chevron-down`
`chevron-left`
`chevron-right`
`chevron-up`
`circle`
`circle-slash`
`clock`
`clock-fill`
`cloud`
`cloud-offline`
`code`
`code-badge`
`code-of-conduct`
`code-review`
`code-square`
`codescan`
`codescan-checkmark`
`codespaces`
`columns`
`command-palette`
`comment`
`comment-ai`
`comment-discussion`
`comment-fill`
`comment-locked`
`commit`
`compose`
`container`
`copilot`
`copilot-error`
`copilot-warning`
`copy`
`cpu`
`credit-card`
`cross-reference`
`crosshairs`
`cursor`
`dash`
`dashboard`
`database`
`dependabot`
`desktop-download`
`device-camera`
`device-camera-video`
`device-desktop`
`device-mobile`
`devices`
`diamond`
`dice`
`diff`
`diff-added`
`diff-ignored`
`diff-modified`
`diff-removed`
`diff-renamed`
`discussion-closed`
`discussion-duplicate`
`discussion-outdated`
`dot`
`dot-fill`
`download`
`duplicate`
`ellipsis`
`exclamation`
`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-check`
`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`
`flag`
`flame`
`flowchart`
`focus-center`
`fold`
`fold-down`
`fold-up`
`gear`
`gift`
`git-branch`
`git-branch-check`
`git-closed-agent`
`git-commit`
`git-compare`
`git-draft-agent`
`git-merge`
`git-merge-agent`
`git-merge-queue`
`git-pull-request`
`git-pull-request-agent`
`git-pull-request-closed`
`git-pull-request-draft`
`git-pull-request-locked`
`git-pull-request-unlisted`
`git-que-merge-agent`
`globe`
`goal`
`grabber`
`graph`
`graph-bar-horizontal`
`graph-bar-vertical`
`graph-stacked-area`
`hash`
`heading`
`heart`
`heart-fill`
`history`
`home`
`home-fill`
`horizontal-rule`
`hourglass`
`hubot`
`id-badge`
`image`
`inbox`
`inbox-fill`
`infinity`
`info`
`issue-closed`
`issue-draft`
`issue-locked`
`issue-opened`
`issue-relates-to`
`issue-reopened`
`issue-tracked-by`
`issue-tracks`
`italic`
`iterations`
`kebab-horizontal`
`key`
`key-asterisk`
`law`
`library`
`light-bulb`
`link`
`link-external`
`list-ordered`
`list-unordered`
`location`
`lock`
`lockup-github`
`log`
`logo-gist`
`logo-github`
`loop`
`mail`
`mark-github`
`markdown`
`maximize`
`mcp`
`megaphone`
`mention`
`meter`
`milestone`
`minimize`
`mirror`
`moon`
`mortar-board`
`move-to-bottom`
`move-to-end`
`move-to-start`
`move-to-top`
`multi-select`
`mute`
`no-entry`
`no-entry-fill`
`node`
`north-star`
`note`
`number`
`organization`
`package`
`package-dependencies`
`package-dependents`
`paintbrush`
`paper-airplane`
`paperclip`
`passkey-fill`
`paste`
`pause`
`pencil`
`pencil-ai`
`people`
`person`
`person-add`
`person-cursor`
`person-fill`
`pin`
`pin-slash`
`pivot-column`
`play`
`plug`
`plus`
`plus-circle`
`project`
`project-check`
`project-roadmap`
`project-symlink`
`project-template`
`pulse`
`question`
`question-bubble`
`quote`
`read`
`redo`
`rel-file-path`
`release`
`reply`
`repo`
`repo-clone`
`repo-delete`
`repo-deleted`
`repo-forked`
`repo-forked-locked`
`repo-locked`
`repo-pull`
`repo-push`
`repo-template`
`report`
`rocket`
`rows`
`rss`
`ruby`
`sandbox`
`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`
`smiley-frown`
`smiley-frustrated`
`smiley-grin`
`smiley-neutral`
`sort-asc`
`sort-desc`
`space`
`spacing-large`
`spacing-medium`
`spacing-small`
`sparkle`
`sparkle-fill`
`sparkles-fill`
`split-view`
`sponsor-tiers`
`square`
`square-circle`
`square-fill`
`squirrel`
`stack`
`stack-add`
`stack-check`
`stack-remove`
`stack-slash`
`star`
`star-fill`
`stop`
`stopwatch`
`strikethrough`
`sun`
`sync`
`tab`
`tab-external`
`table`
`tag`
`tasklist`
`telescope`
`telescope-fill`
`terminal`
`terminal-locked`
`three-bars`
`thumbsdown`
`thumbsup`
`tools`
`tracked-by-closed-completed`
`tracked-by-closed-not-planned`
`trash`
`triangle`
`triangle-circle`
`triangle-down`
`triangle-fill`
`triangle-left`
`triangle-right`
`triangle-up`
`trophy`
`typography`
`undo`
`unfold`
`unlink`
`unlock`
`unmute`
`unread`
`unverified`
`unwrap`
`upload`
`verified`
`versions`
`video`
`view-files`
`vscode`
`wall`
`webhook`
`workflow`
`wrap`
`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. The role name selects the icon style — solid (fa-solid/fas/fa), brands (fa-brands/fab) or regular (fa-regular/far) — and you can pick any spelling:

A solid icon , some more text.
A brand icon , some more text.
A regular icon , some more text.

By default each role emits exactly the classes it is named after: the fa-solid role applied to rocket produces <span class="fa-solid fa-rocket">, while the fas role produces <span class="fas fa-rocket">.

Matching your FontAwesome version¶

Set sd_fontawesome_version to the major version of the FontAwesome CSS you load, and every role spelling is translated to that version’s class scheme — so the role names are version-agnostic: write whichever spelling you prefer, and upgrading (or downgrading) FontAwesome is a one-line conf.py change:

sd_fontawesome_version = "6"

Roles	Style	`"4"`	`"5"`	`"6"`
`fa`, `fas`, `fa-solid`	solid	`fa`	`fas`	`fa-solid`
`fab`, `fa-brands`	brands	`fa`	`fab`	`fa-brands`
`far`, `fa-regular`	regular	`fa`	`far`	`fa-regular`

The default, "as-named", emits the role name verbatim as the leading class (the behaviour shown above, and of previous sphinx-design versions).

Note

The bare fa role maps to solid under "5"/"6" (FontAwesome 4’s single style became solid in v5). Conversely, "4" collapses all style distinctions to fa in the HTML classes, since FontAwesome 4 had no style prefixes — LaTeX output is unaffected (it always uses the role’s own style).

Only the leading style class is translated — icon names that FontAwesome renamed between versions (e.g. v4 external-link vs v6 arrow-up-right-from-square) are emitted as written, just like in the LaTeX note below.

Loading the FontAwesome CSS¶

sphinx-design does not bundle the FontAwesome CSS. By default (sd_fontawesome_source = "none") you, or your theme, are responsible for making it available (many themes already include it).

To have sphinx-design load it for you from a FontAwesome CDN, so you no longer have to hand-edit html_css_files, set:

sd_fontawesome_source = "cdn"

This adds sd_fontawesome_cdn_url (a FontAwesome v6 all.min.css by default) to the HTML output. Override sd_fontawesome_cdn_url to pin a different version or a self-hosted copy.

Warning

Since the FontAwesome icons are fetched directly from their distributed CSS, specifying a height/size to the icon 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 an icon role, then it will be interpreted as a CSS class. There can only be a maximum of 1 ; in the roles’ arguments

MARKDOWN

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

RST

- An icon :fa-solid:`spinner;sd-text-primary`, some more text.
- An icon :fa-brands:`github`, some more text.
- An icon :fa-brands:`gitkraken;sd-text-success fa-xl`, some more text.
- An icon :fa-solid:`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.

Using FontAwesome Pro kits¶

If you use a FontAwesome Pro kit, keep sd_fontawesome_source = "none" (do not also load the free CDN, whose own font-face would fight your kit), load the kit as usual, and either use the v6 role names (fa-solid/fa-brands/fa-regular) directly, or set sd_fontawesome_version = "6", which makes every spelling — including the concise fas/fab/far — emit exactly the classes a Pro kit expects.

Concise role names¶

The fas, fab and far roles (and fa, which FontAwesome itself deprecated in v5) are equally supported, with no plans to remove them. By default (sd_fontawesome_version = "as-named") each role name is emitted verbatim as the leading CSS class, so these produce the v4/v5 class scheme (fas fa-...):

An icon , some more text.
An icon , some more text.
An icon , some more text.

The free CDN builds define both class schemes, so the concise names work fine there as-is. And combined with sd_fontawesome_version, the concise names are future-proof for any setup: keep writing fas/fab/far and set the version knob to match the CSS you load — no source churn when FontAwesome (or your theme’s bundled copy) moves on. The fa-solid/fa-brands/fa-regular spellings remain handy for matching what fontawesome.com shows for each icon. Note that not all regular style icons are free; far/fa-regular only work with the free ones.

FontAwesome in LaTeX output¶

By default, icons are only rendered for HTML builders. To also render them in LaTeX output, set sd_fontawesome_latex to the LaTeX package you want to use:

`sd_fontawesome_latex`	LaTeX package	Rendering
`False` / `"none"` (default)	–	icons skipped (one warning per build)
`True` / `"fontawesome"`	`fontawesome`	`\faicon{name}`
`"fontawesome5"`	`fontawesome5`	`\faIcon{name}` (see below)

sd_fontawesome_latex = "fontawesome5"

With "fontawesome5", the icon style is mapped to that package’s conventions: brand icons resolve by name (\faIcon{github}), regular-style icons use the optional style argument (\faIcon[regular]{name}), and solid icons use the default (\faIcon{name}). Note that sd_fontawesome_version only selects the HTML class scheme; LaTeX rendering is driven by the role’s style and sd_fontawesome_latex alone.

If your theme (or another extension) already loads the fontawesome5 package, set sd_fontawesome_latex = "fontawesome5" so both agree, avoiding the LaTeX error that comes from mixing the fontawesome and fontawesome5 packages.

Note

The LaTeX packages predate FontAwesome 6 and resolve icons by their v5 (or v4, for fontawesome) names. Icons that were renamed in v6 (for example arrow-up-right-from-square, formerly external-link-alt) render in HTML but will raise an “icon not found” error when building PDF output — use the older name if you need LaTeX support for such an icon.

Badges, Buttons & Icons ¶

Badges¶

Badge tooltips¶

The `tooltip` role option¶

Buttons¶

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

Inline Icons¶

Octicon Icons¶

Material Design Icons¶

FontAwesome Icons¶

Matching your FontAwesome version¶

Loading the FontAwesome CSS¶

Using FontAwesome Pro kits¶

Concise role names¶

FontAwesome in LaTeX output¶

Navigation

Related Topics

Badges, Buttons & Icons ¶

Badges¶

Badge tooltips¶

The tooltip role option¶

Buttons¶

button-link and button-ref options¶

Inline Icons¶

Octicon Icons¶

Material Design Icons¶

FontAwesome Icons¶

Matching your FontAwesome version¶

Loading the FontAwesome CSS¶

Using FontAwesome Pro kits¶

Concise role names¶

FontAwesome in LaTeX output¶

The `tooltip` role option¶

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