Parsoid/Parser Unification/Instructions for editors
 | This page is a work in progress and will continue to be regularly updated as we discover new sources of differences that are best fixed with on-wiki changes to wikitext / templates / modules / CSS / JS. |
This page documents on-wiki fixes that might be needed to improve rendering compatibility when Parsoid is enabled on a wiki.
Heading parsing differences
[edit]- On some wikis, headings dont end in a "=" character and have magic words like "__NOTOC__" added after the trailing character. Parsoid doesn't parse these lines as headings. To fix this, move the magic words to their own lines.
- If headings include a template that emits a newline, Parsoid still treats that line as a heading and just introduces multi-line headings.
- When using raw headings in template these should be decorated with a class or ID so they can be distinguished from wikitext headings. Failure to do this can lead to rendering problems in mobile (more information: T417530, T414734). A lint has also been proposed. Post-Parsoid followup: Once Parsoid is deployed everywhere, we will look into removing this constraint since Parsoid can distinguish between them without needing attributes
Do not use duplicate ids
[edit]HTML documents should not be using duplicate ids on elements. Parsoid enforces this by deduplicating element ids where necessary - this is a change from how the current wikitext parser does things. If your CSS or your Javascript code targets an element with an id, then with this change in Parsoid, only the first element will get selected. So, where you expect multiple elements on a page to get the same id, use a CSS class instead to target them (or use other CSS selectors where applicable). We have implemented a linting category for this to help you with removing element id duplication.
Example: edit of a template to add a class on an element and the corresponding edit of a Javascript to target this class
Adapt CSS
[edit]To handle <section> tags in Parsoid's output
[edit]Parsoid wraps <section> tags around page sections. These section tags are semantically useful and simplifies clients that need to work with individual page sections or the section structure of a document. This feature had also been long requested on wikis, and Parsoid's output finally delivers on this. However, this change means some of your CSS selectors may no longer apply if the section tags are present in the page DOM. This phab task captures this issue. While that phab task initially was considering stripping those section tags from read views, we have since come to the conclusion that those section tags are useful and should be present and as such, we are going to close that phab task as declined. This means that individual wikis might need to adapt their CSS in some cases -- we are happy to flag any scenarios that show up during our visual diff testing, but we / you may discover some of these differences *after* we enable Parsoid on a wiki. In those circumstances, please adjust your CSS.
To style references backlinks in Parsoid output
[edit]The Cite extension's Parsoid implementation emits different HTML than the legacy parser output. So, if your wiki's Mediawiki:Common.css has styles targeting reference backlinks, you may need to update that CSS to target Parsoid HTML.
Here are some examples of edits: lezwiki, hsbwiki
To handle rendering-transparent elements (<link>, <meta>, <style>) in template output
[edit]Unlike the old parser, Parsoid inserts explicit markup for category links and other rendering-transparent elements, such as templatestyles. This can require some tweaking to CSS that align elements such as link boxes, because said markup may interfere with the CSS selector. This is the issue reported in T378906.
To address T378906, for template output, Parsoid now wraps all rendering-transparent elements inside a span element with the class mw-empty-elt. CSS that relies on the order of elements ( .class1 + .class2 { ... } ) should be adjusted to take into account the possible presence of at most two such spans between the elements (div and table) that they want to align.
Here is an example of a CSS change on enwiki to handle this.
Workarounds for some known issues with Parsoid
[edit]While we have invested a lot of effort in testing compatibility between Parsoid and core parser output, we may not be able to fix every single issue before rollout, and in some cases, may decide that it is not worth the development and maintenance effort to fix some incompatibility. So, in this section, we will list some such known issues and known workarounds to ensure compatibility with Parsoid.
Access to parent frame from within extensions
[edit]We have seen this issue impact indicators most commonly. The simplest way for this right now is to switch from using the "<indicator ...>" syntactic form to the "{{#tag:indicator|...|...}}" syntactic form. With the former syntax, the indicator arguments are evaluated lazily and within Parsoid (by which time Parsoid no longer has access to the parent frame). With the latter syntax, the indicator arguments are evaluated eagerly and in this case, Parsoid asks the core parser to handle the expansion for it which is how it works right now. There are no plans to add eager-evaluation support inside extension bodies to Parsoid since this is not a common-enough use case and there is an easily available solution for it.
Example: edit of a template to move from the <indicator> syntax to the {{#tag:indicator}} syntax
Including content when using the localurl, fullurl, or canonicalurl parser function in an extlink
[edit]The second argument to the these parser function is supposed to be a querystring, however, in some instances, editors have included the space separated content when used in an external link. For example, the legacy parser was ok with [{{fullurl:Main page|action=edit 123}}]. Parsoid will consider the entire output of the parser function as the link target and since no content is provided, render a broken link. Parsoid compatible equivalent code would be [{{fullurl:Main page|action=edit}} 123]
Modules relying on side-effects to ParserOutput by preprocessing wikitext instead of returning wikitext
[edit]This is best illustrated with an example. This code in an itwiki module (linked to an actual revision) does not actually return any wikitext back to the calling page. It relies on the fact that indicators are added to ParserOutput which are then inspected by the skin to render the indicator content. However, this doesn't work with Parsoid because Parsoid has a native implementation of indicators and so the indicator content is not processed and nothing is added to the Parsoid's ParserOutput. And since the module doesn't return any wikitext, the indicator disappears.
The fix is for a module to always explicitly return wikitext that it wants rendered on the page instead of updating ParserOutput as a side-effect and discarding the wikitext.
This bug only impacts extensions that end up in ParserOutput metadata (instead of core page content) which have a Parsoid native implementation. As far as we know, indicator is the only such extension. But, we recommend that modules rely on explicit wikitext processing always.
Unnecessary escaping of table start/end wikitext with templates
[edit]This is best demonstrated with edits that fix this problem. See this edit (smnwiki) and this edit (fiwiki) among other such edits we've done on other wikis as well. Parsoid doesn't have support for combining template table markup from one template with attributes coming from outside the template. That support is currently not needed outside templates themselves and so we have never supported it. While those edits did not remove other unnecessary escaping, we recommend that you simplify the markup and remove unnecessary use of templates in such tables where the tables are not embedded in parser functions or other contexts where the escaping is necessary.