WMDE Technical Wishes/ReferencePreviews
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
- Reference Previews are currently a default feature on many wikis.
- May 6, 2021: Deployed as a default feature
- 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
- August 19, 2021: Deployed as a default feature on German Wikivoyage
- More wikis will follow in the course of the year.
- No other changes to the feature are planned.
Look and functionality
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 Popups, also used for Page Previews.
- 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.
Reference Previews will be activated by default for everyone (logged-in users, logged-out/anonymous users, 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 users/logged-out users/readers can turn the previews off by clicking the cog wheel and toggling the setting. This will save the preference via a cookie. They can be turned back on using the “Edit preview settings” link in the website footer.
- 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.
- For wikis where Reference Previews are still a beta feature, you will need to activate it in your beta settings.
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
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
citeclass. The English
citetemplates, for example this one, specify the
citeclass 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
citeclass directly into a
reftag, like so:
<ref><cite class="book">reference content</cite></ref>.
Relation to gadgets
Differences from Reference Tooltips
The Reference Tooltips gadget written by Yair rand is very similar to Reference Previews. Two important and notable differences:
- 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) and are not intended to replace the Reference Tooltips gadget. Wikis using Reference Tooltips as a default gadget will 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.
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).
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.
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:
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.
Will Reference Previews be opt-in or opt-out for me?
- Reference Previews will be 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
- 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. However, this behavior may change before the Reference Previews feature is deployed to more wikis.
- 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
- 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.
As always, we welcome your feedback on the talk page!