WMDE Technical Wishes/ReferencePreviews

Reference Previews

The Reference Previews feature displays a preview of a reference within text when hovering over a footnote.

Background: Clicking on a footnote discards the reader's previous position on a wiki page, making it difficult to continue reading after consulting the footnote. A proposed solution to this problem is to offer previews for footnotes. Read more about the history of the project.

Scope: This project is scoped to desktop only; the problem is already solved on mobile.

Coordination and implementation of this wish was performed by the Technical Wishes team at Wikimedia Deutschland, in cooperation with the WMF's Reading Web team.

Status and next steps

• YMay 6, 2021: Deployed as a default feature on some wikis:
  • on German, Marathi, Romanian, Estonian and Basque Wikipedia – wikis without a default gadget for previewing references
  • on Gujarati, Hebrew, Arabic Wikipedia – wikis with a default gadget for previewing references
  • on Finnish Wikipedia – wikis using citation classes which can be used to display reference types in the pop-ups
• Y August 19, 2021: Deployed as a default feature on German Wikivoyage
• Y November 21, 2023: Deployed as a default feature on all remaining wikis using the Popups extension (i.e. all other Wikipedias plus en, he and zh Wikivoyage)
• YFebruary, 2024: In February 2024, Reference Previews became the default for previewing references on some Wikipedias where Reference Tooltips was a default gadget:
  • Some wikis removed the default flag for Reference Tooltips themselves, following announcements to village pumps on all 70 affected Wikipedias.
  • On 21 wikis, global sysops removed the default flag (T355312). Those are wikis that have three or less interface-admins and are also global sysop wikis: af, as, az, ba, be, ce, ckb, hi, hy, ilo, kk, kn, ks, lez, mai, myv, ne, ny, pa, tg, udm. This change was announced on January 23 (ny on Feb 16), with the option to opt out until February 12. Onlyla Wikipedia opted out.
  • To 34 Wikipedias, we suggested they remove the default flag themselves. Those are wikis that have four or more interface-admins, and/or opted out of being a global sysop wiki. Those are: bs, ca, cs, da, en, es, fa, gl, hu, id, it, ja, ka, ko, lv, ml, ms, nl, pl, pt, ru, sh, simple, sk, sr, sv, ta, th, tr, uk, ur, uz, vi, zh-yue. Those wikis can ask the Technical Wishes team for support.
    

Look and functionality

Overview

Reference Previews display a preview of the footnote as it appears at the bottom of the page. Within the preview, any and all footnote content (text, images, tables, ...) can be displayed. At the top of the pop-up, the reference type is displayed (more info).

Reference Previews were designed to create an experience consistent with Page Previews, so that all pop-ups have the same design, regardless of whether you are hovering over a page link or a footnote marker. The feature is part of the MediaWiki extension Cite, responsible for handling references.

Reference Previews and Page Previews next to each other.

Interactions

