WMDE Technical Wishes/Sub-referencing/Learnings - Meta-Wiki
Jump to content
From Meta, a Wikimedia project coordination wiki
WMDE Technical Wishes
Sub-referencing
Sub-referencing: What we’ve observed and learned 3 months after launch
edit
Sub-referencing example
Sub-referencing
is a MediaWiki feature designed to improve reusing references with different details and help contributors provide more precision in citations in Wikipedia articles. Instead of duplicating the same reference multiple times, contributors can now create one main reference and link multiple different sub-references to it. Sub-references may hold page numbers, video timestamps or other details. Our goal is to make citations clearer and easier to maintain in articles with complex citation needs. All of this is in support of improving verifiability, improved reading experience and creating simple editing workflows.
Thanks
edit
We would like to sincerely thank everyone who helped with shaping and building this feature, especially the countless volunteers who provided feedback and ideas over the years. This work was in collaboration between the
Technical Wishes team
at Wikimedia Deutschland, the
Editing
Mobile
and
Content Transform
teams at the Wikimedia Foundation.
Read more below on the journey of building and rolling out sub-references, as well as our learnings and next steps.
Key highlights
edit
Key highlights from our deployment to German-language Wikipedia (dewiki):
On day one of the release, editors added sub-references to 200 articles (see our
tracking category
for the most up-to-date numbers).
The
{{rp}} template
has been replaced in thousands of articles and has even been
deleted
, as a consequence of sub-referencing now better supporting
{{rp}}
’s initial use case.
At least 300 contributors have used the feature
in Visual Editor
at least once, and over 200 contributors worldwide have helped with shaping and improving the feature by joining our discovery and testing activities or by providing feedback on-wiki.
Most early adopters are experienced users who predominantly use the wikitext editor.
The feature is already delivering visible improvements to articles:
The number of similar references
in dewiki articles is starting to slowly decrease, making reference lists easier to navigate and consume by readers.
The dewiki article
Ophiuride
has
earned the status of featured article
while being improved with sub-references. This is a signal that contributors who deeply care about article quality are drawing value from sub-referencing.
Contributors are dropping workarounds like

