Community Wishlist Survey 2021/Citations/Configurable order of references in references section

Configurable order of references in references section

  • Problem: At present references are (numbered and) listed in the order of their invocation in an article. While this is a reasonable default, it would sometimes be useful to list the references according to different sort orders, f.e. chronologically or alphabetically
  • Who would benefit: All readers of articles where the default order is not the preferable one
  • Proposed solution: Add some option like an order= attribute to <references/> wiki markup (and/or a |order= parameter to templates such as Template:Reflist) to define one of the following display orders (the first two are the most important ones, the others are provided to illustrate how this model could be further extended):
  • "Invocation" (default or <references order="invocation">): Order of invocation in article.
  • "Natural" (<references order="natural">): Order of occurence in <references>...</references> sections (or in Template:Reflist |refs=...). Provided that the list of references in there is manually sorted by, f.e., author name or date, this would allow for reference lists to be sorted by name or date (or any other arbitrary order) even if the order of invocation in the article is different.
  • "Reference-ID-ascending" (<references order="id-ascending">): Order in alphanumerical ascending order of the ID values of the <ref name="id">...</ref> attributes in references. Refs without name= would be appended at the end of the list per default "invocation" order above.
  • "Reference-ID-descending" (<references order="id-descending">): Order in alphanumerical descending order of the ID values of the <ref name="id">...</ref> attributes in references. Refs without name= would be appended at the end of the list per default "invocation" order above.
  • "User-defined" (<references order="number-ascending">): Ascending order per numerical argument n (0..999) in <ref order="n">...</ref>; refs without order= would be appended at the end of the list per default "invocation" order above.
  • "Author-ascending" (<references order="name-ascending"): Ascending order per non-numerical string argument name in <ref order="name">...</ref>; refs without order= would be appended at the end of the list per default "invocation" order above.
  • "Date-ascending" (<references order="date-ascending"): Ascending order per ISO 8601 argument date (in "yyyy[-mm[-dd]]" format) in <ref order="date">...</ref>; refs without order= would be appended at the end of the list per default "invocation" order above.
  • "Date-descending" (<references order="date-descending"): Decending order per ISO 8601 argument date (in "yyyy[-mm[-dd]]" format) in <ref order="date">...</ref>; refs without order= would be appended at the end of the list per default "invocation" order above.
  • More comments:
  • In the examples above it is assumed that the implementation could distinguish the three types of <ref order="...">...</ref> attributes (numbers, name strings and ISO 8601 dates) automatically and that references with attribute types not selected as sort keys per <references order="..." would be appended to the list. It would be possible to modify/extend this model in various ways, f.e. to have different attributes for the different types, or to allow sorting of the remaining references according to secondary sort keys.
  • The proposal above works on the level of wiki markup (rather than on template level) in order to remain independent of citation template implementation details in the various Wikipedia entities. It might be possible to achieve similar reference sorting on higher levels, but it would probably require client-sided scripting (Javascript) then and therefore would not be universal.
  • Nevertheless, it would be desirable to have some means to pass name, date or reference-id information from citation templates like CS1/CS2 to <ref></ref> markup. This would allow to provide a name or date in the citation template without having to repeat this information in the <ref name/order=></ref> argument. No such communication model seems to exist at present, but would certainly be desirable to have also for many other purposes. Article-wide variables come to my mind. Perhaps some new kind of strip-markers? (TBD.) Another possible solution could be to change the citation templates to emit the <ref order=...></ref> markup themselves or to create a wrapper template for this.
  • Phabricator tickets:
  • Proposer: Matthiaspaul (talk) 01:55, 26 November 2020 (UTC)


  • I can understand the desire to add sorting options to the references. However, ultimately the order should be controllable by the user in their settings and not what article editors prefer. Thus, I can only fully support this if the user has final say on the ordering based on their preference. RedWolf (talk) 19:33, 10 December 2020 (UTC)
Yeah, I too wish all such configuration settings could be controlled by settings in user preferences, and the scheme certainly could be further extended to provide this in the future. However, at present, the functionality to sort the reference list does not exist at all, so it seems to be desirable to first have this implemented as basic functionality and propose more user configurability in the next round.
--Matthiaspaul (talk) 21:11, 10 December 2020 (UTC)
  • I think this would only be really useful if it reached the stage where readers can sort the references by lots of different attributes. The proposer hints at some of the difficulties we would have in making this tool useful, which would entail citation templates (like {{cite book}} on the English Wikipedia) being able to pass data to the "ref" attributes. The tool will not be very successful if editors need to manually add all the data twice per reference on a per-page basis (which will also double the wikitext length). It's a good idea and would be useful to readers and also editors (I could find typos in refs I write faster if they're sortable) but I do wonder how big a project this would be. — Bilorv (talk) 01:34, 11 December 2020 (UTC)