• Hover over a footnote marker to open the pop-up.
• Click on a footnote marker to jump to the References section (as you would do if there weren't any pop-ups).
• For shorter references, the pop-up window adjusts to a smaller size.
• If the reference size exceeds the maximum pop-up, you can scroll within the preview window.
• External links inside a reference open in a new tab.

The preview functionality relies on JavaScript. If you don't have JavaScript activated, there is no hover effect, and footnote markers remain simple jump marks.

Opt-out feature

Reference Previews are activated by default for everyone (logged-in users, anonymous contributors, readers of a wiki).

• You can toggle them off under the Appearance tab in your preferences.
• You can also open this preference tab directly by clicking on the cog wheel in the pop-up.
• Anonymous contributors/readers can turn the previews off by clicking the cog wheel and toggling the setting. This saves the preference via a cookie. They can be turned back on using the "Edit preview settings" link in the website footer.

Please note:

• If you use the Reference Tooltips or Navigation Popups gadget – either because it's a default gadget on your wiki or because you enabled it individually – you won't see Reference Previews.

Relation to Page Previews

• Both Reference Previews and Page Previews are using the Popups extension.
• You can enable Reference Previews even if Page Previews are disabled, and vice versa.

Exposed reference types

At the top of each pop-up, Reference Previews prominently indicate what kind of source is being referenced. We currently define six reference types:

• Reference (generic)
• Web reference
• Journal reference
• Book reference
• News reference
• Note

We expose the specific reference types because citations and external links play a fundamental role in whether readers trust an article, and readers trust a cited source more when it is perceived as authoritative and accessible (allowing them to verify it independently). Initial tests have supported our assumption that exposed reference types

• help readers decide more quickly if they want to have a closer look at the article's trustworthiness. For example, a journal publication is deemed more trustworthy than a blog post. This improves the information's reliability and transparency.
• serve as an indicator for the accessibility of the referenced material. For example, if the source material is on the web it will likely be easy to access; if it's a book, less so.
• raises awareness among readers of the fact that articles are supported by various types of reference material.

How to assign a reference type to your reference

Each reference is defined by CSS classes, e.g., <cite class="journal"> for journal references. These classes are set in the <cite> element in a reference's content (more info). References without cite tags and classes (e.g., plain <ref> tags) are displayed as "Reference".

To assign a reference type:

• The easiest way is to use a citation template that includes the cite class. The English cite templates, for example this one, specify the cite class already, and derivations of these templates are used in many wikis. Other templates can also be updated to do so.
• If you're not using templates to add references, another option is to add a cite class directly into a ref tag, like so: <ref><cite class="book">reference content</cite></ref>.

Relation to gadgets

Reference Tooltips gadget on en.wikipedia.org

Gadget on nl.wikipedia.org

Differences from Reference Tooltips

The Reference Tooltips gadget written by Yair rand is very similar to Reference Previews. Currently, around 100 wikis are using a (modified) copy of this gadget as the default feature for previewing references (December 2023). Two important and notable differences between this gadget and the Reference Previews feature are:

• Reference Previews exposes the reference type(s), which helps readers more quickly evaluate the trustworthiness of an article (see above).
• Reference Previews' design is consistent with that of Page Previews to create a consistent user experience; both previews are toggled on and off together.

Why we built a new feature

Reference Previews offer an easy way to show reference previews to readers of wikis that aren't using Reference Tooltips (or a variation). They are not intended to replace the Reference Tooltips gadget. Wikis using Reference Tooltips as a default gadget retain it as a default gadget unless they decide otherwise. Individual users who prefer Reference Tooltips can simply enable that gadget, whereupon Reference Previews won't be shown.

The Reference Tooltips gadget is installed on many wikis and is enabled by default on several, allowing readers to use it as well. But most wikis don't have such a gadget as a default. In the 2017 Technical Wishes survey on German Wikipedia, the dewiki community requested a reference preview feature owing to several issues with the gadget on dewiki, some of which follow:

• the fork used on dewiki was practically unmaintained
• the font size was too small
• symbols (such as the PDF icon) were not displayed in previews

At the time at which the team evaluated the wish for implementation, a preview feature – Page Previews – had already been developed as an integrated functionality of MediaWiki, but this feature did not include previews of references. Therefore the team decided that it made sense that this additional feature would also be developed and maintained by WMF/WMDE, and provided to the wiki communities. Reference Previews is therefore not a new feature, per se, but complements the existing Page Previews feature, thus creating a consistent reading experience and a more holistic approach to previews.

Project history

This wish was the top-ranked request from the summer 2017 wishlist survey of the German-speaking community, but it had been under discussion since 2014 on Phabricator (T67114), and the functionality has been implemented as a gadget used on many wikis (read more).

Research

We gathered insights and feedback on the topic both online and in conversations with Wikipedians at Wikimania and German WikiCon 2017. Main outcome:

• This wish was not considered controversial. It would be good to have pop-ups as a feature for everyone; several wikis already had gadgets with that functionality.
• The enwiki and nlwiki gadgets (Reference Tooltips) were cited several times as good examples.
• The look and behavior of the initial designs were received well in tests with readers.

Beta phase

Where and when Reference Previews were deployed to wikis as a beta feature:

• test.wikipedia.org: 2019-02-28
• German Wikipedia: 2019-04-04
• Arabic Wikipedia: 2019-04-04
• All other Wikipedias: 2019-10-24
• English, Chinese and Hebrew Wikivoyages: 2019-10-24

What was changed after the beta release?

After the first release of Reference Previews as a beta feature, we were able to gather a significant amount of feedback. Based on this feedback, parts of the feature were changed, such as:

• Increased maximum height to reduce scrolling (T246029)
• Add a cog wheel inside the popup for settings (T234205)
• Fixed issues with scrollbar (T249530)
• Removed fixed heading in preview window (T249548)
• Removed "jump to reference" link (T265482)
• Click behavior:
  • On click the page jumps down to the References section (T265482)
  • Links to the same page open in same tab (T215419)
  • Internal, sister-wiki and interwiki links open in same tab (T239230)

Frequently Asked Questions

• Height and scrolling: We received a lot of feedback on the size of the popups. While some people asked for smaller popups to make the features less intrusive, in fact most wanted the popups to be bigger to avoid having to scroll. In response to this feedback, we increased the popups' maximum height, minimizing the appearance of scrollbars – the popups now adjust automatically to the length of the reference, only adding a scrollbar if the reference text exceeds the maximum length.
• White space: Previewing a reference is very similar to the experience of previewing a linked page. That's why Reference Previews were designed to be consistent with Page Previews. Both employ more white space and padding than some are accustomed to, but all in all it makes for an easier reading experience.
• Reference type shown at the top: read more about it here.

Can I choose to have previews by click rather than by hover?

No, and here's why. When the beta feature was first released, pop-ups appeared when clicking and when hovering over the footnote marker. After usability testing we changed that behavior: When you hover over the footnote marker, a pop-up appears; when you click on the marker, you jump down to the References section. Testing showed this is the behavior most people expect. We implemented the behavior that works best for most people instead of adding another setting, due to the fact that more settings add undue complexity to the features and code.

Similarly, the team who built Page Previews carefully considered the length of the delay before showing a preview. Their goal was to minimize the accidental or unintended previews popping up on the screen. Reference Previews use this same delay.

Do Reference Previews support nested content?

They do, but you won't see pop-ups within pop-ups. Instead, you can jump to the linked content by clicking. This decision was made to avoid confusion which links within the preview create additional previews and which links do not.

Are Reference Previews opt-in or opt-out for me?

• Reference Previews are opt-out for everyone. You can disable them in your preferences.
• If you have the gadget Reference Tooltips or Navigation Popups enabled, you won't see Reference Previews.
• Read more about this in this section.

Not all footnotes are references. Why is the feature called Reference Previews?

We discussed whether it should be called be Footnote Previews, since the feature previews not only formal references but all kinds of footnotes. Nonetheless, we chose "references" for the following reasons:

• Footnotes are based on references: to create a footnote with wikitext, you use the <ref> (references) tag.
• When you insert a citation with Visual Editor, the word "footnote" doesn't appear. Instead, the interface mentions citations and references.
• The gadget in use across many wikis is also called Reference Tooltips.

What do I do when the footnote in the popup isn't a reference but a note?

In that case, you can assign the class "Note" to your reference, which will change the heading. Read more about how to assign a reference type to your reference.

Are Reference Previews compatible with screen readers?

Yes. Right now, when using Reference Previews, your screen reader handles references just as if there were no pop-up; it simply reads the link aloud, and when you click, it takes you to the corresponding reference in the References section.

External links

A little video explaining the problem and the solution

• project board on Phabricator
• Reference Previews: central help page on Mediawiki.org
• Reference Previews: central feedback page on Mediawiki.org
• extension manual on Mediawiki.org
• Page Previews: main project page on Mediawiki.org
• Page Previews: central feedback page on Mediawiki.org

Related projects

• Page Previews are activated on all Wikipedias and some Wikivoyages. Several wikis have gadgets for page previews.
• Footnote highlighting, implemented by the Technical Wishes team, makes it easier to find your way back up from a footnote.

Feedback

As always, we welcome your feedback on the talk page!