This page is currently a draft.
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?
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?
An extension is affected if it either:
- uses the Parser object
- has a parser hook.
What do I need to do?
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?
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 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?
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 or depending on the hooks you want to implement.
How do I refactor my uses of the Parser class?
My CI is complaining about something else, it seems it can't find Parsoid code
Have a look at Parsoid#Continuous Integration, it might help.
What about testing?
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?
Yes, yes we do - have a look at Gerrit change 751751.