🖲 Add button role

[jnywong]

Ref: 2i2c-org/infrastructure#5346

Co-authored-by: Angus Hollands [email protected]

This PR is a spike for a button role. Sphinx-design has button directives, but these feel under-constrained for mystmd. Furthermore, buttons feel like "special links", and links are inline elements. As a consequence, @jnywong and I decided to implement a button as a special kind of link. We also added a class attribute to the Link node. This will enable primary-secondary styling of buttons in future. This is probably the way that we'll go for all node types — add class and maybe label etc. to every node.
With a recent discussion for adding inline-attributes to roles ({button .secondary}`My button <https://>.` ), this might become a nice UX. This may also be relevant if we support inline attribute annotation of Markdown syntax, e.g. {kind=button}[a button](https://...)
To support sphinx-design, we might consider "upgrading" button directives into block-divs containing {button}`...` in future.
-- @agoose77

References

• Related PR: 🔘 Add support for buttons myst-theme#521
• closes Add a button for call to action and noticeable links #1654

TODO

• Update myst spec!

[changeset-bot]

🦋 Changeset detected

Latest commit: f6d5bcc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
myst-ext-button	Patch
myst-spec-ext	Patch
myst-cli	Patch
myst-common	Patch
myst-config	Patch
myst-frontmatter	Patch
mystmd	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[agoose77]

Buttons feel inherently link-like, i.e. they are not new node types, but more of a styling augmentation.

[rowanc1]

Thanks for the PR (taking a quick look while in draft!). I am curious if there is going to be conceptually more to myst-ext-button package in the future? In which case, maybe expanding the package name to cover it?

[rowanc1]

Nice - this means there is a good fallback.

[jnywong]

Hey @rowanc1 ! Yeah @agoose77 and I were prototyping today and made a lot of pivots!

I am curious if there is going to be conceptually more to myst-ext-button package in the future? In which case, maybe expanding the package name to cover it?

We very quickly found there's a myriad ways authors may want to style links, and initially borrowed some inspiration from the existing card component. For this PR, we're going to be focused on a button package specifically and will hopefully converge on extensibility in a future iteration.

[rowanc1]

Makes sense, forgot about the card package as an analogy.

[choldgraf]

Can you provide short user-facing documentation for how this would be used? That would make it easier to understand the implications of role vs. directive etc.

The most common use-case I can imagine for a button is in situations like this:

Some paragraph with a call to action.

[Click me button]

And some more paragraph text.

It sounds like this implementation would be accomplished with the following, is that right?

Some paragraph with a call to action.

{button}`Some call to action text`

And some more paragraph text.

In the context of landing pages you might see one or more buttons next to each other, e.g.

# Title

![A wide hero-style image]()

[Click me button] [Another button]

In this case, is it correct that accomplishing these would be accomplished with:

# Title

![A wide hero-style image]()

{button}`Button text 1` {button}`Button text 2`

Beyond the case for two buttons side-by-side in a landing page-style site, what usecase do you imagine for the "role-like" functionality? E.g. do you imagine users will be doing things like writing some text and {button}`Click Me` putting an inline button like that?

Finally, just noting that one of the useful features of sphinx-design was that buttons could link to more than just URLs. You could either point to a page / ref / etc, or you could point to a local static file, and it would resolve the links appropriately. I don't think that is critical functionality for an MVP, but just noting it here as we are talking about configuration surface area and what kind of ways we expect people to use the feature

[agoose77]

I can engage on a few of these right now (though I will circle back for a lengthier reply).

Your examples are how we envisaged using a button — that's the benefit of a role vs directive.¹.

E.g. do you imagine users will be doing things like writing some text and {button}Click Me putting an inline button like that?

Yes, in fact that was one of the things I wanted to do for the AGU demo gallery, but couldn't get the styling right with the constraints at the time.

Finally, just noting that one of the useful features of sphinx-design was that buttons could link to more than just URLs.

Yes, this is a useful feature.

We borrowed the label <reference> Sphinx syntax (used in download, for example) to allow separating the label from the URL. Therefore, the following would be the proposed syntax for linking to documents and/or identifiers:

{button}`Click me <#identifier>`
{button}`#identifier`
{button}`Click me <./document.md>`
{button}`./document.md`

To implement this, we also need to extend crossReference with a kind, just like link.

An uncertainty that I have is whether the existence of two nodes that need "button-like" features implies the need to have

{
  "type": "button",
  "children": [
    {
      "type": "link",
      "url": "..."
    }
  ]
}

instead of

{
  "type": "link",
  "kind": "button",
  "url": "..."
}
  

However, I think in the long run I might prefer using annotations e.g.

{kind=button}[Click me](#identifier)
{kind=button}[](#identifier)
{kind=button}[Click me](./document.md)
{kind=button}[](./document.md)

Footnotes

1. For completeness, there's nothing in mystmd that precludes us from having directives produce inline node types. But we tend to consider directives as "block like" rather than "inline like". ↩

[choldgraf]

This and jupyter-book/myst-theme#521 look really nice to me. It sounds like we might want to change the syntax of how buttons are defined (e.g. by attaching them via classes), but that this implementation wouldn't close any of those doors. I'm +1 on merging this in so that we can see how this feature gets used and get a feel for it ourselves.

My only request is that we add a short snippet of docs, perhaps just a short section to https://mystmd.org/guide/dropdowns-cards-and-tabs ? I don't think we strictly need to block on that though because the role will be auto-documented if I understand properly.

That said, I am not the best to judge implementation, so take my review for what it's worth :-)

[rowanc1]

Looks good, feel free to merge whenever @agoose77 and @jnywong.

[agoose77]

I'm rushing off at the end of the day to get to a car dealership in time! I will circle back to this to get it merged on Monday (or sooner if possible), but I am 100% comfortable with anyone else merging it if they give it a quick once over!