Parsoid/Internals/Module Configuration Schema

This page documents the schema used by Parsoid for extension module registration. This structure can either be used as an element in the ParsoidModules clause of an extension's extension.json (preferred), or as the return value for ExtensionModule::getConfig() . (Not recommended except for internal Parsoid modules.) All fields are optional unless otherwise specified.

This field is required.

This is the extension modules's canonical name, and should be unique. Note that a MediaWiki extension can define multiple Parsoid extension modules. This is the unique name of one particular Parsoid extension module, not necessarily the MediaWiki extension's name. The name field does not have to match an extension's directory name nor the name of its page in the Extension namespace on MediaWiki.org. However, if you are only defining a single Parsoid extension module, you might consider making this the same as the top-level name field in extension.json .

{
"name":"FooBar"
}

A list of string class names. Each class name should be a subclass of PFragment , and Parsoid will invoke PFragment::registerClass() on each to ensure objects of this fragment type can be serialized/deserialized.

An annotation handler, which is an object with the following properties:

Example from src/PageTranslation/TranslateExt.php in Extension:Translate :

{
"name":"Translate",
"annotations":{
"tagNames":["translate","tvar"],
"annotationStripper":{
"class":"MediaWiki\\Extension\\Translate\\PageTranslation\\TranslationAnnotationStripper",
"services":[
"Translate:TranslatablePageParser"
]
}
}
}

Map from content type name to an ObjectFactory specification of an object extending ContentModelHandler . A class name string can be used as a shortcut.

Example from src/Ext/JSON/JSON.php in Parsoid :

{
"name":"JSON content",
"contentModels":{
"json":"Wikimedia\\Parsoid\\Ext\\JSON\\JSON"
}
}

A list of ObjectFactory specifications of objects implementing DOMProcessor . Class name strings can be used as shortcuts for object factory specifications.

Example from extension.json in Extension:Cite :

{
"name":"Cite",
"domProcessors":[
{
"class":"Cite\\Parsoid\\RefProcessor",
"services":[
"MainConfig"
]
}
],
"tags":[
...
]
}

Array of fragment handlers. Each handler is an object with the following properties:

The following options keys can be supplied:

• parserFunction (boolean) - whether parser function syntax can be used to invoke this fragment handler
• nohash (boolean) - if false (the default) a # character is prepended to the start of the localized text for the magic word corresponding to key. If the parser function is intended to be invoked without a leading hash, for example {{uc:...}} or the localization for the magic word already contains the hash character, as for {{#bcp47}} this should be set to true.
• hasAsyncContent (boolean) - This must be set to true if the FragmentHandler can ever return an AsyncPFragment indicating asynchronously-available content.

Example from src/ParserTests/ParserTestFragmentHandlers.php in Parsoid:

{
"name":"ParserHook",
"fragmentHandlers":[
{
"key":"f1_wt_nohash",
"handler":{
"factory":"Wikimedia\\Parsoid\\ParserTests\\ParserTestsFragmentHandlers::getHandler",
"args":["f1_wt_nohash"],
},
"options":{
"parserFunction":true,
"nohash":true
}
}
]
}

Array of extension tag handlers. Each handler is an object with the following properties:

The following options keys can be supplied:

• outputHasCoreMwDomSpecMarkup (boolean) - whether the output contents of this extension tag consist of markup parsed by Parsoid. Setting this flag allows Parsoid to perform postprocessing tasks (localization, redlink marking, etc) on the contents of the tag. (T331655 proposes adding a future mixed value for this option.)
• hasWikitextInput (boolean) - whether the input contents of this extension tag consists of wikitext markup. Setting this flag allows annotation tags to be stripped from the input.
• stripNowiki (boolean) - temporary compatibility flag; see phab:T299103 for details.
• wt2html (map) - additional options for conversion from wikitext to html, described below.
• html2wt (map) - additional options for conversion from html to wikitext, described below.

The following wt2html keys can be supplied, which affect how the DOM fragment returned by the ExtensionTagHandler::sourceToDom() method should be handled.

• embedsDomInAttributes (boolean) - as an optimization, ExtensionTagHandler::processAttributeEmbeddedDom() will only be invoked if this property is true.
• embedsHTMLInAttributes (boolean) - as an optimization, ExtensionTagHandler::processAttributeEmbeddedHTML() will only be invoked if this property is true. (deprecated: in new code prefer embedsDomInAttributes/ExtensionTagHandler::processAttributeEmbeddedDom() .)
• attributeWSNormalizationPref (string) - default format for tag attribute space normalization. The can be set to trim (trim whitespace around the attribute), normalize (trim and also normalize inner spaces such as double space to a single space), keepspaces (do not trim or modify inner spaces). The default value is normalize to match usual HTML attribute behavior.
• customizesDataMw (boolean) - set to true if the extension's first node data-mw attribute is set by the extension to avoid clobbering it by mistake. Default value is false.
• setDSR (boolean)
• wrapperName (string)
• unpackOutput (boolean) - deprecated (used only for "sealed" fragments in Cite extension). By default, Parsoid takes the DOM fragment returned by the ExtensionTagHandler::sourceToDom() method, unpacks and splices it into the parent document in the appropriate place. However, if unpackOutput is false, Parsoid will leave a marker instead and store the fragment in a map. It is expected that the extension's wt2htmlPostProcessor DOM processor will appropriately deal with these DOM fragments and manipulate them. For example, the Cite extension relies on this to migrate the ref's fragments to the references section and leave behind a citation that is appropriately globally numbered.

The following html2wt keys can be supplied, which affect how the wikitext generated by ExtensionTagHandler::domToWikitext() interacts with its context:

• format (string) - can be set to block or inline. By default, the wikitext from converting the HTML is rendered inline. However, if extensions specify a block value for this property, the wikitext output is rendered on its own separate line.

Example from src/Ext/Pre/Pre.php in Parsoid:

{
"name":"<pre>",
"tags":[
{
"name":"pre",
"handler":"Wikimedia\\Parsoid\\Ext\\Pre\\Pre",
"options":{
"stripNowiki":true
}
}
]
}

• Parsoid code pages without class names
• Parsoid code