Add support for icons

[agoose77]

This issue tracks our missing support for icons used in the Executable Books and Sphinx ecosystems, defined in https://github.com/executablebooks/sphinx-design.

[agoose77]

@rowanc1 @choldgraf I have started tackling this today, and I have some thoughts on things we could improve relative to SD.

• sphinx-design uses long role names e.g. {material-twotone}
• sphinx-design uses different specs depending on the icon family to define classes and size information, e.g.
  • {octicon}`report;1em;sd-text-info` (name;size;class)
  • {fab}`github;sd-text-info` (name;class)
• sphinx-design has a different role type per icon, e.g. {fab}`github`, {octicon}`report`

I think we should write a new icon role that myst init upgrades the legacy role types to. This new role wouldn't support size information (because that's styling), and we would use the following syntax:

{icon}`fab:github`
{icon}`oct:report`
{icon}`mtt:settings`

If we want to add classes, I'm not sure whether we make an initial release without them and then leverage a more generic inline-attribute syntax e.g. #1423

Otherwise, we could for now inline it in the role body e.g.

{icon}`fab:github .large`

I'm obviously against that.

I also wonder whether we should formally acknowledge that really we have three icon packs with various kinds, e.g.

{icon}`fa:b:github`

or

{icon}`fa:r#github`

So far, I'm in favour of just having each combination of variant and family to be a new "icon pack" e.g. far, fab, oct, mtt, etc.

Does anyone have any thoughts here?

[rowanc1]

Quite like {icon}`fab:github`, and bringing in classes/ids and other inline attributes in a standardized way later. Another alternative closer to the cite roles is {icon:fab}`github`, which also seems ~ok (this could be a standardized way of encoding kind? e.g. prf:example, cite:p).

I think we should transparently alias to previous functionality using the alias in the role if that works?

[agoose77]

@rowanc1 I was thinking about {icon:fab} but completely forgot about it when writing here. I think that's exactly how we should do it.

[agoose77]

@rowanc1 are you not in favour of just introducing this syntax exclusively and upgrading using the upgrade tool?

[rowanc1]

I think until we have JupyterBook v2 docs up, moved over to the primary domain, are actively recommending that, and the majority of the community has moved, everything needs to be backwards compatible content-wise.

Most of the groups and researchers I am working with are in between a transition, and anything that is not backwards compatible (including the glossary) makes it harder for them to try things before they commit to a change. Many of these people are running myst and JBv1 at the same time.

I would like us to adopt a strategy of backwards compatibility and opt-in upgrading of syntax. We can force that to upgrade in a year or so.

Any time things are not backwards compatible and require a content change, we force people to upgrade and commit. There are still things that myst doesn't do, namely search, which make that a hard sell, and most people writing books it isn't worth the switch without that.

[choldgraf]

I'm a big fan of the icon:gh style syntax. As for backward compatibility, I don't think I feel as strongly as @rowanc1 here but if he is getting strong signals from communities then it's worth trying to keep compatibility there, as long as we aren't taking on too much maintenance burden and code complexity.

The important thing is that the "preferred" and future supported UX is the best we can do, even if there are some band-aid patterns supported for legacy purposes

[cboettig]

It would also be great to have support for icons on nav items. I imagine this would be done in the myst.yml, perhaps similar to how it us currently done in yaml in quarto :https://quarto.org/docs/reference/projects/websites.html#nav-items ?

Backwards compatibility with sphinx would be nice; I like the flexibility of the sphinx syntax but it feels vaguely ridiculous to me -- when the markdown syntax is more convoluted than html+css solution it feels like I'm doing it wrong.