Hyper

About

A component to render hyperlinks with a few bells and whistles, implementing the Sphinx role hyper.

Features

The hyper role aims to expand the features of the traditional Sphinx :ref: / {ref} role everyone loves so much for its powerful linking capabilities.

Syntax Extension:

The standard role expression syntax of {ref} is extended, by adding a third slot for conveying additional options to Sphinx roles, building upon fundamentals of Sphinx referencing and linking. A typical markup snippet using the {hyper} role in MyST syntax looks like this.

{hyper}`label <resource> {option1=value1,option2=value2}`

The most basic variant is to just slap an arbitrary resource identifier into its value slot. That can be a Sphinx reference of any kind, or just an URL.

{hyper}`resource`

Referencing and Linking:

The role implementation HyperRefRole inherits all the niceties from AnyXRefRole. Linking features are enhanced by providing rST / MyST cross-over compatibility, and a few other gimmicks like automatically deriving link labels from <title> elements of HTML pages on arbitrary URLs.

Layout and Style:

Other than rendering plain HTML hyperlink anchors, the hyper role provides an array of options to present hyperlinks differently. Hyper currently supports:

Badge

The Badge Hyper renders hyperlinks using the bdg-* roles from sphinx-design.

Button

The Button Hyper renders hyperlinks using the button directive from sphinx-design.

Card

The Card Hyper renders hyperlinks using the card directive from sphinx-design.

Shield

A Shield-typed Hyper renders hyperlinks using badges from Shields.io, building upon the shield directive from sphinx-design-elements.

Synopsis

A hyperlink that navigates to a URL, rendered in different variants, defined using the markup outlined below.

Badge:

Technical advancements in Sphinx

Button:

Technical advancements in Sphinx

Card:

Technical advancements in Sphinx

Shield:

Text:

Technical advancements in Sphinx

Usage

MARKDOWN

:Badge:
    {hyper}`https://community.panodata.org/t/technical-advancements-in-sphinx/278 {type=badge,outline=true,short-title=true}`

:Button:
    {hyper}`https://community.panodata.org/t/technical-advancements-in-sphinx/278 {type=button,outline=true,short-title=true}`

:Card:
    {hyper}`https://community.panodata.org/t/technical-advancements-in-sphinx/278 {type=card,short-title=true}`

:Shield:
    {hyper}`https://community.panodata.org/t/technical-advancements-in-sphinx/278 {type=shield,label=Navigate to,short-title=true}`

:Text:
    {hyper}`https://community.panodata.org/t/technical-advancements-in-sphinx/278 {short-title=true}`

Warning

Currently only works with MyST. reStructuredText is not supported yet, but support can be added.

Fundamentals

The hyper role provides a few configuration options, mimicking and expanding {ref}.

Item

Description and Syntax

Example Domain
mailto:test@example.org

A basic hyper without any options, referencing an URL.

{hyper}`https://example.org` \
{hyper}`mailto:test@example.org`

Read More

Referencing a URL with a self-defined link label.

{hyper}`Read More <https://example.org>`

Linking and Referencing

infocard-directive
#infocard-directive

Links to project-local references can be defined by using reference labels in both reStructuredText and MyST syntax.

{hyper}`infocard-directive` \
{hyper}`#infocard-directive`

Cards
Card Layouts

Using a traditional intersphinx reference is the most compact way to run links to other Sphinx projects.

{hyper}`sd:sd-cards` \
{hyper}`Card Layouts <sd:sd-cards>`

sphinx-design
Grids
Cards

MyST reference syntax is also supported for intersphinx links.

{hyper}`inv:sd:*:doc#index` \
{hyper}`inv:sd:*:label#sd-grids` \
{hyper}`inv:sd#sd-cards`

Grid Table
Sphinx Design
Example Domain

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]: reference

• [label]: #reference

• [label]: inv:project#reference

• [label]: url

Note: This only works in MyST.

{hyper}`Grid Table <[gridtable]>` \
{hyper}`Sphinx Design <[sphinx-design]>` \
{hyper}`Example Domain <[example-org]>`

[gridtable]: gridtable-directive
[sphinx-design]: inv:sd#index
[example-org]: https://example.org/

Variants

The hyper role provides a few rendering variants.

Badge

Adding the option {type=badge} renders the hyperlink using a badge based on the sphinx-design bdg-* roles.

Options

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. The default value is primary.

outline

Display button in outlined color style variant. Use outline=true to toggle that option.

Fundamentals

Item

Description and Syntax

Example Domain

A basic badge hyperlink for URLs, without any options.

{hyper}`https://example.org {type=badge}`

