Jump to content

Parsoid/Parser Unification/Cite CSS

From mediawiki.org

Wikis that use localized numbering schemes for references need to add new CSS. This will help to show citation numbers the same way in all reading and editing modes. If your wiki would prefer to do it yourselves, please see the details and example CSS to copy from, and also add your wiki to the list. Otherwise, the developers will directly help out starting the week of February 5.

Background

[edit]

Like all extensions, the Cite extension has localized messages. However, a significant portion of the localized messages are for formatting and for localizing the numbering scheme.

Parsoid uses CSS to do the number-format-specific localization of the Cite extension. This approach ensures a good editing experience in editing clients like VisualEditor. When citations are modified (added / removed), using CSS ensures that the numbers adjust automatically and consistently. Otherwise, VE (and other clients) would have to make a server request to re-render all citations each time one is added or removed which can make for a poor and inefficient experience.

Wikis should add appropriate CSS rules to their MediaWiki:Common.css file to ensure proper localization of citations in Visual Editor, given this difference in how citation number localization is done. This will become even more important as we start to migrate toward the use of Parsoid HTML for readers, not just for editing.

Which wikis are impacted?

[edit]

Pretty much any wiki that uses localized numbering schemes for references is impacted. See Technical details for more details.

Is there a way to see if my wiki is impacted?

[edit]

If you open a page that has citations in VisualEditor, and the citations on the page render differently from outside VE, then your wiki needs a fix. You either needs language-specific CSS rules (already addressed in T156350), or it needs CSS rules to be added to MediaWiki:Common.css.

Note that you this change may only be needed on pages with named references with multiple linkbacks, OR for pages that used reference groups (like lower-alpha, etc.).

Is there any help writing these CSS rules?

[edit]

The Content Transform Team has written scripts to process language localization messages to programmatically generate CSS rules for a wiki's Common.css file. As part of visual diff testing, we have tested these rules and tweaked them a bit - mostly where the script couldn't get the CSS right to the last detail. You can see these rules here. For most wikis, these rules should work out of the box.

Verifying changes

[edit]

Open a page in VisualEditor (after ensuring caches are purged) to see if the CSS fixes have improved the rendering of citations. Here are screenshots of a page from Hindi wikipedia demonstrating this.

This image shows a snippet of a hiwiki page being edited in Visual Editor. The image shows refs and portion of a reference list.
Current rendering in VisualEditor
This image shows a snippet of a hiwiki page being edited in Visual Editor. The image shows refs and portion of a reference list.
After applying custom CSS rules via browser console

This example shows how applying hiwiki specific CSS rules changes the rendering to use latin numbers for refs and hindi alphabet instead of numbers for backlinks. This new rendering matches how hiwiki displays refs and references today.

When you update your wiki's CSS rules, you should similarly be able to see changes to how the page displays citations in VisualEditor.

How do we plan to roll out these changes?

[edit]

We would ideally like to see these changes rolled out everywhere by February 28, 2023.

Since this is primarily a change in how Cite localization is configured on wikis, the Content Transform Team is proposing to take on the task of adding the CSS rules to MediaWiki:Common.css on your wiki and verifying the changes. This might be especially beneficial to wikis that may not have the volunteer / technical resources available to roll out, test, and tweak the changes. There is a change log of the edits we have made.

If your wiki does not require direct assistance from us in implementing the changes, please add it to the list below. For these wikis, we are still around to assist and help, and we will follow up as appropriate to ensure these changes are made in a timely manner.

We announced this on Tech News.

Steps to implement this on your own

[edit]
  1. Check the table on this page to see if your wikis might be affected.
    • If you don't see your wiki listed there, there is nothing to do for your wiki.
    • You can independently verify this on your own by opening a page (preferable one with at least one reference having multiple back links) and comparing the display outside VisualEditor and within VisualEditor.
  2. Open this file with CSS rules for different wikis.
  3. Search for your wiki (xx.wikipedia.org, xx.wiktionary.org, etc.) and copy the CSS rules listed there.
    • If you think your wiki is affected but don't see CSS rules listed here, please get in touch with us.
  4. Open the MediaWiki:Common.css page on your wiki. Paste the CSS rules you copied in step 3 above and save.
  5. Purge the cache for your test page by appending ?action=purge to the page URL and accept.
  6. Open your test page in Visual Editor and verify that the citations now render identical to how they render outside VisualEditor.
    • If the display matches, you are done.
    • If the display does not match, you may have to make additional changes -- feel free to get in touch with us for assistance.

Wikis preferring to make changes on their own

[edit]

If your wiki prefers to roll out and test these changes by yourselves, please add it to the list (transcluded below), along with your signature.


Reporting bugs

[edit]

You can report bugs on Phabricator - please use the #Parsoid or #Parsoid-Read-Views tag to report your bugs.

Asking for help

[edit]

You can reach out to the Content Transform Team by posting on the Talk page. You may also be able to find us on IRC, but the talk page is probably the best place since the responses there might also help others.