That's one of the reasons why I wrote that the first two examples are the most important ones, as these ones work without having to provide additional arguments. In the example #2 (what I called "Natural" sort order), all the editor would have to do is to manually provide the list-defined citations in the <references>...</references> block in the desired order (whatever that is, alphabetically, chronologically, or whatever else), as it already happens in ==Bibliography== or ==Works== sections most of the time, and the references would be listed in this order (instead of in the order of invocation). This is the core functionality, that would be needed to be implemented, and it would give editors full control over the display order of references without having to add or duplicate any extra arguments.
The other examples further down are already kind of "icing on the cake", as they would provide predefined display sort orders even for unsorted reference lists (or lists in yet another order). Among them, the proposed sort orders "Reference-ID-ascending" and "Reference-ID-descending" would draw on the name= attribute already present in most citations, f.e. <ref name="xyz">...</ref>. As the xyz in there most often is a string in the form "name-year" by convention this is already a good value to sort for, and one which still would not need any additional attribute to be given or additional citation information to be duplicated.
Only in the example cases #5 to #8 (starting with "User-defined"), we would actually need a new attribute like <ref name="xyz" order="abc">...</ref>, which could be any free text to sort for, but could also duplicate values given as parameter values in citation templates (if citation templates are used inside the <ref>...</ref> block at all). I agree, it would be neat if there would be a way to pass the arguments of template parameters like for the author name or publication date into the order= attribute automatically somehow, but even if editors would have to do this manually (as they sort-of-do with the name= attribute all the time already), it would be an acceptable optional overhead, not duplicating the length of citations. As template developers have been creative in the past, I envision that once the basic reference sorting functionality would become available, template developers would soon develop wrapper templates for this so that even this inconvenience would be eliminated for citation template users.
--Matthiaspaul (talk) 13:05, 11 December 2020 (UTC)
  • I'm hoping sorting would be automatic based on criteria specified in a separate template or in the {{reflist}} itself (i.e. {{reflist}} controls whether sorting is alphabetical by title, chronological by source date, etc.), rather than based on a switch in each ref tag. I foresee stupid edit wars over which references appear first, likely trying to move sources an editor wants to promote higher in the sort order, or editors preferentially sorting references based on their POV. I do like the concept, though - ref sorting by invocation order does seem to lead to editors (for the same reasons) overloading an article's lede with preferential sources so that they appear higher in the reflist. Ivanvector (talk) 14:18, 11 December 2020 (UTC)