shield-directive
Shield Badges

Use project-local references.

{hyper}`shield-directive {type=badge}` \
{hyper}`Shield Badges <shield-directive> {type=badge}`

Cards
Card Layouts

Use intersphinx references.

{hyper}`sd:sd-cards {type=badge}` \
{hyper}`Card Layouts <sd:sd-cards> {type=badge}`

Layout

1 2 3

Because hyper roles render as inline elements, like bdg-* badges, multiple instances can be placed side by side, even when written down spanning multiple lines.

{hyper}`1 <https://example.org> {type=badge,outline=true}`
{hyper}`2 <https://example.org> {type=badge,outline=true}`
{hyper}`3 <https://example.org> {type=badge,outline=true}`

Tip

For purposely applying line breaks, use the backslash \ as line continuation character.

Style

Example Domain

The color option determines the color.

{hyper}`https://example.org {type=badge,color=info}`

Example Domain

The outline option draws the badge in a different style.

{hyper}`https://example.org {type=badge,outline=true}`

🌻 Read More 🍀

Text input accepts Unicode glyphs.

{hyper}`🌻 Read More 🍀 <https://example.org> {type=badge,outline=true}`

Button

Adding the option {type=button} renders the hyperlink using a button based on the sphinx-design button directive, it accepts the same options, and the additional icon option.

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. The default value is primary.

outline

Display button in outlined color style variant. Use outline=true to toggle that option.

align

Align the button on the page; left, right, center or justify

expand

Expand to fit parent width. Use expand=true to toggle that option.

click-parent

Make parent container also clickable. Use click-parent=true to toggle that option.

tooltip

Add tooltip text, displayed when hovering over the link.

icon

All icon features of sphinx-design can be used. The icon, when given, will be placed on the left hand side of the text. The micro syntax to describe it is not much different from the original role notation, just note the colon : separates icon family from icon name.

{octicon}`report;1em;sd-text-info`  # Original MyST
octicon:report;1em;sd-text-info     # Hyper inline variant

shadow

Add shadow CSS.

class

Additional CSS classes.

Fundamentals

Item

Description and Syntax

Example Domain
Read More

A basic button hyperlink for URLs, without any options.

{hyper}`https://example.org {type=button}` \
{hyper}`Read More <https://example.org> {type=button}`

shield-directive
Shield Badges

Use project-local references.

{hyper}`shield-directive {type=button}` \
{hyper}`Shield Badges <shield-directive> {type=button}`

Cards
Card Layouts

Use intersphinx references.

{hyper}`sd:sd-cards {type=button}` \
{hyper}`Card Layouts <sd:sd-cards> {type=button}`

Layout

expand option.

Use the expand option to fit the element to the width of its parent. Example Domain

{hyper}`https://example.org {type=button,expand=true}`

align option.

Use the align option.

Example Domain

{hyper}`https://example.org {type=button,align=center}`

Todo

Apparently, the align option does not work?

Because hyper roles render as inline elements, multiple instances can be placed side by side, even when written down spanning multiple lines. Regular button directives are block level elements, which would cause line breaks.

{hyper}`https://example.org {type=button,icon=octicon:rocket,notext=true}`
{hyper}`https://example.org {type=button,icon=octicon:rocket,notext=true}`
{hyper}`https://example.org {type=button,icon=octicon:rocket,notext=true}`

Tip

For purposely applying line breaks, use the backslash \ as line continuation character.

Style

Example Domain
Example Domain
Example Domain

Use outline, color, and shadow options.

{hyper}`https://example.org {type=button,outline=true}` \
{hyper}`https://example.org {type=button,color=info}` \
{hyper}`https://example.org {type=button,shadow=true}`

Todo

Apparently, the shadow option does not work?

Example Domain
Example Domain

Use class and tooltip options.

{hyper}`https://example.org {type=button,class=text-small}` \
{hyper}`https://example.org {type=button,tooltip=Tooltip Message}`

🌻 Read More 🍀

Text input accepts Unicode glyphs.

{hyper}`🌻 Read More 🍀 <https://example.org> {type=button}`

Read More
Read More

The value of the icon option translates to the syntax of an inline icon from sphinx-design, inheriting all its features.

{hyper}`Read More <https://example.org> {type=button,icon=octicon:report}` \
{hyper}`Read More <https://example.org> {type=button,color=info,outline=true,icon=material-outlined:emoji_objects;3em;sd-text-primary}`

Card

Adding the option {type=card} renders the hyperlink using a card based on the sphinx-design card directive, it accepts the same options, and the additional icon option.

Options

