Parsoid/Parser Unification/Instructions for editors

This page will document fixes that might be needed to improve rendering compatibility when Parsoid is enabled on a wiki.

Do not use duplicate ids

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. We are likely going to implement a linting category for this and roll it out in the near future. But, 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).

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 to handle <section> tags in Parsoid's output

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.

Workarounds for some known issues with Parsoid

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

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. We'll eventually fix this in Parsoid, but given the availability of an easy workaround, we are focusing our attention on other higher priority tasks.

Example: edit of a template to move from the <indicator> syntax to the {{#tag:indicator}} syntax