Parsoid/So you want your extension to work with Parsoid

From mediawiki.org

This page aims at gathering information about extension development with Parsoid, in the form of a Frequently Asked Questions (FAQ) list.

What's the point?[edit]

To make Parsoid the default MediaWiki wikitext engine, the dependencies to the legacy parser must be removed. This means that the Parser.php class and the parser hooks are bound to be deprecated at some point. To prepare for that, affected extensions should transition to the Parsoid API.

Is my extension affected?[edit]

An extension is affected if it either:

What do I need to do?[edit]

The following steps are documented in further section in this document; this section aims at being a quick checklist for all the necessary steps.

  • Register the extension to Parsoid
  • Create hooks for Parsoid to reproduce the functionality of the existing parser hooks
  • Refactor the code that references Parser to provide a version that uses the Parsoid extension API for the Parsoid hooks
  • Possibly: add a dependency to Parsoid in the CI of the extension

How do I register the extension to Parsoid?[edit]

This is documented in detail here: Parsoid/Extension API#Extension registration and configuration. You'll need to edit extension.json to either flesh out the whole configuration there, or to refer to a class implementing the Wikimedia\Parsoid\Ext\ExtensionModule interface. There is a small preference among the Parsoid developers for the second option, in order to be consistent with existing code bases and conventions.

How do I create hooks for Parsoid?[edit]

This is documented in detail here: Parsoid/Extension API#Extension registration and configuration and in Parsoid/Extension API#Mapping existing parser hooks. You'll need classes that extend Wikimedia\Parsoid\Ext\DOMProcessor or Wikimedia\Parsoid\Ext\ExtensionTagHandler depending on the hooks you want to implement.

How do I refactor my uses of the Parser class?[edit]

The hooks provide an access to a Wikimedia\Parsoid\Ext\ParsoidExtensionAPI which contains entry points into the Parsoid API. If the needs of your extension are not met by this API, please contact with the Content Transform team by opening a Phabricator ticket so that we can discuss solutions.

My CI is complaining about something else, it seems it can't find Parsoid code[edit]

Have a look at Parsoid#Continuous Integration, it might help.

What about testing?[edit]

During the continuous integration of build of an extension, .txt files in tests/parser/ get added to the list of parser tests to run. These will also be run against Parsoid under two conditions: (a) it contains the parsoid-compatible flag, and (b) the ParsoidPageConfigFactory class is available. (a) is handled in the test file by having its header be

!! options
version=2
parsoid-compatible
!! end

(b), as of the writing of this document (January 2022), requires the addition of 'parsoid' as a dependency to the extension in the CI configuration - an example of this configuration is provided in Gerrit change 745929. Note that this will imply that the tests are run against the tip of the Parsoid branch corresponding to the extension branch (by default, master) and not against the version of Parsoid referenced by MediaWiki core.

Do you have a minimal example for an extension that was easy to adapt?[edit]

Yes, yes we do - have a look at Gerrit change 751751.