The card Hyper understands the same options like offered by the card directive, see card options.

Item

Description and Syntax

Fundamentals

Example Domain

A basic card hyperlink for URLs, without any options.

{hyper}`https://example.org {type=card}`

shield-directive

Shield Badges

Use project-local references.

{hyper}`shield-directive {type=card}` \
{hyper}`Shield Badges <shield-directive> {type=card}`

Cards

Card Layouts

Use intersphinx references.

{hyper}`sd:sd-cards {type=card}` \
{hyper}`Card Layouts <sd:sd-cards> {type=card}`

Title, Header, Footer

header

title

Example Domain

footer

The title, header, and footer options directly translate to the corresponding slots of the card element.

{hyper}`https://example.org {type=card,title=title,header=header,footer=footer}`

content

content

The value of the link title / label can be defined on behalf of the {ref} syntax, as usual, or by using the content option.

{hyper}`content <https://example.org> {type=card}` \
{hyper}`https://example.org {type=card,content=content}`

Style

Example Domain

Shadows.

{hyper}`https://example.org {type=card,shadow=md}`

Example Domain

Icons.

{hyper}`https://example.org {type=card,icon=octicon:rocket}` \
{hyper}`https://example.org {type=card,icon=octicon:rocket;3em,notext=true,text-align=center}`

Shield

Adding the option {type=shield} renders the hyperlink using a badge based on the shield directive implementation.

Options

Please refer to the corresponding shield options, in order to learn about how this component can be configured.

Fundamentals

Item

Description and Syntax

A basic shield hyperlink.

{hyper}`https://example.org {type=shield}` \
{hyper}`mailto:test@example.org {type=shield}`

Using a self-defined linked label works the same way with {type=shield}.

{hyper}`Read More <https://example.org> {type=shield}`

Link to project-local references, with link labels.

{hyper}`Info Card <infocard-directive> {type=shield}` \
{hyper}`Info Card <#infocard-directive> {type=shield}`

Using a traditional intersphinx reference is the most compact way to run links to other Sphinx projects.

{hyper}`sd:sd-cards {type=shield}` \
{hyper}`Card Layouts <sd:sd-cards> {type=shield}`

MyST reference syntax is also supported for intersphinx links.

{hyper}`inv:sd:*:doc#index {type=shield}` \
{hyper}`inv:sd:*:label#sd-grids {type=shield}` \
{hyper}`inv:sd#sd-cards {type=shield}`

Layout

A shield with an additional label, rendered on the left-hand side.

{hyper}`https://example.org {type=shield,label=Read}`

When using an additional shield label on the left-hand side, the text on the right-hand side can be defined through the link label, or the message option.

{hyper}`More <https://example.org> {type=shield,label=Read}` \
{hyper}`https://example.org {type=shield,label=Read,message=More}`

Because hyper roles render as inline elements, multiple instances can be placed side by side, even when written down spanning multiple lines.

{hyper}`1 <https://example.org> {type=shield}`
{hyper}`2 <https://example.org> {type=shield}`
{hyper}`3 <https://example.org> {type=shield}`

Tip

For purposely applying line breaks, use the backslash \ as line continuation character.

Style

About defining colors, an icon, and the style/shape of the shield. The corresponding options accept the same values like the shield directive.

Use the color option to adjust the background color.

{hyper}`https://example.org {type=shield,color=darkgreen,logo=Markdown}`

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.

{hyper}`https://example.org {type=shield,label=Read,message=More,label-color=darkgreen,message-color=orange}` \
{hyper}`https://example.org {type=shield,label=Read,message=More,label-color=hsl(270,60%,70%),message-color=rgb(255,0,153)}` \
{hyper}`https://example.org {type=shield,message=Read More,color=#123456}`

Text input accepts Unicode glyphs.

{hyper}`https://example.org {type=shield,label=🌻 Read,message=More 🍀}`

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

{hyper}`CrateDB <https://cratedb.com> {type=shield,color=gray,logo=CrateDB}`

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

{hyper}`https://example.org {type=shield,style=flat}` \
{hyper}`https://example.org {type=shield,style=flat-square}` \
{hyper}`https://example.org {type=shield,style=plastic}` \
{hyper}`https://example.org {type=shield,style=for-the-badge}` \
{hyper}`https://example.org {type=shield,style=social}`

Text

The textual output variant and its features are outlined at the Fundamentals section.

Gallery

A few more examples, about shortcuts and intersphinx linking.

Badges Everywhere

Badges in multiple colors, optionally outlined.

primary secondary success danger warning info light dark muted

primary secondary success danger warning info light dark muted

