WMDE Technical Wishes/References/VisualEditor automatic reference names - Meta-Wiki

We are considering to work on Community Wishlist/W17: Improve VE references' automatic names and reuse. This has been a long-term issue for wikitext editors (see e.g. en:Wikipedia:VisualEditor/Named references) which has been among the top-voted wishes in several Community Wishlist Surveys, e.g. 2017, 2019, 2022 or 2023.

WMF Community Tech published an investigation in 2019, proposing improvements to the automatically generated reference name instead of following initial proposals to add an option for manually adding reference names in VisualEditor. After careful investigation we’ve decided to follow that approach, mainly because manually assigning a reference name in VisualEditor doesn’t fit in the workflow of automatically creating references and doesn’t add much value to VisualEditor users – but might cause confusion for less experienced users.

We have started a request for comment to learn more about the way editors are currently dealing with automatic reference names and reach community consensus on proposed solutions.

Please note: We will only implement a solution if there’s clear consensus among the global community. Our intention is not to build the perfect solution, but to find a simple and lean one that alleviates the pain caused by auto generated names. We are aware that some experienced VisualEditor users might prefer an option to manually change reference names in VisualEditor, but such a UX intervention is difficult to achieve across reference types and thus out of scope for our team, we can only improve the auto-naming mechanism.

We are interested in this issue because it would also benefit sub-referencing in VisualEditor. If we cannot find consensus on (at least) one of the proposals we’ll have to focus on other improvements to references instead.

We propose several solutions, which can be combined if desired by the community. All of them will:

• Strive to create a name that is less technical, is human-readable and easy to remember.
• Require a "fallback" for the reference name, as in certain cases we will not be able to determine a meaningful name. The fallback can certainly be defined as an improvement to the current naming scheme ":n" (":0", ":1"...) and can be configured by the community.
• Apply only when a reference is re-used (or a sub-reference is created) for the first time in VisualEditor, and the main reference does not have a name assigned. This is the current behavior and it will stay the same.
• Cover all types of references – basic references like <ref>text</ref> and templated references like <ref>{{cite book}}</ref>.
• Give communities, to a certain degree, ownership over their preferred naming scheme.
• Allow for localisations in a given language wiki.

This proposal is based on the following assumption: The naming scheme ":n" feels like wikitext, and is cryptic to contributors. An auto-generated name that describes the reference at a meta level and is human-readable is more acceptable to contributors.

This solution proposes changing the current pattern used to automatically generate reference names from ":n" to something more meaningful that 1) indicates that this is an automatically generated reference name, and 2) makes the type of reference easily identifiable (e.g. book, journal, etc.). The names would be "static" – once generated they can only be changed in wikitext, VisualEditor will not update them if the reference type changes.

As soon as a reference is re-used for the first time in VisualEditor, and the main reference does not have a name assigned, the system would use the reference type to determine the default name using the following naming scheme: "<citation template type>_reference-n".

Resulting in automatic reference names like:

• "reference-1" for basic references (here the type reference is used directly as the name),
• "web_reference-1" when using cite web,
• "book_reference-1" when using cite book,
• "news_reference-1" when using cite news,
• "journal_reference-1" when using cite journal,
• "map_reference-1" when using cite maps,
• "note-1" for notes

The number at the end (e.g. -1) increments if multiple automatically named references of the same type exist. If we cannot determine the reference type, we will fall back to "reference-n". More about assigning a reference type in the Annex.

The reference types are translatable (example of translatable cite messages), making reference names useful for all wikis – "web_reference-1" would be "web_de_referencia-1" on Spanish Wikipedia, "book_reference-1" would be "przypis_do_książki-1" on Polish Wikipedia.

This solution does not cover all of our requirements, but is lean and pragmatic and can be implemented without much effort from the community. Contributors who wish to improve the reference name are invited to edit it manually in the wikitext editor.

To augment this solution and make it more tailored to community wishes, we could provide admins with a central place where they can modify the default names at their discretion.

A central configuration point could be:

Let us know if this fix becomes a burden for you. Are the proposed simple names equally undesirable? Will you write bots to support you in creating meaningful names? Are we creating another sub-optimal name?

This is a "smarter" variant. Meaningful, human-readable reference names would be auto generated based on rules the community defines about which content to use. This approach would need community consensus and is more complex to implement as it will need to handle multiple edge cases (which we will not list all here). However, it offers each language community the possibility to decide on how reference names are generated and what they look like.

As soon as a reference is re-used (or a sub-reference is created) for the first time in VisualEditor, and the main reference does not have a name assigned, we would:

1. Check the type of reference.
2. Follow a defined set of rules.

If the reference at hand is a templated reference (e.g., {{Cite book}}) and a local configuration exists, we generate a name based on that configuration (i.e. which template parameters the solution takes as input as defined by the community).

Assume the following reference:

