5001f914d5
In Doxygen 1.9.7, the URL generation logic changed such that input files in directories (i.e. /docs/Hooks.md) are published with the slug `md_docs_2Hooks.html` instead of `md_docs_Hooks.html`. This was done to improve an edge case where if two conflicting files existed (e.g. docs_Foo.md and docs/Foo.md) both can now get their own stable URL in a determimistic way (e.g. as opposed to a-z sorting and appending _2 only if a conflict exists). But this made other more common URLs no longer stable. Work around this by setting an explict permalink for each markdown file. Ref https://github.com/doxygen/doxygen/issues/10721. Change-Id: Ifeb03602452c1148bd372555bebac9922c583ac2
2.5 KiB
Magic Words
Magic words are localizable keywords used in wikitext. They are used for many small fragments of text, including:
- The names of parser functions e.g.
{{urlencode:...}} - The names of variables, e.g.
{{CURRENTDAY}} - Double-underscore behavior switches, e.g.
__NOTOC__ - Image link parameter names
Magic words have a synonym list, with the canonical English word always present, and a case sensitivity flag. The MagicWord class provides facilities for matching a magic word by converting it to a regex.
A magic word has a unique ID. Often, the ID is the canonical English synonym in lowercase.
To add a magic word in an extension, add a file to the ExtensionMessagesFiles attribute in extension.json, and in that file, set a variable called $magicWords. This array is associative with the language code in the first dimension key and an ID in the second key. The third level array is numerically indexed: the element with key 0 contains the case sensitivity flag, with 0 for case-insensitive and 1 for case-sensitive. The subsequent elements of the array are the synonyms in the relevant language.
To add a magic word in core, add it to $magicWords in MessagesEn.php, following the comment there.
For example, to add a new parser function in an extension: create a file called ExtensionName.i18n.magic.php with the following contents:
<?php
$magicWords = [];
$magicWords['en'] = [
// Case insensitive.
'mag_custom' => [ 0, 'custom' ],
];
$magicWords['es'] = [
'mag_custom' => [ 0, 'aduanero' ],
];
Then in extension.json:
{
"ExtensionMessagesFiles": {
"ExtensionNameMagic": "ExtensionName.i18n.magic.php"
},
"Hooks": {
"ParserFirstCallInit": "MyExtensionHooks::onParserFirstCallInit"
}
}
It is important that the key "ExtensionNameMagic" is unique. It must not be used by another extension.
And in the class file:
<?php
class MyExtensionHooks {
public static function onParserFirstCallInit( $parser ) {
$parser->setFunctionHook( 'mag_custom', [ self::class, 'expandCustom' ] );
return true;
}
public static function expandCustom( $parser, $var1, $var2 ) {
return "custom: var1 is $var1, var2 is $var2";
}
}
- Online documentation (contains more information):
- Magic words: https://www.mediawiki.org/wiki/Manual:Magic_words
- Variables: https://www.mediawiki.org/wiki/Manual:Variable
- Parser functions: https://www.mediawiki.org/wiki/Manual:Parser_functions