{hyper}`primary <https://example.org> {type=badge,color=primary}`
{hyper}`secondary <https://example.org> {type=badge,color=secondary}`
{hyper}`success <https://example.org> {type=badge,color=success}`
{hyper}`danger <https://example.org> {type=badge,color=danger}`
{hyper}`warning <https://example.org> {type=badge,color=warning}`
{hyper}`info <https://example.org> {type=badge,color=info}`
{hyper}`light <https://example.org> {type=badge,color=light}`
{hyper}`dark <https://example.org> {type=badge,color=dark}`
{hyper}`muted <https://example.org> {type=badge,color=muted}`

{hyper}`primary <https://example.org> {type=badge,color=primary,outline=true}`
{hyper}`secondary <https://example.org> {type=badge,color=secondary,outline=true}`
{hyper}`success <https://example.org> {type=badge,color=success,outline=true}`
{hyper}`danger <https://example.org> {type=badge,color=danger,outline=true}`
{hyper}`warning <https://example.org> {type=badge,color=warning,outline=true}`
{hyper}`info <https://example.org> {type=badge,color=info,outline=true}`
{hyper}`light <https://example.org> {type=badge,color=light,outline=true}`
{hyper}`dark <https://example.org> {type=badge,color=dark,outline=true}`
{hyper}`muted <https://example.org> {type=badge,color=muted,outline=true}`

Buttons Everywhere

Buttons in multiple colors, optionally outlined.

primary secondary success danger warning info light dark muted

primary secondary success danger warning info light dark muted

{hyper}`primary <https://example.org> {type=button,color=primary}`
{hyper}`secondary <https://example.org> {type=button,color=secondary}`
{hyper}`success <https://example.org> {type=button,color=success}`
{hyper}`danger <https://example.org> {type=button,color=danger}`
{hyper}`warning <https://example.org> {type=button,color=warning}`
{hyper}`info <https://example.org> {type=button,color=info}`
{hyper}`light <https://example.org> {type=button,color=light}`
{hyper}`dark <https://example.org> {type=button,color=dark}`
{hyper}`muted <https://example.org> {type=button,color=muted}`

{hyper}`primary <https://example.org> {type=button,color=primary,outline=true}`
{hyper}`secondary <https://example.org> {type=button,color=secondary,outline=true}`
{hyper}`success <https://example.org> {type=button,color=success,outline=true}`
{hyper}`danger <https://example.org> {type=button,color=danger,outline=true}`
{hyper}`warning <https://example.org> {type=button,color=warning,outline=true}`
{hyper}`info <https://example.org> {type=button,color=info,outline=true}`
{hyper}`light <https://example.org> {type=button,color=light,outline=true}`
{hyper}`dark <https://example.org> {type=button,color=dark,outline=true}`
{hyper}`muted <https://example.org> {type=button,color=muted,outline=true}`

Shield Shortcuts

Shield shortcut roles help saving a few keystrokes. Examples: hyper-navigate, hyper-open, hyper-tutorial, hyper-read-more, hyper-readme-github, hyper-nb-colab, hyper-nb-binder, hyper-nb-github.

---

{hyper-navigate}`https://example.org`
{hyper-open}`https://example.org`

{hyper-tutorial}`https://example.org`
{hyper-read-more}`https://example.org`
{hyper-readme-github}`https://example.org`

{hyper-nb-colab}`https://example.org`
{hyper-nb-binder}`https://example.org`
{hyper-nb-github}`https://example.org`

Intersphinx across the board

There are some flaws here yet, see backlog below.

Intersphinx Text-Only

• {hyper }sd:index provides Grids Cards Dropdowns Tabs {hyper }sd:badges_buttons {hyper }doc:badges_buttons Additional.

Intersphinx Shields

• provides .

• provides { hyper}myst:syntax/admonitions {type=shield} { hyper}myst:syntax/math {type=shield} .

Backlog

Todo

There are a few errors in here: sd:index, sd:badges_buttons, and doc:badges_buttons can’t be resolved well. See “Intersphinx across the board”.

Todo

Link label resolution does not work yet with project-local links, e.g. infocard-directive, #infocard-directive.

Todo

rgb() / hsl() colors do not work, yet. They contain values separated by commas, which confuses the naive role option parser.

Todo

Resolving myst:syntax/admonitions and myst:syntax/math does not work yet, due to ambiguity errors.

– More than one target found for ‘myst’ cross-reference [myst.xref_ambiguous]

Todo

Maybe use a different way of having shortcuts, not by using dedicated roles, but integrated into the options instead. Also, leverage shield-level style presets, as outlined in their backlog.