While I would appreciate this as well, I'm afraid this is technically impossible to implement. Templates cannot influence anything outside themselves, unfortunately. That's one of the reasons why my proposal is based on the level of the underlying wiki markup rather than on template level.
What would be possible for a template like {{reflist}} is to pass down an argument to control the sort order, so that something like:
{{reflist |order="natural" |refs=
<ref name="R1">{{cite book |...}}</ref>
<ref name="R2">{{cite book |...}}</ref>
would internally issue something like:
<references order="natural">
<ref name="R1">{{cite book |...}}</ref>
<ref name="R2">{{cite book |...}}</ref>
The name="xyz" thing would be unnecessary for sort orders "Invocation" and "Natural" (but required for list-defined references, anyway), but it would be required for sort orders "Reference-ID-ascending" and "Reference-ID-descending". It would also be optional for the other four proposed sort orders which would require order="abc" instead.
Without any such "hint", MediaWiki's Cite extension (the code which would have to be modified to implement this sorting functionality) has no way of knowing a citation's sort weight as it cannot read template parameters (this would be nice to have, but is a fundamental design limitation that AFAICS could only be had through a complete redesign and rewrite of the underlying software - which is unrealistic to happen).
The proposed scheme, however, is universal, that is, it would work regardless of how citations are implemented in a particular wiki (and if this is based on templates or not), and I estimate that it would not require more than a couple of days to code, therefore, it is quite realistic to be actually implemented by the team given enough community support.
--Matthiaspaul (talk) 17:22, 11 December 2020 (UTC)
  • I have long longed for functionality like this for well-developed articles. However, I think the proposed functionality is far richer than necessary. All that's needed is the "Natural" functionality listed above, and since the current function is to put things in an essentially uncontrollable, random order, there can be no objection to simply making "Natural" the new default -- no need to invoke it somehow, no need for the new any new syntax and the extensive options proposed above. A simple implementation would be to for the machinery to parse the refs defined in {reflist | refs=} first -- before parsing any refs defined in the article text proper. This way, refs defined within the {reflist |refs=} will get assigned "reference numbers" in the order they appear there (not the order they appear in the article) and will be output in that order. (As Matthispaul points out, this allows the refs to be placed in any order editors want, manually, without any fussing about sort orders, date formats, syntax, etc etc etc. Few articles have enough refs to make automatic ordering a big convenience.) Ideally, the refs in the {reflist |refs=} will be the only refs there are at all; however, if there are any stray refs defined in the article proper (or if editors haven't bothered to use {reflist |refs=}) then any refs defined in the article get parsed last, after all the refs in {reflist |refs=}; so they'll get the highest "reference numbers" and be output last. Thus all refs do get output no matter what; and if editors wish to control their order by listing them in {reflist |refs=} they can, and if they don't want to bother doing that then everything works just like it does now. EEng (talk) 14:39, 11 December 2020 (UTC)
I see your point, however, replacing the current sort order by "Natural", there will be editors who will miss references sorted by "Invocation" order (while other sort orders are desirable at times, it is not that the default "invocation" order would not be desirable as well in many articles - you see them as "random" and "undesirable", but I doubt the majority of readers would agree with this). While "Natural" would allow editors to sort the references in the references block according to the invocation order as well (and thereby can be seen as providing a superset of possible output orders), it would require more maintenance to keep the listed references in the same order as the order of invocation.
So, if we were pressed to have only one hardwired sort order, "Natural" would certainly be a better option than "Invocation", and I would support this as well. (In my proposal, I kept "Invocation" as the default for backward compatibility - not all users would want for the sort order to suddenly change to "Natural" all over the place without first changing the order of references in the list.) However, I think, that while we are here already, the overhead to make this configurable (at least for the two important sort orders #1 and #2) is minimal, and at least for the first few proposed sort orders all that would be required to get a "Natural" sort order would be to add some order="natural" attribute/parameter. Hardly unbearable.
The other proposed sort orders are "icing on the cake". I provided them to illustrate how this scheme could be extended if the developers have enough time for it, but I would also be happy if the developers would just implement the first two (or first four) sort orders. The good thing is that this could be implemented in steps, adding more sophistication over time.
--Matthiaspaul (talk) 18:22, 11 December 2020 (UTC)
An elegant approach for where list-defined refs are used, @EEng. Pelagic (talk) 04:47, 16 December 2020 (UTC)

I would like for the reader to be able to sort references similar to how they can sort wikitables. Setting a sort order in wikitext will lead to fights. I've been slapped down before for sorting list-defined refs the "wrong way", and that ordering wasn't even reader-facing. Currently the rendered HTML is structured like <li id="cite_note-18"><span class="mw-cite-backlink">...</span> <span class="reference-text"><cite id="..." class="citation book cs1">...</span></li>. Could we add some attributes (date, authkey) to the top-level <li> and use client-side Javascript to manipulate the DOM and sort the list items by attribute? —Pelagic (talk) 04:30, 16 December 2020 (UTC)

Cite template could add a <sortkeys date=2020-12-16 authkey=smith /> element inside the <ref> tags, then server-side processing could copy those attributes onto the generated <li>. Pelagic (talk) 04:39, 16 December 2020 (UTC)


  •   Support PianistHere (talk) 02:02, 9 December 2020 (UTC)
  •   Support ──post by kenny2wiki  Talk  Contribs  02:40, 9 December 2020 (UTC)
  • Meh. It's not that this would be bad, but it's not really something I've ever really wanted as a reader, and I can't really envision a situation in which someone would. It's rare that someone knows a reference exists on a page but can't find it through either going to the place where it's cited on the page or using ctrl+F or something similar. {{u|Sdkb}}talk 05:23, 9 December 2020 (UTC)
It's not so much as to not find a reference, more to have similar references grouped together. For example, an author might have published multiple works in a year, and it might be desireable for the reader to be immediately pointed to the other publications while reading one of them. Similar, studying one reference, it might be highly desirable to find other related works published shortly before or after the date of publication. If you check reference lists in publications, they are often sorted alphabetically or chronologically (or by other keys or methods), while, at present, in Wikipedia they are listed in the order of their invocation, which might look almost "random" if only looking at the list of references.
Yet another case were it might be helpful to have the references sorted by some key is in PDF exports or printed articles, where "clicking on a link" is not available as a means to find a reference in the list.
--Matthiaspaul (talk) 21:11, 10 December 2020 (UTC)
  •   Support Does not seem to be urgent, but everything that implies a better source check is positive for the trust of the readers. Xavi Dengra (MESSAGES) 11:01, 9 December 2020 (UTC)
  •   Support not strong issue - but if the Read view allowed options to read in one order or another that may help discoverability, without complicating editing views? Kaybeesquared (talk) 13:23, 9 December 2020 (UTC)
  •   Support Libcub (talk) 18:37, 10 December 2020 (UTC)
  •   Support, although I'd like it to be configurable by the reader with a dropdown list or something. NaBUru38 (talk) 20:27, 10 December 2020 (UTC)
  •   Support Srđan (talk) 22:14, 10 December 2020 (UTC)
  •   Support noting my comment above. Ivanvector (talk) 14:18, 11 December 2020 (UTC)
  •   Support Tutwakhamoe (talk) 21:22, 14 December 2020 (UTC)
  •   Oppose as proposed, anyway. It relies on ISO date formatting, which is "reader-hateful" and something many of us avoid ever using, and even normalize to whatever the dominant date format is in the article (at en.wikipedia). Some projects might even forbid that date format in their style manual. There is "an idea" in here somewhere, but this is not a good proposed implementation. Given that we had automated date formatting (and auto-linking) back in the late 2000s, which was controversial and (at en.wikipedia, anyway) eventually undone, the code for that could maybe be repurposed as something done in the background for citation sorting, without affecting the displayed date output.  — SMcCandlish ¢ >ʌⱷ҅ʌ<  05:23, 15 December 2020 (UTC)
Unfortunately, you misunderstood the idea in various ways. My proposal does not rely on ISO date formatting and has nothing at all to do with automated date formatting or even the output format of dates.
I used the ISO date format in the last two of the examples ("Date-ascending" and "Date-descending") to illustrate possible extensions to the requested basic functionality ("Invocation" and "Natural"). These two examples are entirely optional (as has been pointed out several times). They could just as well use any other date format of choice (or none at all), however, as this whole proposal works on markup level and one of the goals is to be universal, machine-readable and independent of any configuration differences in the various Wikipedia entities, the international date format per ISO 8601 is a quite natural choice. Also, no style guide forbids to use ISO 8601 dates on source code level, only for (some) display purposes - after all, it's just an argument to an attribute. Further, the proposal has nothing to do with the display of dates; the dates in whatever format are just given on source code level as sort weights and never displayed anywhere - dates used for display purposes are defined in the citation itself - which has nothing to do with the date in the proposed order= attribute of the surrounding <ref></ref> block.
So, if you don't like ISO dates, just ignore the last two examples or think of them as if they were using a date format of your preference. After all, the description is to "transport the message" and illustrate how a realistic example implementation could look like, the decision on the actual attribute names and detail syntax remains up to the implementors.
--Matthiaspaul (talk) 23:15, 15 December 2020 (UTC)
  •   Support for user-side sorting. Uanfala (talk) 22:53, 19 December 2020 (UTC)
  •   Support I support that idea, but there should be clear and strich rules as to when to use that function and when not. Using the function should not be a matter of taste or individual preferences, and the risk of conflicts must be reduced to the minimum. Nachtbold (talk) 12:21, 21 December 2020 (UTC)
  • Question: Sorry, what are we supporting or opposing? If it's the general idea of replacing the current chaos-order with something else, sure. If it's the rococo orgy of options proposed by Matthiaspaul, then No, because that's never going to get done and even if it did it would just bloat new editors' learning curve for no reason at all -- no one's going to use all that COBOL-like crap. Neither does the reader need to be able to change the order. In all humility, my proposal to simply parse {reflist|refs=} first is amazingly simple, gives editors complete control, and might actually get done before all of us have gone to meet our Maker. The idea that there will be editors who will miss references sorted by "Invocation" is just (sorry) absurd -- since a new reference can be inserted by anyone at any point at any moment, "Invocation" order is no order at all -- there's nothing to miss unless you like chaos. EEng (talk) 14:57, 24 September 2021 (UTC)