and
{{rp}}
, which has led to the full bibliographic information becoming available for the reader in
Reference Previews
Following the deployment to German-language Wikipedia on September 22, 2025, the points above as well as the feedback received so far validates that we are solving a meaningful problem for contributors. We have yet to analyse whether habits are being formed related to contributors making use of sub-referencing to create more precise citations and content that is easier to verify.
Goals and design principles
edit
Our goal was informed by a hypothesis that a simple to use, intuitive and well integrated feature would provide value for both contributors and readers.
For contributors, the feature is intended to reduce manual effort and citation errors, and to allow more precise citations, especially in Visual Editor, with the outcome of improving verifiability and citation quality.
For readers, we intended to improve the organization and clarity of reference lists, support more accurate assessments of neutrality, and facilitate directed further research by providing detailed, reusable citation information.
While designing and building this feature, we were guided by a set of design principles that shaped the solution and helped meet the needs of diverse communities:
Improve contributor workflows and reduce technical friction:
This required us to think of ways to integrate the new feature seamlessly into editing workflows, and most importantly in the contributors' preferred editors (Visual Editor and wikitext). Particularly for Visual Editor, the feature needed to have a strong benefit over citation templates that are currently poorly integrated into Visual Editor.
Wikitext compatibility:
Specifically for wikitext, we built this feature upon existing syntax rather than introducing an entirely new concept.
Allow for optional adoption:
The feature is intentionally designed to be an optional one. Contributors can continue using other citation styles if they prefer them over this feature.
Respect community autonomy through flexibility:
Instead of creating rigid structures, we wanted to enable communities to decide which types of content may be included through this feature and to
use templates
as appropriate.
Adoption, impact and community engagement during the first pilot
edit
First pilot
edit
Sub-referencing was first piloted on the German-language Wikipedia, and launched on September 22, 2025. This approach made it possible to gather early feedback in a controlled environment where we have strong ties to the community. One of the earliest feedback points was that reuse of sub-references is important and thus we worked on
merging re-used sub-references
so that they appear as re-used in the Visual Editor and reader views. Our plan for subsequent rollouts is
detailed below
, see also
T414094
Uptake and adoption by the German-language Wikipedia community in numbers
edit
To date, over 200 contributors from different Wikimedia projects have engaged with us directly, on-wiki and through other feedback channels (e.g. through user testing) to help us shape and improve sub-referencing.
Following the release to the German-language Wikipedia, interest and early adoption was immediate. A sizable number of articles (200) received the feature within 24 hours after the deployment. Below we list more data points that demonstrate uptake by the German-language Wikipedia community.
General numbers
(as of 01-19-2026):
6,162 articles using sub-references (see
category
for up to date numbers).
Over 15,000 sub-references have been created – roughly 10% of those using Visual Editor.
The proportion of references which are similar to one another has been reduced by a small percentage (-0.08%). This indicates a first movement towards more structured and less cluttered reference lists.
While the vast majority of sub-references are created in wikitext, we wanted to better understand how sub-referencing is discovered and used in Visual Editor, as the solution for wikitext is a more straightforward approach where we expect fewer issues.
Visual Editor numbers
(as of 01-19-2026):
347 unique contributors have created or edited sub-references at least once (incl. temporary accounts), with 14.7% (51) being logged-in contributors with less than 100 edits (ie. newcomers).
Visual Editor usage is steady, with an average of 85 sub-reference interactions per day (includes adding, editing, and deleting).
On average, 12 unique sessions per day resulted in interactions with sub-referencing
(note: this number reflects interaction events rather than total saved references)
What we’re learning from these numbers about contributor patterns
edit
From the numbers above it’s evident that sub-referencing is not a mass-use feature but a situational one, used in special cases and especially those where precision is needed. The feature is being used intentionally and consistently.
Furthermore, we’re currently seeing considerably higher usage in wikitext compared to Visual Editor.
We believe that this reflects the feature’s adoption primarily by experienced editors, who tend to work in the wikitext editor and are often responsible for complex citation edits.
Early data indicates that many of the sub-references created are a product of converting existing re-used references into sub-references rather than expanding and adding new details. This suggests that the feature is being used to clean up and improve citations by removing duplicates. Once the bulk of these tasks have been completed, we’ll be curious to learn whether habits are starting to form where contributors naturally choose to add sub-references whenever they feel the need to make more precise citations and make content easier to verify.
Nevertheless, we have observed edits demonstrating that sub-referencing is not just used for clean-ups, as described above, but also during the creation of new articles and in the expansion of existing articles, even by newcomers. This signals that less experienced users can also understand and integrate sub-referencing into their citation workflows. What we still need to understand is whether sub-referencing has improved the reuse of references, which we expect to better understand once the feature is rolled out to more wikis and more qualitative feedback reaches us.
Readers did not immediately notice sub-referencing in the articles presented to them, when we interviewed them about the feature. After being made aware of them by pointing out the difference between [1] and [1.1] they recognized the feature's value, saying that it gives them a better overview of how many sources were used. Also, sub-references that point to specific parts of a book were seen as beneficial, as they make it possible to verify information or learn more about a topic without having to consult the entire source.
In general, we’re learning that references and sources are important and are consulted by a relatively small group of readers.
Impact on articles
edit
In conjunction with the adoption and contributor patterns presented above, we’re seeing some clear examples of various positive impacts on articles:
One clear example is the dewiki article
Explosion des Oppauer Stickstoffwerkes
. Since adopting sub-references, the article’s wikitext size was reduced by
20%
, as the number of references decreased from
103 to 48
, and the overall article size shrunk from
109,000 bytes to 89,000 bytes
Diff
).
The article
Helmut Lachenmann
also experienced a similar consolidation, with references dropping from
105 to 42.
Beyond the reduction of duplicate and similar
references, all references used multiple times in the article were moved into the references list in wikitext
, enabling a cleaner structure and providing contributors with more easily maintainable citations (
Diff
).
Some contributors have replaced the usage of the
{{rp}} template
and
workarounds
, which previously served similar purposes in the articles. This simplification reduces complexity for contributors and ensures full bibliographic information (including in this case page numbers)
is displayed in
Reference Previews
, thus improving the reading experience
. See
Magdalena Spínola
for replacing (
Diff
) and
Caspar Christian Vogt von Elspe
Diff
) or
In den Rhythmen von Tukaj
Diff
) for replacing
{{rp}}
. Other

