RC.12 breaks ref shortcode application behaviors

[cbutcosk]

Before proceeding, make sure there isn’t an existing issue for this bug.

• I have searched the existing issues and determined this is a new bug.

Expected Behavior

Using quire-starter-default I expect ref shortcodes to produce links that jump me to the figure if given the figure ID.

Actual Behavior

ref produces an anchor link but clicking does nothing and produces no console messages AFAICT.

Steps to Reproduce

• npm install @thegetty/quire-11ty @thegetty/quire-cli ; npx quire new test
• cd test
• npx quire preview
• Go to http://localhost:8080/essay/ and click on any of the figure ref links toward the bottom of the text.

Version Numbers

[CLI] Command 'info' called with options { debug: true }
[test]
quire-cli 1.0.0-rc.10
quire-11ty 1.0.0-rc.13
starter https://github.com/thegetty/[email protected]
[System]
quire-cli 1.0.0-rc.10
node v18.17.0
npm 6.14.18
os Darwin 22.6.0

Web Browser

Safari (16.6) and Chrome (latest)

Relevant Terminal/Shell Output

No response

Supporting Information

No response

[Erin-Cecele]

Good catch, @cbutcosk. Thanks for bringing this to our attention. The original version of the ref shortcode was made for figure callout links (as you note.) We've since changed its behavior which is likely why it's not working in the starter. We'll get that fixed ASAP.

In the meantime, it would be helpful to know if you have been using the ref shortcode (as per its original intended use) in any of your Quire publications. Please advise.

[cbutcosk]

@Erin-Cecele Almost every quire publication I've helped implement has used ref and in a brief perusal of recent projects most of the projects I checked also used ref for the linking-to-a-figure use case. Now, perhaps that's because the starter project has them and so it seems like a "quire-ish" thing to do?

It is definitely still an expectation among most authors I speak to that you can easily link to an in-essay figure! Is ref deprecated for the figure-linking use case in favor of some simpler mechanism or some mechanism within the new ref/née annoRef?

[Erin-Cecele]

Hi @cbutcosk. I'm sorry for the confusion. The ref shortcode was added early in the v1 development process. Despite it being undocumented and somewhat untested, it made its way into our default starter. Since it essentially duplicates the function of internal Markdown links (which is easier and more flexible to use), we decided to fold the ref shortcode into a new, more powerful feature (and shortcode previously called annoRef) that will be documented and announced soon.

In retrospect, it would have been good to make our decisions around the ref shortcode part of a public discussion so members of the community could have weighed, and so it wouldn't catch people off guard as it did with you.

Also, in addition to your work with Georgia O'Keeffe, what other Quire publications have you been working on? We would love to hear about them!

[cbutcosk]

@Erin-Cecele Thanks for the explanation, that sequence of events makes a lot of sense.

As an implementer it's really important to have a quire doc I can point to and say "do whatever they did to create the author things you like". So I have haltingly tried to treat quire-starter-default as a canonical expression of "how to quire", though that turns out to be a bit unstable in the release candidate series. That's fine too but it makes it hard to follow quire's process in an author / content editor role.

So anyway I totally agree: please be empowered to start conversations about this stuff as it heads into / out of the roadmap! Everyone out here definitely appreciates your advocacy. :)

Re ref vs raw MD links. I suspect that authorial and editorial roles expect there to be more magic in a figure reference than an MD anchor link. The raw link ergonomics... aren't great! [Figure 1.](#a-really-great-fig-1) is a little incantatory vs { ref 'a-really-great-fig-1' }. The repeat-use case is a little nicer in MD since authors get to name their anchor link text, but it looks (to me) like the expected behavior would be ref remaining its old self, accepting an optional anchor text param, and managing later fig ref instances itself (eg, when "Figure 1." -> "fig. 1" in later references).

But in fairness I have not futzed with annoRef at all so perhaps that has the more complex behaviors I'm seeking at the upper end of the complexity spectrum.

[Erin-Cecele]

Thank you again, @cbutcosk. We will document the new {% ref %} shortcode at our earliest convenience and get the default starter fixed to prevent further confusion.

In the meantime, here is a quick preview of what the new {% ref %} shortcode can do. This shortcode is for use only on pages with layout: entry and can only be applied to IIIF zooming images.

At its most simple it can be used as such:
{% ref fig='fig-367' text='repair work' %}

fig = image id
text = display text

At its most complicated it can be used as:
{% ref fig='fig-367' text='repair work' region='4700,2640,888,577' anno='wax,borders,outline' onscroll='true' %}

region = section of the image that it will Zoom into
anno = what annotation layers will be turned on
onscroll = as you scroll past the figure callout the image will change in the lightbox that appears on the left side of layout: entry pages.

Hope that sheds light on how we have reimagined the {% ref %} shortcode and increased its functionality in Quire.

I also want to address your point about link ergonomics. We agree that a figure callout-specific shortcode, where you have the ability to override the display text (similar to the way the {% cite %} shortcode works), would be more user friendly. The complication is that the old {% ref %} shortcode supported multiple ids with multiple links.

For example: {% ref 'fig-4', 'fig-5' %} would have rendered Markdown equivalent to [figs. 4](#fig-4) and [5](#fig-5) and {% ref 'fig-4', 'fig-5', 'fig-6', 'fig-7' %} would have rendered Markdown equivalent to [figs. 4](#fig-4), [5](#fig-5), [6](#fig-6), and [7](#fig-7). Overriding display text becomes complicated as you would need multiple display texts for the multiple links, ultimately making the shortcode unwieldy.

Do you think there is a desire for a new shortcode that would only handle one figure callout at a time? It's likely not something Getty would have the bandwidth to implement, but we could poll the community. If there is a strong interest in developing a new shortcode, we could encourage someone in the community to contribute that capability back to Quire. Let us know your thoughts.

[Erin-Cecele]

Update: we fixed the related issue #886 to prevent further confusion when using the default-starter. However, we are leaving this issue open and labeled as "needs discussion" to gather additional feedback about potentially creating a new shortcode that would only handle one figure call out at a time.