<ref>{{cite web |title=IT's Your Vibe: the motto of Milano Cortina 2026 |url=https://milanocortina2026.olympics.com/en/news/its-your-vibe-motto-milano-cortina-2026 |access-date=20 February 2025 |website=Olympics.com |publisher=[[International Olympic Committee]]}}</ref>

If community configuration defines "website" as the desired parameter for assigning reference names when using {{cite web}}, the automatically generated reference name would be <ref name="Olympics.com">.

If no configuration exists, we would check if a URL is present. The URL can possibly allow us to derive a meaningful name from the second level domain.

The reference above would get the name <ref name="olympics"> when using the domain to create a reference name.

If there is no URL we fallback to the proposed solution 1.

Without a (usable) URL the reference above would get the name <ref name="web_reference_1"> (if the cite class is defined in {{cite web}}) or <ref name="reference_1"> if no citation type is defined.

For basic references, we would directly check whether a URL exists and derive the name from it. If the URL is unusable (e.g. too long) we fallback to solution 1 (e.g. <ref name="reference_1">).

Note that while detecting the URL and using it for creating a reference name is possible, we cannot do the same with other reference content in basic references, because there’s no common indicator for content like author names, access or publication dates etc. across different wikis, languages and citation styles. For the same reason we need to rely on community configured rules when creating reference names based on template parameters.

Some edge cases will be handled in the code (e.g., normalisation or sanitization of template data), and some will fallback to solution 1 (or 1.1.).

We've prepared more examples for you in the Annex below.

To deliver value within the limited time remaining for the Technical Wishes team to make improvements to the references focus area, we had to determine that the following aspects are explicitly out of scope:

• VisualEditor UI changes: The proposed solutions will not include changes to the VisualEditor’s UI. This is because we want to avoid burdening contributors (new and experienced) who may not be familiar with the issue. Furthermore, a UI-based solution would likely result in a high percentage of fallbacks to the sub-optimal default reference names. The effort required to design and validate a suitable user flow that works across all types of references, would not be proportionate to the expected net benefit for users.
• Coexistence of old and new naming schemes: Old and new names will co-exist in articles. After a solution is implemented you will still see reference names like :0 or :54. If we were to fix existing auto-generated names, it would significantly enlarge the scope of this project. We also don’t want to modify existing articles, communities should remain in control of improving them. The new naming logic will only apply when a (previously unnamed) reference is reused in VisualEditor.
• Updating of existing reference names: We will create a reference name upon the first re-use (or the creation of the first sub-reference) and as long as a name does not exist yet. Any subsequent changes to the reference content will not affect the previously auto generated reference name.
• Changes when copying references from other pages: Copying a named reference from a different article will keep its name preserved. Handling renaming of references is considered a separate problem.
• Accessibility improvements: Existing accessibility issues when reading wikitext, for instance for screenreaders, will probably not be improved with this solution.
• Machine Learning: Machine Learning could potentially be a great aid in generating meaningful names from <ref> content. However, after careful consideration, we have decided not to pursue ML for this use case. Since the scope is small for this problem, the effort outweighs the net-benefit.

What support would help you make a decision about naming schemes? E.g. which template parameters to derive a meaningful name from?

We can provide data on how often many citation template or basic reference type is used on your wiki, as well as how likely the solution above defaulting to a fallback. In addition, we can make recommendations based on patterns we currently observe on wikis to help define the naming schemes needed for solution 2, e.g. <author name>-<year>.

Please share your thoughts on our talk page and help us spread the word about this request for comment. Feel free to discuss in your native language, we want to make sure that everyone can participate.

We are happy about suggestions for improving certain details of the proposed solutions. Any other feedback and alternative proposals are also welcome – even though it’s out of scope for us, it might still be relevant for future work on this topic. As indicated above, we can only implement the solutions if there’s clear consensus by the global community.

Please support us interpreting consensus by clearly indicating your opinion (e.g. by using polling templates like  Support/ Neutral/ Oppose). We are aware of en:WP:NOTVOTE, but given that we are facilitating this discussion with users from different wikis, potentially commenting in their native language, clearly indicating your position helps us avoid misunderstandings.

Thank you for participating!

Each reference type 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. References without cite tags and classes (e.g., plain <ref> tags) get the basic "reference" type. Most wikis use citation templates like {{Cite book}} to assign the cite class.

The table below illustrates how automatically generated reference names could look using the different solutions presented above:

<ref>Barbara J. Hayden, Archaiologikon Mouseion Herakleiou (2005) - ''Reports on the Vrokastro Area, Eastern Crete'', University of Pennsylvania Museum of Archaeology, p. 227</ref>

<ref>Patricia Sabatini, [http://www.post-gazette.com/pg/09289/1005873-28.stm "Inflation unlikely to be a threat as economy emerges from recession"], ''Pittsburgh Post-Gazette'', October 16, 2009. Retrieved 2010-01-21.</ref>

<ref name="post-gazette-1">

<ref>{{cite web |title=IT's Your Vibe: the motto of Milano Cortina 2026 |url=https://milanocortina2026.olympics.com/en/news/its-your-vibe-motto-milano-cortina-2026 |access-date=20 February 2025 |website=Olympics.com |publisher=[[International Olympic Committee]]}}</ref>

<ref name="web_reference-1">

<ref name="Olympics.com">

<ref name="IT's_Your_Vibe:_the_motto_of_Milano Cortina_2026">

<ref>{{cite book|title=The Olympic Games: The First Thousand Years|author1=[[Moses I. Finley]]|date=14 June 1976|publisher=[[Dover Publications]]}}</ref>

<ref name="book_reference-1">

<ref name="Moses_I._Finley">

<ref name="The_Olympic_Games:_The_First_Thousand_Years">