-workarounds (e.g. in
Maschinenparadigma
previously included
different details for the entire reference.
Converting to sub-referencing
simplified the wikitext and greatly improved Reference Previews.
In the article
Berlin-Gropiusstadt
, we’ve observed contributors turn previously inserted duplicates in the form of short citations (e.g. "Pfeifer 1998, p. 55-59") into sub-references to consolidate and improve the structure of the reference list (
Diff
). Just as with replacing other workarounds, such as the
{{rp}}
template, this led to the full bibliographic information becoming available to the reader through Reference Previews.
What types of details are contributors adding via sub-references?
edit
Contributors are using sub-referencing for a wide variety of reference details. This tells us that flexibility is important and that creativity can take up many unexpected forms. Here is a list of use cases we’ve observed in articles:
Page numbers – e.g.
Musa Bigiev
Page numbers, directly linking to GoogleBooks – e.g.
Doris Stockhausen
Page numbers and chapters – e.g.
Bischofsheim (Zeil am Main)
Chapters – e.g.
Q-Schlüssel
Paragraphs – e.g.
Riesenstern
Volumes – e.g.
Kreis Herzogtum Lauenburg
Magazine editions – e.g.
Horst Christoph
Quotes – e.g.
Liste lateinischer Phrasen/M
Annotations – e.g.
Autokrise
File numbers – e.g.
Bliesheim
Marginal notes – e.g.
Gesetz gegen den unlauteren Wettbewerb
Math formula + links to WolframAlpha calculations – e.g.
Ophiuride
Sub-pages of the same website – e.g.
Das macht Schule
Audio timestamps – e.g.
Bernard Rambert
Video timestamps – e.g.
Johann Rast
Community perspectives on sub-reference templates
edit
One of the main questions we asked ourselves while developing sub-referencing was how community templates would be used and whether they could be integrated seamlessly. We consulted the communities and listened closely to their perspectives on sub-reference templates. The feedback we received was mixed:
A small minority of users suggested we introduce technical limitations – or at least community guidelines – to restrict the
details="..."
attribute to basic wikitext to reduce the risk of reference errors.
Most users want flexibility in the way they’re using sub-references, similar to the flexibility allowed by regular references. Starting in 2024 we’ve observed contributors creating and experimenting with a
demo template for sub-references
on the Beta Cluster. Once sub-referencing got deployed to German Wikipedia we quickly saw different kinds of templates being used within sub-references (most notably the German equivalents of
{{cite web}}
{{cite book}}
{{Webarchive}}
and
{{Google books}}
).
Most users appear to be fine with the current level of template support – but that’s also because most sub-referencing users are very experienced and are predominantly wikitext users.
Among less experienced Visual Editor users we’ve learned that encountering a free-form field in the sub-reference dialog leads to uncertainty compared to entering content into a structured content form (i.e. template dialog)
In essence, the feedback we have received indicates that templates
can and should
live within the
details="..."
attribute of sub-references. If communities decide that they want a standardised set of templates to be seamlessly integrated into Visual Editor, we could support that direction and explore technical solutions. At the same time, just as with main references, whether and how templates are used remains ultimately a
community decision
, and clear
community-driven guidelines
will be essential to ensure consistency and maintainability. You can join the conversation on
metawiki
or
dewiki
Community feedback
edit
Contributors of the German-language Wikipedia provided thoughtful and constructive feedback on both the visual and usability aspects of sub-referencing.
Ease of use
edit
One contributor shared that the feature feels very smooth and intuitive to use, and that it significantly enhances their ability to work with greater precision in Visual Editor. Others expressed their appreciation that the feature is finally available!
Needed improvements to rendering and style of sub-referencing in the reader view
edit
A contributor compared the
current view
to a
similar one on French Wikipedia
, where the "additional details" (in this case page numbers) were displayed using responsive reference groups instead of a long list taking up too much space.
Several contributors expressed concerns about the current numbering format for sub-references (e.g.,
1.1, 1.2, 1.3
). They noted that when many sub-references accumulate, this style can feel visually heavy and become cumbersome, resulting in long sequences like
23.15
, or
1.285
which may reduce readability in the article text and clutter the reference list.
Some contributors reported difficulty to visually distinguish the decimal point, which creates accessibility challenges. Others suggested that alternatives such as
1a, 1b,
etc. would be clearer, more readable (particularly for visually impaired users), and better aligned with common citation practices in several non-English contexts. Contributors also asked whether it will be possible to customize or configure footnote marker styles to match local preference.
As a result we’d like to explore the rendering and views in the reference list to accommodate some of these needs (see
roadmap below
).
Preferred over other templates
edit
The wikitext syntax with the details attribute is considered to provide simplicity over
{{sfn}}
by some editors.
Several contributors expressed a clear improvement in contrast to the
{{rp}}
template as the latter introduces accessibility problems due to it splitting citation content across wikitext and the article text. They welcomed sub-referencing as a cleaner alternative and appreciate that it allows page numbers and other details to stay within the reference structure. Contributors of the German-language Wikipedia indicated that they would gladly support retiring
{{rp}}
and proceeded to
delete the template
after replacing its usage with sub-references. English-language Wikipedia’s creator of
{{rp}}
stated in 2018
that they would like to move away from using the template in favour of the proposed feature.
We’re thrilled to see contributors benefiting from sub-referencing compared to other templates that were built for similar use cases, but which had their own imperfections. It will be interesting to observe how
{{sfn}}
users will, or will not, adopt sub-referencing.
Social aspects
edit
Some German-language Wikipedia contributors have emphasized that the decision to use sub-references in an article is a stylistic preference and should follow the guidelines described in
de:WP:KORR
(roughly equivalent to
WP:CITEVAR
on English). In short, sub-references should neither be mandated nor prohibited and ideally usage will be guided by contributor consensus. In other words, by checking with the article’s main author before converting citations to sub-references.
Another topic that came up often in the feedback, is the question of what goes into the sub-reference. It should not be enforced technically nor by individuals, but rather through a community consensus. Some contributors argue for clearer guidelines or even limits, while others highlight the importance of flexibility to accommodate the varying citation needs depending on the topic being written.
This validates our approach in designing the feature as an optional one. Following community wishes, we would continue to recommend to contributors to respect the main author’s preferred citation style.
Further deployments and our next steps
edit
Deployment steps
edit
We’re planning to roll out the feature to all wikis in 2026. Our plan for deployments is documented in (
T414094
). Check back here for progress on deployments. Dates and times will be refined as we make progress. We will reach out to wikis accordingly.
Pilot wiki – phase 1
: German-language Wikipedia.
Pilot wikis – phase 2
: As soon as we have addressed most of the critical feedback for improvements we’ll start rolling out to wikis that don’t rely on or use the
{{reflist}} template
Global rollout – phase 1
: Begins as soon as we’ve reached a good level of compatibility for users working in VE with articles that use the
{{reflist}}
template. We will deploy in batches to left-to-right language wikis.
Global rollout – phase 2
: Once we’ve tested and validated right-to-left language support for sub-referencing we will deploy to all right-to-left wikis.
Roadmap for sub-referencing
edit
The usage and feedback demonstrates a strong engagement and clear direction from the community for us to continue to iterate and improve on the feature. The following is intended to outline our general next steps. The items below might change at any given time depending on what the Technical Wishes team can support and will be updated continuously as we progress with the work:
Rendering in reference list
: Iterate on how sub-references are displayed in the reference list, reducing the space the items take up and presenting them in a more tidy and coherent look and feel (
T413221
).
Unlinking sub-refs in VE
: In Visual Editor, contributors may decide that a sub-reference is no longer needed in a given part of the article and would rather replace it by its main reference or simply remove it entirely? We want to support this action with a simple workflow to unlink a sub-reference, while taking into consideration all the different scenarios that may take place (
T413220
).
Parsoid compatibility:
Investigating Parsoid compatibility and fixing any remaining issues so that sub-refs are displayed as expected in reader and Visual Editor Parsoid modes. This is in collaboration with the Content Transform Team.
Compatibility with wikis that use the
{{reflist}}
template:
Improving the underlying architecture to allow for robust creation and management of sub-references in Visual Editor, especially in the presence of
{{reflist}}
, allowing for a global rollout (
T397501
Right-to-left language compatibility:
Testing compatibility with RTL wikis and fixing remaining issues.
Template inclusion in VE:
Similar to existing citation templates such as Cite Book or Cite Web, we aim to explore seamless integration of templates into the sub-reference experience in Visual Editor, should the community reach consensus on one or more templates for use with sub-references.
Bug resolution:
A list of bugs is available on Phabricator
here
, which we will cover step by step depending on severity.
Other smaller items
might emerge, which we would consider case by case and depending on relevance.
Notes
edit
The Technical Wishes team has worked on this feature on and off for many years. If you want to know more, here’s an
overview of the history and complexity of this problem
The number of wikitext editors using sub-referencing is harder to determine. The number is very likely much higher given that most sub-references have been added in wikitext.
We count similar references as follows: Number of refs with similar but not identical text as another ref, where similarity is measured as: differing in length by less than 10 characters, and with a
Levenshtein edit distance
less than 10% of the longer text. See
here
for more information on the Scraper data we used to do this calculation.
Retrieved from "
Categories
WMDE Technical Wishes
Citations
WMDE Technical Wishes/Sub-referencing/Learnings
Add topic